@shopimind/integration-kit-js 1.0.0

package/dist/http/routes.js

@@ -0,0 +1,150 @@
+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';
+/** 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). */
+function constantTimeEqual(a, b) {
+    const da = createHmac('sha256', ADMIN_CMP_KEY).update(a).digest();
+    const db = createHmac('sha256', ADMIN_CMP_KEY).update(b).digest();
+    return timingSafeEqual(da, db);
+}
+const webhookPayload = {
+    parse: false,
+    output: 'data',
+    allow: 'application/json',
+    maxBytes: 1024 * 1024,
+};
+const smallPayload = {
+    parse: false,
+    output: 'data',
+    allow: 'application/json',
+    maxBytes: 64 * 1024,
+};
+const rawBody = (req) => {
+    const p = req.payload;
+    if (p == null)
+        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;
+}
+function parseConfigs(body) {
+    try {
+        return body ? JSON.parse(body) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function adminOk(req, token) {
+    if (!token)
+        return false;
+    const x = req.headers['x-admin-token'];
+    const auth = req.headers.authorization;
+    const presented = typeof x === 'string' && x
+        ? x
+        : typeof auth === 'string'
+            ? auth.replace(/^Bearer\s+/i, '')
+            : '';
+    if (!presented)
+        return false;
+    return constantTimeEqual(presented, token);
+}
+const clientIp = (req) => req.info?.remoteAddress || 'unknown';
+export function buildRoutes(deps) {
+    return [
+        {
+            method: 'POST',
+            path: '/webhook/receive',
+            options: { payload: webhookPayload },
+            handler: async (req, h) => {
+                // Per-IP rate limit BEFORE HMAC verification: caps the cost of a flood of
+                // unsigned (or forged) requests, each of which would otherwise force an HMAC.
+                if (deps.webhookRateLimit && !deps.webhookRateLimit(clientIp(req)))
+                    return h.response({ success: false, error: 'rate_limited' }).code(429);
+                const res = await handleWebhook(rawBody(req), req.headers, deps.dispatcher);
+                return h.response(res.body).code(res.status);
+            },
+        },
+        {
+            method: 'POST',
+            path: '/webhook/test-connection',
+            options: { payload: smallPayload },
+            handler: async (req, h) => {
+                const body = rawBody(req);
+                const sig = verifyShopimindSignature(body, req.headers, sigOptsOf(deps.dispatcher));
+                if (!sig.ok)
+                    return h.response({ success: false, error: 'unauthorized' }).code(401);
+                return h.response(await handleTestConnection(parseConfigs(body), deps.dispatcher)).code(200);
+            },
+        },
+        {
+            method: 'POST',
+            path: '/webhook/remote-data/{resource}',
+            options: { payload: smallPayload },
+            handler: async (req, h) => {
+                const body = rawBody(req);
+                const sig = verifyShopimindSignature(body, req.headers, sigOptsOf(deps.dispatcher));
+                if (!sig.ok)
+                    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);
+            },
+        },
+        {
+            method: 'POST',
+            path: '/inbound/{action}',
+            options: { payload: smallPayload },
+            handler: async (req, h) => {
+                const action = String(req.params.action);
+                const res = await handleInbound(action, rawBody(req), req.headers, deps.inbound);
+                return h.response(res.body).code(res.status);
+            },
+        },
+        {
+            method: 'GET',
+            path: '/health',
+            handler: (_req, h) => h.response({ status: 'ok' }).code(200),
+        },
+        {
+            method: 'POST',
+            path: '/admin/sync/{id}',
+            options: { payload: { parse: false, maxBytes: 4 * 1024 } },
+            handler: async (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);
+                const id = String(req.params.id ?? '');
+                if (!id)
+                    return h.response({ success: false, error: 'invalid_id' }).code(400);
+                // `?full=true` forces a full backfill (initial re-sync); default = incremental.
+                const full = String(req.query?.full ?? '') === 'true';
+                const summary = await deps.runSyncForInstall(id, full);
+                return h.response({ success: true, summary }).code(200);
+            },
+        },
+        {
+            method: 'GET',
+            path: '/admin/status/{id}',
+            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);
+                const id = String(req.params.id ?? '');
+                if (!id)
+                    return h.response({ success: false, error: 'invalid_id' }).code(400);
+                return h.response({ runs: deps.recentRuns(id) }).code(200);
+            },
+        },
+    ];
+}

package/dist/http/server.d.ts

@@ -0,0 +1,7 @@
+import type { Server } from '@hapi/hapi';
+export interface ServerOptions {
+    port: number;
+    host?: string;
+}
+/** Bare Hapi server (dual-stack by default, CORS off, validation logged). */
+export declare function createServer(opts: ServerOptions): Server;

package/dist/http/server.js

@@ -0,0 +1,19 @@
+import Hapi from '@hapi/hapi';
+/** Bare Hapi server (dual-stack by default, CORS off, validation logged). */
+export function createServer(opts) {
+    return Hapi.server({
+        port: opts.port,
+        // INTENTIONAL: bind to 0.0.0.0 (all interfaces) by default. This server is meant to
+        // run as a containerized service where the orchestrator / ingress controls exposure;
+        // binding to a loopback-only address would make it unreachable from outside the pod.
+        host: opts.host ?? '0.0.0.0',
+        routes: {
+            cors: false,
+            // INTENTIONAL: failAction 'log' (do NOT reject). Routes parse the RAW request body
+            // themselves (HMAC is computed over the exact bytes, payload.parse=false), so Joi
+            // request validation is non-authoritative here -- making it blocking would risk
+            // rejecting otherwise-valid signed requests. We log validation findings instead.
+            validate: { failAction: 'log' },
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @shopimind/integration-kit-js — public surface.
+ *
+ * Primitives, persistence, authoring contract, sync engine and HTTP runtime
+ * (server, routes) to build a ShopiMind integration.
+ */
+export * from './security/signature.js';
+export * from './security/crypto.js';
+export * from './security/redaction.js';
+export * from './sync/paginate.js';
+export * from './sync/concurrency.js';
+export * from './sync/cursor.js';
+export * from './sync/engine.js';
+export * from '@shopimind/sdk-js';
+export * from './sdk/source-scope.js';
+export type { BulkResult, SendBulk, SendBulkOptions } from './sdk/send-bulk.js';
+export * from './provisioning/ensure.js';
+export * from './provisioning/runner.js';
+export * from './config/config-store.js';
+export * from './lifecycle/dispatcher.js';
+export * from './lifecycle/inbound.js';
+export * from './store/db.js';
+export * from './store/migrate.js';
+export * from './store/migrations.js';
+export * from './store/repositories.js';
+export type * from './store/types.js';
+export * from './logging/logger.js';
+export * from './integration/define-integration.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 './testing/harness.js';
+export type * from './contracts/index.js';

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * @shopimind/integration-kit-js — public surface.
+ *
+ * Primitives, persistence, authoring contract, sync engine and HTTP runtime
+ * (server, routes) to build a ShopiMind integration.
+ */
+// Security
+export * from './security/signature.js';
+export * from './security/crypto.js';
+export * from './security/redaction.js';
+// Sync (safe cursor)
+export * from './sync/paginate.js';
+export * from './sync/concurrency.js';
+export * from './sync/cursor.js';
+export * from './sync/engine.js';
+// Re-export of the ShopiMind SDK: an integration imports everything from
+// `@shopimind/integration-kit-js` (resources, SpmHelpers, types).
+export * from '@shopimind/sdk-js';
+// Provisioned source helper (`ctx.withSource` -> SourceHandle).
+export * from './sdk/source-scope.js';
+// Idempotent provisioning + plan runner
+export * from './provisioning/ensure.js';
+export * from './provisioning/runner.js';
+// Persisted config (secrets encrypted at rest)
+export * from './config/config-store.js';
+// Lifecycle (dispatcher: signature + REDACTED log + provisioning)
+export * from './lifecycle/dispatcher.js';
+// Inbound routes (secured middleware: integrator app -> integration -> ShopiMind)
+export * from './lifecycle/inbound.js';
+// Persistence (versioned migrations + typed repositories)
+export * from './store/db.js';
+export * from './store/migrate.js';
+export * from './store/migrations.js';
+export * from './store/repositories.js';
+// Redacting logger
+export * from './logging/logger.js';
+// Integration authoring contract
+export * from './integration/define-integration.js';
+// Neutral integration manifest (describes the integration in a portable way)
+export * from './manifest.js';
+// HTTP runtime (Hapi server + routes + bootstrap)
+export * from './http/server.js';
+export * from './http/routes.js';
+export * from './runtime/create-app.js';
+export * from './runtime/rate-limiter.js';
+// Test helpers
+export * from './testing/harness.js';

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

@@ -0,0 +1,16 @@
+import type { Integration } from './types.js';
+/**
+ * Entry point of the author contract. Identity + boot-time validation: a
+ * malformed spec throws early (rather than behaving silently wrong).
+ */
+export declare function defineIntegration<S>(integration: Integration<S>): Integration<S>;
+export declare function validateIntegration<S>(c: Integration<S>): void;
+/**
+ * Validates the events of a materialized ProvisioningPlan: each event must carry
+ * a non-empty `code_name`. Called by the provisioning runner once the (async)
+ * plan has been produced — `validateIntegration` cannot do this because the plan
+ * depends on a runtime context.
+ */
+export declare function validateProvisioningEvents(events: ReadonlyArray<{
+    code_name?: string;
+}>): void;

package/dist/integration/define-integration.js

@@ -0,0 +1,50 @@
+/**
+ * Entry point of the author contract. Identity + boot-time validation: a
+ * malformed spec throws early (rather than behaving silently wrong).
+ */
+export function defineIntegration(integration) {
+    validateIntegration(integration);
+    return integration;
+}
+export function validateIntegration(c) {
+    if (!c.slug || !/^[a-z0-9_-]+$/.test(c.slug)) {
+        throw new Error(`invalid integration.slug: "${c.slug}" (expected [a-z0-9_-]+)`);
+    }
+    // meta.version must be present and a strict semver-ish `x.y.z` (it feeds the manifest).
+    if (!c.meta || !/^\d+\.\d+\.\d+$/.test(c.meta.version ?? '')) {
+        throw new Error(`invalid integration.meta.version: "${c.meta?.version}" (expected x.y.z)`);
+    }
+    const entities = c.syncSteps.map((s) => s.entity);
+    // Each sync step must declare a non-empty entity (whitespace-only is rejected).
+    for (const step of c.syncSteps) {
+        if (typeof step.entity !== 'string' || step.entity.trim() === '') {
+            throw new Error('sync step has an empty entity');
+        }
+    }
+    const dup = entities.find((e, i) => entities.indexOf(e) !== i);
+    if (dup) {
+        throw new Error(`duplicate sync step for entity "${dup}"`);
+    }
+    for (const step of c.syncSteps) {
+        if (step.cursorScope === 'per-source' && !step.sources) {
+            throw new Error(`step "${step.entity}" has scope 'per-source' but does not declare sources()`);
+        }
+    }
+    // NOTE: provisioned events live in the ProvisioningPlan returned by the
+    // `provisioning(ctx)` function, which needs a runtime ctx and is therefore not
+    // reachable from this static, boot-time validator. Each event's `code_name` is
+    // validated by `validateProvisioningEvents` when the plan is materialized.
+}
+/**
+ * Validates the events of a materialized ProvisioningPlan: each event must carry
+ * a non-empty `code_name`. Called by the provisioning runner once the (async)
+ * plan has been produced — `validateIntegration` cannot do this because the plan
+ * depends on a runtime context.
+ */
+export function validateProvisioningEvents(events) {
+    for (const ev of events) {
+        if (typeof ev.code_name !== 'string' || ev.code_name.trim() === '') {
+            throw new Error('provisioning event is missing a code_name');
+        }
+    }
+}

package/dist/integration/types.d.ts

@@ -0,0 +1,148 @@
+import type { ConfigSchema, RawConfigs, WidgetDeclaration, NewDataSource, NewCustomDataDefinition, NewEvent, SpmOrderStatus } from '../contracts/index.js';
+import type { SpmHttpClient } from '@shopimind/sdk-js';
+import type { SourceHandle } from '../sdk/source-scope.js';
+import type { SendBulk } from '../sdk/send-bulk.js';
+import type { IntegrationStateRepo } from '../store/repositories.js';
+import type { CursorRow } from '../store/types.js';
+import type { Logger } from '../logging/logger.js';
+import type { PaginateOptions } from '../sync/paginate.js';
+/**
+ * Integration metadata (feeds the manifest).
+ */
+export interface IntegrationMeta {
+    name: string;
+    version: string;
+    categories?: string[];
+    icon_url?: string;
+    short_description?: string;
+    description?: string;
+    /** An integration may require external auth (OAuth). Defaults to false. */
+    requires_external_auth?: boolean;
+    documentation_url?: string;
+}
+export interface RemoteOption {
+    value: string;
+    label: string;
+}
+/** Context injected into an integration: typed settings, typed SDK, encrypted state, redacting logger. */
+export interface IntegrationContext<S> {
+    /** OPAQUE installation token, issued by ShopiMind. Never interpret it. */
+    installationId: string;
+    settings: S;
+    /** Ready-to-use ShopiMind SDK client (`SpmCustomers.bulkSave(ctx.spm, ...)`). */
+    spm: SpmHttpClient;
+    /**
+     * Safe bulk push (envelope + rejection handling), usable here AND in sync steps.
+     * Throws on a transport failure; surfaces per-item rejections — never drops them.
+     * In a sync step, the rejections it reports HOLD the cursor (no silent data loss).
+     *   `ctx.sendBulk(SpmCustomDataRecords.bulkSave, records)`
+     */
+    sendBulk: SendBulk;
+    state: IntegrationStateRepo;
+    logger: Logger;
+    /** Records the INTEGRATOR account tied to this installation (correlation bridge). */
+    setExternalAccount(account: {
+        id: string;
+        name?: string | null;
+    }): void;
+    /**
+     * PER-INSTALLATION HMAC secret for inbound routes (middleware). Pass it to the
+     * integrator's app (typically in `onActivate`) so it can sign its inbound calls.
+     * `''` in an ephemeral context (configuration assistant).
+     */
+    inboundSecret: string;
+    /**
+     * Handle SCOPED TO A PROVISIONED SOURCE: automatically tags each pushed catalog
+     * entity with its `id_data_source` (prevents overwriting native data).
+     * `sourceKey` must match a source declared in `provisioning.dataSources`.
+     * (Also namespace your identifiers: the source alone does not isolate them.)
+     */
+    withSource(sourceKey: string): SourceHandle;
+}
+export interface SyncWindow {
+    since: Date | null;
+    until: Date;
+}
+/** Context for a sync step: window derived from the cursor + bounded primitives. */
+export interface SyncStepContext<S> extends IntegrationContext<S> {
+    entity: string;
+    /** '' for the global scope; a source id (e.g. store) for 'per-source'. */
+    sourceKey: string;
+    window: SyncWindow;
+    cursor: CursorRow | null;
+    /** Streaming pagination (avoids OOM). */
+    paginate<T>(fetchPage: (page: number) => Promise<T[]>, opts?: PaginateOptions): AsyncGenerator<T, void, void>;
+    /** Map with bounded concurrency (avoids 429s). */
+    mapConcurrent<I, O>(items: Iterable<I>, limit: number, fn: (item: I, index: number) => Promise<O>): Promise<O[]>;
+}
+export interface SyncStepResult {
+    items: number;
+    errors: string[];
+    /** Bound up to which the cursor should advance IF the run is clean. */
+    advanceCursorTo?: Date;
+}
+/**
+ * A synchronization step. The ENGINE manages the cursor (advances only if
+ * `errors` is empty) and the source iteration: the integration never touches
+ * the cursor.
+ */
+export interface SyncStep<S> {
+    entity: string;
+    cursorScope: 'global' | 'per-source';
+    /**
+     * By default, per-item rejections reported during the step HOLD the cursor (the
+     * window is replayed next run) — no silent data loss. Set `true` for a windowed
+     * 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.
+     */
+    tolerateRejects?: boolean;
+    enabled(settings: S): boolean;
+    /** For 'per-source': the source keys to iterate over (e.g. store ids). */
+    sources?(ctx: IntegrationContext<S>): Promise<string[]> | string[];
+    run(ctx: SyncStepContext<S>): Promise<SyncStepResult>;
+}
+/** ShopiMind resources to ensure on activation (find-or-create by the kit). */
+export interface ProvisioningPlan {
+    /** `parentKey` references another source in the same plan (resolved to `parent_id`). */
+    dataSources?: Array<{
+        key: string;
+        decl: NewDataSource;
+        parentKey?: string;
+    }>;
+    customData?: NewCustomDataDefinition[];
+    events?: NewEvent[];
+    orderStatuses?: SpmOrderStatus[];
+}
+export interface LifecycleHooks<S> {
+    onInstall?(ctx: IntegrationContext<S>): Promise<void> | void;
+    onActivate?(ctx: IntegrationContext<S>): Promise<void> | void;
+    onDeactivate?(ctx: IntegrationContext<S>): Promise<void> | void;
+    onUninstall?(ctx: IntegrationContext<S>): Promise<void> | void;
+    onConfigUpdated?(ctx: IntegrationContext<S>): Promise<void> | void;
+}
+/**
+ * The author contract. An integration only writes pure functions + typed
+ * declarations, passed to `defineIntegration`.
+ */
+export interface Integration<S> {
+    slug: string;
+    meta: IntegrationMeta;
+    configSchema: ConfigSchema;
+    parseSettings(raw: RawConfigs): S;
+    testConnection(ctx: IntegrationContext<S>): Promise<boolean>;
+    remoteData?: Record<string, (ctx: IntegrationContext<S>) => Promise<RemoteOption[]>>;
+    provisioning?(ctx: IntegrationContext<S>): ProvisioningPlan | Promise<ProvisioningPlan>;
+    widgets?: WidgetDeclaration[];
+    syncSteps: SyncStep<S>[];
+    hooks?: LifecycleHooks<S>;
+    /**
+     * INBOUND routes (the middleware): the integrator's app calls them to trigger
+     * an event / push data in REAL TIME. The kit authenticates (per-installation
+     * HMAC), resolves the installation and provides `ctx` (with `ctx.spm` ready).
+     * Each handler is GENERIC: it does whatever it wants through `ctx.spm` via the
+     * SDK (`SpmEvents.trigger(ctx.spm, ...)`, `SpmCustomDataRecords.bulkSave(ctx.spm, ...)`...).
+     * Exposed at `POST /inbound/{action}`.
+     */
+    inbound?: Record<string, (ctx: IntegrationContext<S>, payload: unknown) => Promise<void> | void>;
+}

package/dist/integration/types.js

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

package/dist/lifecycle/dispatcher.d.ts

@@ -0,0 +1,33 @@
+import type { RawConfigs, WebhookResponse, RemoteDataResponse } from '../contracts/index.js';
+import type { Integration } from '../integration/types.js';
+import { type SpmHttpClient } from '@shopimind/sdk-js';
+import type { Repositories } from '../store/repositories.js';
+import type { Logger } from '../logging/logger.js';
+export declare const ACCESS_TOKEN_KEY = "__access_token";
+/** State key where the provisioning result (sourceIds/defIds) is stored. */
+export declare const PROVISIONING_KEY = "__provisioning";
+export interface DispatcherDeps<S> {
+    integration: Integration<S>;
+    repos: Repositories;
+    secret: string;
+    toleranceSeconds?: number;
+    logger: Logger;
+    /** Builds the ShopiMind SDK client for an access_token. */
+    makeSpmClient(accessToken: string): SpmHttpClient;
+    /** Called after a successful activation (the runtime starts the backfill here). */
+    afterActivate?: (installationId: string) => void;
+    now?: () => number;
+}
+export interface HttpResult {
+    status: number;
+    body: WebhookResponse;
+}
+/**
+ * Entry point for lifecycle webhooks. Verifies the signature against the RAW
+ * body, logs a REDACTED payload (secrets never reach the log), then dispatches.
+ */
+export declare function handleWebhook<S>(rawBody: string, headers: Record<string, string | string[] | undefined>, deps: DispatcherDeps<S>): Promise<HttpResult>;
+/** Validates the integration credentials (wizard step). No ShopiMind access. */
+export declare function handleTestConnection<S>(configs: RawConfigs, deps: DispatcherDeps<S>): Promise<WebhookResponse>;
+/** Populates a dynamic select in the config wizard. */
+export declare function handleRemoteData<S>(resource: string, configs: RawConfigs, deps: DispatcherDeps<S>): Promise<RemoteDataResponse>;