@shopimind/integration-kit-js 1.0.0

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 ShopiMind. Tous droits réservés / All rights reserved.
+
+FR — Ce dépôt est rendu public à des fins de transparence et de démonstration
+uniquement. Aucune licence d'utilisation, de copie, de modification, de
+distribution ou de création d'œuvres dérivées n'est accordée, en tout ou en
+partie, sans l'accord écrit préalable de ShopiMind.
+
+EN — This repository is made public for transparency and demonstration purposes
+only. No license is granted to use, copy, modify, distribute, or create
+derivative works of any part of it without ShopiMind's prior written consent.

package/README.md

@@ -0,0 +1,118 @@
+# @shopimind/integration-kit-js
+
+[![CI](https://github.com/shopimind/integration-kit-js/actions/workflows/ci.yml/badge.svg)](https://github.com/shopimind/integration-kit-js/actions/workflows/ci.yml)
+
+The toolkit for **building a ShopiMind integration**. You write your business logic; the kit provides all the infrastructure.
+
+An integration has to receive lifecycle webhooks, sync data reliably, expose widgets, and talk to the ShopiMind API securely. With this kit you only declare **what is specific to your system** (pure functions + declarations) — the rest is provided and tested once.
+
+**The kit handles for you:**
+- 🔐 Secured webhooks — HMAC signature verification + anti-replay
+- 🔄 Incremental, **cursor-safe** sync — no data loss on error
+- 🌊 Streaming pagination + bounded concurrency — no memory blow-up, no request bursts (429)
+- 💾 Local persistence (SQLite) with **encrypted secrets** at rest
+- 🔌 **Typed** ShopiMind API client (the SDK, re-exported)
+- ⚙️ **Idempotent** provisioning of data sources, custom data and events
+- 🌐 HTTP server + lifecycle handling (install / activate / config / sync)
+- 🧩 Widget declarations
+
+## Requirements
+
+Node.js 18+ and TypeScript (ESM / `NodeNext`).
+
+## Install
+
+```bash
+npm i @shopimind/integration-kit-js
+```
+
+The ShopiMind SDK is a dependency and is **re-exported**, so you can import SDK resources directly from the kit.
+
+## Quick start
+
+### 1. Describe your integration
+
+```ts
+// integration.ts
+import { defineIntegration } from '@shopimind/integration-kit-js';
+
+export const integration = defineIntegration({
+  slug: 'my-pos',
+  meta: { name: 'My POS', version: '1.0.0' },
+
+  configSchema: { steps: [ /* the configuration form shown to the merchant */ ] },
+  parseSettings: (raw) => ({ /* your typed settings */ }),
+
+  testConnection: async (ctx) => {
+    // check access to the partner system with ctx.settings
+    return true;
+  },
+
+  provisioning: async (ctx) => ({
+    dataSources: [ /* ... */ ],
+    customData:  [ /* ... */ ],
+    events:      [ /* ... */ ],
+  }),
+
+  widgets: [ /* widgets exposed in the ShopiMind editor */ ],
+
+  syncSteps: [
+    {
+      entity: 'customers',
+      cursorScope: 'global',
+      enabled: (s) => s.syncCustomers,
+      run: async (ctx) => {
+        // ctx.spm.* (ShopiMind API), ctx.paginate(...), ctx.state, ctx.logger...
+        return { items: 0, errors: [] };
+      },
+    },
+  ],
+});
+// Integration<S> types every field (strict TypeScript).
+```
+
+### 2. Run the app
+
+```ts
+// main.ts
+import { createIntegrationApp } from '@shopimind/integration-kit-js';
+import { integration } from './integration.js';
+
+const env = process.env;
+
+const app = createIntegrationApp(integration, {
+  databasePath: env.DATABASE_PATH ?? './data/store.sqlite',
+  webhookSecret: env.WEBHOOK_SECRET!,     // HMAC secret for ShopiMind webhooks
+  credentialsKey: env.CREDENTIALS_KEY,    // 64-hex AES key used to encrypt stored secrets
+  port: env.PORT ? Number(env.PORT) : 8080,
+});
+
+void app.start();
+```
+
+`createIntegrationApp` wires the HTTP server, the lifecycle dispatcher (signed webhooks), persistence and the sync engine — the kit builds the ShopiMind SDK client itself. You only have to deploy.
+
+> **Encryption is fail-closed.** Without `credentialsKey`, startup fails — pass `allowPlaintextSecrets: true` to allow plaintext secret storage **for local development only**.
+
+## The building blocks of an integration
+
+| Field | Role |
+|---|---|
+| `configSchema` | the configuration form shown to the merchant |
+| `parseSettings` | turns the raw config into typed settings |
+| `testConnection` | checks access to the partner system |
+| `provisioning` | idempotently creates the data sources / custom data / events on the ShopiMind side |
+| `widgets` | widgets exposed in the ShopiMind editor |
+| `syncSteps` | the sync steps — **the cursor is managed by the kit** |
+| `hooks` *(optional)* | lifecycle callbacks (`onActivate`, `onConfigUpdated`, ...) |
+
+## Guarantees
+
+- The **cursor only advances when a step finished without error** → no silent data loss; the window is replayed on the next run.
+- **Partner secrets are encrypted** at rest and **redacted in logs**.
+- **Pagination streams** and **concurrency is bounded** → controlled memory, no request bursts.
+- **Webhooks are verified** (signature + anti-replay window) **before** any processing.
+
+## License
+
+Source-available, proprietary — see [LICENSE](./LICENSE). You may use and modify the kit for your own use of the ShopiMind service; redistribution and independent use are not granted.

package/dist/config/config-store.d.ts

@@ -0,0 +1,6 @@
+import type { ConfigSchema, ConfigField, RawConfigs } from '../contracts/index.js';
+import type { IntegrationStateRepo } from '../store/repositories.js';
+export declare function collectFields(schema: ConfigSchema): ConfigField[];
+export declare function sensitiveKeys(schema: ConfigSchema): string[];
+export declare function saveConfigs(state: IntegrationStateRepo, id: string, schema: ConfigSchema, configs: RawConfigs): void;
+export declare function loadConfigs(state: IntegrationStateRepo, id: string, schema: ConfigSchema): RawConfigs;

package/dist/config/config-store.js

@@ -0,0 +1,56 @@
+/**
+ * Persistence of an installation's configuration. Fields declared `sensitive`
+ * are ENCRYPTED at rest (API key, etc.), the others are stored in plaintext.
+ * `loadConfigs` reconstructs the raw map for `integration.parseSettings`.
+ */
+const PLAIN_KEY = 'cfg';
+const SECRET_PREFIX = 'cfgsec:';
+export function collectFields(schema) {
+    const out = [];
+    if (schema.steps)
+        for (const s of schema.steps)
+            out.push(...s.fields);
+    if (schema.fields)
+        out.push(...schema.fields);
+    if (schema.groups)
+        for (const g of schema.groups)
+            out.push(...g.fields);
+    return out;
+}
+export function sensitiveKeys(schema) {
+    return collectFields(schema)
+        .filter((f) => f.sensitive === true)
+        .map((f) => f.key);
+}
+export function saveConfigs(state, id, schema, configs) {
+    const secret = new Set(sensitiveKeys(schema));
+    const plain = {};
+    for (const [k, v] of Object.entries(configs)) {
+        if (secret.has(k)) {
+            if (v != null && v !== '')
+                state.setSecret(id, SECRET_PREFIX + k, String(v));
+            else
+                state.delete(id, SECRET_PREFIX + k); // empty value -> actually erase the secret
+        }
+        else {
+            plain[k] = v;
+        }
+    }
+    // Also erase secrets whose key is no longer present in the payload
+    // (otherwise an old secret would survive indefinitely and be re-injected on load).
+    for (const k of secret) {
+        if (!(k in configs))
+            state.delete(id, SECRET_PREFIX + k);
+    }
+    state.set(id, PLAIN_KEY, JSON.stringify(plain));
+}
+export function loadConfigs(state, id, schema) {
+    const raw = state.get(id, PLAIN_KEY);
+    const plain = raw ? JSON.parse(raw) : {};
+    for (const k of sensitiveKeys(schema)) {
+        const v = state.get(id, SECRET_PREFIX + k);
+        if (v != null)
+            plain[k] = v;
+    }
+    return plain;
+}

package/dist/contracts/common.d.ts

@@ -0,0 +1,11 @@
+/** Localized text, e.g. `{ fr: "Clients", en: "Customers" }`. */
+export interface Localized {
+    fr?: string;
+    en?: string;
+    [lang: string]: string | undefined;
+}
+/**
+ * Raw map of configuration values received in lifecycle payloads.
+ * An integration transforms it into typed `Settings` via `parseSettings` (zod).
+ */
+export type RawConfigs = Record<string, unknown>;

package/dist/contracts/common.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/config-schema.d.ts

@@ -0,0 +1,79 @@
+import type { Localized } from './common.js';
+/**
+ * Reference to a remote-data resolver for a dynamic select.
+ * The integration exposes a `remoteData[resource]` resolver; ShopiMind calls
+ * `POST /webhook/remote-data/{resource}` and populates the select with the options.
+ *
+ * A dynamic select is declared via a structured `remote: RemoteRef`; the three
+ * fields `resource`, `label_field` and `value_field` are required.
+ */
+export interface RemoteRef {
+    resource: string;
+    label_field: string;
+    value_field: string;
+    description_field?: string;
+}
+/** Scalar field types of an installation form. */
+export type ConfigFieldType = 'text' | 'password' | 'email' | 'url' | 'number' | 'checkbox' | 'textarea' | 'datetime';
+export type ConfigSelectType = 'select' | 'multiselect';
+export interface ConfigOption {
+    value: string;
+    label?: string | Localized;
+}
+interface ConfigFieldBase {
+    key: string;
+    required?: boolean;
+    label: Localized;
+    help?: Localized;
+    default?: string | number | boolean;
+    /** `integrator` = set by the integrator via the API, hidden from the merchant. */
+    owner?: 'merchant' | 'integrator';
+    /** Sensitive value -> encrypted at rest, never exposed to the front-end or widgets. */
+    sensitive?: boolean;
+    /** The field accepts a ShopiMind variable `{var=...}`. */
+    supports_variables?: boolean;
+}
+/** Scalar field (text, number, checkbox, date, ...). */
+export interface ScalarConfigField extends ConfigFieldBase {
+    type: ConfigFieldType;
+}
+/**
+ * Select / multiselect field. Options are STATIC (`options`) OR dynamic
+ * (`remote: RemoteRef`). There is no other form — in particular, no `remote_data`.
+ */
+export interface SelectConfigField extends ConfigFieldBase {
+    type: ConfigSelectType;
+    options?: ConfigOption[];
+    remote?: RemoteRef;
+}
+export type ConfigField = ScalarConfigField | SelectConfigField;
+/** Action triggered on step completion (e.g. validate the connection). */
+export interface StepAction {
+    action: 'test_connection';
+}
+/** A step of the configuration wizard. */
+export interface ConfigStep {
+    /**
+     * Step identifier. Recommended: makes step validation tracking reliable, as it
+     * relies on `step.key`.
+     */
+    key?: string;
+    label: Localized;
+    description?: Localized;
+    fields: ConfigField[];
+    on_complete?: StepAction;
+}
+export interface ConfigGroup {
+    label?: Localized;
+    fields: ConfigField[];
+}
+/**
+ * Configuration schema of an integration: either a wizard (`steps`), a flat list
+ * (`fields`), or groups (`groups`).
+ */
+export interface ConfigSchema {
+    steps?: ConfigStep[];
+    fields?: ConfigField[];
+    groups?: ConfigGroup[];
+}
+export {};

package/dist/contracts/config-schema.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared contracts.
+ *
+ * Public surface: TYPES only (config, widgets, SDK, lifecycle).
+ * Consumed by `@shopimind/integration-kit-js` and by each integration.
+ */
+export type * from './common.js';
+export type * from './config-schema.js';
+export type * from './widget.js';
+export type * from './sdk.js';
+export type * from './lifecycle.js';

package/dist/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/lifecycle.d.ts

@@ -0,0 +1,59 @@
+import type { RawConfigs } from './common.js';
+/**
+ * Lifecycle events sent by ShopiMind (discriminant `event`, in the past tense),
+ * HMAC-signed.
+ */
+export type LifecycleEvent = 'integration.installed' | 'integration.activated' | 'integration.deactivated' | 'integration.uninstalled' | 'integration.config_updated';
+export interface LifecyclePayloadBase {
+    event: LifecycleEvent;
+    id_shop_integration: number;
+    id_shop?: number;
+    integration_slug?: string;
+    shop_domain?: string;
+    shop_name?: string;
+}
+export interface InstallPayload extends LifecyclePayloadBase {
+    event: 'integration.installed';
+    /** The API key (prefix `int...`) — received here, must be persisted: it is not sent again. */
+    access_token?: string;
+    configs?: RawConfigs;
+    installed_at?: string;
+    /** OAuth variant (Type B): no id_shop_integration at install time. */
+    external_account_id?: string;
+    external_account_name?: string;
+}
+export interface ActivatePayload extends LifecyclePayloadBase {
+    event: 'integration.activated';
+    access_token?: string;
+    configs?: RawConfigs;
+    activated_at?: string;
+}
+export interface DeactivatePayload extends LifecyclePayloadBase {
+    event: 'integration.deactivated';
+    deactivated_at?: string;
+}
+export interface UninstallPayload extends LifecyclePayloadBase {
+    event: 'integration.uninstalled';
+    uninstalled_at?: string;
+}
+export interface ConfigUpdatedPayload extends LifecyclePayloadBase {
+    event: 'integration.config_updated';
+    configs?: RawConfigs;
+}
+export type LifecyclePayload = InstallPayload | ActivatePayload | DeactivatePayload | UninstallPayload | ConfigUpdatedPayload;
+/**
+ * Response expected by ShopiMind: MUST contain `success: true`, otherwise the
+ * call is treated as a failure (and, depending on the event, the key may be revoked).
+ */
+export interface WebhookResponse {
+    success: boolean;
+    error?: string;
+    [k: string]: unknown;
+}
+/** Response from a remote-data resolver: populates a select in the config wizard. */
+export interface RemoteDataResponse {
+    data: Array<{
+        value: string;
+        label: string;
+    }>;
+}

package/dist/contracts/lifecycle.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/sdk.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Authoring types specific to the kit (provisioning declarations + shapes the
+ * integration builds). Entity types and the envelope come from the SDK
+ * (`@shopimind/sdk-js`, re-exported by the kit).
+ */
+/** Declaration of a data source to ensure (provisioning). */
+export interface NewDataSource {
+    label: string;
+    type: string;
+    parent_id?: number;
+    config?: string;
+}
+/**
+ * Canonical type of a custom data field, aligned with the ShopiMind API / SDK.
+ *
+ * This union is the kit's OWN AUTHORING allow-list, deliberately kept distinct
+ * from the SDK DTO's field-type type. We restate it here so the author contract
+ * stays stable even if the SDK DTO widens/renames its variants, and so the
+ * compile-time error a user gets points at the kit (their dependency) rather than
+ * leaking the underlying SDK type. Keep the two in sync when a new type lands.
+ */
+export type CustomDataFieldType = 'bool' | 'text' | 'longtext' | 'number' | 'decimal' | 'list' | 'date' | 'datetime' | 'json' | 'geolocation';
+export interface NewCustomDataField {
+    name: string;
+    /** Display label (default: `name`). */
+    label?: string;
+    type: CustomDataFieldType;
+    /** Required field (default: false). */
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+    options?: Array<string | number>;
+}
+export interface NewCustomDataDefinition {
+    /** Technical name (e.g. `pos_profile`). Sent as-is to the API (`name` field). */
+    name: string;
+    description?: string;
+    unique_keys?: string[];
+    fields: NewCustomDataField[];
+    relationships?: Array<{
+        target: string;
+        by: string;
+    }>;
+}
+/** Order status to provision (declaration). */
+export interface SpmOrderStatus {
+    status_id: string;
+    lang: string;
+    name: string;
+    is_deleted: boolean;
+    created_at: string;
+    updated_at: string;
+    id_data_source?: number;
+}
+/**
+ * Declaration of an event type (provisioned on activation).
+ *
+ * Note on `name`: the ShopiMind API accepts an i18n map (`{ en: 'POS sale', fr: 'Vente POS' }`),
+ * so the kit types it as `Record<string, string>`. The SDK's create DTO types
+ * `name` narrowly as `string`, hence the intentional `as unknown` cast at the
+ * single call site (`ensureEvent` in `provisioning/ensure.ts`): the runtime
+ * payload is correct, only the SDK's compile-time type is too tight here.
+ */
+export interface NewEvent {
+    code_name: string;
+    name: Record<string, string>;
+    properties?: Record<string, unknown>;
+}

package/dist/contracts/sdk.js

@@ -0,0 +1,6 @@
+/**
+ * Authoring types specific to the kit (provisioning declarations + shapes the
+ * integration builds). Entity types and the envelope come from the SDK
+ * (`@shopimind/sdk-js`, re-exported by the kit).
+ */
+export {};

package/dist/contracts/widget.d.ts

@@ -0,0 +1,70 @@
+import type { Localized } from './common.js';
+/**
+ * Integration widget declarations.
+ *
+ * Any deviation of an integration from this contract breaks compilation rather
+ * than producing a silently invalid declaration.
+ */
+export type WidgetLocalizedText = Localized;
+export type WidgetTarget = 'email_template' | 'popup' | 'smart_content' | 'stats_dashboard';
+export type WidgetRenderType = 'image' | 'html';
+/** Applicable only to `render_type: html`. */
+export type WidgetRenderMode = 'static' | 'dynamic';
+export type WidgetConfigFieldType = 'text' | 'number' | 'color' | 'select' | 'checkbox' | 'datetime';
+export interface WidgetConfigFieldOption {
+    value: string;
+    label?: string | WidgetLocalizedText;
+}
+export interface WidgetConfigField {
+    key: string;
+    type: WidgetConfigFieldType;
+    default?: string | number | boolean;
+    label?: WidgetLocalizedText;
+    options?: WidgetConfigFieldOption[];
+    /** The field accepts a ShopiMind variable `{var=...}`. */
+    supports_variables?: boolean;
+    /** Text translated per language (html widgets) — resolved via a `{LANG_...}` token. */
+    translatable?: boolean;
+    /** Sample value for the image preview when the field carries a `{var=...}`. */
+    preview_value?: string;
+    /** `type: color` — emits the hex WITHOUT `#` (for image URLs). */
+    strip_hash?: boolean;
+    /** Conditional visibility: show when the sibling field matches one of the values. */
+    visible_when?: {
+        field: string;
+        in: string[];
+    };
+    /** Re-parses the panel when THIS field changes (drives `visible_when`). */
+    refresh_fields?: boolean;
+}
+export interface WidgetConfigGroup {
+    label?: WidgetLocalizedText;
+    fields: WidgetConfigField[];
+}
+export interface WidgetConfigSchema {
+    fields?: WidgetConfigField[];
+    groups?: WidgetConfigGroup[];
+    style_groups?: WidgetConfigGroup[];
+}
+/** A widget declaration exposed by the integration. */
+export interface WidgetDeclaration {
+    key: string;
+    name: WidgetLocalizedText;
+    description?: WidgetLocalizedText;
+    icon_url?: string;
+    preview_image_url?: string;
+    targets: WidgetTarget[];
+    render_type: WidgetRenderType;
+    /** `render_type: html` only (omitted for `image`). */
+    render_mode?: WidgetRenderMode;
+    /** `render_type: image`. */
+    image_url_template?: string;
+    /** `render_type: html` + `render_mode: static`. */
+    html_template?: string;
+    /** `render_type: html` + `render_mode: static` (optional). */
+    css_template?: string;
+    /** `render_type: html` + `render_mode: dynamic` — key of a ShopiMind renderer. */
+    renderer_key?: string;
+    default_width?: number;
+    config_schema?: WidgetConfigSchema;
+}

package/dist/contracts/widget.js

@@ -0,0 +1 @@
+export {};

package/dist/http/routes.d.ts

@@ -0,0 +1,18 @@
+import type { ServerRoute } from '@hapi/hapi';
+import { type DispatcherDeps } from '../lifecycle/dispatcher.js';
+import { type InboundDeps } from '../lifecycle/inbound.js';
+export interface RouteDeps<S> {
+    dispatcher: DispatcherDeps<S>;
+    inbound: InboundDeps<S>;
+    adminToken?: string | null;
+    /** Limiter (per IP) for /admin/* routes -- bounds token brute-forcing + backfill abuse. */
+    adminRateLimit?(key: string): boolean;
+    /**
+     * Limiter (per IP) for POST /webhook/receive -- bounds a flood of unsigned requests
+     * before the (relatively costly) HMAC verification runs. Returns true if allowed.
+     */
+    webhookRateLimit?(key: string): boolean;
+    runSyncForInstall(id: string, full: boolean): Promise<unknown>;
+    recentRuns(id: string): unknown;
+}
+export declare function buildRoutes<S>(deps: RouteDeps<S>): ServerRoute[];