@shopimind/integration-kit-js 1.0.0

package/dist/lifecycle/dispatcher.js

@@ -0,0 +1,315 @@
+import { SpmClient } from '@shopimind/sdk-js';
+import { verifyShopimindSignature } 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';
+import { ensureInboundSecret } from './inbound.js';
+import { makeWithSource } from '../sdk/source-scope.js';
+import { makeSendBulk } from '../sdk/send-bulk.js';
+export const ACCESS_TOKEN_KEY = '__access_token';
+/** State key where the provisioning result (sourceIds/defIds) is stored. */
+export const PROVISIONING_KEY = '__provisioning';
+/** Opaque installation id from the payload. */
+function installIdOf(p) {
+    if (p.installation_id != null && p.installation_id !== '')
+        return String(p.installation_id);
+    if (p.id_shop_integration != null)
+        return String(p.id_shop_integration);
+    return undefined;
+}
+const EVENT_TO_HANDLER = {
+    'integration.installed': 'install',
+    'integration.activated': 'activate',
+    'integration.deactivated': 'deactivate',
+    'integration.uninstalled': 'uninstall',
+    'integration.config_updated': 'config_updated',
+};
+/**
+ * Entry point for lifecycle webhooks. Verifies the signature against the RAW
+ * 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);
+    let payload;
+    try {
+        payload = rawBody ? JSON.parse(rawBody) : {};
+    }
+    catch {
+        deps.repos.webhookLog.log({ event: 'unparseable', signature_ok: sig.ok, payload_json: '[unparseable body omitted]' });
+        return { status: 400, body: { success: false, error: 'invalid_json' } };
+    }
+    // REDACTED log — before any processing, signed or not. Masking by key NAME
+    // (`redact`) is not enough: partner secrets declared `sensitive` in the
+    // config_schema (e.g. `private_key`, `client_id`, `login`, `pin`...) do not
+    // necessarily match the regex and would be written IN CLEAR, bypassing the
+    // AES at rest. So first mask the sensitive `configs` per the schema, then redact.
+    deps.repos.webhookLog.log({
+        event: payload.event ?? 'unknown',
+        installation_id: installIdOf(payload) ?? null,
+        signature_ok: sig.ok,
+        payload_json: JSON.stringify(redact(maskSchemaSecrets(payload, deps.integration.configSchema))),
+    });
+    if (!sig.ok) {
+        // OPAQUE 401: the precise reason stays in the server logs (already logged
+        // above via signature_ok), never returned to the caller (anti-calibration).
+        deps.logger.warn('webhook rejected', { reason: sig.reason, event: payload.event });
+        return { status: 401, body: { success: false, error: 'unauthorized' } };
+    }
+    const handlerName = payload.event ? EVENT_TO_HANDLER[payload.event] : undefined;
+    if (!handlerName)
+        return { status: 200, body: { success: false, error: 'unknown_event' } };
+    // Anti-replay: the signature uniquely binds (timestamp, body). We claim this
+    // key BEFORE processing; a verbatim replay is short-circuited. The key is
+    // RELEASED if processing fails (!success response or exception) so ShopiMind
+    // can resend the webhook and it will be reprocessed.
+    const installId = installIdOf(payload);
+    const dedupKey = headerOf(headers, 'x-shopimind-signature');
+    const dedupable = !!(installId && dedupKey);
+    if (dedupable && !deps.repos.webhookSeen.claim(installId, dedupKey)) {
+        return { status: 200, body: { success: true } }; // already processed -> harmless replay
+    }
+    try {
+        const body = await runHandler(handlerName, payload, deps);
+        if (dedupable && body.success === false)
+            deps.repos.webhookSeen.release(installId, dedupKey);
+        return { status: 200, body };
+    }
+    catch (e) {
+        if (dedupable)
+            deps.repos.webhookSeen.release(installId, dedupKey);
+        deps.logger.error('lifecycle handler failed', { event: payload.event, error: errMsg(e) });
+        return { status: 200, body: { success: false, error: 'internal_error' } };
+    }
+}
+function runHandler(name, p, deps) {
+    switch (name) {
+        case 'install':
+            return onInstall(p, deps);
+        case 'activate':
+            return onActivate(p, deps);
+        case 'deactivate':
+            return onDeactivate(p, deps);
+        case 'uninstall':
+            return onUninstall(p, deps);
+        case 'config_updated':
+            return onConfigUpdated(p, deps);
+    }
+}
+async function onInstall(p, deps) {
+    const id = installIdOf(p);
+    if (!id)
+        return { success: true };
+    if (p.access_token)
+        deps.repos.state.setSecret(id, ACCESS_TOKEN_KEY, p.access_token);
+    deps.repos.installs.upsert({
+        installation_id: id,
+        shop_domain: p.shop_domain ?? null,
+        shop_name: p.shop_name ?? null,
+        status: 'inactive',
+        installed_at: p.installed_at ?? null,
+    });
+    if (p.configs)
+        saveConfigs(deps.repos.state, id, deps.integration.configSchema, p.configs);
+    return { success: true };
+}
+async function onActivate(p, deps) {
+    const id = installIdOf(p);
+    if (!id)
+        return { success: false, error: 'missing_installation_id' };
+    if (p.access_token)
+        deps.repos.state.setSecret(id, ACCESS_TOKEN_KEY, p.access_token);
+    // The install is persisted 'inactive' until activation is validated:
+    // the 'active' status is only set AT THE END (testConnection + provisioning OK).
+    deps.repos.installs.upsert({
+        installation_id: id,
+        shop_domain: p.shop_domain ?? null,
+        shop_name: p.shop_name ?? null,
+        status: 'inactive',
+        installed_at: p.installed_at ?? null,
+    });
+    if (p.configs)
+        saveConfigs(deps.repos.state, id, deps.integration.configSchema, p.configs);
+    const ctx = buildContext(id, deps);
+    const ok = await deps.integration.testConnection(ctx).catch(() => false);
+    if (!ok) {
+        deps.repos.installs.setStatus(id, 'inactive', {});
+        return { success: false, error: 'connection_failed' };
+    }
+    if (deps.integration.provisioning) {
+        const plan = await deps.integration.provisioning(ctx);
+        const prov = await runProvisioning(ctx.spm, plan);
+        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
+            // just sources/defs: an events-only integration (loyalty/reviews) provisions
+            // neither source nor def. HARD failure only if NOTHING succeeded; otherwise
+            // best-effort, but partial errors are TRACED (no more silent swallowing).
+            const provisionedCount = Object.keys(prov.sourceIds).length + Object.keys(prov.defIds).length + prov.events + prov.orderStatuses;
+            if (provisionedCount === 0) {
+                deps.repos.installs.setStatus(id, 'inactive', {});
+                return { success: false, error: `provisioning_failed: ${prov.errors[0]}` };
+            }
+            deps.logger.warn('partial provisioning: some resources failed', { installation_id: id, errors: prov.errors });
+        }
+    }
+    if (deps.integration.hooks?.onActivate)
+        await deps.integration.hooks.onActivate(ctx);
+    deps.repos.installs.setStatus(id, 'active', { activated_at: p.activated_at ?? null }); // validated -> active
+    deps.afterActivate?.(id);
+    return { success: true };
+}
+async function onDeactivate(p, deps) {
+    const id = installIdOf(p);
+    if (!id)
+        return { success: true };
+    // Idempotent transition: already deactivated/uninstalled -> no-op (does not replay the hook).
+    const current = deps.repos.installs.find(id);
+    if (current && (current.status === 'inactive' || current.status === 'uninstalled'))
+        return { success: true };
+    deps.repos.installs.setStatus(id, 'inactive', { deactivated_at: p.deactivated_at ?? null });
+    await runHookSafe(deps.integration.hooks?.onDeactivate, id, deps);
+    return { success: true };
+}
+async function onUninstall(p, deps) {
+    const id = installIdOf(p);
+    if (!id)
+        return { success: true };
+    // Idempotent transition: already uninstalled -> no-op (does not replay the hook).
+    const current = deps.repos.installs.find(id);
+    if (current && current.status === 'uninstalled')
+        return { success: true };
+    deps.repos.installs.setStatus(id, 'uninstalled', { uninstalled_at: p.uninstalled_at ?? null });
+    await runHookSafe(deps.integration.hooks?.onUninstall, id, deps);
+    return { success: true };
+}
+async function onConfigUpdated(p, deps) {
+    const id = installIdOf(p);
+    if (!id)
+        return { success: true };
+    if (p.configs)
+        saveConfigs(deps.repos.state, id, deps.integration.configSchema, p.configs);
+    try {
+        const ctx = buildContext(id, deps);
+        if (deps.integration.provisioning) {
+            const plan = await deps.integration.provisioning(ctx);
+            const prov = await runProvisioning(ctx.spm, plan);
+            deps.repos.state.set(id, PROVISIONING_KEY, JSON.stringify({ sourceIds: prov.sourceIds, defIds: prov.defIds }));
+        }
+        if (deps.integration.hooks?.onConfigUpdated)
+            await deps.integration.hooks.onConfigUpdated(ctx);
+    }
+    catch (e) {
+        // Best-effort: the config is already saved (above) even if reprovisioning
+        // failed; the failure is logged but NOT surfaced to ShopiMind. We keep the
+        // { success: true } return DELIBERATELY (ShopiMind contract): a config update
+        // must not be rejected just because reprovisioning could not complete. Logged
+        // at ERROR (not warn) because a failed reprovision can leave the integration
+        // out of sync with the new config and warrants operator attention.
+        deps.logger.error('config_updated reprovisioning failed (best-effort, not surfaced)', { error: errMsg(e) });
+    }
+    return { success: true };
+}
+/** Validates the integration credentials (wizard step). No ShopiMind access. */
+export async function handleTestConnection(configs, deps) {
+    const ctx = ephemeralContext(configs, deps);
+    const ok = await deps.integration.testConnection(ctx).catch(() => false);
+    return ok ? { success: true } : { success: false, error: 'connection_failed' };
+}
+/** Populates a dynamic select in the config wizard. */
+export async function handleRemoteData(resource, configs, deps) {
+    const resolver = deps.integration.remoteData?.[resource];
+    if (!resolver)
+        return { data: [] };
+    const ctx = ephemeralContext(configs, deps);
+    const options = await resolver(ctx).catch(() => []);
+    return { data: options };
+}
+function buildContext(id, deps) {
+    const token = deps.repos.state.get(id, ACCESS_TOKEN_KEY);
+    if (!token)
+        throw new Error(`no access_token for installation ${id}`);
+    const configs = loadConfigs(deps.repos.state, id, deps.integration.configSchema);
+    const spm = deps.makeSpmClient(token);
+    const logger = deps.logger.child({ installation_id: id });
+    const sendBulk = makeSendBulk(spm, logger);
+    return {
+        installationId: id,
+        settings: deps.integration.parseSettings(configs),
+        spm,
+        sendBulk,
+        state: deps.repos.state,
+        logger,
+        setExternalAccount: (acc) => deps.repos.installs.setExternalAccount(id, acc.id, acc.name ?? null),
+        inboundSecret: ensureInboundSecret(deps.repos.state, id),
+        withSource: makeWithSource(deps.repos.state, id, PROVISIONING_KEY, sendBulk),
+    };
+}
+/** Context without an installation (config wizard): the ShopiMind SDK is not callable here. */
+function ephemeralContext(configs, deps) {
+    const spm = unavailableSpmClient();
+    return {
+        installationId: '',
+        settings: deps.integration.parseSettings(configs),
+        spm,
+        sendBulk: makeSendBulk(spm, deps.logger),
+        state: deps.repos.state,
+        logger: deps.logger,
+        setExternalAccount: () => { },
+        inboundSecret: '',
+        withSource: () => {
+            throw new Error('withSource is unavailable during the configuration wizard (no installation)');
+        },
+    };
+}
+async function runHookSafe(hook, id, deps) {
+    if (!hook)
+        return;
+    try {
+        await hook(buildContext(id, deps));
+    }
+    catch (e) {
+        deps.logger.warn('lifecycle hook failed', { error: errMsg(e) });
+    }
+}
+/**
+ * "Unavailable" SDK client for the configuration wizard (no installation): its
+ * adapter rejects every call. The SDK therefore never calls ShopiMind here; an
+ * integration must not use `ctx.spm` during configuration.
+ */
+function unavailableSpmClient() {
+    const client = SpmClient.getClient('v1', '', { baseUrl: 'http://localhost', retry: false, labelSource: null });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.defaults.adapter = () => {
+        throw new Error('ShopiMind SDK is unavailable during the configuration step');
+    };
+    return client;
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function headerOf(headers, name) {
+    const v = headers[name];
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * Masks, within `payload.configs`, the fields declared `sensitive` by the
+ * config_schema — before logging. Complements `redact()` (masking by key name)
+ * by covering secrets whose key does not match the generic regex.
+ */
+function maskSchemaSecrets(payload, schema) {
+    const configs = payload.configs;
+    if (!configs || typeof configs !== 'object')
+        return payload;
+    const sensitive = new Set(sensitiveKeys(schema));
+    if (sensitive.size === 0)
+        return payload;
+    const masked = {};
+    for (const [k, v] of Object.entries(configs))
+        masked[k] = sensitive.has(k) ? '[redacted]' : v;
+    return { ...payload, configs: masked };
+}

package/dist/lifecycle/inbound.d.ts

@@ -0,0 +1,50 @@
+import type { Integration, IntegrationContext } from '../integration/types.js';
+import type { IntegrationStateRepo, Repositories } from '../store/repositories.js';
+import type { Logger } from '../logging/logger.js';
+/** State key where the PER-INSTALLATION HMAC secret for inbound routes lives. */
+export declare const INBOUND_SECRET_KEY = "__inbound_secret";
+/** Lazily ensures a per-installation inbound secret, encrypted at rest; returns it. */
+export declare function ensureInboundSecret(state: IntegrationStateRepo, installationId: string): string;
+export interface InboundDeps<S> {
+    integration: Integration<S>;
+    repos: Repositories;
+    logger: Logger;
+    /** Builds the context for an installation (decrypted token, `ctx.spm` ready) or null. */
+    buildContext(installationId: string): IntegrationContext<S> | null;
+    toleranceSeconds?: number;
+    /** Returns true if the call is allowed (per-installation rate limit). */
+    rateLimit?(installationId: string): boolean;
+    now?: () => number;
+}
+export interface InboundResult {
+    status: number;
+    body: {
+        success: boolean;
+        error?: string;
+        replayed?: boolean;
+    };
+}
+/**
+ * Handles an INBOUND call (integrator app -> integration). Enforced pipeline:
+ * per-installation HMAC auth -> rate limit -> idempotency (persisted) -> handler
+ * with a ready `ctx`. The ShopiMind API token is NEVER exposed to the caller.
+ *
+ * Return codes:
+ * - 200 'success': handler ran and finished 'done' (status 'done'); OR an
+ *   already-processed replay (`replayed: true`) short-circuited via the prior
+ *   'done' fast-path, or via a non-fresh claim whose status is 'done'
+ *   (replayed) or 'received' (a concurrent attempt is still in progress).
+ * - 400 'missing_installation_header' / 'invalid_json': malformed request.
+ * - 401 'unauthorized': unknown installation (no secret) OR signature mismatch.
+ *   The reason is opaque to the caller and only logged server-side.
+ * - 404 'unknown_action': no inbound handler registered for `action`.
+ * - 409 'no_context': `buildContext` returned null — the installation exists and
+ *   is authenticated, but its context cannot be built right now (e.g. missing
+ *   access_token / not activated). The caller MAY retry later once activated;
+ *   nothing is claimed or executed in this case.
+ * - 429 'rate_limited': per-installation rate limit tripped.
+ * - 500 'internal_error': the handler threw. The attempt is persisted 'failed'
+ *   so a later identical call (same dedup key) RE-EXECUTES the handler; the
+ *   caller can safely retry. Idempotency only dedupes on success ('done').
+ */
+export declare function handleInbound<S>(action: string, rawBody: string, headers: Record<string, string | string[] | undefined>, deps: InboundDeps<S>): Promise<InboundResult>;

package/dist/lifecycle/inbound.js

@@ -0,0 +1,124 @@
+import { randomBytes } from 'node:crypto';
+import { verifyIntegratorSignature } from '../security/signature.js';
+/** State key where the PER-INSTALLATION HMAC secret for inbound routes lives. */
+export const INBOUND_SECRET_KEY = '__inbound_secret';
+const INSTALLATION_HEADER = 'x-integration-installation';
+const SIGNATURE_HEADER = 'x-integration-signature';
+const IDEMPOTENCY_HEADER = 'x-idempotency-key';
+/**
+ * Dummy secret to pay the HMAC cost on an unknown installation (anti-timing).
+ * NON-SENSITIVE CONSTANT: this value is not a credential and never validates any
+ * request. It exists solely to spend the same CPU as a real verification so an
+ * attacker cannot distinguish "unknown installation" from "bad signature" by
+ * timing. Leaking it is harmless; it grants no access.
+ */
+const DUMMY_SECRET = 'insec_unknown_installation_constant_time_guard';
+/** Lazily ensures a per-installation inbound secret, encrypted at rest; returns it. */
+export function ensureInboundSecret(state, installationId) {
+    const existing = state.get(installationId, INBOUND_SECRET_KEY);
+    if (existing)
+        return existing;
+    const secret = 'insec_' + randomBytes(24).toString('hex');
+    state.setSecret(installationId, INBOUND_SECRET_KEY, secret);
+    return secret;
+}
+const ok = (extra = {}) => ({ status: 200, body: { success: true, ...extra } });
+const fail = (status, error) => ({ status, body: { success: false, error } });
+/**
+ * Handles an INBOUND call (integrator app -> integration). Enforced pipeline:
+ * per-installation HMAC auth -> rate limit -> idempotency (persisted) -> handler
+ * with a ready `ctx`. The ShopiMind API token is NEVER exposed to the caller.
+ *
+ * Return codes:
+ * - 200 'success': handler ran and finished 'done' (status 'done'); OR an
+ *   already-processed replay (`replayed: true`) short-circuited via the prior
+ *   'done' fast-path, or via a non-fresh claim whose status is 'done'
+ *   (replayed) or 'received' (a concurrent attempt is still in progress).
+ * - 400 'missing_installation_header' / 'invalid_json': malformed request.
+ * - 401 'unauthorized': unknown installation (no secret) OR signature mismatch.
+ *   The reason is opaque to the caller and only logged server-side.
+ * - 404 'unknown_action': no inbound handler registered for `action`.
+ * - 409 'no_context': `buildContext` returned null — the installation exists and
+ *   is authenticated, but its context cannot be built right now (e.g. missing
+ *   access_token / not activated). The caller MAY retry later once activated;
+ *   nothing is claimed or executed in this case.
+ * - 429 'rate_limited': per-installation rate limit tripped.
+ * - 500 'internal_error': the handler threw. The attempt is persisted 'failed'
+ *   so a later identical call (same dedup key) RE-EXECUTES the handler; the
+ *   caller can safely retry. Idempotency only dedupes on success ('done').
+ */
+export async function handleInbound(action, rawBody, headers, deps) {
+    const installationId = headerValue(headers, INSTALLATION_HEADER);
+    if (!installationId)
+        return fail(400, 'missing_installation_header');
+    const secret = deps.repos.state.get(installationId, INBOUND_SECRET_KEY);
+    if (!secret) {
+        // OPAQUE 401 + still pay the HMAC cost (anti timing/installation-enumeration
+        // oracle). The precise reason stays in the server logs, never in the response.
+        verifyIntegratorSignature(rawBody, headers, { secret: DUMMY_SECRET, ...(deps.now ? { now: deps.now } : {}) });
+        deps.logger.warn('inbound rejected', { reason: 'unknown_installation', installationId });
+        return fail(401, 'unauthorized');
+    }
+    const sigOpts = { secret };
+    if (deps.toleranceSeconds != null)
+        sigOpts.toleranceSeconds = deps.toleranceSeconds;
+    if (deps.now)
+        sigOpts.now = deps.now;
+    const sig = verifyIntegratorSignature(rawBody, headers, sigOpts);
+    if (!sig.ok) {
+        deps.logger.warn('inbound rejected', { reason: sig.reason ?? 'signature_mismatch', installationId });
+        return fail(401, 'unauthorized');
+    }
+    if (deps.rateLimit && !deps.rateLimit(installationId))
+        return fail(429, 'rate_limited');
+    const handler = deps.integration.inbound?.[action];
+    if (!handler)
+        return fail(404, 'unknown_action');
+    let payload;
+    try {
+        payload = rawBody ? JSON.parse(rawBody) : {};
+    }
+    catch {
+        return fail(400, 'invalid_json');
+    }
+    // MANDATORY anti-replay, enforced by the server (never opt-in). The dedup key
+    // is, by default, derived from the SIGNATURE (which uniquely binds timestamp+body
+    // under the secret) -> any verbatim replay is short-circuited, even without an
+    // idempotency header. An `x-idempotency-key` provided by the caller takes
+    // precedence (application-level idempotency across possible re-signatures).
+    const sigRaw = headerValue(headers, SIGNATURE_HEADER) ?? '';
+    const dedupKey = headerValue(headers, IDEMPOTENCY_HEADER) ?? `sig:${action}:${sigRaw}`;
+    // Fast path: replay of a call already processed successfully (avoids building the ctx).
+    const prior = deps.repos.inboundEvents.find(installationId, dedupKey);
+    if (prior && prior.status === 'done')
+        return ok({ replayed: true });
+    // Context build BEFORE claiming: if it fails we return 409 'no_context' and
+    // claim NOTHING, so a later retry (once the installation is activated) is not
+    // wrongly short-circuited as an already-seen replay.
+    const ctx = deps.buildContext(installationId);
+    if (!ctx)
+        return fail(409, 'no_context');
+    // ATOMIC claim before execution (anti-TOCTOU): two concurrent calls cannot
+    // execute the handler twice.
+    const claim = deps.repos.inboundEvents.claim(installationId, dedupKey, action);
+    if (!claim.fresh && claim.status === 'done')
+        return ok({ replayed: true });
+    if (!claim.fresh && claim.status === 'received')
+        return ok({ replayed: true }); // already in progress
+    // fresh, or a previous 'failed' attempt -> (re)execute by reusing the claimed row.
+    try {
+        await handler(ctx, payload);
+        deps.repos.inboundEvents.finish(claim.rowId, 'done');
+        return ok();
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        deps.repos.inboundEvents.finish(claim.rowId, 'failed', msg);
+        deps.logger.error('inbound handler failed', { action, error: msg });
+        return fail(500, 'internal_error');
+    }
+}
+function headerValue(headers, name) {
+    const v = headers[name];
+    return Array.isArray(v) ? v[0] : v;
+}

package/dist/logging/logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Logger that REDACTS by default. No "raw" method is exposed: every piece of
+ * metadata passes through `redact()` before emission, so a secret cannot leak
+ * into the logs.
+ */
+export interface Logger {
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+export interface LogLine {
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    meta?: unknown;
+    bindings?: Record<string, unknown>;
+}
+export interface LoggerOptions {
+    bindings?: Record<string, unknown>;
+    /** Injectable sink (tests). Defaults to JSON console output. */
+    sink?: (line: LogLine) => void;
+}
+export declare function createLogger(opts?: LoggerOptions): Logger;

package/dist/logging/logger.js

@@ -0,0 +1,23 @@
+import { redact } from '../security/redaction.js';
+const defaultSink = (line) => {
+    const payload = JSON.stringify({ ...line.bindings, level: line.level, message: line.message, meta: line.meta });
+    if (line.level === 'error')
+        console.error(payload);
+    else if (line.level === 'warn')
+        console.warn(payload);
+    else
+        console.log(payload);
+};
+export function createLogger(opts = {}) {
+    const bindings = opts.bindings ?? {};
+    const sink = opts.sink ?? defaultSink;
+    const emit = (level, message, meta) => {
+        sink({ level, message, meta: meta === undefined ? undefined : redact(meta), bindings });
+    };
+    return {
+        info: (m, meta) => emit('info', m, meta),
+        warn: (m, meta) => emit('warn', m, meta),
+        error: (m, meta) => emit('error', m, meta),
+        child: (extra) => createLogger({ bindings: { ...bindings, ...extra }, ...(opts.sink ? { sink: opts.sink } : {}) }),
+    };
+}

package/dist/manifest.d.ts

@@ -0,0 +1,52 @@
+import type { Integration } from './integration/types.js';
+import type { ConfigSchema, WidgetDeclaration } from './contracts/index.js';
+/**
+ * Integration manifest: a NEUTRAL, portable description of an integration,
+ * derived entirely from `defineIntegration`. It describes the integration
+ * without coupling to a deployment: no secret, no status, no absolute URL
+ * (endpoints are relative paths, the baseUrl is added at registration time).
+ *
+ * KNOWN LIMITATIONS (manifest v1):
+ * - It does NOT describe the integration's declared INBOUND routes
+ *   (`Integration.inbound`): only the fixed lifecycle/test/remote webhooks are
+ *   listed. Consumers cannot discover the available `POST /inbound/{action}`
+ *   endpoints from the manifest alone.
+ * - It does NOT describe widget ENDPOINTS: `widgets` carries the declarations as
+ *   authored, but any backing endpoint/route a widget needs is not surfaced here.
+ * Both are expected to be addressed in a future manifest version.
+ */
+export interface IntegrationManifest {
+    manifest_version: 1;
+    slug: string;
+    name: string;
+    version: string;
+    /** NEUTRAL category keys (e.g. `'pos'`). */
+    categories?: string[];
+    icon_url?: string;
+    short_description?: string;
+    description?: string;
+    documentation_url?: string;
+    /**
+     * EXPERIMENTAL flag: signals the integration expects external auth (OAuth).
+     * It is purely advisory for now — the OAuth flow is NOT wired into the runtime,
+     * so setting it does not yet change activation/auth behavior. Treat as unstable
+     * until the runtime supports it.
+     */
+    requires_external_auth?: boolean;
+    config_schema: ConfigSchema;
+    widgets: WidgetDeclaration[];
+    /** RELATIVE endpoint paths (never an absolute URL: the baseUrl is added at deployment). */
+    webhooks: {
+        lifecycle: string;
+        test_connection: string;
+        remote_data: string;
+    };
+    /** Handled lifecycle events (fixed contract). */
+    lifecycle_events: string[];
+    /** Declared `remoteData` resources (keys). */
+    remote_resources: string[];
+}
+/**
+ * Derives the neutral manifest of an integration. PURE function (deterministic).
+ */
+export declare function buildIntegrationManifest<S>(integration: Integration<S>): IntegrationManifest;

package/dist/manifest.js

@@ -0,0 +1,36 @@
+/** Fixed lifecycle events of the protocol. */
+const LIFECYCLE_EVENTS = ['install', 'activate', 'deactivate', 'uninstall', 'config_updated'];
+/**
+ * Derives the neutral manifest of an integration. PURE function (deterministic).
+ */
+export function buildIntegrationManifest(integration) {
+    const m = integration.meta;
+    const manifest = {
+        manifest_version: 1,
+        slug: integration.slug,
+        name: m.name,
+        version: m.version,
+        config_schema: integration.configSchema,
+        widgets: integration.widgets ?? [],
+        webhooks: {
+            lifecycle: '/webhook/receive',
+            test_connection: '/webhook/test-connection',
+            remote_data: '/webhook/remote-data/{resource}',
+        },
+        lifecycle_events: [...LIFECYCLE_EVENTS],
+        remote_resources: Object.keys(integration.remoteData ?? {}),
+    };
+    if (m.categories !== undefined)
+        manifest.categories = m.categories;
+    if (m.icon_url !== undefined)
+        manifest.icon_url = m.icon_url;
+    if (m.short_description !== undefined)
+        manifest.short_description = m.short_description;
+    if (m.description !== undefined)
+        manifest.description = m.description;
+    if (m.documentation_url !== undefined)
+        manifest.documentation_url = m.documentation_url;
+    if (m.requires_external_auth !== undefined)
+        manifest.requires_external_auth = m.requires_external_auth;
+    return manifest;
+}

package/dist/provisioning/ensure.d.ts

@@ -0,0 +1,24 @@
+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.
+ *
+ * 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 declare function ensureDataSource(client: SpmHttpClient, input: NewDataSource): Promise<number>;
+/**
+ * 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 declare function ensureCustomDataDefinition(client: SpmHttpClient, def: NewCustomDataDefinition): Promise<number>;
+/** Creates an event type, tolerating a 409 "already exists" (idempotent). */
+export declare function ensureEvent(client: SpmHttpClient, event: NewEvent): Promise<void>;