Integration starter

Don't start from a blank page. The ShopiMind integration starter is a minimal, secure Node.js skeleton that already wires up the entire foundation of an integration:

• reception and HMAC verification of all lifecycle webhooks;
• the end-to-end OAuth Type B flow;
• a local store (SQLite) that tracks installations and API keys per store;
• an adapter to the ShopiMind SDK to call the API back;
• optional scheduled-sync plumbing (daily scheduler, idempotent provisioning, encryption of credentials at rest).

Philosophy: replace the demo logic with your real product, but keep the security primitives intact (HMAC verification, response contract, key management).

Get the starter

GitHub repository

The starter will be published on GitHub. Link coming soon — it will be added here.

Getting started

cp .env.example .env
# Fill in WEBHOOK_SECRET (provided by ShopiMind)
yarn install
yarn start    # or: yarn dev (hot reload)

The server starts on http://localhost:8082. Exposed routes:

Method	Path	Role
GET	/health	Liveness probe
POST	/webhook/receive	All lifecycle events
POST	/webhook/test-connection	Connection test from the ShopiMind UI
POST	/webhook/remote-data/{resource}	Dynamic options of a select
GET	/oauth/authorize	Step 2 of OAuth Type B (consent)
POST	/oauth/consent	Step 4 of OAuth Type B (redirect)

Environment variables

Variable	Role	Default
WEBHOOK_SECRET	HMAC secret (provided by ShopiMind)	— (required)
SHOPIMIND_API_URL	ShopiMind API base, without /v1	http://localhost:5500
PORT	HTTP port	8082
SIGNATURE_TOLERANCE_SECONDS	Anti-replay window	300
DATABASE_PATH	SQLite file	./data/shopimind.sqlite
CREDENTIALS_KEY	AES-256-GCM key (encryption of credentials at rest) — optional	—

Structure

src/
├── server.js          ← server bootstrap
├── config.js          ← env loading
├── db.js              ← SQLite store (installs + webhook log)
├── lib/
│   ├── signature.js   ← HMAC verification
│   ├── shopimind.js   ← SDK adapter (the only file that touches the SDK)
│   ├── provisioning.js← ensureDataSource / …Definition / …Event (idempotent)
│   ├── crypto.js      ← encryption of credentials at rest (optional)
│   ├── scheduler.js   ← dependency-free daily job (optional)
│   └── sync-engine.js ← run history + cursors (scheduled sync, optional)
└── routes/
    ├── health.js
    ├── lifecycle.js   ← all webhooks + test-connection + remote-data
    ├── oauth.js       ← OAuth Type B
    └── widgets.js     ← widget contract reference (exposes no route)

Customize

• Webhook business logic → src/routes/lifecycle.js (install, activate, … handlers).
• OAuth consent UI → replace the demo form in src/routes/oauth.js.
• New API call → a one-line helper in src/lib/shopimind.js, or the SDK class directly (require('@shopimind/sdk-shopimind')).
• Scheduled sync → compose scheduler + sync-engine + provisioning.

Going further

• Lifecycle & webhooks — the inbound contract in detail.
• Configuration — declare your config schema.
• Calling the ShopiMind API — push your data.
• JavaScript SDK — the reference for the SDK used by the starter.