@shopimind/integration-kit-js 1.3.0 → 1.4.0

package/README.md

@@ -62,7 +62,7 @@ export const integration = defineIntegration({
       cursorScope: 'global',
       enabled: (s) => s.syncCustomers,
       run: async (ctx) => {
-        // ctx.spm.* (ShopiMind API), ctx.paginate(...), ctx.state, ctx.logger...
+        // ctx.sendBulk(fn, items) — safe push · ctx.spm + SDK statics · ctx.paginate(...) · ctx.state · ctx.logger
         return { items: 0, errors: [] };
       },
     },

package/dist/contracts/lifecycle.d.ts

@@ -4,10 +4,40 @@ import type { RawConfigs } from './common.js';
  * HMAC-signed.
  */
 export type LifecycleEvent = 'integration.installed' | 'integration.activated' | 'integration.deactivated' | 'integration.uninstalled' | 'integration.config_updated';
+/**
+ * Common fields of a lifecycle webhook payload.
+ *
+ * IDENTITY CONTRACT — `installation_id` is the SINGLE source of truth. It is the
+ * OPAQUE token ShopiMind issues per installation; the integration never
+ * interprets it, it only correlates by it (see the store schema). NestJS sends
+ * `{ event, installation_id, ... }` — nothing else is required to route the event.
+ *
+ * The `id_shop_integration` numeric alias is LEGACY: it predates the opaque token
+ * and is kept ONLY so an older ShopiMind deployment (or an old fixture) that still
+ * emits it keeps working. The dispatcher reads `installation_id` FIRST and falls
+ * back to `id_shop_integration` only when the opaque token is absent. New payloads
+ * must not rely on it.
+ */
 export interface LifecyclePayloadBase {
     event: LifecycleEvent;
-    id_shop_integration: number;
+    /** OPAQUE installation token — the required identity of the installation. */
+    installation_id: string;
+    /**
+     * @deprecated Legacy numeric alias for `installation_id`. Retained for
+     * backward compatibility with older ShopiMind deployments/fixtures; the
+     * dispatcher only uses it as a fallback when `installation_id` is absent.
+     */
+    id_shop_integration?: number;
+    /**
+     * @deprecated ShopiMind-internal shop id. Never sent by the current wire format
+     * and never needed by an integration (which correlates by `installation_id`).
+     * Kept optional so an old payload carrying it does not fail to type-check.
+     */
     id_shop?: number;
+    /**
+     * @deprecated The integration already knows its own slug (`integration.slug`);
+     * ShopiMind does not send this. Kept optional for backward compatibility only.
+     */
     integration_slug?: string;
     shop_domain?: string;
     shop_name?: string;

package/dist/contracts/sdk.d.ts

@@ -9,6 +9,18 @@ export interface NewDataSource {
     type: string;
     parent_id?: number;
     config?: string;
+    /**
+     * STABLE MATCHING KEY (E16). Name of a property inside the source's `config`
+     * (parsed as JSON) that uniquely and PERMANENTLY identifies this source — e.g.
+     * `'hiboutik_store_id'`. When set, `ensureDataSource` matches an existing source by
+     * `config[stableConfigKey]` FIRST, falling back to the `label` only if no config
+     * match is found. This lets a source survive a LABEL RENAME (a merchant renaming
+     * their store no longer spawns a duplicate; the existing source's label is updated
+     * to the new one). Omit it to keep the legacy label-only behaviour unchanged.
+     *
+     * This field is kit-only authoring metadata: it is NOT forwarded to the API.
+     */
+    stableConfigKey?: string;
 }
 /**
  * Canonical type of a custom data field, aligned with the ShopiMind API / SDK.
@@ -53,14 +65,22 @@ export interface NewCustomDataDefinition {
         targetField?: string;
     }>;
 }
-/** Order status to provision (declaration). */
+/**
+ * Order status to provision (declaration).
+ *
+ * `status_id`, `lang` and `name` are the AUTHORING essentials. The technical
+ * bookkeeping fields (`is_deleted`, `created_at`, `updated_at`) are OPTIONAL (E11):
+ * the kit fills sensible defaults at provisioning time (`is_deleted: false`,
+ * timestamps: now), so an author no longer has to hand-write ceremony the API needs
+ * but the integration doesn't care about. Supplying them explicitly still works.
+ */
 export interface SpmOrderStatus {
     status_id: string;
     lang: string;
     name: string;
-    is_deleted: boolean;
-    created_at: string;
-    updated_at: string;
+    is_deleted?: boolean;
+    created_at?: string;
+    updated_at?: string;
     id_data_source?: number;
 }
 /**

package/dist/http/routes.d.ts

@@ -14,5 +14,16 @@ export interface RouteDeps<S> {
     webhookRateLimit?(key: string): boolean;
     runSyncForInstall(id: string, full: boolean): Promise<unknown>;
     recentRuns(id: string): unknown;
+    /** E4 — dead-lettered rejected items for an installation (bounded). */
+    rejectedItems?(id: string, limit: number): unknown;
+    /**
+     * E5 — enriched health snapshot (DB ping, run ages, cursors in error). Routes
+     * only reads `status` (to pick 200 vs 503) and forwards the whole object as JSON.
+     */
+    healthReport?(): {
+        status: 'ok' | 'degraded';
+    };
+    /** E5 — JSON overview across installations (admin). */
+    overview?(): object;
 }
 export declare function buildRoutes<S>(deps: RouteDeps<S>): ServerRoute[];

package/dist/http/routes.js

@@ -1,7 +1,7 @@
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { handleWebhook, handleTestConnection, handleRemoteData, } from '../lifecycle/dispatcher.js';
 import { handleInbound } from '../lifecycle/inbound.js';
-import { verifyShopimindSignature } from '../security/signature.js';
+import { verifyShopimindSignatureMulti } from '../security/signature.js';
 /** Ephemeral (per-process) HMAC key to compare the admin token at fixed length. */
 const ADMIN_CMP_KEY = randomBytes(32);
 /** Constant-time comparison WITHOUT length leakage (compares HMAC digests). */
@@ -28,13 +28,12 @@ const rawBody = (req) => {
         return '';
     return Buffer.isBuffer(p) ? p.toString('utf8') : String(p);
 };
-function sigOptsOf(d) {
-    const o = { secret: d.secret };
-    if (d.toleranceSeconds != null)
-        o.toleranceSeconds = d.toleranceSeconds;
-    if (d.now)
-        o.now = d.now;
-    return o;
+/** Verifies a ShopiMind signature against the dispatcher's secret(s) (E6 rotation-aware). */
+function verifyDispatcherSignature(d, body, headers) {
+    return verifyShopimindSignatureMulti(body, headers, d.secret, {
+        ...(d.toleranceSeconds != null ? { toleranceSeconds: d.toleranceSeconds } : {}),
+        ...(d.now ? { now: d.now } : {}),
+    }).ok;
 }
 function parseConfigs(body) {
     try {
@@ -80,8 +79,7 @@ export function buildRoutes(deps) {
             options: { payload: smallPayload },
             handler: async (req, h) => {
                 const body = rawBody(req);
-                const sig = verifyShopimindSignature(body, req.headers, sigOptsOf(deps.dispatcher));
-                if (!sig.ok)
+                if (!verifyDispatcherSignature(deps.dispatcher, body, req.headers))
                     return h.response({ success: false, error: 'unauthorized' }).code(401);
                 return h.response(await handleTestConnection(parseConfigs(body), deps.dispatcher)).code(200);
             },
@@ -92,8 +90,7 @@ export function buildRoutes(deps) {
             options: { payload: smallPayload },
             handler: async (req, h) => {
                 const body = rawBody(req);
-                const sig = verifyShopimindSignature(body, req.headers, sigOptsOf(deps.dispatcher));
-                if (!sig.ok)
+                if (!verifyDispatcherSignature(deps.dispatcher, body, req.headers))
                     return h.response({ success: false, error: 'unauthorized' }).code(401);
                 const resource = String(req.params.resource);
                 return h.response(await handleRemoteData(resource, parseConfigs(body), deps.dispatcher)).code(200);
@@ -112,7 +109,50 @@ export function buildRoutes(deps) {
         {
             method: 'GET',
             path: '/health',
-            handler: (_req, h) => h.response({ status: 'ok' }).code(200),
+            handler: (_req, h) => {
+                // E5 — enriched health: DB ping + last-run age per active installation +
+                // cursors in error. A degraded snapshot returns 503 so an orchestrator's
+                // readiness/liveness probe (Hiboutik F8) can act on it. UNAUTHENTICATED and
+                // deliberately COARSE (no secrets, no per-shop identifiers beyond ids) — it
+                // is a probe endpoint. If no report provider is wired, fall back to the
+                // original always-ok shape (backward compatible).
+                if (!deps.healthReport)
+                    return h.response({ status: 'ok' }).code(200);
+                const report = deps.healthReport();
+                return h.response(report).code(report.status === 'degraded' ? 503 : 200);
+            },
+        },
+        {
+            method: 'GET',
+            path: '/admin/overview',
+            handler: (req, h) => {
+                if (deps.adminRateLimit && !deps.adminRateLimit(clientIp(req)))
+                    return h.response({ success: false, error: 'rate_limited' }).code(429);
+                if (!adminOk(req, deps.adminToken))
+                    return h.response({ success: false, error: 'unauthorized' }).code(401);
+                if (!deps.overview)
+                    return h.response({ success: false, error: 'not_supported' }).code(501);
+                return h.response(deps.overview()).code(200);
+            },
+        },
+        {
+            method: 'GET',
+            path: '/admin/installations/{id}/rejected',
+            handler: (req, h) => {
+                if (deps.adminRateLimit && !deps.adminRateLimit(clientIp(req)))
+                    return h.response({ success: false, error: 'rate_limited' }).code(429);
+                if (!adminOk(req, deps.adminToken))
+                    return h.response({ success: false, error: 'unauthorized' }).code(401);
+                if (!deps.rejectedItems)
+                    return h.response({ success: false, error: 'not_supported' }).code(501);
+                const id = String(req.params.id ?? '');
+                if (!id)
+                    return h.response({ success: false, error: 'invalid_id' }).code(400);
+                // Bounded: default 100, hard cap 500 (the repo clamps again defensively).
+                const rawLimit = Number(req.query?.limit ?? 100);
+                const limit = Number.isFinite(rawLimit) ? Math.max(1, Math.min(rawLimit, 500)) : 100;
+                return h.response({ items: deps.rejectedItems(id, limit) }).code(200);
+            },
         },
         {
             method: 'POST',

package/dist/index.d.ts

@@ -27,11 +27,14 @@ export * from './store/repositories.js';
 export type * from './store/types.js';
 export * from './logging/logger.js';
 export * from './integration/define-integration.js';
+export * from './integration/define-bulk-step.js';
 export type * from './integration/types.js';
 export * from './manifest.js';
 export * from './http/server.js';
 export * from './http/routes.js';
 export * from './runtime/create-app.js';
 export * from './runtime/rate-limiter.js';
+export * from './runtime/health.js';
+export * from './runtime/outbound.js';
 export * from './testing/harness.js';
 export type * from './contracts/index.js';

package/dist/index.js

@@ -38,6 +38,7 @@ export * from './store/repositories.js';
 export * from './logging/logger.js';
 // Integration authoring contract
 export * from './integration/define-integration.js';
+export * from './integration/define-bulk-step.js';
 // Neutral integration manifest (describes the integration in a portable way)
 export * from './manifest.js';
 // HTTP runtime (Hapi server + routes + bootstrap)
@@ -45,5 +46,7 @@ export * from './http/server.js';
 export * from './http/routes.js';
 export * from './runtime/create-app.js';
 export * from './runtime/rate-limiter.js';
+export * from './runtime/health.js';
+export * from './runtime/outbound.js';
 // Test helpers
 export * from './testing/harness.js';

package/dist/integration/define-bulk-step.d.ts

@@ -0,0 +1,41 @@
+import type { SyncStep, SyncStepContext, IntegrationContext } from './types.js';
+import type { BulkResult } from '../sdk/send-bulk.js';
+/**
+ * `defineBulkStep` (E12) — pure sugar over the common "stream a window, map each raw
+ * item to a record, push in batches, advance the cursor to `window.until`" shape that
+ * every catalog/entity sync step repeats. The author supplies only the domain bits:
+ * where to read (`stream`), how to shape (`map`), and how to push (`push`). The kit
+ * handles the batching, the try/catch (an error is collected, the cursor holds), the
+ * item count, and — by default — `advanceCursorTo = window.until` on a clean run.
+ *
+ * It produces a plain {@link SyncStep}, so it composes with everything else (the
+ * engine's cursor rules, reject holding, backoff, dead-letter…) unchanged. Authors
+ * who need finer control keep writing steps by hand.
+ */
+export interface BulkStepConfig<S, Raw, Rec> {
+    entity: string;
+    /** Cursor scope. Defaults to `'global'` (E12). */
+    cursorScope?: 'global' | 'per-source';
+    /** Whether the step runs for the given settings. Defaults to `() => true` (E12). */
+    enabled?: (settings: S) => boolean;
+    /** Required for `cursorScope: 'per-source'` — the source keys to iterate. */
+    sources?: (ctx: IntegrationContext<S>) => Promise<string[]> | string[];
+    /** See {@link SyncStep.tolerateRejects}. Forwarded as-is. */
+    tolerateRejects?: boolean | {
+        maxRatio: number;
+    };
+    /** Batch size before a flush. Default 500. */
+    batchSize?: number;
+    /** Streams the raw items for the step's window (async iterable / generator). */
+    stream: (ctx: SyncStepContext<S>) => AsyncIterable<Raw>;
+    /** Maps a raw item to a record to push. Return `null`/`undefined` to skip it. */
+    map: (raw: Raw, ctx: SyncStepContext<S>) => Rec | null | undefined;
+    /** Pushes a batch of records (typically `ctx.sendBulk(...)` or `ctx.withSource(k).send(...)`). */
+    push: (ctx: SyncStepContext<S>, records: Rec[]) => Promise<BulkResult | unknown>;
+    /**
+     * Overrides the cursor bound on a clean run. Defaults to `ctx.window.until`
+     * (the standard windowed advance). Return `null` to NOT advance (a pure fan-out).
+     */
+    advanceTo?: (ctx: SyncStepContext<S>) => Date | null;
+}
+export declare function defineBulkStep<S, Raw, Rec>(config: BulkStepConfig<S, Raw, Rec>): SyncStep<S>;

package/dist/integration/define-bulk-step.js

@@ -0,0 +1,44 @@
+export function defineBulkStep(config) {
+    const batchSize = Math.max(1, config.batchSize ?? 500);
+    const step = {
+        entity: config.entity,
+        cursorScope: config.cursorScope ?? 'global',
+        enabled: config.enabled ?? (() => true),
+        ...(config.sources ? { sources: config.sources } : {}),
+        ...(config.tolerateRejects !== undefined ? { tolerateRejects: config.tolerateRejects } : {}),
+        run: async (ctx) => {
+            const errors = [];
+            let items = 0;
+            let batch = [];
+            const flush = async () => {
+                if (batch.length === 0)
+                    return;
+                const toSend = batch;
+                batch = [];
+                await config.push(ctx, toSend);
+                items += toSend.length;
+            };
+            try {
+                for await (const raw of config.stream(ctx)) {
+                    const rec = config.map(raw, ctx);
+                    if (rec == null)
+                        continue;
+                    batch.push(rec);
+                    if (batch.length >= batchSize)
+                        await flush();
+                }
+                await flush();
+            }
+            catch (e) {
+                // Collected, not thrown: the engine holds the cursor (window replays). Rejections
+                // reported by `push` still feed the engine's reject sink independently.
+                errors.push(`bulk step '${config.entity}': ${e instanceof Error ? e.message : String(e)}`);
+                return { items, errors };
+            }
+            // Clean run: advance to window.until by default (E12), unless overridden/null.
+            const advanceTo = config.advanceTo ? config.advanceTo(ctx) : ctx.window.until;
+            return advanceTo == null ? { items, errors } : { items, errors, advanceCursorTo: advanceTo };
+        },
+    };
+    return step;
+}

package/dist/integration/define-integration.d.ts

@@ -14,3 +14,26 @@ export declare function validateIntegration<S>(c: Integration<S>): void;
 export declare function validateProvisioningEvents(events: ReadonlyArray<{
     code_name?: string;
 }>): void;
+/** Minimal shape a custom-data definition must satisfy for the E10 guards. */
+interface GuardableDefinition {
+    name: string;
+    fields: Array<{
+        name: string;
+    }>;
+    unique_keys?: string[];
+    relationships?: Array<{
+        sourceField: string;
+    }>;
+}
+/**
+ * Structural guards for a custom-data definition (E10). A definition whose
+ * `unique_keys` or `relationships.sourceField` reference a field it does not
+ * declare is a MISCONFIGURATION that the API would reject opaquely at provisioning
+ * time (or, worse, accept and misbehave). Catch it early with a precise message.
+ *
+ * Called by the provisioning runner once the (async) plan is materialized — the
+ * plan is not reachable from the boot-time `validateIntegration`. Kept lenient in
+ * shape (only the checked fields are required) so the runner can pass its own DTO.
+ */
+export declare function validateCustomDataDefinition(def: GuardableDefinition): void;
+export {};

package/dist/integration/define-integration.js

@@ -48,3 +48,26 @@ export function validateProvisioningEvents(events) {
         }
     }
 }
+/**
+ * Structural guards for a custom-data definition (E10). A definition whose
+ * `unique_keys` or `relationships.sourceField` reference a field it does not
+ * declare is a MISCONFIGURATION that the API would reject opaquely at provisioning
+ * time (or, worse, accept and misbehave). Catch it early with a precise message.
+ *
+ * Called by the provisioning runner once the (async) plan is materialized — the
+ * plan is not reachable from the boot-time `validateIntegration`. Kept lenient in
+ * shape (only the checked fields are required) so the runner can pass its own DTO.
+ */
+export function validateCustomDataDefinition(def) {
+    const fieldNames = new Set(def.fields.map((f) => f.name));
+    for (const key of def.unique_keys ?? []) {
+        if (!fieldNames.has(key)) {
+            throw new Error(`custom data '${def.name}': unique_keys contains '${key}' which is not a declared field`);
+        }
+    }
+    for (const rel of def.relationships ?? []) {
+        if (!fieldNames.has(rel.sourceField)) {
+            throw new Error(`custom data '${def.name}': relationship sourceField '${rel.sourceField}' is not a declared field`);
+        }
+    }
+}

package/dist/integration/types.d.ts

@@ -103,8 +103,16 @@ export interface SyncStep<S> {
      * stream where a PERMANENT rejection (a malformed item the API always rejects)
      * would otherwise freeze the window forever ("poison pill"). Even when `true`,
      * rejections are still surfaced (logged + counted); only the cursor may advance.
+     *
+     * `{ maxRatio }` (E8) is a middle ground: tolerate rejections (advance the cursor)
+     * ONLY while the reject ratio over the window stays at or below `maxRatio`
+     * (rejected / attempted, 0..1). Above it, revert to the strict behaviour and HOLD
+     * the cursor — a guard-rail so a suddenly-bad batch is not waved through blindly.
+     * `true` is equivalent to `{ maxRatio: 1 }`; `false`/omitted keeps the strict hold.
      */
-    tolerateRejects?: boolean;
+    tolerateRejects?: boolean | {
+        maxRatio: number;
+    };
     enabled(settings: S): boolean;
     /** For 'per-source': the source keys to iterate over (e.g. store ids). */
     sources?(ctx: IntegrationContext<S>): Promise<string[]> | string[];

package/dist/lifecycle/dispatcher.d.ts

@@ -9,7 +9,12 @@ export declare const PROVISIONING_KEY = "__provisioning";
 export interface DispatcherDeps<S> {
     integration: Integration<S>;
     repos: Repositories;
-    secret: string;
+    /**
+     * Webhook signing secret(s). A single string is the common case; an array opens a
+     * rotation window (E6) where a request signed with ANY listed secret passes —
+     * used while swapping `current` -> `next`. Backward compatible with a plain string.
+     */
+    secret: string | string[];
     toleranceSeconds?: number;
     logger: Logger;
     /** Builds the ShopiMind SDK client for an access_token. */

package/dist/lifecycle/dispatcher.js

@@ -1,5 +1,5 @@
 import { SpmClient } from '@shopimind/sdk-js';
-import { verifyShopimindSignature } from '../security/signature.js';
+import { verifyShopimindSignatureMulti } from '../security/signature.js';
 import { redact } from '../security/redaction.js';
 import { saveConfigs, loadConfigs, sensitiveKeys } from '../config/config-store.js';
 import { runProvisioning } from '../provisioning/runner.js';
@@ -30,12 +30,11 @@ const EVENT_TO_HANDLER = {
  * body, logs a REDACTED payload (secrets never reach the log), then dispatches.
  */
 export async function handleWebhook(rawBody, headers, deps) {
-    const sigOpts = { secret: deps.secret };
-    if (deps.toleranceSeconds != null)
-        sigOpts.toleranceSeconds = deps.toleranceSeconds;
-    if (deps.now)
-        sigOpts.now = deps.now;
-    const sig = verifyShopimindSignature(rawBody, headers, sigOpts);
+    // E6 — verify against one or several secrets (rotation window).
+    const sig = verifyShopimindSignatureMulti(rawBody, headers, deps.secret, {
+        ...(deps.toleranceSeconds != null ? { toleranceSeconds: deps.toleranceSeconds } : {}),
+        ...(deps.now ? { now: deps.now } : {}),
+    });
     let payload;
     try {
         payload = rawBody ? JSON.parse(rawBody) : {};
@@ -143,7 +142,7 @@ async function onActivate(p, deps) {
     }
     if (deps.integration.provisioning) {
         const plan = await deps.integration.provisioning(ctx);
-        const prov = await runProvisioning(ctx.spm, plan);
+        const prov = await runProvisioning(ctx.spm, plan, ctx.logger);
         deps.repos.state.set(id, PROVISIONING_KEY, JSON.stringify({ sourceIds: prov.sourceIds, defIds: prov.defIds }));
         if (prov.errors.length > 0) {
             // Count ALL successful resources (sources, defs, events, statuses) — not
@@ -198,7 +197,7 @@ async function onConfigUpdated(p, deps) {
         const ctx = buildContext(id, deps);
         if (deps.integration.provisioning) {
             const plan = await deps.integration.provisioning(ctx);
-            const prov = await runProvisioning(ctx.spm, plan);
+            const prov = await runProvisioning(ctx.spm, plan, ctx.logger);
             deps.repos.state.set(id, PROVISIONING_KEY, JSON.stringify({ sourceIds: prov.sourceIds, defIds: prov.defIds }));
         }
         if (deps.integration.hooks?.onConfigUpdated)

package/dist/provisioning/ensure.d.ts

@@ -1,12 +1,18 @@
 import { type SpmHttpClient } from '@shopimind/sdk-js';
 import type { NewDataSource, NewCustomDataDefinition, NewEvent } from '../contracts/index.js';
 /**
- * Finds a data source by `label`, otherwise creates it. Returns its id.
+ * Finds a data source, otherwise creates it. Returns its id.
  *
- * Invariant: `label` is expected to be UNIQUE across an account's data sources;
- * the find-or-create matches on it as a natural key. The comparison is trimmed
- * on both sides so trailing/leading whitespace differences do not spawn a
- * duplicate source.
+ * Matching (E16):
+ *  - if `input.stableConfigKey` is set, match FIRST on `config[stableConfigKey]`
+ *    (a permanent identifier, e.g. the store id) — a source found this way but with
+ *    a DIFFERENT label has its label UPDATED to the new one (a rename no longer
+ *    spawns a duplicate);
+ *  - otherwise (or if no config match), fall back to matching by `label` as a
+ *    natural key (the legacy behaviour, unchanged when `stableConfigKey` is absent).
+ *
+ * Comparisons are trimmed on both sides so incidental whitespace does not spawn a
+ * duplicate source. `stableConfigKey` is kit-only metadata — never sent to the API.
  */
 export declare function ensureDataSource(client: SpmHttpClient, input: NewDataSource): Promise<number>;
 /**

package/dist/provisioning/ensure.js

@@ -38,21 +38,57 @@ function toSdkDef(def) {
 function normKey(v) {
     return typeof v === 'string' ? v.trim() : v == null ? '' : String(v).trim();
 }
+/** Extracts a property from a source's `config` (a JSON string), tolerating malformed JSON. */
+function configValue(config, key) {
+    if (typeof config !== 'string' || config === '')
+        return undefined;
+    try {
+        const parsed = JSON.parse(config);
+        const v = parsed?.[key];
+        return v == null ? undefined : normKey(v);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
- * Finds a data source by `label`, otherwise creates it. Returns its id.
+ * Finds a data source, otherwise creates it. Returns its id.
  *
- * Invariant: `label` is expected to be UNIQUE across an account's data sources;
- * the find-or-create matches on it as a natural key. The comparison is trimmed
- * on both sides so trailing/leading whitespace differences do not spawn a
- * duplicate source.
+ * Matching (E16):
+ *  - if `input.stableConfigKey` is set, match FIRST on `config[stableConfigKey]`
+ *    (a permanent identifier, e.g. the store id) — a source found this way but with
+ *    a DIFFERENT label has its label UPDATED to the new one (a rename no longer
+ *    spawns a duplicate);
+ *  - otherwise (or if no config match), fall back to matching by `label` as a
+ *    natural key (the legacy behaviour, unchanged when `stableConfigKey` is absent).
+ *
+ * Comparisons are trimmed on both sides so incidental whitespace does not spawn a
+ * duplicate source. `stableConfigKey` is kit-only metadata — never sent to the API.
  */
 export async function ensureDataSource(client, input) {
-    const existing = SpmHelpers.unwrapOrThrow(await SpmDataSources.list(client), 'listDataSources');
+    const existing = SpmHelpers.unwrapOrThrow(await SpmDataSources.list(client), 'listDataSources') ?? [];
     const wantedLabel = normKey(input.label);
-    const found = (existing ?? []).find((s) => normKey(s.label) === wantedLabel);
+    // E16 — stable-key match first (survives a label rename).
+    if (input.stableConfigKey) {
+        const wantedKeyValue = configValue(input.config, input.stableConfigKey);
+        if (wantedKeyValue !== undefined) {
+            const byKey = existing.find((s) => configValue(s.config, input.stableConfigKey) === wantedKeyValue);
+            if (byKey) {
+                const id = numId(byKey, 'id_data_source', 'id');
+                // Label drifted (merchant renamed the store) -> update it, do NOT duplicate.
+                if (normKey(byKey.label) !== wantedLabel) {
+                    await SpmDataSources.update(client, id, { label: input.label });
+                }
+                return id;
+            }
+        }
+    }
+    const found = existing.find((s) => normKey(s.label) === wantedLabel);
     if (found)
         return numId(found, 'id_data_source', 'id');
-    const created = SpmHelpers.unwrapOrThrow(await SpmDataSources.create(client, input), 'createDataSource');
+    // `stableConfigKey` is authoring-only metadata: strip it from the create DTO.
+    const { stableConfigKey: _drop, ...createDto } = input;
+    const created = SpmHelpers.unwrapOrThrow(await SpmDataSources.create(client, createDto), 'createDataSource');
     return numId(created, 'id_data_source', 'id');
 }
 /**

package/dist/provisioning/runner.d.ts

@@ -1,5 +1,7 @@
 import { type SpmHttpClient } from '@shopimind/sdk-js';
 import type { ProvisioningPlan } from '../integration/types.js';
+import type { NewCustomDataDefinition } from '../contracts/index.js';
+import type { Logger } from '../logging/logger.js';
 /**
  * Runs a `ProvisioningPlan` (idempotent find-or-create). Best-effort per
  * resource: an error is collected without interrupting the others. Returns the
@@ -13,4 +15,12 @@ export interface ProvisioningResult {
     orderStatuses: number;
     errors: string[];
 }
-export declare function runProvisioning(client: SpmHttpClient, plan: ProvisioningPlan): Promise<ProvisioningResult>;
+export declare function runProvisioning(client: SpmHttpClient, plan: ProvisioningPlan, logger?: Logger): Promise<ProvisioningResult>;
+/**
+ * Topologically sorts the custom-data plan so a definition is always emitted AFTER
+ * the sibling definitions it references via custom→custom relationships (E10). Only
+ * intra-plan custom targets create an edge; system targets and out-of-plan/numeric
+ * targets do not. Throws on a dependency cycle (unresolvable ordering). Definitions
+ * without in-plan dependencies keep their declaration order (stable).
+ */
+export declare function topoSortCustomData(defs: NewCustomDataDefinition[]): NewCustomDataDefinition[];