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";constclient=newShelfWatch({apiKey: "swpk_…",projectId: "PROJECT_UUID",});constvisits=awaitclient.visits.list({startDate: "2026-07-01",endDate: "2026-07-31",});console.log(visits.data);constdetail=awaitclient.visits.get(visits.data[0].visit_uuid,{includeKpis: true,});

OAuth client credentials

constclient=newShelfWatch({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:

awaitclient.visits.list({startDate: "2026-07-01",endDate: "2026-07-31",visitStatus: ["completed"],storeCode: ["S001","S002"],});conststores=awaitclient.mdm.stores({q: "delhi"});constreports=awaitclient.reports.list();constrows=awaitclient.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{awaitclient.visits.get("missing-uuid");}catch(err){if(errinstanceofNotFoundError){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.