@ekanos/sdk 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,19 @@
+/**
+ * @ekanos/sdk/testing — the partner test harness surface.
+ *
+ * `createMockContext()` is the day-1 in-memory `IntegrationContext`
+ * (proposal §4): partners code and test against `ctx` here before anything
+ * lands in a sandbox. Self-contained — no Supabase, no Vault, no network —
+ * and enforcement (storage schemas, secret tiers, egress) is the same
+ * shared implementation from `@ekanos/sdk/context` that production uses.
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("Context & testing entrypoints (P1)").
+ */
+export { createMockContext } from './mock-context.js';
+// Event-surface invocation: run declared webhook/schedule handlers locally,
+// with the same payload-validation and context-derivation semantics the real
+// transports will have. Used by partner unit tests and the harness Triggers
+// panel alike.
+export { invokeWebhook, invokeSchedule } from './invoke.js';
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AASnD,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,eAAe;AACf,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC","sourcesContent":["/**\n * @ekanos/sdk/testing — the partner test harness surface.\n *\n * `createMockContext()` is the day-1 in-memory `IntegrationContext`\n * (proposal §4): partners code and test against `ctx` here before anything\n * lands in a sandbox. Self-contained — no Supabase, no Vault, no network —\n * and enforcement (storage schemas, secret tiers, egress) is the same\n * shared implementation from `@ekanos/sdk/context` that production uses.\n *\n * Surface discipline: additions require an entry in\n * docs/devex/sdk-export-map.md (\"Context & testing entrypoints (P1)\").\n */\n\nexport { createMockContext } from './mock-context';\nexport type {\n  MockContextOptions,\n  MockFetchHandler,\n  MockIntegrationContext,\n  RecordedFetchCall,\n  RecordedLog,\n} from './mock-context';\n\n// Event-surface invocation: run declared webhook/schedule handlers locally,\n// with the same payload-validation and context-derivation semantics the real\n// transports will have. Used by partner unit tests and the harness Triggers\n// panel alike.\nexport { invokeWebhook, invokeSchedule } from './invoke';\nexport type {\n  DefinitionContextOptions,\n  InvokeWebhookOptions,\n  InvokeScheduleOptions,\n  WebhookInvocationOutcome,\n  ScheduleInvocationOutcome,\n} from './invoke';\n"]}

package/dist/testing/invoke.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Local execution of the declared event surfaces — `invokeWebhook()` and
+ * `invokeSchedule()` deliver to a definition's handlers exactly the way a
+ * transport would, against a `createMockContext()` built FROM the definition
+ * (its slug, storage schemas, and egress list), so a handler unit test
+ * exercises the same schemas and the same egress allowlist production will.
+ *
+ * Transport semantics reproduced here, so they cannot drift from the docs:
+ *  - the payload is parsed against `payloadSchema` BEFORE the handler runs;
+ *    an invalid payload throws and the handler never sees it;
+ *  - signature verification is the TRANSPORT's job — the local transport
+ *    logs it as skipped (one warn line on `ctx.logs`), it never verifies and
+ *    the handler never does either;
+ *  - a schedule invocation carries `{scheduledFor, invokedAt, trigger}` with
+ *    `trigger: 'manual'` by default (a human pressed the button).
+ */
+import type { IntegrationDefinition, ScheduleInvocation, ScheduleResult, StorageSchemas, WebhookEvent, WebhookResult } from '@ekanos/integration-schema';
+import { type MockContextOptions, type MockIntegrationContext } from './mock-context.js';
+/**
+ * Everything `createMockContext` takes except the fields the definition
+ * itself is the authority on — the helpers derive `integration`,
+ * `storageSchemas`, and `egress` from the definition so a test cannot
+ * accidentally run a handler against schemas or an allowlist the definition
+ * does not declare.
+ */
+export type DefinitionContextOptions<Schemas extends StorageSchemas = StorageSchemas> = Omit<MockContextOptions<Schemas>, 'integration' | 'storageSchemas' | 'egress'>;
+interface BaseInvokeOptions<Schemas extends StorageSchemas> {
+    /**
+     * Reuse an existing mock context so state (storage, secrets, logs)
+     * accumulates across invocations — the harness does this. When set,
+     * `context` wins and `contextOptions` must be omitted.
+     */
+    context?: MockIntegrationContext<Schemas>;
+    /** Seeds and stubs for the context the helper creates. */
+    contextOptions?: DefinitionContextOptions<Schemas>;
+}
+export interface InvokeWebhookOptions<Schemas extends StorageSchemas = StorageSchemas> extends BaseInvokeOptions<Schemas> {
+    /** Delivery headers the event carries. Defaults to `{}`. */
+    headers?: Record<string, string>;
+    /** Transport-assigned event id. Defaults to a random UUID. */
+    eventId?: string;
+    /** ISO receipt time. Defaults to now. */
+    receivedAt?: string;
+}
+export interface InvokeScheduleOptions<Schemas extends StorageSchemas = StorageSchemas> extends BaseInvokeOptions<Schemas> {
+    /** Defaults to `'manual'` — a human pressed "Run now". */
+    trigger?: ScheduleInvocation['trigger'];
+    /** The tick this invocation stands for. Defaults to now. */
+    scheduledFor?: string;
+}
+export interface WebhookInvocationOutcome<Schemas extends StorageSchemas = StorageSchemas> {
+    result: WebhookResult;
+    /** The event the handler received (payload already schema-parsed). */
+    event: WebhookEvent;
+    /** The context the handler ran against — assert on its recordings. */
+    ctx: MockIntegrationContext<Schemas>;
+}
+export interface ScheduleInvocationOutcome<Schemas extends StorageSchemas = StorageSchemas> {
+    result: ScheduleResult;
+    invocation: ScheduleInvocation;
+    ctx: MockIntegrationContext<Schemas>;
+}
+/**
+ * Delivers one payload to one declared webhook, the way a transport would.
+ * Throws if the id is undeclared or the payload fails `payloadSchema`;
+ * returns the handler's result plus the event and the context it ran
+ * against. Never verifies signatures — that is the transport's job, and the
+ * local transport records the skip as a `warn` log line.
+ */
+export declare function invokeWebhook<Schemas extends StorageSchemas = StorageSchemas>(definition: IntegrationDefinition<Schemas>, webhookId: string, payload: unknown, options?: InvokeWebhookOptions<Schemas>): Promise<WebhookInvocationOutcome<Schemas>>;
+/**
+ * Fires one declared schedule, the way the scheduler would. Throws if the id
+ * is undeclared; returns the handler's result plus the invocation and the
+ * context it ran against.
+ */
+export declare function invokeSchedule<Schemas extends StorageSchemas = StorageSchemas>(definition: IntegrationDefinition<Schemas>, scheduleId: string, options?: InvokeScheduleOptions<Schemas>): Promise<ScheduleInvocationOutcome<Schemas>>;
+export {};

package/dist/testing/invoke.js

@@ -0,0 +1,83 @@
+import { createMockContext, } from './mock-context.js';
+function contextFor(definition, options) {
+    var _a, _b;
+    if (options.context) {
+        if (options.contextOptions) {
+            throw new TypeError('Pass either `context` (reuse an existing mock context) or ' +
+                '`contextOptions` (seed a fresh one), not both — seeds cannot be ' +
+                'applied to a context that already exists.');
+        }
+        return options.context;
+    }
+    return createMockContext(Object.assign(Object.assign(Object.assign(Object.assign({}, ((_a = options.contextOptions) !== null && _a !== void 0 ? _a : {})), { integration: { slug: definition.slug } }), (definition.storage ? { storageSchemas: definition.storage } : {})), { egress: (_b = definition.egress) !== null && _b !== void 0 ? _b : [] }));
+}
+function listIds(ids) {
+    return ids.length > 0 ? ids.map((id) => `"${id}"`).join(', ') : '(none)';
+}
+/**
+ * Delivers one payload to one declared webhook, the way a transport would.
+ * Throws if the id is undeclared or the payload fails `payloadSchema`;
+ * returns the handler's result plus the event and the context it ran
+ * against. Never verifies signatures — that is the transport's job, and the
+ * local transport records the skip as a `warn` log line.
+ */
+export async function invokeWebhook(definition, webhookId, payload, options = {}) {
+    var _a, _b, _c, _d, _e;
+    const webhook = ((_a = definition.webhooks) !== null && _a !== void 0 ? _a : []).find((w) => w.id === webhookId);
+    if (!webhook) {
+        throw new Error(`Integration "${definition.slug}" declares no webhook "${webhookId}". ` +
+            `Declared webhook ids: ${listIds(((_b = definition.webhooks) !== null && _b !== void 0 ? _b : []).map((w) => w.id))}.`);
+    }
+    const parsed = webhook.payloadSchema.safeParse(payload);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+            return `  - ${path}: ${issue.message}`;
+        })
+            .join('\n');
+        throw new Error(`Payload rejected by webhook "${webhookId}"'s payloadSchema — the ` +
+            `transport refuses such a delivery before the handler runs:\n${issues}`);
+    }
+    const ctx = contextFor(definition, options);
+    if (webhook.signature !== 'none') {
+        ctx.logger.warn({
+            webhookId,
+            header: webhook.signature.header,
+            secretName: webhook.signature.secretName,
+        }, 'Signature verification SKIPPED (local transport). The host ingress ' +
+            'verifies this header against the named secret before the handler ' +
+            'runs — handlers never verify signatures themselves.');
+    }
+    const event = {
+        id: (_c = options.eventId) !== null && _c !== void 0 ? _c : `evt_${crypto.randomUUID()}`,
+        receivedAt: (_d = options.receivedAt) !== null && _d !== void 0 ? _d : new Date().toISOString(),
+        headers: (_e = options.headers) !== null && _e !== void 0 ? _e : {},
+        payload: parsed.data,
+    };
+    const result = await webhook.handler(ctx, event);
+    return { result, event, ctx };
+}
+/**
+ * Fires one declared schedule, the way the scheduler would. Throws if the id
+ * is undeclared; returns the handler's result plus the invocation and the
+ * context it ran against.
+ */
+export async function invokeSchedule(definition, scheduleId, options = {}) {
+    var _a, _b, _c, _d;
+    const schedule = ((_a = definition.schedules) !== null && _a !== void 0 ? _a : []).find((s) => s.id === scheduleId);
+    if (!schedule) {
+        throw new Error(`Integration "${definition.slug}" declares no schedule "${scheduleId}". ` +
+            `Declared schedule ids: ${listIds(((_b = definition.schedules) !== null && _b !== void 0 ? _b : []).map((s) => s.id))}.`);
+    }
+    const ctx = contextFor(definition, options);
+    const now = new Date().toISOString();
+    const invocation = {
+        scheduledFor: (_c = options.scheduledFor) !== null && _c !== void 0 ? _c : now,
+        invokedAt: now,
+        trigger: (_d = options.trigger) !== null && _d !== void 0 ? _d : 'manual',
+    };
+    const result = await schedule.handler(ctx, invocation);
+    return { result, invocation, ctx };
+}
+//# sourceMappingURL=invoke.js.map

package/dist/testing/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../src/testing/invoke.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Local execution of the declared event surfaces — `invokeWebhook()` and\n * `invokeSchedule()` deliver to a definition's handlers exactly the way a\n * transport would, against a `createMockContext()` built FROM the definition\n * (its slug, storage schemas, and egress list), so a handler unit test\n * exercises the same schemas and the same egress allowlist production will.\n *\n * Transport semantics reproduced here, so they cannot drift from the docs:\n *  - the payload is parsed against `payloadSchema` BEFORE the handler runs;\n *    an invalid payload throws and the handler never sees it;\n *  - signature verification is the TRANSPORT's job — the local transport\n *    logs it as skipped (one warn line on `ctx.logs`), it never verifies and\n *    the handler never does either;\n *  - a schedule invocation carries `{scheduledFor, invokedAt, trigger}` with\n *    `trigger: 'manual'` by default (a human pressed the button).\n */\nimport type {\n  IntegrationDefinition,\n  ScheduleInvocation,\n  ScheduleResult,\n  StorageSchemas,\n  WebhookEvent,\n  WebhookResult,\n} from '@ekanos/integration-schema';\n\nimport {\n  type MockContextOptions,\n  type MockIntegrationContext,\n  createMockContext,\n} from './mock-context';\n\n/**\n * Everything `createMockContext` takes except the fields the definition\n * itself is the authority on — the helpers derive `integration`,\n * `storageSchemas`, and `egress` from the definition so a test cannot\n * accidentally run a handler against schemas or an allowlist the definition\n * does not declare.\n */\nexport type DefinitionContextOptions<\n  Schemas extends StorageSchemas = StorageSchemas,\n> = Omit<\n  MockContextOptions<Schemas>,\n  'integration' | 'storageSchemas' | 'egress'\n>;\n\ninterface BaseInvokeOptions<Schemas extends StorageSchemas> {\n  /**\n   * Reuse an existing mock context so state (storage, secrets, logs)\n   * accumulates across invocations — the harness does this. When set,\n   * `context` wins and `contextOptions` must be omitted.\n   */\n  context?: MockIntegrationContext<Schemas>;\n  /** Seeds and stubs for the context the helper creates. */\n  contextOptions?: DefinitionContextOptions<Schemas>;\n}\n\nexport interface InvokeWebhookOptions<\n  Schemas extends StorageSchemas = StorageSchemas,\n> extends BaseInvokeOptions<Schemas> {\n  /** Delivery headers the event carries. Defaults to `{}`. */\n  headers?: Record<string, string>;\n  /** Transport-assigned event id. Defaults to a random UUID. */\n  eventId?: string;\n  /** ISO receipt time. Defaults to now. */\n  receivedAt?: string;\n}\n\nexport interface InvokeScheduleOptions<\n  Schemas extends StorageSchemas = StorageSchemas,\n> extends BaseInvokeOptions<Schemas> {\n  /** Defaults to `'manual'` — a human pressed \"Run now\". */\n  trigger?: ScheduleInvocation['trigger'];\n  /** The tick this invocation stands for. Defaults to now. */\n  scheduledFor?: string;\n}\n\nexport interface WebhookInvocationOutcome<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  result: WebhookResult;\n  /** The event the handler received (payload already schema-parsed). */\n  event: WebhookEvent;\n  /** The context the handler ran against — assert on its recordings. */\n  ctx: MockIntegrationContext<Schemas>;\n}\n\nexport interface ScheduleInvocationOutcome<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  result: ScheduleResult;\n  invocation: ScheduleInvocation;\n  ctx: MockIntegrationContext<Schemas>;\n}\n\nfunction contextFor<Schemas extends StorageSchemas>(\n  definition: IntegrationDefinition<Schemas>,\n  options: BaseInvokeOptions<Schemas>,\n): MockIntegrationContext<Schemas> {\n  if (options.context) {\n    if (options.contextOptions) {\n      throw new TypeError(\n        'Pass either `context` (reuse an existing mock context) or ' +\n          '`contextOptions` (seed a fresh one), not both — seeds cannot be ' +\n          'applied to a context that already exists.',\n      );\n    }\n    return options.context;\n  }\n\n  return createMockContext<Schemas>({\n    ...(options.contextOptions ?? {}),\n    integration: { slug: definition.slug },\n    ...(definition.storage ? { storageSchemas: definition.storage } : {}),\n    egress: definition.egress ?? [],\n  });\n}\n\nfunction listIds(ids: readonly string[]): string {\n  return ids.length > 0 ? ids.map((id) => `\"${id}\"`).join(', ') : '(none)';\n}\n\n/**\n * Delivers one payload to one declared webhook, the way a transport would.\n * Throws if the id is undeclared or the payload fails `payloadSchema`;\n * returns the handler's result plus the event and the context it ran\n * against. Never verifies signatures — that is the transport's job, and the\n * local transport records the skip as a `warn` log line.\n */\nexport async function invokeWebhook<\n  Schemas extends StorageSchemas = StorageSchemas,\n>(\n  definition: IntegrationDefinition<Schemas>,\n  webhookId: string,\n  payload: unknown,\n  options: InvokeWebhookOptions<Schemas> = {},\n): Promise<WebhookInvocationOutcome<Schemas>> {\n  const webhook = (definition.webhooks ?? []).find((w) => w.id === webhookId);\n\n  if (!webhook) {\n    throw new Error(\n      `Integration \"${definition.slug}\" declares no webhook \"${webhookId}\". ` +\n        `Declared webhook ids: ${listIds((definition.webhooks ?? []).map((w) => w.id))}.`,\n    );\n  }\n\n  const parsed = webhook.payloadSchema.safeParse(payload);\n\n  if (!parsed.success) {\n    const issues = parsed.error.issues\n      .map((issue) => {\n        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';\n        return `  - ${path}: ${issue.message}`;\n      })\n      .join('\\n');\n    throw new Error(\n      `Payload rejected by webhook \"${webhookId}\"'s payloadSchema — the ` +\n        `transport refuses such a delivery before the handler runs:\\n${issues}`,\n    );\n  }\n\n  const ctx = contextFor(definition, options);\n\n  if (webhook.signature !== 'none') {\n    ctx.logger.warn(\n      {\n        webhookId,\n        header: webhook.signature.header,\n        secretName: webhook.signature.secretName,\n      },\n      'Signature verification SKIPPED (local transport). The host ingress ' +\n        'verifies this header against the named secret before the handler ' +\n        'runs — handlers never verify signatures themselves.',\n    );\n  }\n\n  const event: WebhookEvent = {\n    id: options.eventId ?? `evt_${crypto.randomUUID()}`,\n    receivedAt: options.receivedAt ?? new Date().toISOString(),\n    headers: options.headers ?? {},\n    payload: parsed.data,\n  };\n\n  const result = await webhook.handler(ctx, event);\n\n  return { result, event, ctx };\n}\n\n/**\n * Fires one declared schedule, the way the scheduler would. Throws if the id\n * is undeclared; returns the handler's result plus the invocation and the\n * context it ran against.\n */\nexport async function invokeSchedule<\n  Schemas extends StorageSchemas = StorageSchemas,\n>(\n  definition: IntegrationDefinition<Schemas>,\n  scheduleId: string,\n  options: InvokeScheduleOptions<Schemas> = {},\n): Promise<ScheduleInvocationOutcome<Schemas>> {\n  const schedule = (definition.schedules ?? []).find(\n    (s) => s.id === scheduleId,\n  );\n\n  if (!schedule) {\n    throw new Error(\n      `Integration \"${definition.slug}\" declares no schedule \"${scheduleId}\". ` +\n        `Declared schedule ids: ${listIds((definition.schedules ?? []).map((s) => s.id))}.`,\n    );\n  }\n\n  const ctx = contextFor(definition, options);\n  const now = new Date().toISOString();\n\n  const invocation: ScheduleInvocation = {\n    scheduledFor: options.scheduledFor ?? now,\n    invokedAt: now,\n    trigger: options.trigger ?? 'manual',\n  };\n\n  const result = await schedule.handler(ctx, invocation);\n\n  return { result, invocation, ctx };\n}\n"]}

package/dist/testing/mock-context.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `createMockContext()` — the day-1 in-memory `IntegrationContext` for the
+ * partner harness (proposal §4, amended by rulings 1–4). Self-contained:
+ * nothing here touches Supabase, Vault, or the network. Enforcement is the
+ * SAME shared implementation the production wrapper uses
+ * (`@ekanos/sdk/context`): schema validation via `parseStorageValue`, egress
+ * via `isEgressAllowed` — a test that passes the mock cannot be a schema or
+ * egress surprise later.
+ */
+import type { z } from 'zod';
+import type { IntegrationActor, IntegrationContext, StorageKeySchema, StorageSchemaMap, StorageSchemas } from '../context/types.js';
+type ScopeSeed<M> = M extends StorageSchemaMap ? {
+    [K in keyof M & string]?: z.input<StorageKeySchema<M[K]>>;
+} : Record<never, never>;
+export interface MockFetchHandler {
+    /** A string matches URLs that start with it; a RegExp is tested against the full URL. */
+    match: string | RegExp;
+    respond: (request: Request) => Response | Promise<Response>;
+}
+export interface MockContextOptions<Schemas extends StorageSchemas = StorageSchemas> {
+    accountId?: string;
+    accountSlug?: string | null;
+    userId?: string | null;
+    actor?: IntegrationActor;
+    sourceId?: string | null;
+    timezone?: string | null;
+    integration: {
+        slug: string;
+        productId?: string;
+    };
+    /**
+     * The storage declaration `defineIntegration({ storage })` will carry —
+     * the mock enforces the identical schemas via the same shared validator
+     * (ruling 1). Omit it and every storage access throws.
+     */
+    storageSchemas?: Schemas;
+    /** Seed rows: key → data, per scope. Validated on construction via the write path. */
+    storage?: {
+        account?: ScopeSeed<Schemas['account']>;
+        user?: ScopeSeed<Schemas['user']>;
+    };
+    /**
+     * Seed secrets, by tier (ruling 2): `account` values are the rows this
+     * integration stored — writable via `secrets.set()`; `admin` values stand
+     * in for admin-issued source/global-tier credentials — readable, and a
+     * `set()` against a name resolvable only there throws `SecretAccessError`.
+     */
+    secrets?: {
+        account?: Record<string, string>;
+        admin?: Record<string, string>;
+    };
+    /** Same allowlist the manifest would declare — enforced by the stub. */
+    egress?: readonly string[];
+    /** Programmable responses; unmatched allowed calls resolve 200 `{}`. */
+    fetchHandlers?: MockFetchHandler[];
+}
+export interface RecordedFetchCall {
+    url: string;
+    init?: RequestInit;
+    denied: boolean;
+}
+export interface RecordedLog {
+    level: 'debug' | 'info' | 'warn' | 'error';
+    context: Record<string, unknown>;
+    message: string;
+}
+export interface MockIntegrationContext<Schemas extends StorageSchemas = StorageSchemas> extends IntegrationContext<Schemas> {
+    /** Every ctx.fetch call, allowed or denied, in order. */
+    readonly fetchCalls: readonly RecordedFetchCall[];
+    /** Every log line, per level. */
+    readonly logs: readonly RecordedLog[];
+    /** Current readable storage state (expired entries excluded), key → data. */
+    dumpStorage(): {
+        account: Record<string, unknown>;
+        user: Record<string, unknown>;
+    };
+}
+export declare function createMockContext<Schemas extends StorageSchemas = StorageSchemas>(options: MockContextOptions<Schemas>): MockIntegrationContext<Schemas>;
+export {};

package/dist/testing/mock-context.js

@@ -0,0 +1,206 @@
+import { isEgressAllowed } from '../context/egress.js';
+import { EgressDeniedError, SecretAccessError } from '../context/errors.js';
+import { assertStorageKeyDeclared, assertStorageKeyWritable, parseStorageValue, } from '../context/storage-validation.js';
+function isExpired(row) {
+    return row.expiresAt !== null && Date.parse(row.expiresAt) <= Date.now();
+}
+function parseExpiresAt(options) {
+    const expiresAt = options === null || options === void 0 ? void 0 : options.expiresAt;
+    if (expiresAt === undefined)
+        return null;
+    if (Number.isNaN(Date.parse(expiresAt))) {
+        throw new TypeError(`expiresAt "${expiresAt}" is not a parseable timestamp. Pass an ` +
+            `ISO-8601 string, e.g. new Date(Date.now() + 60_000).toISOString().`);
+    }
+    return expiresAt;
+}
+function createInMemoryStore(args) {
+    const { scope, schemas, rows, guard } = args;
+    return {
+        async get(key) {
+            guard();
+            assertStorageKeyDeclared({ scope, key, schemas });
+            const row = rows.get(key);
+            if (!row)
+                return null;
+            if (isExpired(row)) {
+                rows.delete(key);
+                return null;
+            }
+            const data = parseStorageValue({
+                scope,
+                key,
+                operation: 'read',
+                schemas,
+                value: row.data,
+            });
+            return {
+                data,
+                externalId: row.externalId,
+                expiresAt: row.expiresAt,
+                updatedAt: row.updatedAt,
+            };
+        },
+        async set(key, data, options) {
+            var _a;
+            guard();
+            assertStorageKeyWritable({ scope, key });
+            const parsed = parseStorageValue({
+                scope,
+                key,
+                operation: 'write',
+                schemas,
+                value: data,
+            });
+            rows.set(key, {
+                data: parsed,
+                externalId: (_a = options === null || options === void 0 ? void 0 : options.externalId) !== null && _a !== void 0 ? _a : null,
+                expiresAt: parseExpiresAt(options),
+                updatedAt: new Date().toISOString(),
+            });
+        },
+        async delete(key) {
+            guard();
+            assertStorageKeyWritable({ scope, key });
+            assertStorageKeyDeclared({ scope, key, schemas });
+            rows.delete(key);
+        },
+    };
+}
+function dumpScope(rows) {
+    const out = {};
+    for (const [key, row] of rows) {
+        if (!isExpired(row))
+            out[key] = row.data;
+    }
+    return out;
+}
+export function createMockContext(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+    const userId = options.userId !== undefined ? options.userId : 'mock-user-id';
+    const actor = (_a = options.actor) !== null && _a !== void 0 ? _a : (userId !== null
+        ? { kind: 'user', userId }
+        : { kind: 'machine', tokenId: 'mock-token-id', createdBy: null });
+    const schemas = (_b = options.storageSchemas) !== null && _b !== void 0 ? _b : {};
+    const accountRows = new Map();
+    const userRows = new Map();
+    const seedScope = (scope, rows, seed) => {
+        for (const [key, value] of Object.entries(seed !== null && seed !== void 0 ? seed : {})) {
+            const parsed = parseStorageValue({
+                scope,
+                key,
+                operation: 'write',
+                schemas: schemas[scope],
+                value,
+            });
+            rows.set(key, {
+                data: parsed,
+                externalId: null,
+                expiresAt: null,
+                updatedAt: new Date().toISOString(),
+            });
+        }
+    };
+    seedScope('account', accountRows, (_c = options.storage) === null || _c === void 0 ? void 0 : _c.account);
+    seedScope('user', userRows, (_d = options.storage) === null || _d === void 0 ? void 0 : _d.user);
+    const guardUserScope = () => {
+        if (actor.kind === 'machine') {
+            throw new Error('ctx.storage.user is unavailable for machine actors: there is no ' +
+                'user to scope the row to. Store machine-written state in ' +
+                'ctx.storage.account instead.');
+        }
+    };
+    // The stores validate every key and value at runtime via the shared
+    // validator; the cast narrows the runtime-checked store to the
+    // schema-typed interface the declaration promises.
+    const storage = {
+        account: createInMemoryStore({
+            scope: 'account',
+            schemas: schemas.account,
+            rows: accountRows,
+            guard: () => void 0,
+        }),
+        user: createInMemoryStore({
+            scope: 'user',
+            schemas: schemas.user,
+            rows: userRows,
+            guard: guardUserScope,
+        }),
+    };
+    const accountSecrets = new Map(Object.entries((_f = (_e = options.secrets) === null || _e === void 0 ? void 0 : _e.account) !== null && _f !== void 0 ? _f : {}));
+    const adminSecrets = new Map(Object.entries((_h = (_g = options.secrets) === null || _g === void 0 ? void 0 : _g.admin) !== null && _h !== void 0 ? _h : {}));
+    const secrets = {
+        async get(name) {
+            var _a, _b;
+            return (_b = (_a = accountSecrets.get(name)) !== null && _a !== void 0 ? _a : adminSecrets.get(name)) !== null && _b !== void 0 ? _b : null;
+        },
+        async names() {
+            return [
+                ...new Set([...accountSecrets.keys(), ...adminSecrets.keys()]),
+            ].sort();
+        },
+        async set(name, value) {
+            if (!accountSecrets.has(name) && adminSecrets.has(name)) {
+                throw new SecretAccessError(name);
+            }
+            accountSecrets.set(name, value);
+        },
+    };
+    const fetchCalls = [];
+    const egress = (_j = options.egress) !== null && _j !== void 0 ? _j : [];
+    const fetchHandlers = (_k = options.fetchHandlers) !== null && _k !== void 0 ? _k : [];
+    // Not an async function: a denied call must throw synchronously, before
+    // any I/O (proposal §2.3) — same behavior the production wrapper has.
+    const fetch = (input, init) => {
+        const url = new URL(input).toString();
+        const allowed = isEgressAllowed(url, egress);
+        fetchCalls.push(init === undefined
+            ? { url, denied: !allowed }
+            : { url, init, denied: !allowed });
+        if (!allowed) {
+            throw new EgressDeniedError(new URL(url).origin);
+        }
+        const handler = fetchHandlers.find((candidate) => typeof candidate.match === 'string'
+            ? url.startsWith(candidate.match)
+            : candidate.match.test(url));
+        if (handler) {
+            return Promise.resolve(handler.respond(new Request(url, init)));
+        }
+        return Promise.resolve(new Response('{}', {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        }));
+    };
+    const logs = [];
+    const record = (level) => (context, message) => {
+        logs.push({ level, context, message });
+    };
+    const logger = {
+        debug: record('debug'),
+        info: record('info'),
+        warn: record('warn'),
+        error: record('error'),
+    };
+    return {
+        accountId: (_l = options.accountId) !== null && _l !== void 0 ? _l : 'mock-account-id',
+        accountSlug: (_m = options.accountSlug) !== null && _m !== void 0 ? _m : null,
+        userId: actor.kind === 'machine' ? null : userId,
+        actor,
+        sourceId: (_o = options.sourceId) !== null && _o !== void 0 ? _o : null,
+        integration: {
+            slug: options.integration.slug,
+            productId: (_p = options.integration.productId) !== null && _p !== void 0 ? _p : 'mock-product-id',
+        },
+        timezone: (_q = options.timezone) !== null && _q !== void 0 ? _q : null,
+        storage,
+        secrets,
+        fetch,
+        logger,
+        fetchCalls,
+        logs,
+        dumpStorage() {
+            return { account: dumpScope(accountRows), user: dumpScope(userRows) };
+        },
+    };
+}
+//# sourceMappingURL=mock-context.js.map

package/dist/testing/mock-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-context.js","sourceRoot":"","sources":["../../src/testing/mock-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `createMockContext()` — the day-1 in-memory `IntegrationContext` for the\n * partner harness (proposal §4, amended by rulings 1–4). Self-contained:\n * nothing here touches Supabase, Vault, or the network. Enforcement is the\n * SAME shared implementation the production wrapper uses\n * (`@ekanos/sdk/context`): schema validation via `parseStorageValue`, egress\n * via `isEgressAllowed` — a test that passes the mock cannot be a schema or\n * egress surprise later.\n */\nimport type { z } from 'zod';\n\nimport { isEgressAllowed } from '../context/egress';\nimport { EgressDeniedError, SecretAccessError } from '../context/errors';\nimport {\n  assertStorageKeyDeclared,\n  assertStorageKeyWritable,\n  parseStorageValue,\n} from '../context/storage-validation';\nimport type {\n  IntegrationActor,\n  IntegrationContext,\n  IntegrationFetch,\n  IntegrationLogger,\n  IntegrationSecrets,\n  IntegrationStorage,\n  ScopedStore,\n  StorageEntry,\n  StorageKeySchema,\n  StorageSchemaMap,\n  StorageSchemas,\n  StorageWriteOptions,\n} from '../context/types';\n\ntype StorageScope = 'account' | 'user';\n\n// Seeds are typed off the DECLARED schema, resolved out of whichever\n// declaration form the key used — a bare zod schema or a\n// `{ schema, clientReadable }` descriptor.\ntype ScopeSeed<M> = M extends StorageSchemaMap\n  ? { [K in keyof M & string]?: z.input<StorageKeySchema<M[K]>> }\n  : Record<never, never>;\n\nexport interface MockFetchHandler {\n  /** A string matches URLs that start with it; a RegExp is tested against the full URL. */\n  match: string | RegExp;\n  respond: (request: Request) => Response | Promise<Response>;\n}\n\nexport interface MockContextOptions<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  accountId?: string;\n  accountSlug?: string | null;\n  userId?: string | null;\n  actor?: IntegrationActor;\n  sourceId?: string | null;\n  timezone?: string | null;\n  integration: { slug: string; productId?: string };\n  /**\n   * The storage declaration `defineIntegration({ storage })` will carry —\n   * the mock enforces the identical schemas via the same shared validator\n   * (ruling 1). Omit it and every storage access throws.\n   */\n  storageSchemas?: Schemas;\n  /** Seed rows: key → data, per scope. Validated on construction via the write path. */\n  storage?: {\n    account?: ScopeSeed<Schemas['account']>;\n    user?: ScopeSeed<Schemas['user']>;\n  };\n  /**\n   * Seed secrets, by tier (ruling 2): `account` values are the rows this\n   * integration stored — writable via `secrets.set()`; `admin` values stand\n   * in for admin-issued source/global-tier credentials — readable, and a\n   * `set()` against a name resolvable only there throws `SecretAccessError`.\n   */\n  secrets?: {\n    account?: Record<string, string>;\n    admin?: Record<string, string>;\n  };\n  /** Same allowlist the manifest would declare — enforced by the stub. */\n  egress?: readonly string[];\n  /** Programmable responses; unmatched allowed calls resolve 200 `{}`. */\n  fetchHandlers?: MockFetchHandler[];\n}\n\nexport interface RecordedFetchCall {\n  url: string;\n  init?: RequestInit;\n  denied: boolean;\n}\n\nexport interface RecordedLog {\n  level: 'debug' | 'info' | 'warn' | 'error';\n  context: Record<string, unknown>;\n  message: string;\n}\n\nexport interface MockIntegrationContext<\n  Schemas extends StorageSchemas = StorageSchemas,\n> extends IntegrationContext<Schemas> {\n  /** Every ctx.fetch call, allowed or denied, in order. */\n  readonly fetchCalls: readonly RecordedFetchCall[];\n  /** Every log line, per level. */\n  readonly logs: readonly RecordedLog[];\n  /** Current readable storage state (expired entries excluded), key → data. */\n  dumpStorage(): {\n    account: Record<string, unknown>;\n    user: Record<string, unknown>;\n  };\n}\n\ninterface StoredRow {\n  data: unknown;\n  externalId: string | null;\n  expiresAt: string | null;\n  updatedAt: string;\n}\n\nfunction isExpired(row: StoredRow): boolean {\n  return row.expiresAt !== null && Date.parse(row.expiresAt) <= Date.now();\n}\n\nfunction parseExpiresAt(\n  options: StorageWriteOptions | undefined,\n): string | null {\n  const expiresAt = options?.expiresAt;\n  if (expiresAt === undefined) return null;\n  if (Number.isNaN(Date.parse(expiresAt))) {\n    throw new TypeError(\n      `expiresAt \"${expiresAt}\" is not a parseable timestamp. Pass an ` +\n        `ISO-8601 string, e.g. new Date(Date.now() + 60_000).toISOString().`,\n    );\n  }\n  return expiresAt;\n}\n\nfunction createInMemoryStore(args: {\n  scope: StorageScope;\n  schemas: StorageSchemaMap | undefined;\n  rows: Map<string, StoredRow>;\n  guard: () => void;\n}): ScopedStore {\n  const { scope, schemas, rows, guard } = args;\n\n  return {\n    async get(key: string): Promise<StorageEntry<unknown> | null> {\n      guard();\n      assertStorageKeyDeclared({ scope, key, schemas });\n      const row = rows.get(key);\n      if (!row) return null;\n      if (isExpired(row)) {\n        rows.delete(key);\n        return null;\n      }\n      const data = parseStorageValue({\n        scope,\n        key,\n        operation: 'read',\n        schemas,\n        value: row.data,\n      });\n      return {\n        data,\n        externalId: row.externalId,\n        expiresAt: row.expiresAt,\n        updatedAt: row.updatedAt,\n      };\n    },\n\n    async set(\n      key: string,\n      data: unknown,\n      options?: StorageWriteOptions,\n    ): Promise<void> {\n      guard();\n      assertStorageKeyWritable({ scope, key });\n      const parsed = parseStorageValue({\n        scope,\n        key,\n        operation: 'write',\n        schemas,\n        value: data,\n      });\n      rows.set(key, {\n        data: parsed,\n        externalId: options?.externalId ?? null,\n        expiresAt: parseExpiresAt(options),\n        updatedAt: new Date().toISOString(),\n      });\n    },\n\n    async delete(key: string): Promise<void> {\n      guard();\n      assertStorageKeyWritable({ scope, key });\n      assertStorageKeyDeclared({ scope, key, schemas });\n      rows.delete(key);\n    },\n  };\n}\n\nfunction dumpScope(rows: Map<string, StoredRow>): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  for (const [key, row] of rows) {\n    if (!isExpired(row)) out[key] = row.data;\n  }\n  return out;\n}\n\nexport function createMockContext<\n  Schemas extends StorageSchemas = StorageSchemas,\n>(options: MockContextOptions<Schemas>): MockIntegrationContext<Schemas> {\n  const userId = options.userId !== undefined ? options.userId : 'mock-user-id';\n  const actor: IntegrationActor =\n    options.actor ??\n    (userId !== null\n      ? { kind: 'user', userId }\n      : { kind: 'machine', tokenId: 'mock-token-id', createdBy: null });\n\n  const schemas: StorageSchemas = options.storageSchemas ?? {};\n\n  const accountRows = new Map<string, StoredRow>();\n  const userRows = new Map<string, StoredRow>();\n\n  const seedScope = (\n    scope: StorageScope,\n    rows: Map<string, StoredRow>,\n    seed: Record<string, unknown> | undefined,\n  ) => {\n    for (const [key, value] of Object.entries(seed ?? {})) {\n      const parsed = parseStorageValue({\n        scope,\n        key,\n        operation: 'write',\n        schemas: schemas[scope],\n        value,\n      });\n      rows.set(key, {\n        data: parsed,\n        externalId: null,\n        expiresAt: null,\n        updatedAt: new Date().toISOString(),\n      });\n    }\n  };\n  seedScope('account', accountRows, options.storage?.account);\n  seedScope('user', userRows, options.storage?.user);\n\n  const guardUserScope = () => {\n    if (actor.kind === 'machine') {\n      throw new Error(\n        'ctx.storage.user is unavailable for machine actors: there is no ' +\n          'user to scope the row to. Store machine-written state in ' +\n          'ctx.storage.account instead.',\n      );\n    }\n  };\n\n  // The stores validate every key and value at runtime via the shared\n  // validator; the cast narrows the runtime-checked store to the\n  // schema-typed interface the declaration promises.\n  const storage = {\n    account: createInMemoryStore({\n      scope: 'account',\n      schemas: schemas.account,\n      rows: accountRows,\n      guard: () => void 0,\n    }),\n    user: createInMemoryStore({\n      scope: 'user',\n      schemas: schemas.user,\n      rows: userRows,\n      guard: guardUserScope,\n    }),\n  } as unknown as IntegrationStorage<Schemas>;\n\n  const accountSecrets = new Map(\n    Object.entries(options.secrets?.account ?? {}),\n  );\n  const adminSecrets = new Map(Object.entries(options.secrets?.admin ?? {}));\n\n  const secrets: IntegrationSecrets = {\n    async get(name) {\n      return accountSecrets.get(name) ?? adminSecrets.get(name) ?? null;\n    },\n    async names() {\n      return [\n        ...new Set([...accountSecrets.keys(), ...adminSecrets.keys()]),\n      ].sort();\n    },\n    async set(name, value) {\n      if (!accountSecrets.has(name) && adminSecrets.has(name)) {\n        throw new SecretAccessError(name);\n      }\n      accountSecrets.set(name, value);\n    },\n  };\n\n  const fetchCalls: RecordedFetchCall[] = [];\n  const egress = options.egress ?? [];\n  const fetchHandlers = options.fetchHandlers ?? [];\n\n  // Not an async function: a denied call must throw synchronously, before\n  // any I/O (proposal §2.3) — same behavior the production wrapper has.\n  const fetch: IntegrationFetch = (input, init) => {\n    const url = new URL(input).toString();\n    const allowed = isEgressAllowed(url, egress);\n    fetchCalls.push(\n      init === undefined\n        ? { url, denied: !allowed }\n        : { url, init, denied: !allowed },\n    );\n    if (!allowed) {\n      throw new EgressDeniedError(new URL(url).origin);\n    }\n    const handler = fetchHandlers.find((candidate) =>\n      typeof candidate.match === 'string'\n        ? url.startsWith(candidate.match)\n        : candidate.match.test(url),\n    );\n    if (handler) {\n      return Promise.resolve(handler.respond(new Request(url, init)));\n    }\n    return Promise.resolve(\n      new Response('{}', {\n        status: 200,\n        headers: { 'content-type': 'application/json' },\n      }),\n    );\n  };\n\n  const logs: RecordedLog[] = [];\n  const record =\n    (level: RecordedLog['level']) =>\n    (context: Record<string, unknown>, message: string) => {\n      logs.push({ level, context, message });\n    };\n  const logger: IntegrationLogger = {\n    debug: record('debug'),\n    info: record('info'),\n    warn: record('warn'),\n    error: record('error'),\n  };\n\n  return {\n    accountId: options.accountId ?? 'mock-account-id',\n    accountSlug: options.accountSlug ?? null,\n    userId: actor.kind === 'machine' ? null : userId,\n    actor,\n    sourceId: options.sourceId ?? null,\n    integration: {\n      slug: options.integration.slug,\n      productId: options.integration.productId ?? 'mock-product-id',\n    },\n    timezone: options.timezone ?? null,\n    storage,\n    secrets,\n    fetch,\n    logger,\n    fetchCalls,\n    logs,\n    dumpStorage() {\n      return { account: dumpScope(accountRows), user: dumpScope(userRows) };\n    },\n  };\n}\n"]}

package/dist/types/icon.d.ts

@@ -0,0 +1,12 @@
+import type { CSSProperties, ComponentType } from 'react';
+/**
+ * The shape an integration-declared icon renders through, defined locally so
+ * the SDK's root entrypoint imports nothing from the host. `@kit/ui/icon`
+ * owns the canonical definition (and the icon-name union lives in the host
+ * design system, which validates icon names at gate time); to the SDK an icon
+ * is just a component taking presentation props.
+ */
+export type IconRenderer = ComponentType<{
+    className?: string;
+    style?: CSSProperties;
+}>;

package/dist/types/icon.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=icon.js.map

package/dist/types/icon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon.js","sourceRoot":"","sources":["../../src/types/icon.ts"],"names":[],"mappings":"","sourcesContent":["import type { CSSProperties, ComponentType } from 'react';\n\n/**\n * The shape an integration-declared icon renders through, defined locally so\n * the SDK's root entrypoint imports nothing from the host. `@kit/ui/icon`\n * owns the canonical definition (and the icon-name union lives in the host\n * design system, which validates icon names at gate time); to the SDK an icon\n * is just a component taking presentation props.\n */\nexport type IconRenderer = ComponentType<{\n  className?: string;\n  style?: CSSProperties;\n}>;\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SDK-owned type definitions (adversarial review outcome 5,
+ * docs/devex/sdk-export-map.md): the canonical partner-facing shapes live
+ * here, import nothing from `@kit/*`, and are held mutually assignable with
+ * `@kit/integrations-core`'s copies by `__tests__/core-parity.test-d.ts`.
+ */
+export type { IconRenderer } from './icon.js';
+export type { AccountProductData, AccountProductDataType, ActivationFormProps, ActivationResult, HealthCheckResult, HealthStatus, IntegrationCapability, IntegrationComponentProps, IntegrationConfig, IntegrationMetadata, IntegrationPermission, MarketplaceTileProps, WidgetConfig, } from './integration.js';
+export type { WidgetAskContext, WidgetSnapshot, WidgetSuggestedPrompt, } from './widget-ask-context.js';
+export type { WorkspaceTargetDefinition } from './workspace-target.js';

package/dist/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * SDK-owned type definitions (adversarial review outcome 5,
+ * docs/devex/sdk-export-map.md): the canonical partner-facing shapes live
+ * here, import nothing from `@kit/*`, and are held mutually assignable with
+ * `@kit/integrations-core`'s copies by `__tests__/core-parity.test-d.ts`.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * SDK-owned type definitions (adversarial review outcome 5,\n * docs/devex/sdk-export-map.md): the canonical partner-facing shapes live\n * here, import nothing from `@kit/*`, and are held mutually assignable with\n * `@kit/integrations-core`'s copies by `__tests__/core-parity.test-d.ts`.\n */\n\nexport type { IconRenderer } from './icon';\n\nexport type {\n  AccountProductData,\n  AccountProductDataType,\n  ActivationFormProps,\n  ActivationResult,\n  HealthCheckResult,\n  HealthStatus,\n  IntegrationCapability,\n  IntegrationComponentProps,\n  IntegrationConfig,\n  IntegrationMetadata,\n  IntegrationPermission,\n  MarketplaceTileProps,\n  WidgetConfig,\n} from './integration';\n\nexport type {\n  WidgetAskContext,\n  WidgetSnapshot,\n  WidgetSuggestedPrompt,\n} from './widget-ask-context';\n\nexport type { WorkspaceTargetDefinition } from './workspace-target';\n"]}