ShelfWatch JavaScript/TypeScript SDK

Official Node.js client for ShelfWatch APIs v2.

npm install shelfwatch

Requires Node.js 18 or newer (uses the built-in fetch API).

Quick start

Create credentials in ShelfWatch Console → Integrations, then:

import { ShelfWatch } from "shelfwatch";

const client = new ShelfWatch({
  apiKey: "swpk_…",
  projectId: "PROJECT_UUID",
});

const visits = await client.visits.list({
  startDate: "2026-07-01",
  endDate: "2026-07-31",
});
console.log(visits.data);

const detail = await client.visits.get(visits.data[0].visit_uuid, {
  includeKpis: true,
});

OAuth client credentials

const client = new ShelfWatch({
  clientId: "swoc_…",
  clientSecret: "swocs_…",
  projectId: "PROJECT_UUID",
});
// Access tokens are fetched and refreshed automatically.

CommonJS

const { ShelfWatch } = require("shelfwatch");

API coverage

Resource	Methods
client.visits	list, get
client.mdm	stores, users, categories, brands, skus, schedules
client.reports	list, generate

Filters that accept multiple values can be passed as a comma-separated string or an array:

await client.visits.list({
  startDate: "2026-07-01",
  endDate: "2026-07-31",
  visitStatus: ["completed"],
  storeCode: ["S001", "S002"],
});

const stores = await client.mdm.stores({ q: "delhi" });
const reports = await client.reports.list();
const rows = await client.reports.generate("visit-level", {
  startDate: "2026-07-01",
  endDate: "2026-07-07",
});

Full HTTP reference: ShelfWatch Console → Help and Support, or the apis-v2 docs.

Errors

Typed exceptions map to HTTP status codes:

Exception	Status
ValidationError	400
AuthenticationError	401
ForbiddenError	403
NotFoundError	404
RateLimitError	429
ServerError	5xx
ShelfWatchError	other

import { ShelfWatch, NotFoundError } from "shelfwatch";

try {
  await client.visits.get("missing-uuid");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log(err.statusCode, err.message);
  }
}

Development

npm install
npm test
npm run build

Publish to npm

./scripts/publish.sh --dry-run   # pack without publishing
./scripts/publish.sh             # npm publish
./scripts/publish.sh --tag beta  # publish with a dist-tag

Bump version in package.json and VERSION in src/client.ts before each release.