@shopimind/integration-kit-js 1.2.0 → 1.4.0

package/dist/provisioning/runner.js

@@ -1,7 +1,7 @@
 import { SpmOrdersStatuses, SpmHelpers } from '@shopimind/sdk-js';
-import { validateProvisioningEvents } from '../integration/define-integration.js';
+import { validateProvisioningEvents, validateCustomDataDefinition } from '../integration/define-integration.js';
 import { ensureDataSource, ensureCustomDataDefinition, ensureEvent } from './ensure.js';
-export async function runProvisioning(client, plan) {
+export async function runProvisioning(client, plan, logger) {
     const result = { sourceIds: {}, defIds: {}, events: 0, orderStatuses: 0, errors: [] };
     for (const ds of plan.dataSources ?? []) {
         try {
@@ -13,9 +13,19 @@ export async function runProvisioning(client, plan) {
             result.errors.push(`source ${ds.key}: ${errMsg(e)}`);
         }
     }
-    for (const def of plan.customData ?? []) {
+    // E10 — order the custom-data plan so every custom→custom target is CREATED BEFORE
+    // the definition that references it (its id must exist to resolve the relationship).
+    // A topological sort removes the "declare X before Y" foot-gun entirely; a genuine
+    // dependency CYCLE is a hard error (unresolvable). A relationship to an out-of-plan
+    // custom name is left as-is and warned about (see resolveCustomRelationTargets).
+    const orderedCustomData = topoSortCustomData(plan.customData ?? []);
+    for (const def of orderedCustomData) {
         try {
-            result.defIds[def.name] = await ensureCustomDataDefinition(client, def);
+            // E10 — structural guards before the network call: unique_keys ⊆ fields and
+            // relationships.sourceField ∈ fields. A misconfig fails here with a precise
+            // message instead of an opaque API rejection.
+            validateCustomDataDefinition(def);
+            result.defIds[def.name] = await ensureCustomDataDefinition(client, resolveCustomRelationTargets(def, result.defIds, logger));
         }
         catch (e) {
             result.errors.push(`def ${def.name}: ${errMsg(e)}`);
@@ -35,7 +45,16 @@ export async function runProvisioning(client, plan) {
     }
     if (plan.orderStatuses && plan.orderStatuses.length > 0) {
         try {
-            const env = await SpmOrdersStatuses.bulkSave(client, plan.orderStatuses, { chunk: true });
+            // E11 — fill the technical bookkeeping fields the API needs but the author
+            // should not have to hand-write. Explicit values are preserved.
+            const nowIso = new Date().toISOString();
+            const statuses = plan.orderStatuses.map((s) => ({
+                ...s,
+                is_deleted: s.is_deleted ?? false,
+                created_at: s.created_at ?? nowIso,
+                updated_at: s.updated_at ?? nowIso,
+            }));
+            const env = await SpmOrdersStatuses.bulkSave(client, statuses, { chunk: true });
             result.orderStatuses = SpmHelpers.extractCounts(env).sent;
         }
         catch (e) {
@@ -44,6 +63,77 @@ export async function runProvisioning(client, plan) {
     }
     return result;
 }
+/**
+ * Resolves a custom relationship's `targetSchema` declared by NAME (a sibling
+ * definition in the same plan) to the sibling's numeric id — mirroring how
+ * dataSources resolve `parentKey` -> `parent_id`. Thanks to the topological sort
+ * (E10) the sibling is always created before this definition. A `targetSchema` that
+ * is already numeric is left untouched; a custom target that is NON-NUMERIC and NOT
+ * in the plan cannot be resolved to an id — it is left as-is and WARNED about (E10).
+ */
+function resolveCustomRelationTargets(def, defIds, logger) {
+    if (!def.relationships?.length)
+        return def;
+    return {
+        ...def,
+        relationships: def.relationships.map((r) => {
+            if (r.targetSchemaType !== 'custom')
+                return r;
+            if (defIds[r.targetSchema] != null)
+                return { ...r, targetSchema: String(defIds[r.targetSchema]) };
+            // Not resolved by name. If it is not already a numeric id, it references an
+            // out-of-plan definition we cannot resolve here — surface it rather than
+            // silently shipping an unresolvable target to the API.
+            if (!/^\d+$/.test(String(r.targetSchema))) {
+                logger?.warn(`custom data '${def.name}': relationship target '${r.targetSchema}' is not in this plan and not a numeric id — left unresolved`, { definition: def.name, sourceField: r.sourceField, targetSchema: r.targetSchema });
+            }
+            return r;
+        }),
+    };
+}
+/**
+ * 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 function topoSortCustomData(defs) {
+    if (defs.length <= 1)
+        return defs;
+    const byName = new Map(defs.map((d) => [d.name, d]));
+    const deps = new Map();
+    for (const d of defs) {
+        const targets = (d.relationships ?? [])
+            .filter((r) => r.targetSchemaType === 'custom' && byName.has(r.targetSchema) && r.targetSchema !== d.name)
+            .map((r) => r.targetSchema);
+        deps.set(d.name, [...new Set(targets)]);
+    }
+    const sorted = [];
+    const state = new Map();
+    const stack = [];
+    const visit = (name) => {
+        const s = state.get(name);
+        if (s === 'done')
+            return;
+        if (s === 'visiting') {
+            throw new Error(`custom data: dependency cycle detected (${[...stack, name].join(' -> ')})`);
+        }
+        state.set(name, 'visiting');
+        stack.push(name);
+        for (const dep of deps.get(name) ?? [])
+            visit(dep);
+        stack.pop();
+        state.set(name, 'done');
+        const def = byName.get(name);
+        if (def)
+            sorted.push(def);
+    };
+    // Iterate in declaration order so independent definitions keep their relative order.
+    for (const d of defs)
+        visit(d.name);
+    return sorted;
+}
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }

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

@@ -7,7 +7,12 @@ import { type Logger } from '../logging/logger.js';
 import { type SyncSummary } from '../sync/engine.js';
 export interface CreateAppOptions<S> {
     databasePath: string;
-    webhookSecret: string;
+    /**
+     * Webhook signing secret(s). A single string is the common case; pass an array to
+     * open a secret ROTATION window (E6) — a webhook signed with ANY listed secret is
+     * accepted while you swap `current` -> `next`. Backward compatible with a string.
+     */
+    webhookSecret: string | string[];
     /**
      * Override for the ShopiMind SDK base URL (otherwise env `SHOPIMIND_CORE_API_BASE`,
      * then `https://core.shopimind.com`). Useful in tests / preprod.
@@ -28,6 +33,12 @@ export interface CreateAppOptions<S> {
     adminToken?: string | null;
     signatureToleranceSeconds?: number;
     backfillDays?: number;
+    /**
+     * Defensive overlap (E9) applied to every INCREMENTAL sync window: shifts `since`
+     * back by this many seconds so a boundary item is not missed. Idempotent (upserts).
+     * Default 0 (no overlap).
+     */
+    overlapSeconds?: number;
     port?: number;
     host?: string;
     logger?: Logger;

package/dist/runtime/create-app.js

@@ -11,6 +11,7 @@ import { makeWithSource } from '../sdk/source-scope.js';
 import { makeCustomData } from '../sdk/custom-data-scope.js';
 import { makeSendBulk } from '../sdk/send-bulk.js';
 import { createRateLimiter } from './rate-limiter.js';
+import { buildHealthReport, buildOverview } from './health.js';
 import { createServer } from '../http/server.js';
 import { buildRoutes } from '../http/routes.js';
 /**
@@ -77,7 +78,13 @@ export function createIntegrationApp(integration, opts) {
                 runs: repos.runs,
                 makeSource: (sb) => makeWithSource(repos.state, id, PROVISIONING_KEY, sb),
                 makeCustomData: (sb) => makeCustomData(repos.state, id, PROVISIONING_KEY, sb, base.spm),
-            }, { fullBackfill: o?.full ?? false, backfillDays });
+                // E4 — feed the dead-letter sink so rejected items survive the run.
+                rejectedItems: repos.rejectedItems,
+            }, {
+                fullBackfill: o?.full ?? false,
+                backfillDays,
+                ...(opts.overlapSeconds != null ? { overlapSeconds: opts.overlapSeconds } : {}),
+            });
         }
         finally {
             running.delete(id);
@@ -117,6 +124,11 @@ export function createIntegrationApp(integration, opts) {
         webhookRateLimit,
         runSyncForInstall: (id, full) => runSyncOnce(id, { full }),
         recentRuns: (id) => repos.runs.recent(id),
+        // E4 — dead-lettered rejects for an installation (admin, bounded).
+        rejectedItems: (id, limit) => repos.rejectedItems.listByInstallation(id, limit),
+        // E5 — enriched health probe + admin overview.
+        healthReport: () => buildHealthReport(db, repos, opts.now ? opts.now() : Date.now()),
+        overview: () => buildOverview(repos, opts.now ? opts.now() : Date.now()),
         inbound: {
             integration,
             repos,
@@ -163,8 +175,15 @@ export function createIntegrationApp(integration, opts) {
             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 });
+            const rejected = repos.rejectedItems.purgeOlderThan(retentionDays); // E4 dead-letter (90j)
+            if (log + seen + inbound + rejected > 0) {
+                logger.info('retention purge', {
+                    webhook_log: log,
+                    webhook_seen: seen,
+                    inbound_event: inbound,
+                    rejected_item: rejected,
+                    retentionDays,
+                });
             }
         }
         catch (e) {

package/dist/runtime/health.d.ts

@@ -0,0 +1,62 @@
+import type { Db } from '../store/db.js';
+import type { Repositories } from '../store/repositories.js';
+/**
+ * Health & overview reports (E5).
+ *
+ * `/health` is an UNAUTHENTICATED probe endpoint: it must stay coarse (no secrets,
+ * no PII beyond opaque installation ids) and cheap. It answers three questions an
+ * orchestrator / on-call needs:
+ *   - is the DB reachable? (a `SELECT 1` ping)
+ *   - is any active installation stalled? (age of its last finished run)
+ *   - are cursors stuck? (count of cursors in the `error` status)
+ * The snapshot is `degraded` (HTTP 503) when the DB is unreachable, or a run is
+ * older than `staleRunThresholdMs`, or cursors-in-error exceeds `maxCursorsInError`.
+ *
+ * `/admin/overview` is the AUTHENTICATED, richer JSON counterpart (installations,
+ * their latest run, recent webhooks) for a human/dashboard.
+ */
+export interface HealthThresholds {
+    /** A last run older than this marks the installation (and the snapshot) stale. Default 6h. */
+    staleRunThresholdMs?: number;
+    /** More cursors-in-error than this degrades the snapshot. Default 10. */
+    maxCursorsInError?: number;
+}
+export interface HealthReport {
+    status: 'ok' | 'degraded';
+    db: 'ok' | 'error';
+    active_installations: number;
+    cursors_in_error: number;
+    /** Per active installation: age (ms) of the last finished run (null if never run). */
+    installations: Array<{
+        installation_id: string;
+        last_run_at: string | null;
+        last_run_age_ms: number | null;
+        last_run_status: string | null;
+        stale: boolean;
+    }>;
+    checked_at: string;
+}
+export declare function buildHealthReport(db: Db, repos: Repositories, nowMs: number, thresholds?: HealthThresholds): HealthReport;
+export interface OverviewReport {
+    active_installations: number;
+    cursors_in_error: number;
+    installations: Array<{
+        installation_id: string;
+        status: string;
+        shop_domain: string | null;
+        last_run: {
+            id: number;
+            status: string;
+            started_at: string;
+            finished_at: string | null;
+        } | null;
+    }>;
+    recent_webhooks: Array<{
+        event: string | null;
+        installation_id: string | null;
+        signature_ok: number;
+        created_at: string;
+    }>;
+    generated_at: string;
+}
+export declare function buildOverview(repos: Repositories, nowMs: number): OverviewReport;

package/dist/runtime/health.js

@@ -0,0 +1,70 @@
+export function buildHealthReport(db, repos, nowMs, thresholds = {}) {
+    const staleThreshold = thresholds.staleRunThresholdMs ?? 6 * 60 * 60_000;
+    const maxInError = thresholds.maxCursorsInError ?? 10;
+    let dbOk = true;
+    try {
+        db.prepare('SELECT 1').get();
+    }
+    catch {
+        dbOk = false;
+    }
+    // If the DB is down, everything else is unknowable — report degraded immediately
+    // rather than throwing (the probe must always answer).
+    if (!dbOk) {
+        return {
+            status: 'degraded',
+            db: 'error',
+            active_installations: 0,
+            cursors_in_error: 0,
+            installations: [],
+            checked_at: new Date(nowMs).toISOString(),
+        };
+    }
+    const active = repos.installs.listActive();
+    const cursorsInError = repos.cursors.countInError();
+    const installations = active.map((inst) => {
+        const last = repos.runs.recent(inst.installation_id, 1)[0];
+        const finishedAt = last?.finished_at ?? null;
+        // SQLite datetime('now') stores UTC without a zone suffix; append 'Z' to parse.
+        const ageMs = finishedAt ? nowMs - Date.parse(finishedAt + 'Z') : null;
+        const stale = ageMs != null && ageMs > staleThreshold;
+        return {
+            installation_id: inst.installation_id,
+            last_run_at: finishedAt,
+            last_run_age_ms: ageMs != null && Number.isFinite(ageMs) ? ageMs : null,
+            last_run_status: last?.status ?? null,
+            stale,
+        };
+    });
+    const anyStale = installations.some((i) => i.stale);
+    const degraded = cursorsInError > maxInError || anyStale;
+    return {
+        status: degraded ? 'degraded' : 'ok',
+        db: 'ok',
+        active_installations: active.length,
+        cursors_in_error: cursorsInError,
+        installations,
+        checked_at: new Date(nowMs).toISOString(),
+    };
+}
+export function buildOverview(repos, nowMs) {
+    const active = repos.installs.listActive();
+    const installations = active.map((inst) => {
+        const last = repos.runs.recent(inst.installation_id, 1)[0];
+        return {
+            installation_id: inst.installation_id,
+            status: inst.status,
+            shop_domain: inst.shop_domain,
+            last_run: last
+                ? { id: last.id, status: last.status, started_at: last.started_at, finished_at: last.finished_at }
+                : null,
+        };
+    });
+    return {
+        active_installations: active.length,
+        cursors_in_error: repos.cursors.countInError(),
+        installations,
+        recent_webhooks: repos.webhookLog.recent(20),
+        generated_at: new Date(nowMs).toISOString(),
+    };
+}

package/dist/runtime/outbound.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Outbound-call helpers (E7) — for a connector talking to its PARTNER's API
+ * (Hiboutik, etc.), not to ShopiMind. They are the outbound counterparts of the
+ * inbound rate-limiter the runtime already uses for its own routes.
+ *
+ *  - `makeOutboundLimiter` wraps the kit's token-bucket into an async gate that
+ *    RESOLVES when a token is free (instead of returning a boolean), so a caller
+ *    just `await limiter()` before each partner request — bounding request rate to
+ *    stay under the partner's quota.
+ *  - `fetchWithRetry` retries transient failures (429 / 5xx / network) with
+ *    EXPONENTIAL BACKOFF + JITTER and honours a `Retry-After` header when present —
+ *    the correct, server-directed way to back off, instead of a fixed linear sleep.
+ */
+export interface OutboundLimiterOptions {
+    /** Max burst (tokens). Default 20. */
+    capacity?: number;
+    /** Sustained rate (tokens/second). Default 5. */
+    refillPerSec?: number;
+    /** Injectable clock (ms). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable sleep (ms). Defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Poll interval (ms) while waiting for a token. Default 25. */
+    pollMs?: number;
+}
+/**
+ * Builds an async rate gate keyed by an optional string (default a single shared
+ * key). `await limiter()` resolves once a token is available. Reuses the kit's
+ * token-bucket so behaviour matches the inbound limiter.
+ */
+export declare function makeOutboundLimiter(opts?: OutboundLimiterOptions): (key?: string) => Promise<void>;
+export interface FetchRetryOptions {
+    /** Max attempts (including the first). Default 4. */
+    maxAttempts?: number;
+    /** Base backoff (ms) for the exponential schedule. Default 500. */
+    baseDelayMs?: number;
+    /** Cap on any single backoff (ms). Default 30_000. */
+    maxDelayMs?: number;
+    /** Injectable sleep (ms). Defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable jitter in [0,1). Defaults to `Math.random`. */
+    random?: () => number;
+    /** Predicate: should this HTTP status be retried? Default 429 or >=500. */
+    retryOnStatus?: (status: number) => boolean;
+}
+/** Minimal response shape `fetchWithRetry` needs (compatible with the WHATWG `Response`). */
+export interface RetriableResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Parses a `Retry-After` header: either a delay in SECONDS, or an HTTP date. Returns
+ * the delay in ms, or `null` if absent/unparseable. `nowMs` lets the date form be tested.
+ */
+export declare function parseRetryAfterMs(value: string | null, nowMs?: number): number | null;
+/** Exponential backoff with full jitter, capped — bounded by `Retry-After` when the server sent one. */
+export declare function backoffDelayMs(attempt: number, opts?: {
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    random?: () => number;
+    retryAfterMs?: number | null;
+}): number;
+/**
+ * Runs `doFetch` (returning any WHATWG-`Response`-like object) with retry on 429 /
+ * 5xx / network errors, honouring `Retry-After` + exponential backoff with jitter.
+ * The final response (or thrown error) after the last attempt is returned/rethrown.
+ * `doFetch` is a thunk so the caller controls the URL/options/`fetch` implementation.
+ */
+export declare function fetchWithRetry<R extends RetriableResponse>(doFetch: () => Promise<R>, opts?: FetchRetryOptions): Promise<R>;

package/dist/runtime/outbound.js

@@ -0,0 +1,90 @@
+import { createRateLimiter } from './rate-limiter.js';
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Builds an async rate gate keyed by an optional string (default a single shared
+ * key). `await limiter()` resolves once a token is available. Reuses the kit's
+ * token-bucket so behaviour matches the inbound limiter.
+ */
+export function makeOutboundLimiter(opts = {}) {
+    const tryTake = createRateLimiter({
+        capacity: opts.capacity ?? 20,
+        refillPerSec: opts.refillPerSec ?? 5,
+        ...(opts.now ? { now: opts.now } : {}),
+    });
+    const sleep = opts.sleep ?? realSleep;
+    const pollMs = opts.pollMs ?? 25;
+    return async (key = 'default') => {
+        // Spin-wait with a short sleep: the bucket refills over time, so a blocked call
+        // eventually gets a token. Cheap and dependency-free (no queue bookkeeping).
+        while (!tryTake(key)) {
+            await sleep(pollMs);
+        }
+    };
+}
+const defaultRetryOnStatus = (status) => status === 429 || status >= 500;
+/**
+ * Parses a `Retry-After` header: either a delay in SECONDS, or an HTTP date. Returns
+ * the delay in ms, or `null` if absent/unparseable. `nowMs` lets the date form be tested.
+ */
+export function parseRetryAfterMs(value, nowMs = Date.now()) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const dateMs = Date.parse(value);
+    if (!Number.isNaN(dateMs))
+        return Math.max(0, dateMs - nowMs);
+    return null;
+}
+/** Exponential backoff with full jitter, capped — bounded by `Retry-After` when the server sent one. */
+export function backoffDelayMs(attempt, opts = {}) {
+    const base = opts.baseDelayMs ?? 500;
+    const max = opts.maxDelayMs ?? 30_000;
+    const random = opts.random ?? Math.random;
+    // Server-directed wait wins when present (respect its explicit instruction).
+    if (opts.retryAfterMs != null)
+        return Math.min(opts.retryAfterMs, max);
+    const exp = Math.min(base * 2 ** attempt, max);
+    return Math.floor(random() * exp); // full jitter
+}
+/**
+ * Runs `doFetch` (returning any WHATWG-`Response`-like object) with retry on 429 /
+ * 5xx / network errors, honouring `Retry-After` + exponential backoff with jitter.
+ * The final response (or thrown error) after the last attempt is returned/rethrown.
+ * `doFetch` is a thunk so the caller controls the URL/options/`fetch` implementation.
+ */
+export async function fetchWithRetry(doFetch, opts = {}) {
+    const maxAttempts = Math.max(1, opts.maxAttempts ?? 4);
+    const sleep = opts.sleep ?? realSleep;
+    const retryOn = opts.retryOnStatus ?? defaultRetryOnStatus;
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const isLast = attempt === maxAttempts - 1;
+        try {
+            const res = await doFetch();
+            if (!retryOn(res.status) || isLast)
+                return res;
+            const retryAfterMs = parseRetryAfterMs(res.headers.get('retry-after'));
+            await sleep(backoffDelayMs(attempt, {
+                ...(opts.baseDelayMs != null ? { baseDelayMs: opts.baseDelayMs } : {}),
+                ...(opts.maxDelayMs != null ? { maxDelayMs: opts.maxDelayMs } : {}),
+                ...(opts.random ? { random: opts.random } : {}),
+                retryAfterMs,
+            }));
+        }
+        catch (e) {
+            // Network-level error (no response): retry unless this was the last attempt.
+            lastError = e;
+            if (isLast)
+                throw e;
+            await sleep(backoffDelayMs(attempt, {
+                ...(opts.baseDelayMs != null ? { baseDelayMs: opts.baseDelayMs } : {}),
+                ...(opts.maxDelayMs != null ? { maxDelayMs: opts.maxDelayMs } : {}),
+                ...(opts.random ? { random: opts.random } : {}),
+            }));
+        }
+    }
+    // Unreachable (the loop returns or throws), but satisfies the type checker.
+    throw lastError ?? new Error('fetchWithRetry: exhausted attempts');
+}

package/dist/security/signature.d.ts

@@ -22,6 +22,15 @@ export interface SignatureOptions {
 }
 /** Verifies a ShopiMind -> integration webhook (`x-shopimind-*` headers). */
 export declare function verifyShopimindSignature(rawBody: string, headers: Record<string, string | string[] | undefined>, opts: SignatureOptions): SignatureCheck;
+/**
+ * Verifies a ShopiMind -> integration webhook against ONE OR SEVERAL secrets (E6).
+ * During a secret ROTATION the connector runs `[current, next]` (or `[next, current]`)
+ * for a window: a request signed with EITHER passes. The check succeeds on the first
+ * secret that verifies; if all fail, the LAST failure reason is returned (the timestamp
+ * checks are secret-independent, so the reason is representative). A single string
+ * behaves exactly like {@link verifyShopimindSignature} — fully backward compatible.
+ */
+export declare function verifyShopimindSignatureMulti(rawBody: string, headers: Record<string, string | string[] | undefined>, secrets: string | string[], opts?: Omit<SignatureOptions, 'secret'>): SignatureCheck;
 /**
  * Verifies an inbound integrator-app -> integration call (`x-integration-*` headers).
  * The `secret` is resolved PER-INSTALLATION by the caller.

package/dist/security/signature.js

@@ -12,6 +12,31 @@ export function verifyShopimindSignature(rawBody, headers, opts) {
         now: opts.now,
     });
 }
+/**
+ * Verifies a ShopiMind -> integration webhook against ONE OR SEVERAL secrets (E6).
+ * During a secret ROTATION the connector runs `[current, next]` (or `[next, current]`)
+ * for a window: a request signed with EITHER passes. The check succeeds on the first
+ * secret that verifies; if all fail, the LAST failure reason is returned (the timestamp
+ * checks are secret-independent, so the reason is representative). A single string
+ * behaves exactly like {@link verifyShopimindSignature} — fully backward compatible.
+ */
+export function verifyShopimindSignatureMulti(rawBody, headers, secrets, opts = {}) {
+    const list = (Array.isArray(secrets) ? secrets : [secrets]).filter((s) => s !== '' && s != null);
+    if (list.length === 0)
+        return { ok: false, reason: 'no_secret_configured' };
+    let last = { ok: false, reason: 'unverified' };
+    for (const secret of list) {
+        const check = verifyShopimindSignature(rawBody, headers, {
+            secret,
+            ...(opts.toleranceSeconds != null ? { toleranceSeconds: opts.toleranceSeconds } : {}),
+            ...(opts.now ? { now: opts.now } : {}),
+        });
+        if (check.ok)
+            return check;
+        last = check;
+    }
+    return last;
+}
 /**
  * Verifies an inbound integrator-app -> integration call (`x-integration-*` headers).
  * The `secret` is resolved PER-INSTALLATION by the caller.

package/dist/store/migrations.js

@@ -125,4 +125,41 @@ export const MIGRATIONS = [
       );
     `,
     },
+    {
+        version: 5,
+        name: 'cursor_failure_escalation',
+        sql: `
+      -- Repeated-failure escalation (E3). A run-level counter per cursor:
+      --   - incremented every time the step fails/holds (last_status = 'error'),
+      --   - reset to 0 on a clean advance.
+      -- The engine uses it for EXPONENTIAL backoff (skip 2^(k-1) ticks, capped ~24h)
+      -- so a persistently-failing source stops hammering a broken upstream every tick,
+      -- and escalates to an ERROR log at the 3rd consecutive failure. The GOLDEN RULE
+      -- is untouched: this only decides WHEN to retry, never whether the cursor moves.
+      ALTER TABLE sync_cursor ADD COLUMN consecutive_failures INTEGER NOT NULL DEFAULT 0;
+    `,
+    },
+    {
+        version: 6,
+        name: 'rejected_item_dead_letter',
+        sql: `
+      -- Dead-letter of per-item REJECTIONS (E4). When a bulk push reports rejected
+      -- items (validation, permanent-ish), the engine records them here instead of
+      -- letting the warn scroll away — so an operator can inspect what the API refused
+      -- and, later, replay it. Bounded per run (the engine caps inserts at 500/run) to
+      -- keep a poison batch from flooding the store. Subject to the same retention purge
+      -- as the other log tables.
+      CREATE TABLE rejected_item (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        installation_id  TEXT NOT NULL,
+        run_id           INTEGER,
+        entity           TEXT,
+        source_key       TEXT,
+        payload_json     TEXT,
+        reason           TEXT,
+        created_at       TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX idx_rejected_item_install ON rejected_item(installation_id, created_at);
+    `,
+    },
 ];

package/dist/store/repositories.d.ts

@@ -1,6 +1,6 @@
 import type DatabaseT from 'better-sqlite3';
 import type { SecretCipher } from '../security/crypto.js';
-import type { InstallRow, InstallUpsert, CursorRow, CursorWrite, SyncRunRow, InboundEventRow } from './types.js';
+import type { InstallRow, InstallUpsert, CursorRow, CursorWrite, SyncRunRow, InboundEventRow, RejectedItemRow } from './types.js';
 /** Installs (one row per installation). COALESCE upsert: a null field does not overwrite. */
 export declare class InstallRepo {
     private readonly db;
@@ -28,6 +28,13 @@ export declare class WebhookLogRepo {
     }): void;
     /** Retention: deletes log rows older than `days` days. Returns the number of rows removed. */
     purgeOlderThan(days: number): number;
+    /** Most recent webhook log entries (newest first) — for /admin/overview (E5). */
+    recent(limit?: number): Array<{
+        event: string | null;
+        installation_id: string | null;
+        signature_ok: number;
+        created_at: string;
+    }>;
 }
 /** Replay protection for lifecycle webhooks (key derived from the signature). */
 export declare class WebhookSeenRepo {
@@ -46,6 +53,10 @@ export declare class CursorRepo {
     constructor(db: DatabaseT.Database);
     get(installationId: string, entity: string, sourceKey?: string): CursorRow | undefined;
     set(installationId: string, entity: string, sourceKey: string, w: CursorWrite): void;
+    /** All cursors for an installation (for /health, /admin/overview). */
+    listByInstallation(installationId: string): CursorRow[];
+    /** Number of cursors currently in the `error` status (health signal). */
+    countInError(): number;
 }
 /** History of sync runs. */
 export declare class RunRepo {
@@ -90,6 +101,28 @@ export declare class InboundEventRepo {
     /** Retention: deletes inbound rows older than `days` days. Returns the number of rows removed. */
     purgeOlderThan(days: number): number;
 }
+/**
+ * Dead-letter of per-item REJECTIONS (E4). The engine records here what the
+ * ShopiMind API refused during a bulk push (validation), capped per run so a
+ * poison batch cannot flood the store; an operator inspects/replays via the admin
+ * endpoint. Subject to the same retention purge as the other log tables.
+ */
+export declare class RejectedItemRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    add(entry: {
+        installation_id: string;
+        run_id?: number | null;
+        entity?: string | null;
+        source_key?: string | null;
+        payload_json: string;
+        reason?: string | null;
+    }): void;
+    /** Most recent rejected items for an installation, newest first (bounded). */
+    listByInstallation(installationId: string, limit?: number): RejectedItemRow[];
+    /** Retention: deletes rejected-item rows older than `days` days. Returns rows removed. */
+    purgeOlderThan(days: number): number;
+}
 export interface Repositories {
     installs: InstallRepo;
     webhookLog: WebhookLogRepo;
@@ -98,5 +131,6 @@ export interface Repositories {
     runs: RunRepo;
     state: IntegrationStateRepo;
     inboundEvents: InboundEventRepo;
+    rejectedItems: RejectedItemRepo;
 }
 export declare function createRepositories(db: DatabaseT.Database, cipher: SecretCipher): Repositories;