@shopimind/integration-kit-js 1.0.0

package/dist/sdk/source-scope.js

@@ -0,0 +1,34 @@
+/**
+ * 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 function makeWithSource(state, installationId, provisioningKey, sendBulk) {
+    return (sourceKey) => {
+        const raw = state.get(installationId, provisioningKey);
+        // Parse defensively: corrupt/unreadable persisted state must surface as the
+        // business error "source not provisioned" (below), never as an opaque
+        // SyntaxError. An unparseable blob is treated as "no sources provisioned".
+        let sourceIds = {};
+        if (raw) {
+            try {
+                sourceIds = JSON.parse(raw).sourceIds ?? {};
+            }
+            catch {
+                sourceIds = {};
+            }
+        }
+        const id = sourceIds[sourceKey];
+        if (id == null) {
+            throw new Error(`withSource("${sourceKey}"): source not provisioned — declare it in provisioning.dataSources`);
+        }
+        const tag = (items) => items.map((i) => ({ ...i, id_data_source: id }));
+        return {
+            id,
+            tag,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            send: (fn, items, opts) => sendBulk(fn, tag(items), opts),
+        };
+    };
+}

package/dist/security/crypto.d.ts

@@ -0,0 +1,19 @@
+export interface CryptoOptions {
+    /** 64-character hex key (32 bytes). */
+    key?: string | null;
+    /** `true` => a missing key throws at construction. */
+    production?: boolean;
+}
+export declare class SecretCipher {
+    private readonly key;
+    constructor(opts: CryptoOptions);
+    /** `true` when no key is configured -> secrets stored IN PLAINTEXT (dev only). */
+    get insecure(): boolean;
+    /**
+     * Encrypts a secret. `aad` (Additional Authenticated Data) binds the ciphertext
+     * to its location (e.g. `${installationId}:${key}`): a valid blob then cannot be
+     * relocated/swapped from one row to another (the auth tag covers the AAD).
+     */
+    encrypt(plaintext: string, aad?: string): string;
+    decrypt(stored: string, aad?: string): string;
+}

package/dist/security/crypto.js

@@ -0,0 +1,82 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+/**
+ * AES-256-GCM encryption of secrets at rest (partner API keys).
+ *
+ * In PRODUCTION, a missing key is FATAL. In dev, a `plain:` fallback is allowed
+ * so a key is not required locally.
+ */
+const ALGO = 'aes-256-gcm';
+const PLAIN_PREFIX = 'plain:';
+const GCM_PREFIX = 'gcm:';
+export class SecretCipher {
+    key;
+    constructor(opts) {
+        this.key = parseKey(opts.key);
+        if ((opts.production ?? false) && !this.key) {
+            throw new Error('CREDENTIALS_KEY is required in production (64 hex characters / 32 bytes) to encrypt secrets at rest');
+        }
+    }
+    /** `true` when no key is configured -> secrets stored IN PLAINTEXT (dev only). */
+    get insecure() {
+        return this.key === null;
+    }
+    /**
+     * Encrypts a secret. `aad` (Additional Authenticated Data) binds the ciphertext
+     * to its location (e.g. `${installationId}:${key}`): a valid blob then cannot be
+     * relocated/swapped from one row to another (the auth tag covers the AAD).
+     */
+    encrypt(plaintext, aad) {
+        if (!this.key) {
+            // Dev only -- in production the constructor has already thrown.
+            return `${PLAIN_PREFIX}${plaintext}`;
+        }
+        const iv = randomBytes(12);
+        const cipher = createCipheriv(ALGO, this.key, iv);
+        if (aad)
+            cipher.setAAD(Buffer.from(aad, 'utf8'));
+        const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return `${GCM_PREFIX}${iv.toString('hex')}:${tag.toString('hex')}:${ct.toString('hex')}`;
+    }
+    decrypt(stored, aad) {
+        if (stored.startsWith(PLAIN_PREFIX)) {
+            // The format prefix is part of the stored value (so it is forgeable).
+            // Only accept plaintext if no key is configured (dev). If a key exists, a
+            // `plain:` blob is tampering -> reject (GCM integrity takes precedence).
+            if (this.key)
+                throw new Error('plaintext secret rejected: a CREDENTIALS_KEY is configured');
+            return stored.slice(PLAIN_PREFIX.length);
+        }
+        if (!stored.startsWith(GCM_PREFIX))
+            throw new Error('unrecognized ciphertext format');
+        if (!this.key)
+            throw new Error('CREDENTIALS_KEY is required to decrypt a stored secret');
+        const parts = stored.slice(GCM_PREFIX.length).split(':');
+        if (parts.length !== 3)
+            throw new Error('malformed GCM ciphertext');
+        const [ivHex, tagHex, ctHex] = parts;
+        const iv = Buffer.from(ivHex, 'hex');
+        const tag = Buffer.from(tagHex, 'hex');
+        if (iv.length !== 12)
+            throw new Error('invalid GCM IV (12 bytes expected)');
+        if (tag.length !== 16)
+            throw new Error('invalid GCM tag (16 bytes expected)');
+        const decipher = createDecipheriv(ALGO, this.key, iv);
+        if (aad)
+            decipher.setAAD(Buffer.from(aad, 'utf8'));
+        decipher.setAuthTag(tag);
+        return Buffer.concat([
+            decipher.update(Buffer.from(ctHex, 'hex')),
+            decipher.final(),
+        ]).toString('utf8');
+    }
+}
+function parseKey(key) {
+    if (!key)
+        return null;
+    const buf = Buffer.from(key, 'hex');
+    if (buf.length !== 32) {
+        throw new Error(`CREDENTIALS_KEY must be 32 bytes (64 hex), received ${buf.length} byte(s)`);
+    }
+    return buf;
+}

package/dist/security/redaction.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Masks secrets before logging.
+ *
+ * Run values through this function before writing them to logs so that no API key
+ * appears in plaintext.
+ */
+/**
+ * Recursively replaces the values of sensitive keys with `[redacted]`.
+ *
+ * Guards against circular references (a node already on the current path is replaced
+ * with `[Circular]`) and against excessive nesting (beyond {@link MAX_DEPTH} levels the
+ * value is truncated). Plain JSON-shaped objects are unaffected by these guards.
+ */
+export declare function redact<T>(value: T): T;
+export declare function isSensitiveKey(key: string): boolean;

package/dist/security/redaction.js

@@ -0,0 +1,56 @@
+/**
+ * Masks secrets before logging.
+ *
+ * Run values through this function before writing them to logs so that no API key
+ * appears in plaintext.
+ */
+const SENSITIVE = /(secret|password|passwd|api[_-]?key|token|access[_-]?token|client[_-]?secret|authorization|credential)/i;
+/**
+ * Maximum recursion depth. Beyond this level the value is truncated (replaced with a
+ * sentinel) to guard against pathologically deep structures that could exhaust the
+ * stack — and so a deeply-nested secret can never leak unredacted.
+ */
+const MAX_DEPTH = 8;
+/**
+ * Recursively replaces the values of sensitive keys with `[redacted]`.
+ *
+ * Guards against circular references (a node already on the current path is replaced
+ * with `[Circular]`) and against excessive nesting (beyond {@link MAX_DEPTH} levels the
+ * value is truncated). Plain JSON-shaped objects are unaffected by these guards.
+ */
+export function redact(value) {
+    return redactInternal(value, new WeakSet(), 0);
+}
+function redactInternal(value, seen, depth) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    // Bound the recursion depth: beyond this level TRUNCATE rather than return the value
+    // as-is, so a sensitive key nested very deep can never leak unredacted to logs (fail-closed).
+    if (depth >= MAX_DEPTH) {
+        return '[truncated: max depth]';
+    }
+    // Break cycles: if this object is already on the current traversal path, stop.
+    if (seen.has(value)) {
+        return '[Circular]';
+    }
+    seen.add(value);
+    let result;
+    if (Array.isArray(value)) {
+        result = value.map((v) => redactInternal(v, seen, depth + 1));
+    }
+    else {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SENSITIVE.test(k) ? '[redacted]' : redactInternal(v, seen, depth + 1);
+        }
+        result = out;
+    }
+    // Allow the same object to reappear on sibling branches; we only forbid it on the
+    // active path (true cycles), not on legitimate shared references.
+    seen.delete(value);
+    return result;
+}
+export function isSensitiveKey(key) {
+    return SENSITIVE.test(key);
+}

package/dist/security/signature.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HMAC signature verification for incoming webhooks.
+ *
+ * The algorithm (HMAC-SHA256 over `${timestamp}.${rawBody}`, constant-time
+ * comparison, asymmetric anti-replay window) is provided by `SpmWebhookSignature`
+ * from the SDK. This module only binds the headers to that scheme:
+ *  - ShopiMind -> integration (lifecycle webhooks): `x-shopimind-*` headers,
+ *    secret = `webhook_secret` (shared between ShopiMind and the integration);
+ *  - Integrator app -> integration (inbound routes / middleware): `x-integration-*`
+ *    headers, PER-INSTALLATION secret (never the ShopiMind API token).
+ */
+export interface SignatureCheck {
+    ok: boolean;
+    reason?: string;
+}
+export interface SignatureOptions {
+    secret: string;
+    /** Anti-replay window in seconds (default 300). */
+    toleranceSeconds?: number;
+    /** Injectable clock; defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Verifies a ShopiMind -> integration webhook (`x-shopimind-*` headers). */
+export declare function verifyShopimindSignature(rawBody: string, headers: Record<string, string | string[] | undefined>, opts: SignatureOptions): SignatureCheck;
+/**
+ * Verifies an inbound integrator-app -> integration call (`x-integration-*` headers).
+ * The `secret` is resolved PER-INSTALLATION by the caller.
+ */
+export declare function verifyIntegratorSignature(rawBody: string, headers: Record<string, string | string[] | undefined>, opts: SignatureOptions): SignatureCheck;
+/** Builds the signature for a body (`${ts}.${body}`). */
+export declare function signShopimindBody(rawBody: string, secret: string, timestampSeconds: number): string;

package/dist/security/signature.js

@@ -0,0 +1,30 @@
+import { SpmWebhookSignature } from '@shopimind/sdk-js';
+const SHOPIMIND_TIMESTAMP_HEADER = 'x-shopimind-timestamp';
+const SHOPIMIND_SIGNATURE_HEADER = 'x-shopimind-signature';
+const INTEGRATION_TIMESTAMP_HEADER = 'x-integration-timestamp';
+const INTEGRATION_SIGNATURE_HEADER = 'x-integration-signature';
+/** Verifies a ShopiMind -> integration webhook (`x-shopimind-*` headers). */
+export function verifyShopimindSignature(rawBody, headers, opts) {
+    return SpmWebhookSignature.verifyFromHeaders(rawBody, headers, opts.secret, {
+        timestampHeader: SHOPIMIND_TIMESTAMP_HEADER,
+        signatureHeader: SHOPIMIND_SIGNATURE_HEADER,
+        toleranceSeconds: opts.toleranceSeconds,
+        now: opts.now,
+    });
+}
+/**
+ * Verifies an inbound integrator-app -> integration call (`x-integration-*` headers).
+ * The `secret` is resolved PER-INSTALLATION by the caller.
+ */
+export function verifyIntegratorSignature(rawBody, headers, opts) {
+    return SpmWebhookSignature.verifyFromHeaders(rawBody, headers, opts.secret, {
+        timestampHeader: INTEGRATION_TIMESTAMP_HEADER,
+        signatureHeader: INTEGRATION_SIGNATURE_HEADER,
+        toleranceSeconds: opts.toleranceSeconds,
+        now: opts.now,
+    });
+}
+/** Builds the signature for a body (`${ts}.${body}`). */
+export function signShopimindBody(rawBody, secret, timestampSeconds) {
+    return SpmWebhookSignature.sign(rawBody, secret, timestampSeconds);
+}

package/dist/store/db.d.ts

@@ -0,0 +1,7 @@
+import Database from 'better-sqlite3';
+export type Db = Database.Database;
+/**
+ * Opens (or creates) the SQLite store, applies the PRAGMAs and runs the migrations.
+ * Use `:memory:` for tests. The parent directory is created if needed.
+ */
+export declare function openDatabase(path: string): Db;

package/dist/store/db.js

@@ -0,0 +1,22 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import Database from 'better-sqlite3';
+import { MIGRATIONS } from './migrations.js';
+import { runMigrations } from './migrate.js';
+/**
+ * Opens (or creates) the SQLite store, applies the PRAGMAs and runs the migrations.
+ * Use `:memory:` for tests. The parent directory is created if needed.
+ */
+export function openDatabase(path) {
+    if (path !== ':memory:') {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    const db = new Database(path);
+    db.pragma('journal_mode = WAL');
+    // Wait up to 5s on a locked database before raising SQLITE_BUSY, so a concurrent
+    // writer does not fail immediately under contention.
+    db.pragma('busy_timeout = 5000');
+    db.pragma('foreign_keys = ON');
+    runMigrations(db, MIGRATIONS);
+    return db;
+}

package/dist/store/migrate.d.ts

@@ -0,0 +1,10 @@
+import type DatabaseT from 'better-sqlite3';
+import type { Migration } from './migrations.js';
+/**
+ * Applies the missing migrations in order, each within a transaction.
+ * Keeps a `schema_migrations` registry. Idempotent: re-running only applies what
+ * is missing (returns the number of migrations applied).
+ */
+export declare function runMigrations(db: DatabaseT.Database, migrations: Migration[]): number;
+/** Currently applied schema version (0 if blank). */
+export declare function currentSchemaVersion(db: DatabaseT.Database): number;

package/dist/store/migrate.js

@@ -0,0 +1,35 @@
+/**
+ * Applies the missing migrations in order, each within a transaction.
+ * Keeps a `schema_migrations` registry. Idempotent: re-running only applies what
+ * is missing (returns the number of migrations applied).
+ */
+export function runMigrations(db, migrations) {
+    db.exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+       version INTEGER PRIMARY KEY,
+       name TEXT NOT NULL,
+       applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+     );`);
+    const row = db.prepare('SELECT MAX(version) AS v FROM schema_migrations').get();
+    const current = row.v ?? 0;
+    const pending = migrations
+        .filter((m) => m.version > current)
+        .sort((a, b) => a.version - b.version);
+    const record = db.prepare('INSERT INTO schema_migrations (version, name) VALUES (?, ?)');
+    const apply = db.transaction((m) => {
+        db.exec(m.sql);
+        record.run(m.version, m.name);
+    });
+    for (const m of pending)
+        apply(m);
+    return pending.length;
+}
+/** Currently applied schema version (0 if blank). */
+export function currentSchemaVersion(db) {
+    const exists = db
+        .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='schema_migrations'`)
+        .get();
+    if (!exists)
+        return 0;
+    const row = db.prepare('SELECT MAX(version) AS v FROM schema_migrations').get();
+    return row.v ?? 0;
+}

package/dist/store/migrations.d.ts

@@ -0,0 +1,27 @@
+/**
+ * VERSIONED SQLite migrations. The SQL is embedded (no asset to copy into
+ * `dist`). The runner applies the missing versions within a transaction.
+ *
+ * Schema centered on `installation_id` (OPAQUE token issued by ShopiMind, treated
+ * as a string). The local store is the integrator's CORRELATION REGISTRY: it links
+ * a ShopiMind installation (`installation_id`) to ITS internal account
+ * (`external_account_ref`/`_name`). No internal ShopiMind id (PK, `id_shop`) is
+ * stored here.
+ *
+ * Encryption — be honest about what is and is NOT protected:
+ *   - ONLY secrets written via `integration_state.setSecret` are encrypted at rest
+ *     (AES-256-GCM, `encrypted = 1`).
+ *   - PII (`shop_domain`, `shop_name`, `external_account_name`) and plain values
+ *     written via `integration_state.set` are stored IN CLEAR TEXT.
+ *   - The SQLite file itself is NOT encrypted. Protect it via filesystem/disk
+ *     controls if at-rest confidentiality of the whole store is required.
+ *
+ * Migrations are APPEND-ONLY: NEVER edit a migration that has already been
+ * published/shipped — add a new versioned migration instead.
+ */
+export interface Migration {
+    version: number;
+    name: string;
+    sql: string;
+}
+export declare const MIGRATIONS: Migration[];

package/dist/store/migrations.js

@@ -0,0 +1,128 @@
+/**
+ * VERSIONED SQLite migrations. The SQL is embedded (no asset to copy into
+ * `dist`). The runner applies the missing versions within a transaction.
+ *
+ * Schema centered on `installation_id` (OPAQUE token issued by ShopiMind, treated
+ * as a string). The local store is the integrator's CORRELATION REGISTRY: it links
+ * a ShopiMind installation (`installation_id`) to ITS internal account
+ * (`external_account_ref`/`_name`). No internal ShopiMind id (PK, `id_shop`) is
+ * stored here.
+ *
+ * Encryption — be honest about what is and is NOT protected:
+ *   - ONLY secrets written via `integration_state.setSecret` are encrypted at rest
+ *     (AES-256-GCM, `encrypted = 1`).
+ *   - PII (`shop_domain`, `shop_name`, `external_account_name`) and plain values
+ *     written via `integration_state.set` are stored IN CLEAR TEXT.
+ *   - The SQLite file itself is NOT encrypted. Protect it via filesystem/disk
+ *     controls if at-rest confidentiality of the whole store is required.
+ *
+ * Migrations are APPEND-ONLY: NEVER edit a migration that has already been
+ * published/shipped — add a new versioned migration instead.
+ */
+export const MIGRATIONS = [
+    {
+        version: 1,
+        name: 'core',
+        sql: `
+      CREATE TABLE installs (
+        installation_id        TEXT PRIMARY KEY,
+        shop_domain            TEXT,
+        shop_name              TEXT,
+        external_account_ref   TEXT,
+        external_account_name  TEXT,
+        status                 TEXT NOT NULL DEFAULT 'inactive',
+        installed_at           TEXT,
+        activated_at           TEXT,
+        deactivated_at         TEXT,
+        uninstalled_at         TEXT,
+        created_at             TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at             TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX idx_installs_status ON installs(status);
+
+      CREATE TABLE webhook_log (
+        id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+        event                TEXT,
+        installation_id      TEXT,
+        signature_ok         INTEGER NOT NULL DEFAULT 0,
+        payload_json         TEXT,
+        created_at           TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX idx_webhook_log_install ON webhook_log(installation_id);
+
+      CREATE TABLE integration_state (
+        installation_id      TEXT NOT NULL,
+        key                  TEXT NOT NULL,
+        value                TEXT,
+        encrypted            INTEGER NOT NULL DEFAULT 0,
+        updated_at           TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (installation_id, key)
+      );
+    `,
+    },
+    {
+        version: 2,
+        name: 'sync',
+        sql: `
+      CREATE TABLE sync_run (
+        id                   INTEGER PRIMARY KEY AUTOINCREMENT,
+        installation_id      TEXT NOT NULL,
+        status               TEXT NOT NULL DEFAULT 'running',
+        summary_json         TEXT,
+        started_at           TEXT NOT NULL DEFAULT (datetime('now')),
+        finished_at          TEXT
+      );
+      CREATE INDEX idx_sync_run_install ON sync_run(installation_id);
+
+      -- Cursor per (installation, entity, source_key). source_key = '' for the
+      -- global scope; a store id for the 'per-source' scope.
+      CREATE TABLE sync_cursor (
+        installation_id      TEXT NOT NULL,
+        entity               TEXT NOT NULL,
+        source_key           TEXT NOT NULL DEFAULT '',
+        last_synced_at       TEXT,
+        last_status          TEXT,
+        last_error           TEXT,
+        items                INTEGER NOT NULL DEFAULT 0,
+        updated_at           TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (installation_id, entity, source_key)
+      );
+    `,
+    },
+    {
+        version: 3,
+        name: 'inbound',
+        sql: `
+      -- Log of INBOUND calls (integrator app -> integration, the middleware).
+      -- Backs idempotency (unique key per installation) and audit. Persisted BEFORE
+      -- processing -> no event lost; a replay after success is short-circuited.
+      CREATE TABLE inbound_event (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        installation_id  TEXT NOT NULL,
+        idempotency_key  TEXT NOT NULL,
+        action           TEXT,
+        status           TEXT NOT NULL DEFAULT 'received',
+        error            TEXT,
+        received_at      TEXT NOT NULL DEFAULT (datetime('now')),
+        processed_at     TEXT
+      );
+      CREATE UNIQUE INDEX idx_inbound_event_key ON inbound_event(installation_id, idempotency_key);
+    `,
+    },
+    {
+        version: 4,
+        name: 'webhook_dedup',
+        sql: `
+      -- Replay protection for lifecycle webhooks: we claim a key derived from the
+      -- SIGNATURE (unique per timestamp+body) BEFORE processing. A verbatim replay
+      -- (same signature) within the tolerance window is short-circuited. The row is
+      -- kept only if processing SUCCEEDS (otherwise released -> retry allowed).
+      CREATE TABLE webhook_seen (
+        installation_id  TEXT NOT NULL,
+        dedup_key        TEXT NOT NULL,
+        created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (installation_id, dedup_key)
+      );
+    `,
+    },
+];

package/dist/store/repositories.d.ts

@@ -0,0 +1,102 @@
+import type DatabaseT from 'better-sqlite3';
+import type { SecretCipher } from '../security/crypto.js';
+import type { InstallRow, InstallUpsert, CursorRow, CursorWrite, SyncRunRow, InboundEventRow } from './types.js';
+/** Installs (one row per installation). COALESCE upsert: a null field does not overwrite. */
+export declare class InstallRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    upsert(u: InstallUpsert): void;
+    setStatus(installationId: string, status: InstallRow['status'], stamps?: {
+        activated_at?: string | null;
+        deactivated_at?: string | null;
+        uninstalled_at?: string | null;
+    }): void;
+    /** Sets the INTEGRATOR account associated with the installation (the correlation bridge). */
+    setExternalAccount(installationId: string, ref: string | null, name?: string | null): void;
+    find(installationId: string): InstallRow | undefined;
+    listActive(): InstallRow[];
+}
+/** Webhook log. The `payload_json` MUST already be redacted by the runtime. */
+export declare class WebhookLogRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    log(entry: {
+        event: string | null;
+        installation_id?: string | null;
+        signature_ok: boolean;
+        payload_json: string;
+    }): void;
+    /** Retention: deletes log rows older than `days` days. Returns the number of rows removed. */
+    purgeOlderThan(days: number): number;
+}
+/** Replay protection for lifecycle webhooks (key derived from the signature). */
+export declare class WebhookSeenRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    /** Atomically claims processing; `false` if the signature was already seen (replay). */
+    claim(installationId: string, dedupKey: string): boolean;
+    /** Releases a claim (failed processing) -> an identical resend can retry. */
+    release(installationId: string, dedupKey: string): void;
+    /** Retention: deletes dedup rows older than `days` days. Returns the number of rows removed. */
+    purgeOlderThan(days: number): number;
+}
+/** Sync cursors, scoped by (installation, entity, source_key). */
+export declare class CursorRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    get(installationId: string, entity: string, sourceKey?: string): CursorRow | undefined;
+    set(installationId: string, entity: string, sourceKey: string, w: CursorWrite): void;
+}
+/** History of sync runs. */
+export declare class RunRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    start(installationId: string): number;
+    finish(runId: number, status: 'ok' | 'partial' | 'failed', summary: unknown): void;
+    recent(installationId: string, limit?: number): SyncRunRow[];
+}
+/**
+ * Private integration state (KV per installation). Sensitive values are encrypted
+ * at rest via the kit's `SecretCipher`.
+ */
+export declare class IntegrationStateRepo {
+    private readonly db;
+    private readonly cipher;
+    constructor(db: DatabaseT.Database, cipher: SecretCipher);
+    private write;
+    set(installationId: string, key: string, value: string): void;
+    setSecret(installationId: string, key: string, value: string): void;
+    get(installationId: string, key: string): string | null;
+    delete(installationId: string, key: string): void;
+}
+/** Log of inbound calls (middleware idempotency + audit). */
+export declare class InboundEventRepo {
+    private readonly db;
+    constructor(db: DatabaseT.Database);
+    find(installationId: string, idempotencyKey: string): InboundEventRow | undefined;
+    /**
+     * ATOMICALLY claims the processing of an inbound call (anti-TOCTOU). The INSERT
+     * `ON CONFLICT DO NOTHING` relies on the UNIQUE index (installation_id, idempotency_key):
+     * - `fresh: true` => row created by THIS call -> it is responsible for processing;
+     * - `fresh: false` => a row already existed -> `status` tells where it stands
+     *   ('received' = in progress/already claimed, 'done' = processed, 'failed' = retryable).
+     */
+    claim(installationId: string, idempotencyKey: string, action: string | null): {
+        rowId: number;
+        fresh: boolean;
+        status: InboundEventRow['status'];
+    };
+    finish(id: number, status: 'done' | 'failed', error?: string | null): void;
+    /** Retention: deletes inbound rows older than `days` days. Returns the number of rows removed. */
+    purgeOlderThan(days: number): number;
+}
+export interface Repositories {
+    installs: InstallRepo;
+    webhookLog: WebhookLogRepo;
+    webhookSeen: WebhookSeenRepo;
+    cursors: CursorRepo;
+    runs: RunRepo;
+    state: IntegrationStateRepo;
+    inboundEvents: InboundEventRepo;
+}
+export declare function createRepositories(db: DatabaseT.Database, cipher: SecretCipher): Repositories;