@shopimind/integration-kit-js 1.0.0

package/dist/provisioning/ensure.js

@@ -0,0 +1,104 @@
+import { SpmDataSources, SpmCustomDataDefinitions, SpmEvents, SpmHelpers, } from '@shopimind/sdk-js';
+/**
+ * Idempotent find-or-create for ShopiMind resources, calling the SDK directly
+ * (`unwrapOrThrow` unwraps the envelope / throws `SpmApiError` on failure). An
+ * integration only declares the shapes.
+ */
+/** Reads an id, tolerating either field name the API may return. */
+function numId(o, ...keys) {
+    for (const k of keys) {
+        if (o[k] != null)
+            return Number(o[k]);
+    }
+    return 0;
+}
+/** Maps a kit field to an SDK/API field (label defaults to name, required defaults to false). */
+function toSdkField(f) {
+    return {
+        name: f.name,
+        label: f.label ?? f.name,
+        type: f.type,
+        required: f.required ?? false,
+        ...(f.description !== undefined ? { description: f.description } : {}),
+        ...(f.default !== undefined ? { default: f.default } : {}),
+        ...(f.options !== undefined ? { options: f.options } : {}),
+    };
+}
+/** Maps a kit definition to an SDK/API DTO. */
+function toSdkDef(def) {
+    return {
+        name: def.name,
+        ...(def.description !== undefined ? { description: def.description } : {}),
+        ...(def.unique_keys !== undefined ? { unique_keys: def.unique_keys } : {}),
+        fields: def.fields.map(toSdkField),
+        ...(def.relationships !== undefined ? { relationships: def.relationships } : {}),
+    };
+}
+/** Normalizes a natural key for comparison (trim; nullish -> empty string). */
+function normKey(v) {
+    return typeof v === 'string' ? v.trim() : v == null ? '' : String(v).trim();
+}
+/**
+ * Finds a data source by `label`, 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.
+ */
+export async function ensureDataSource(client, input) {
+    const existing = SpmHelpers.unwrapOrThrow(await SpmDataSources.list(client), 'listDataSources');
+    const wantedLabel = normKey(input.label);
+    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');
+    return numId(created, 'id_data_source', 'id');
+}
+/**
+ * Finds a custom-data definition by its natural key (`name`, falling back to the
+ * API's `schema_name`), otherwise creates and activates it. Convergent
+ * provisioning: if the integration has evolved, the existing definition is
+ * extended (only the missing fields are sent) instead of being left untouched.
+ *
+ * Invariant: a definition's `name` (alias `schema_name`) is expected to be UNIQUE
+ * across an account; it is matched as a natural key. The comparison is trimmed on
+ * both sides so incidental whitespace differences do not spawn a duplicate.
+ */
+export async function ensureCustomDataDefinition(client, def) {
+    const existing = SpmHelpers.unwrapOrThrow(await SpmCustomDataDefinitions.list(client), 'listCustomDataDefinitions');
+    const wantedName = normKey(def.name);
+    const found = (existing ?? []).find((d) => normKey(d.name ?? d.schema_name) === wantedName);
+    if (found) {
+        const id = numId(found, 'id_definition', 'id');
+        const full = SpmHelpers.unwrapOrThrow(await SpmCustomDataDefinitions.get(client, id), 'getCustomDataDefinition');
+        const fields = Array.isArray(full.fields) ? full.fields : [];
+        const have = new Set(fields.map((f) => f.name).filter((n) => !!n));
+        const missing = def.fields.filter((f) => !have.has(f.name));
+        if (missing.length > 0) {
+            SpmHelpers.unwrapOrThrow(await SpmCustomDataDefinitions.extend(client, id, {
+                fields: missing.map(toSdkField),
+            }), 'extendCustomDataDefinition');
+        }
+        return id;
+    }
+    const created = SpmHelpers.unwrapOrThrow(await SpmCustomDataDefinitions.create(client, toSdkDef(def)), 'createCustomDataDefinition');
+    const id = numId(created, 'id_definition', 'id');
+    // Activation is best-effort and idempotent: a 409 means "already active", which
+    // is the desired end state, so we tolerate it. Any OTHER non-ok envelope is a
+    // genuine surprise (e.g. 5xx, permission) — we surface it as a warning rather
+    // than throwing, so a freshly created (but not yet activated) definition does
+    // not abort the whole provisioning run, but the operator still gets a signal.
+    const activated = await SpmCustomDataDefinitions.activate(client, id);
+    if (!activated.ok && activated.statusCode !== 409) {
+        console.warn(`ensureCustomDataDefinition: activate(${id}) returned status ${activated.statusCode}; definition created but not confirmed active`);
+    }
+    return id;
+}
+/** Creates an event type, tolerating a 409 "already exists" (idempotent). */
+export async function ensureEvent(client, event) {
+    const res = await SpmEvents.create(client, event);
+    if (res.ok || res.statusCode === 409)
+        return;
+    SpmHelpers.unwrapOrThrow(res, 'createEvent'); // throws SpmApiError for any other error
+}

package/dist/provisioning/runner.d.ts

@@ -0,0 +1,16 @@
+import { type SpmHttpClient } from '@shopimind/sdk-js';
+import type { ProvisioningPlan } from '../integration/types.js';
+/**
+ * Runs a `ProvisioningPlan` (idempotent find-or-create). Best-effort per
+ * resource: an error is collected without interrupting the others. Returns the
+ * resolved ids (sources by `key`, definitions by `name`) that the integration
+ * then reuses during sync.
+ */
+export interface ProvisioningResult {
+    sourceIds: Record<string, number>;
+    defIds: Record<string, number>;
+    events: number;
+    orderStatuses: number;
+    errors: string[];
+}
+export declare function runProvisioning(client: SpmHttpClient, plan: ProvisioningPlan): Promise<ProvisioningResult>;

package/dist/provisioning/runner.js

@@ -0,0 +1,49 @@
+import { SpmOrdersStatuses, SpmHelpers } from '@shopimind/sdk-js';
+import { validateProvisioningEvents } from '../integration/define-integration.js';
+import { ensureDataSource, ensureCustomDataDefinition, ensureEvent } from './ensure.js';
+export async function runProvisioning(client, plan) {
+    const result = { sourceIds: {}, defIds: {}, events: 0, orderStatuses: 0, errors: [] };
+    for (const ds of plan.dataSources ?? []) {
+        try {
+            const parentId = ds.parentKey ? result.sourceIds[ds.parentKey] : undefined;
+            const decl = parentId != null ? { ...ds.decl, parent_id: parentId } : ds.decl;
+            result.sourceIds[ds.key] = await ensureDataSource(client, decl);
+        }
+        catch (e) {
+            result.errors.push(`source ${ds.key}: ${errMsg(e)}`);
+        }
+    }
+    for (const def of plan.customData ?? []) {
+        try {
+            result.defIds[def.name] = await ensureCustomDataDefinition(client, def);
+        }
+        catch (e) {
+            result.errors.push(`def ${def.name}: ${errMsg(e)}`);
+        }
+    }
+    for (const ev of plan.events ?? []) {
+        try {
+            // Contract guard: reject a malformed event (missing code_name) before the
+            // network call. Collected per-resource (best-effort), like other errors.
+            validateProvisioningEvents([ev]);
+            await ensureEvent(client, ev);
+            result.events += 1;
+        }
+        catch (e) {
+            result.errors.push(`event ${ev.code_name}: ${errMsg(e)}`);
+        }
+    }
+    if (plan.orderStatuses && plan.orderStatuses.length > 0) {
+        try {
+            const env = await SpmOrdersStatuses.bulkSave(client, plan.orderStatuses, { chunk: true });
+            result.orderStatuses = SpmHelpers.extractCounts(env).sent;
+        }
+        catch (e) {
+            result.errors.push(`order statuses: ${errMsg(e)}`);
+        }
+    }
+    return result;
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/runtime/create-app.d.ts

@@ -0,0 +1,66 @@
+import type { Server } from '@hapi/hapi';
+import { type SpmHttpClient } from '@shopimind/sdk-js';
+import type { Integration } from '../integration/types.js';
+import { type Db } from '../store/db.js';
+import { type Repositories } from '../store/repositories.js';
+import { type Logger } from '../logging/logger.js';
+import { type SyncSummary } from '../sync/engine.js';
+export interface CreateAppOptions<S> {
+    databasePath: string;
+    webhookSecret: string;
+    /**
+     * Override for the ShopiMind SDK base URL (otherwise env `SHOPIMIND_CORE_API_BASE`,
+     * then `https://core.shopimind.com`). Useful in tests / preprod.
+     */
+    spmBaseUrl?: string;
+    /**
+     * Override for SDK client construction. Lets a caller inject a client instance
+     * instead of the kit building one via `SpmClient.getClient`.
+     */
+    makeSpmClient?: (accessToken: string) => SpmHttpClient;
+    credentialsKey?: string | null;
+    /**
+     * EXPLICITLY allows storing secrets IN PLAINTEXT when no `credentialsKey` is
+     * provided (LOCAL DEVELOPMENT ONLY). Defaults to `false` -> without a key,
+     * startup fails. A loud WARN is emitted when enabled.
+     */
+    allowPlaintextSecrets?: boolean;
+    adminToken?: string | null;
+    signatureToleranceSeconds?: number;
+    backfillDays?: number;
+    port?: number;
+    host?: string;
+    logger?: Logger;
+    /** Runs a full backfill automatically on activation (default true). */
+    autoBackfillOnActivate?: boolean;
+    /** Enables the internal incremental sync scheduler (default true). */
+    autoSync?: boolean;
+    /**
+     * Interval (in MINUTES) between two automatic incremental syncs of each active
+     * installation. Default 15. A value <= 0 disables the scheduler.
+     */
+    syncIntervalMinutes?: number;
+    /**
+     * Retention (in DAYS) for the webhook log and the anti-replay / inbound-event
+     * tables. A daily purge deletes rows older than this. Default 90. A value <= 0
+     * disables the purge (tables then grow unbounded).
+     */
+    retentionDays?: number;
+    now?: () => number;
+}
+export interface IntegrationApp {
+    server: Server;
+    db: Db;
+    repos: Repositories;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    runSyncOnce(installationId: string, opts?: {
+        full?: boolean;
+    }): Promise<SyncSummary | null>;
+}
+/**
+ * Assembles a ready-to-run integration: store + crypto + repositories + logger +
+ * dispatcher + sync engine + HTTP server + internal scheduler. The kit builds the
+ * SDK client itself (direct dependency on `@shopimind/sdk-js`).
+ */
+export declare function createIntegrationApp<S>(integration: Integration<S>, opts: CreateAppOptions<S>): IntegrationApp;

package/dist/runtime/create-app.js

@@ -0,0 +1,211 @@
+import { SpmClient } from '@shopimind/sdk-js';
+import { openDatabase } from '../store/db.js';
+import { createRepositories } from '../store/repositories.js';
+import { SecretCipher } from '../security/crypto.js';
+import { createLogger } from '../logging/logger.js';
+import { loadConfigs } from '../config/config-store.js';
+import { runIntegrationSync } from '../sync/engine.js';
+import { ACCESS_TOKEN_KEY, PROVISIONING_KEY } from '../lifecycle/dispatcher.js';
+import { ensureInboundSecret } from '../lifecycle/inbound.js';
+import { makeWithSource } from '../sdk/source-scope.js';
+import { makeSendBulk } from '../sdk/send-bulk.js';
+import { createRateLimiter } from './rate-limiter.js';
+import { createServer } from '../http/server.js';
+import { buildRoutes } from '../http/routes.js';
+/**
+ * Assembles a ready-to-run integration: store + crypto + repositories + logger +
+ * dispatcher + sync engine + HTTP server + internal scheduler. The kit builds the
+ * SDK client itself (direct dependency on `@shopimind/sdk-js`).
+ */
+export function createIntegrationApp(integration, opts) {
+    const db = openDatabase(opts.databasePath);
+    // Fail-closed by default: without a key, encryption at rest is MANDATORY
+    // (the constructor throws), unless explicitly opted out via `allowPlaintextSecrets`.
+    const allowPlaintext = opts.allowPlaintextSecrets ?? false;
+    const cipher = new SecretCipher({ key: opts.credentialsKey ?? null, production: !allowPlaintext });
+    const repos = createRepositories(db, cipher);
+    const logger = opts.logger ?? createLogger({ bindings: { integration: integration.slug } });
+    if (cipher.insecure) {
+        logger.warn('SECRETS STORED IN PLAINTEXT: no CREDENTIALS_KEY (allowPlaintextSecrets enabled). ' +
+            'For local development only -- NEVER use in preprod/production.');
+    }
+    const backfillDays = opts.backfillDays ?? 365;
+    // The kit builds the SDK client itself; an `opts.makeSpmClient` override lets a
+    // caller inject a client instance instead.
+    const makeSpmClient = opts.makeSpmClient ??
+        ((token) => SpmClient.getClient('v1', token, { labelSource: null, ...(opts.spmBaseUrl ? { baseUrl: opts.spmBaseUrl } : {}) }));
+    const buildContext = (id) => {
+        const token = repos.state.get(id, ACCESS_TOKEN_KEY);
+        if (!token)
+            return null;
+        const configs = loadConfigs(repos.state, id, integration.configSchema);
+        const spm = makeSpmClient(token);
+        const ctxLogger = logger.child({ installation_id: id });
+        const sendBulk = makeSendBulk(spm, ctxLogger);
+        return {
+            installationId: id,
+            settings: integration.parseSettings(configs),
+            spm,
+            sendBulk,
+            state: repos.state,
+            logger: ctxLogger,
+            setExternalAccount: (acc) => repos.installs.setExternalAccount(id, acc.id, acc.name ?? null),
+            inboundSecret: ensureInboundSecret(repos.state, id),
+            withSource: makeWithSource(repos.state, id, PROVISIONING_KEY, sendBulk),
+        };
+    };
+    // Per-installation overlap lock: prevents a post-activation backfill, a scheduled
+    // sync, and an admin call from running at the same time on the same installation
+    // (race on the cursors).
+    const running = new Set();
+    const runSyncOnce = async (id, o) => {
+        if (running.has(id)) {
+            logger.warn('sync skipped: already running for this installation', { installation_id: id });
+            return null;
+        }
+        const base = buildContext(id);
+        if (!base) {
+            logger.warn('sync skipped: no context (unknown installation or no token)', { installation_id: id });
+            return null;
+        }
+        running.add(id);
+        try {
+            return await runIntegrationSync(integration, base, {
+                cursors: repos.cursors,
+                runs: repos.runs,
+                makeSource: (sb) => makeWithSource(repos.state, id, PROVISIONING_KEY, sb),
+            }, { fullBackfill: o?.full ?? false, backfillDays });
+        }
+        finally {
+            running.delete(id);
+        }
+    };
+    const autoBackfill = opts.autoBackfillOnActivate ?? true;
+    const dispatcher = {
+        integration,
+        repos,
+        secret: opts.webhookSecret,
+        logger,
+        makeSpmClient,
+        ...(opts.signatureToleranceSeconds != null ? { toleranceSeconds: opts.signatureToleranceSeconds } : {}),
+        ...(opts.now ? { now: opts.now } : {}),
+        ...(autoBackfill
+            ? {
+                afterActivate: (id) => {
+                    setImmediate(() => {
+                        void runSyncOnce(id, { full: true }).catch((e) => logger.error('post-activation backfill failed', { installation_id: id, error: String(e) }));
+                    });
+                },
+            }
+            : {}),
+    };
+    const inboundRateLimit = createRateLimiter(opts.now ? { now: opts.now } : {});
+    // Dedicated limiter for /admin/* routes (per IP): bounds token brute-forcing and
+    // backfill abuse -- stricter than the inbound limiter.
+    const adminRateLimit = createRateLimiter({ capacity: 10, refillPerSec: 1, ...(opts.now ? { now: opts.now } : {}) });
+    // Per-IP limiter for POST /webhook/receive: bounds a flood of unsigned/forged
+    // requests before the (costly) HMAC verification runs.
+    const webhookRateLimit = createRateLimiter(opts.now ? { now: opts.now } : {});
+    const server = createServer({ port: opts.port ?? 8080, ...(opts.host ? { host: opts.host } : {}) });
+    server.route(buildRoutes({
+        dispatcher,
+        adminToken: opts.adminToken ?? null,
+        adminRateLimit,
+        webhookRateLimit,
+        runSyncForInstall: (id, full) => runSyncOnce(id, { full }),
+        recentRuns: (id) => repos.runs.recent(id),
+        inbound: {
+            integration,
+            repos,
+            logger,
+            buildContext,
+            rateLimit: inboundRateLimit,
+            ...(opts.signatureToleranceSeconds != null ? { toleranceSeconds: opts.signatureToleranceSeconds } : {}),
+            ...(opts.now ? { now: opts.now } : {}),
+        },
+    }));
+    // ---- Internal scheduler (periodic incremental sync) -----------------------
+    const intervalMinutes = opts.syncIntervalMinutes ?? 15;
+    const autoSync = (opts.autoSync ?? true) && intervalMinutes > 0;
+    let timer = null;
+    let sweeping = false;
+    /** One pass: incremental sync of all active installations. */
+    const sweep = async () => {
+        if (sweeping)
+            return; // the previous pass has not finished -> skip this tick
+        sweeping = true;
+        try {
+            for (const inst of repos.installs.listActive()) {
+                try {
+                    await runSyncOnce(inst.installation_id, { full: false });
+                }
+                catch (e) {
+                    logger.error('scheduled sync failed', {
+                        installation_id: inst.installation_id,
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                }
+            }
+        }
+        finally {
+            sweeping = false;
+        }
+    };
+    // ---- Retention: bounded growth of the log / anti-replay tables -------------
+    const retentionDays = opts.retentionDays ?? 90;
+    const retentionEnabled = retentionDays > 0;
+    let retentionTimer = null;
+    const purgeOldRecords = () => {
+        try {
+            const log = repos.webhookLog.purgeOlderThan(retentionDays);
+            const seen = repos.webhookSeen.purgeOlderThan(retentionDays);
+            const inbound = repos.inboundEvents.purgeOlderThan(retentionDays);
+            if (log + seen + inbound > 0) {
+                logger.info('retention purge', { webhook_log: log, webhook_seen: seen, inbound_event: inbound, retentionDays });
+            }
+        }
+        catch (e) {
+            logger.error('retention purge failed', { error: e instanceof Error ? e.message : String(e) });
+        }
+    };
+    return {
+        server,
+        db,
+        repos,
+        start: async () => {
+            await server.start();
+            logger.info('integration started', { uri: server.info.uri });
+            if (autoSync) {
+                timer = setInterval(() => {
+                    void sweep();
+                }, intervalMinutes * 60_000);
+                timer.unref();
+                logger.info('sync scheduler enabled', { intervalMinutes });
+            }
+            if (retentionEnabled) {
+                purgeOldRecords();
+                retentionTimer = setInterval(() => purgeOldRecords(), 24 * 60 * 60_000);
+                retentionTimer.unref();
+                logger.info('retention enabled', { retentionDays });
+            }
+        },
+        stop: async () => {
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            if (retentionTimer) {
+                clearInterval(retentionTimer);
+                retentionTimer = null;
+            }
+            try {
+                await server.stop();
+            }
+            catch {
+                /* server not started */
+            }
+            db.close();
+        },
+        runSyncOnce,
+    };
+}

package/dist/runtime/rate-limiter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Token-bucket limiter, keyed (e.g. per installation). In-memory -- sufficient for
+ * a single instance. `capacity` max tokens, refilled at `refillPerSec` tokens/second.
+ * Returns a function `(key) => boolean`: true if the call is allowed.
+ *
+ * Eviction: keys are tracked in a Map. To avoid an unbounded memory leak (and a slow
+ * DoS via a flood of distinct keys, e.g. one per spoofed IP), the Map is capped at
+ * `maxKeys` entries. When the cap is reached, fully-refilled (idle) buckets are pruned
+ * first, then -- if still over the cap -- the least-recently-seen buckets are evicted.
+ * Evicting a full bucket is harmless: a re-created bucket also starts at `capacity`.
+ */
+export interface RateLimiterOptions {
+    capacity?: number;
+    refillPerSec?: number;
+    now?: () => number;
+    /** Upper bound on the number of tracked keys before eviction kicks in (default 10000). */
+    maxKeys?: number;
+}
+export declare function createRateLimiter(opts?: RateLimiterOptions): (key: string) => boolean;

package/dist/runtime/rate-limiter.js

@@ -0,0 +1,46 @@
+export function createRateLimiter(opts = {}) {
+    const capacity = opts.capacity ?? 20;
+    const refillPerSec = opts.refillPerSec ?? 5;
+    const now = opts.now ?? Date.now;
+    const maxKeys = opts.maxKeys ?? 10000;
+    const buckets = new Map();
+    /**
+     * Keep the Map bounded. Called when a brand-new key would push the Map over `maxKeys`.
+     * First drop buckets that are fully refilled (idle -- safe to forget, they reset to
+     * `capacity` on recreation); if that is not enough, evict in least-recently-seen order.
+     * Map preserves insertion order, but `last` is the authoritative recency, so we sort.
+     */
+    const evict = () => {
+        // Pass 1: prune idle (fully-refilled) buckets -- losing them changes nothing.
+        for (const [k, b] of buckets) {
+            if (b.tokens >= capacity)
+                buckets.delete(k);
+            if (buckets.size < maxKeys)
+                return;
+        }
+        if (buckets.size < maxKeys)
+            return;
+        // Pass 2: still full of active buckets -- evict the least-recently-seen ones.
+        const entries = [...buckets.entries()].sort((a, b) => a[1].last - b[1].last);
+        const toRemove = buckets.size - maxKeys + 1;
+        for (let i = 0; i < toRemove && i < entries.length; i += 1) {
+            buckets.delete(entries[i][0]);
+        }
+    };
+    return (key) => {
+        const t = now();
+        const existing = buckets.get(key);
+        if (!existing && buckets.size >= maxKeys)
+            evict();
+        const b = existing ?? { tokens: capacity, last: t };
+        b.tokens = Math.min(capacity, b.tokens + ((t - b.last) / 1000) * refillPerSec);
+        b.last = t;
+        if (b.tokens < 1) {
+            buckets.set(key, b);
+            return false;
+        }
+        b.tokens -= 1;
+        buckets.set(key, b);
+        return true;
+    };
+}

package/dist/sdk/send-bulk.d.ts

@@ -0,0 +1,46 @@
+import { type SpmEnvelope, type SpmHttpClient } from '@shopimind/sdk-js';
+import type { Logger } from '../logging/logger.js';
+/**
+ * Normalized result of a safe bulk push. Note there is no `failed` field: a
+ * transport-level failure (`failed_count > 0`) THROWS (it must replay), so a
+ * resolved result only ever carries successfully-attempted + per-item-rejected items.
+ */
+export interface BulkResult {
+    sent: number;
+    /** Items the API REJECTED (validation, per-item, permanent-ish). Returned, not thrown. */
+    rejected: number;
+    /** The rejected items (bounded by chunk size) — for logging / targeted retry. */
+    rejected_items: unknown[];
+}
+/** Options forwarded to the SDK bulk call (chunking is ON by default). */
+export interface SendBulkOptions {
+    chunk?: boolean;
+    chunkSize?: number;
+}
+type FlatBulkFn<T> = (client: SpmHttpClient, data: T[], opts?: SendBulkOptions) => Promise<SpmEnvelope>;
+/**
+ * Safe bulk push. The SAFETY primitive of the kit, usable everywhere (sync steps
+ * AND real-time inbound handlers). Two call forms:
+ *  - flat:  `sendBulk(SpmProducts.bulkSave, items, opts?)`  — for the `(client, data, opts)` shape
+ *  - thunk: `sendBulk(() => SpmProductsVariations.bulkSave(client, productId, items, { chunk: true }))`
+ *           — for path-param shapes the flat form cannot express.
+ *
+ * Throws `SpmApiError` on any TRANSPORT failure — a global `!ok` OR `failed_count > 0`
+ * (a chunk that errored): transport is transient, so the caller must REPLAY. Per-item
+ * REJECTIONS (validation) are NOT a throw (one bad item must not abort the whole batch):
+ * they are RETURNED (and surfaced via the optional `onReject` sink + a warn log). The
+ * sync engine uses the sink to hold the cursor. Nothing is ever dropped silently.
+ */
+export interface SendBulk {
+    <T>(fn: FlatBulkFn<T>, items: T[], opts?: SendBulkOptions): Promise<BulkResult>;
+    (thunk: () => Promise<SpmEnvelope>): Promise<BulkResult>;
+}
+/**
+ * Builds a {@link SendBulk}. `onReject`, when provided, is called with the REJECTED
+ * (validation) count + items so the sync engine can hold the cursor. Transport
+ * failures (`failed_count`) THROW instead — they can never reach the sink, so
+ * `tolerateRejects` cannot tolerate them. A warn log fires regardless, so neither
+ * rejections nor failures are ever invisible.
+ */
+export declare function makeSendBulk(client: SpmHttpClient, logger: Logger, onReject?: (count: number, items: unknown[]) => void): SendBulk;
+export {};

package/dist/sdk/send-bulk.js

@@ -0,0 +1,40 @@
+import { SpmApiError, SpmHelpers, } from '@shopimind/sdk-js';
+function rejectedItemsOf(env) {
+    const d = env.data && typeof env.data === 'object' ? env.data : {};
+    return Array.isArray(d.rejected_items) ? d.rejected_items : [];
+}
+/**
+ * Builds a {@link SendBulk}. `onReject`, when provided, is called with the REJECTED
+ * (validation) count + items so the sync engine can hold the cursor. Transport
+ * failures (`failed_count`) THROW instead — they can never reach the sink, so
+ * `tolerateRejects` cannot tolerate them. A warn log fires regardless, so neither
+ * rejections nor failures are ever invisible.
+ */
+export function makeSendBulk(client, logger, onReject) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (async (fnOrThunk, items, opts) => {
+        const env = items === undefined
+            ? await fnOrThunk()
+            : await fnOrThunk(client, items, { chunk: true, ...opts });
+        // Transport/HTTP failure -> throw (the caller replays). Never a silent drop.
+        if (!env.ok)
+            throw new SpmApiError(env, 'sendBulk');
+        const { sent, rejected, failed } = SpmHelpers.extractCounts(env);
+        const rejected_items = rejectedItemsOf(env);
+        // FAILED = transport-level chunk failure (transient). The merged envelope couples
+        // failed_count>0 to ok:false (so the !ok throw above usually fires first), but a
+        // single bulk could still report failed_count on a 200 — so re-assert it here.
+        // Transport must REPLAY -> throw; `tolerateRejects` can therefore never tolerate it.
+        if (failed > 0) {
+            logger.warn('bulk push had failed chunks (transport) — replay required', { sent, rejected, failed });
+            throw new SpmApiError(env, `sendBulk (${failed} transport failure(s))`);
+        }
+        // REJECTED = per-item validation (permanent-ish): surfaced (warn + sink) and
+        // RETURNED, not thrown — one bad item must not abort the whole batch.
+        if (rejected > 0) {
+            logger.warn('bulk push had rejected items (validation)', { sent, rejected });
+            onReject?.(rejected, rejected_items);
+        }
+        return { sent, rejected, rejected_items };
+    });
+}

package/dist/sdk/source-scope.d.ts

@@ -0,0 +1,38 @@
+import type { SpmEnvelope, SpmHttpClient } from '@shopimind/sdk-js';
+import type { IntegrationStateRepo } from '../store/repositories.js';
+import type { BulkResult, SendBulk, SendBulkOptions } from './send-bulk.js';
+/**
+ * Handle for a PROVISIONED source. Exposes its `id_data_source` plus a `tag()`
+ * that injects it into every item — the recommended way to ensure an integration
+ * NEVER overwrites the merchant's native catalog. The SDK is not re-wrapped: the
+ * integration tags items then pushes them itself via the SDK
+ * (`SpmProducts.bulkSave(ctx.spm, tagged)`).
+ *
+ * Note: the source alone is not enough. On the core side, `id_data_source` is NOT
+ * part of the upsert key. You must ALSO namespace your identifiers (prefix/offset)
+ * so the upsert lands on rows distinct from the native ones. `tag()` guarantees the
+ * tag; namespacing remains the responsibility of your mappers.
+ */
+export interface SourceHandle {
+    /** `id_data_source` of the provisioned source (resolved by key). */
+    readonly id: number;
+    /** Tags each item with `id_data_source` (to be pushed afterwards via the SDK). */
+    tag<T extends object>(items: T[]): Array<T & {
+        id_data_source: number;
+    }>;
+    /**
+     * Tags then pushes via the safe bulk primitive: source tagging + envelope/rejection
+     * safety in one call (flat `(client, data, opts)` shape). For path-param bulks
+     * (variations/images/addresses), use `ctx.sendBulk(() => fn(ctx.spm, parentId, src.tag(items)))`.
+     */
+    send<T extends object>(fn: (client: SpmHttpClient, data: Array<T & {
+        id_data_source: number;
+    }>, opts?: SendBulkOptions) => Promise<SpmEnvelope>, items: T[], opts?: SendBulkOptions): Promise<BulkResult>;
+}
+/**
+ * Builds `ctx.withSource`: resolves the `id_data_source` of a PROVISIONED source
+ * (from the integration state) and returns a {@link SourceHandle}. Throws if the
+ * source was not declared in `provisioning.dataSources` (guard: pushing catalog data
+ * without a dedicated source is not allowed).
+ */
+export declare function makeWithSource(state: IntegrationStateRepo, installationId: string, provisioningKey: string, sendBulk: SendBulk): (sourceKey: string) => SourceHandle;