@ekanos/sdk 0.1.0

package/dist/context/require-context.js

@@ -0,0 +1,36 @@
+function isIntegrationContext(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    const storage = candidate.storage;
+    return (typeof candidate.accountId === 'string' &&
+        typeof candidate.fetch === 'function' &&
+        typeof candidate.storage === 'object' &&
+        storage !== undefined &&
+        storage !== null &&
+        typeof storage.account === 'object' &&
+        typeof storage.user === 'object' &&
+        typeof candidate.secrets === 'object' &&
+        candidate.secrets !== null &&
+        typeof candidate.logger === 'object' &&
+        candidate.logger !== null);
+}
+/**
+ * Narrow the internal tool context's `integrationContext` passthrough to the
+ * SDK's `IntegrationContext`. Throws with a remediation message when the host
+ * path did not attach one — a migrated tool must only run on wired paths.
+ */
+export function requireContext(toolContext) {
+    const candidate = toolContext.integrationContext;
+    if (!isIntegrationContext(candidate)) {
+        throw new Error('No capability context is attached to this tool context. ' +
+            'requireContext() only works on host paths that build one: the ' +
+            'integration MCP route (which attaches ctx.integrationContext after ' +
+            'authorization) or withIntegrationContext(slug, …). Either invoke ' +
+            'this tool through a wired path, or — in tests — pass ' +
+            '{ integrationContext: createMockContext({ … }) } from ' +
+            '@ekanos/sdk/testing.');
+    }
+    return candidate;
+}
+//# sourceMappingURL=require-context.js.map

package/dist/context/require-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-context.js","sourceRoot":"","sources":["../../src/context/require-context.ts"],"names":[],"mappings":"AAsBA,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAAgC,CAAC;IACnD,MAAM,OAAO,GAAG,SAAS,CAAC,OAA8C,CAAC;IAEzE,OAAO,CACL,OAAO,SAAS,CAAC,SAAS,KAAK,QAAQ;QACvC,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU;QACrC,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QACrC,OAAO,KAAK,SAAS;QACrB,OAAO,KAAK,IAAI;QAChB,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QACnC,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAChC,OAAO,SAAS,CAAC,OAAO,KAAK,QAAQ;QACrC,SAAS,CAAC,OAAO,KAAK,IAAI;QAC1B,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;QACpC,SAAS,CAAC,MAAM,KAAK,IAAI,CAC1B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAsC;IAEtC,MAAM,SAAS,GAAG,WAAW,CAAC,kBAAkB,CAAC;IAEjD,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,0DAA0D;YACxD,gEAAgE;YAChE,qEAAqE;YACrE,mEAAmE;YACnE,uDAAuD;YACvD,wDAAwD;YACxD,sBAAsB,CACzB,CAAC;IACJ,CAAC;IAED,OAAO,SAAwC,CAAC;AAClD,CAAC","sourcesContent":["/**\n * `requireContext()` — the typed accessor migrated tools use to read the\n * host-built capability context off the internal `ToolContext`.\n *\n * The host attaches the context ADDITIVELY as an untyped passthrough field\n * (`integrationContext?: unknown` on `@kit/integrations-core`'s ToolContext —\n * core cannot import the SDK without a package cycle). This function is the\n * SDK-side narrowing: structural assertion + remediation error, so first-party\n * tools get full typing from the package they already depend on.\n *\n * Dependency-pure and isomorphic like the rest of `/context`.\n */\nimport type { IntegrationContext, StorageSchemas } from './types';\n\n/**\n * The one field `requireContext` reads. `@kit/integrations-core`'s\n * `ToolContext` satisfies this structurally without core importing the SDK.\n */\nexport interface IntegrationContextCarrier {\n  integrationContext?: unknown;\n}\n\nfunction isIntegrationContext(value: unknown): value is IntegrationContext {\n  if (typeof value !== 'object' || value === null) return false;\n  const candidate = value as Record<string, unknown>;\n  const storage = candidate.storage as Record<string, unknown> | undefined;\n\n  return (\n    typeof candidate.accountId === 'string' &&\n    typeof candidate.fetch === 'function' &&\n    typeof candidate.storage === 'object' &&\n    storage !== undefined &&\n    storage !== null &&\n    typeof storage.account === 'object' &&\n    typeof storage.user === 'object' &&\n    typeof candidate.secrets === 'object' &&\n    candidate.secrets !== null &&\n    typeof candidate.logger === 'object' &&\n    candidate.logger !== null\n  );\n}\n\n/**\n * Narrow the internal tool context's `integrationContext` passthrough to the\n * SDK's `IntegrationContext`. Throws with a remediation message when the host\n * path did not attach one — a migrated tool must only run on wired paths.\n */\nexport function requireContext<Schemas extends StorageSchemas = StorageSchemas>(\n  toolContext: IntegrationContextCarrier,\n): IntegrationContext<Schemas> {\n  const candidate = toolContext.integrationContext;\n\n  if (!isIntegrationContext(candidate)) {\n    throw new Error(\n      'No capability context is attached to this tool context. ' +\n        'requireContext() only works on host paths that build one: the ' +\n        'integration MCP route (which attaches ctx.integrationContext after ' +\n        'authorization) or withIntegrationContext(slug, …). Either invoke ' +\n        'this tool through a wired path, or — in tests — pass ' +\n        '{ integrationContext: createMockContext({ … }) } from ' +\n        '@ekanos/sdk/testing.',\n    );\n  }\n\n  return candidate as IntegrationContext<Schemas>;\n}\n"]}

package/dist/context/storage-validation.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The shared storage validator (ruling 1) — ONE implementation, used by the
+ * `@ekanos/sdk/testing` mock today and the production `ctx.storage` wrapper
+ * when host wiring lands, so the mock enforces exactly what prod enforces.
+ */
+import type { z } from 'zod';
+import type { StorageKeyDeclarationInput, StorageSchemaMap } from './types.js';
+type StorageScope = 'account' | 'user';
+/**
+ * Normalizes either declaration form — a bare zod schema, or a
+ * `{ schema, clientReadable }` descriptor — into the resolved pair. ONE
+ * implementation, so the mock, the production `ctx.storage` wrapper, and the
+ * browser-facing storage route all read a declaration the same way.
+ *
+ * The zod-schema test is duck-typed on `safeParse` rather than `instanceof
+ * z.ZodType` on purpose: a partner package may bundle its own zod copy, and a
+ * cross-realm schema must not be misread as a descriptor (which would then
+ * fail the descriptor branch and report a nonsense error).
+ *
+ * `clientReadable` FAILS CLOSED: the bare-schema form and an omitted flag
+ * both resolve to `false`. Widening exposure is always an explicit act.
+ */
+export declare function resolveStorageKeyDeclaration(declaration: StorageKeyDeclarationInput): {
+    schema: z.ZodType;
+    clientReadable: boolean;
+};
+/**
+ * Whether a declared key opted in to the generic browser-readable storage
+ * route. An UNDECLARED key and a declared-but-not-opted-in key both answer
+ * `false` — the route must not distinguish them, or it becomes an existence
+ * oracle for a partner's server-only key names.
+ */
+export declare function isStorageKeyClientReadable(args: {
+    key: string;
+    schemas: StorageSchemaMap | undefined;
+}): boolean;
+/**
+ * Resolves the declared schema for a storage key, throwing
+ * `StorageValidationError` when the key is undeclared (strict keys). Used
+ * directly by `delete`, and by `parseStorageValue` for reads and writes.
+ */
+export declare function assertStorageKeyDeclared(args: {
+    scope: StorageScope;
+    key: string;
+    schemas: StorageSchemaMap | undefined;
+}): z.ZodType;
+/**
+ * Rejects writes and deletes against host-managed read-only data_types
+ * (finding C). ONE implementation for the `@ekanos/sdk/testing` mock and the
+ * production `ctx.storage` wrapper, so a write that prod refuses also fails
+ * in partner tests. Runs BEFORE the declared-key check so a read-only key
+ * reports the real reason rather than "undeclared".
+ */
+export declare function assertStorageKeyWritable(args: {
+    scope: StorageScope;
+    key: string;
+}): void;
+/**
+ * Validates one storage value against its declared schema and returns the
+ * schema's OUTPUT value (defaults and transforms applied). Throws
+ * `StorageValidationError` on an undeclared key or a schema mismatch, with
+ * the zod issues formatted into the remediation hint.
+ */
+export declare function parseStorageValue(args: {
+    scope: StorageScope;
+    key: string;
+    operation: 'read' | 'write';
+    schemas: StorageSchemaMap | undefined;
+    value: unknown;
+}): unknown;
+export {};

package/dist/context/storage-validation.js

@@ -0,0 +1,132 @@
+import { StorageValidationError } from './errors.js';
+/**
+ * Account data_types a partner may READ through `ctx.storage` but never
+ * write or delete (authz-hardening finding C). `activation` rows are host
+ * lifecycle state: the activation flow creates them and admin deactivation
+ * removes them. A partner that could write `activation` (any subtype) could
+ * re-create its own activation row after an admin deactivated it —
+ * self-reactivation. Reads stay allowed: the capability-context proposal
+ * (§2.1) deliberately exposes the non-secret activation payload through
+ * `ctx.storage.account.get('activation')`.
+ */
+const READ_ONLY_ACCOUNT_DATA_TYPES = new Set(['activation']);
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `  - ${path}: ${issue.message}`;
+    })
+        .join('\n');
+}
+/**
+ * Normalizes either declaration form — a bare zod schema, or a
+ * `{ schema, clientReadable }` descriptor — into the resolved pair. ONE
+ * implementation, so the mock, the production `ctx.storage` wrapper, and the
+ * browser-facing storage route all read a declaration the same way.
+ *
+ * The zod-schema test is duck-typed on `safeParse` rather than `instanceof
+ * z.ZodType` on purpose: a partner package may bundle its own zod copy, and a
+ * cross-realm schema must not be misread as a descriptor (which would then
+ * fail the descriptor branch and report a nonsense error).
+ *
+ * `clientReadable` FAILS CLOSED: the bare-schema form and an omitted flag
+ * both resolve to `false`. Widening exposure is always an explicit act.
+ */
+export function resolveStorageKeyDeclaration(declaration) {
+    if (typeof (declaration === null || declaration === void 0 ? void 0 : declaration.safeParse) ===
+        'function') {
+        return { schema: declaration, clientReadable: false };
+    }
+    const descriptor = declaration;
+    return {
+        schema: descriptor.schema,
+        clientReadable: descriptor.clientReadable === true,
+    };
+}
+/**
+ * Whether a declared key opted in to the generic browser-readable storage
+ * route. An UNDECLARED key and a declared-but-not-opted-in key both answer
+ * `false` — the route must not distinguish them, or it becomes an existence
+ * oracle for a partner's server-only key names.
+ */
+export function isStorageKeyClientReadable(args) {
+    var _a;
+    const declaration = (_a = args.schemas) === null || _a === void 0 ? void 0 : _a[args.key];
+    if (!declaration)
+        return false;
+    return resolveStorageKeyDeclaration(declaration).clientReadable;
+}
+/**
+ * Resolves the declared schema for a storage key, throwing
+ * `StorageValidationError` when the key is undeclared (strict keys). Used
+ * directly by `delete`, and by `parseStorageValue` for reads and writes.
+ */
+export function assertStorageKeyDeclared(args) {
+    var _a;
+    const declaration = (_a = args.schemas) === null || _a === void 0 ? void 0 : _a[args.key];
+    if (!declaration) {
+        throw new StorageValidationError({
+            scope: args.scope,
+            key: args.key,
+            hint: `No schema is declared for ${args.scope} storage key "${args.key}". ` +
+                `Storage keys are strict: declare the key and its zod schema in ` +
+                `defineIntegration({ storage: { ${args.scope}: { '${args.key}': z.object({ … }) } } }) ` +
+                `(or in createMockContext({ storageSchemas }) in tests) before reading, ` +
+                `writing, or deleting it.`,
+        });
+    }
+    return resolveStorageKeyDeclaration(declaration).schema;
+}
+/**
+ * Rejects writes and deletes against host-managed read-only data_types
+ * (finding C). ONE implementation for the `@ekanos/sdk/testing` mock and the
+ * production `ctx.storage` wrapper, so a write that prod refuses also fails
+ * in partner tests. Runs BEFORE the declared-key check so a read-only key
+ * reports the real reason rather than "undeclared".
+ */
+export function assertStorageKeyWritable(args) {
+    if (args.scope !== 'account')
+        return;
+    const slashIndex = args.key.indexOf('/');
+    const dataType = slashIndex === -1 ? args.key : args.key.slice(0, slashIndex);
+    if (READ_ONLY_ACCOUNT_DATA_TYPES.has(dataType)) {
+        throw new StorageValidationError({
+            scope: args.scope,
+            key: args.key,
+            hint: `Storage key "${args.key}" uses the host-managed "${dataType}" ` +
+                `data_type, which ctx.storage can read but never write or delete. ` +
+                `Activation rows are created by the host activation flow and ` +
+                `removed by deactivation — an integration cannot (re)create or ` +
+                `drop its own activation. Persist integration state under a ` +
+                `"settings", "sync_state", "metrics_summary", or "cache" key instead.`,
+        });
+    }
+}
+/**
+ * Validates one storage value against its declared schema and returns the
+ * schema's OUTPUT value (defaults and transforms applied). Throws
+ * `StorageValidationError` on an undeclared key or a schema mismatch, with
+ * the zod issues formatted into the remediation hint.
+ */
+export function parseStorageValue(args) {
+    const schema = assertStorageKeyDeclared(args);
+    const result = schema.safeParse(args.value);
+    if (!result.success) {
+        const issues = formatIssues(result.error.issues);
+        const hint = args.operation === 'write'
+            ? `The value written to ${args.scope} storage key "${args.key}" fails ` +
+                `its declared schema. Fix the write payload to match the schema ` +
+                `declared in defineIntegration({ storage }):\n${issues}`
+            : `The data stored at ${args.scope} storage key "${args.key}" no longer ` +
+                `matches its declared schema. Handle schema evolution explicitly: ` +
+                `widen the schema (z.union with the legacy shape) or migrate to a ` +
+                `versioned key, then rewrite the row via set(). Issues:\n${issues}`;
+        throw new StorageValidationError({
+            scope: args.scope,
+            key: args.key,
+            hint,
+        });
+    }
+    return result.data;
+}
+//# sourceMappingURL=storage-validation.js.map

package/dist/context/storage-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-validation.js","sourceRoot":"","sources":["../../src/context/storage-validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared storage validator (ruling 1) — ONE implementation, used by the\n * `@ekanos/sdk/testing` mock today and the production `ctx.storage` wrapper\n * when host wiring lands, so the mock enforces exactly what prod enforces.\n */\nimport type { z } from 'zod';\n\nimport { StorageValidationError } from './errors';\nimport type {\n  StorageKeyDeclaration,\n  StorageKeyDeclarationInput,\n  StorageSchemaMap,\n} from './types';\n\ntype StorageScope = 'account' | 'user';\n\n/**\n * Account data_types a partner may READ through `ctx.storage` but never\n * write or delete (authz-hardening finding C). `activation` rows are host\n * lifecycle state: the activation flow creates them and admin deactivation\n * removes them. A partner that could write `activation` (any subtype) could\n * re-create its own activation row after an admin deactivated it —\n * self-reactivation. Reads stay allowed: the capability-context proposal\n * (§2.1) deliberately exposes the non-secret activation payload through\n * `ctx.storage.account.get('activation')`.\n */\nconst READ_ONLY_ACCOUNT_DATA_TYPES = new Set(['activation']);\n\nfunction formatIssues(issues: readonly z.ZodIssue[]): string {\n  return 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}\n\n/**\n * Normalizes either declaration form — a bare zod schema, or a\n * `{ schema, clientReadable }` descriptor — into the resolved pair. ONE\n * implementation, so the mock, the production `ctx.storage` wrapper, and the\n * browser-facing storage route all read a declaration the same way.\n *\n * The zod-schema test is duck-typed on `safeParse` rather than `instanceof\n * z.ZodType` on purpose: a partner package may bundle its own zod copy, and a\n * cross-realm schema must not be misread as a descriptor (which would then\n * fail the descriptor branch and report a nonsense error).\n *\n * `clientReadable` FAILS CLOSED: the bare-schema form and an omitted flag\n * both resolve to `false`. Widening exposure is always an explicit act.\n */\nexport function resolveStorageKeyDeclaration(\n  declaration: StorageKeyDeclarationInput,\n): { schema: z.ZodType; clientReadable: boolean } {\n  if (\n    typeof (declaration as { safeParse?: unknown } | null)?.safeParse ===\n    'function'\n  ) {\n    return { schema: declaration as z.ZodType, clientReadable: false };\n  }\n\n  const descriptor = declaration as StorageKeyDeclaration;\n\n  return {\n    schema: descriptor.schema,\n    clientReadable: descriptor.clientReadable === true,\n  };\n}\n\n/**\n * Whether a declared key opted in to the generic browser-readable storage\n * route. An UNDECLARED key and a declared-but-not-opted-in key both answer\n * `false` — the route must not distinguish them, or it becomes an existence\n * oracle for a partner's server-only key names.\n */\nexport function isStorageKeyClientReadable(args: {\n  key: string;\n  schemas: StorageSchemaMap | undefined;\n}): boolean {\n  const declaration = args.schemas?.[args.key];\n  if (!declaration) return false;\n\n  return resolveStorageKeyDeclaration(declaration).clientReadable;\n}\n\n/**\n * Resolves the declared schema for a storage key, throwing\n * `StorageValidationError` when the key is undeclared (strict keys). Used\n * directly by `delete`, and by `parseStorageValue` for reads and writes.\n */\nexport function assertStorageKeyDeclared(args: {\n  scope: StorageScope;\n  key: string;\n  schemas: StorageSchemaMap | undefined;\n}): z.ZodType {\n  const declaration = args.schemas?.[args.key];\n  if (!declaration) {\n    throw new StorageValidationError({\n      scope: args.scope,\n      key: args.key,\n      hint:\n        `No schema is declared for ${args.scope} storage key \"${args.key}\". ` +\n        `Storage keys are strict: declare the key and its zod schema in ` +\n        `defineIntegration({ storage: { ${args.scope}: { '${args.key}': z.object({ … }) } } }) ` +\n        `(or in createMockContext({ storageSchemas }) in tests) before reading, ` +\n        `writing, or deleting it.`,\n    });\n  }\n\n  return resolveStorageKeyDeclaration(declaration).schema;\n}\n\n/**\n * Rejects writes and deletes against host-managed read-only data_types\n * (finding C). ONE implementation for the `@ekanos/sdk/testing` mock and the\n * production `ctx.storage` wrapper, so a write that prod refuses also fails\n * in partner tests. Runs BEFORE the declared-key check so a read-only key\n * reports the real reason rather than \"undeclared\".\n */\nexport function assertStorageKeyWritable(args: {\n  scope: StorageScope;\n  key: string;\n}): void {\n  if (args.scope !== 'account') return;\n\n  const slashIndex = args.key.indexOf('/');\n  const dataType = slashIndex === -1 ? args.key : args.key.slice(0, slashIndex);\n\n  if (READ_ONLY_ACCOUNT_DATA_TYPES.has(dataType)) {\n    throw new StorageValidationError({\n      scope: args.scope,\n      key: args.key,\n      hint:\n        `Storage key \"${args.key}\" uses the host-managed \"${dataType}\" ` +\n        `data_type, which ctx.storage can read but never write or delete. ` +\n        `Activation rows are created by the host activation flow and ` +\n        `removed by deactivation — an integration cannot (re)create or ` +\n        `drop its own activation. Persist integration state under a ` +\n        `\"settings\", \"sync_state\", \"metrics_summary\", or \"cache\" key instead.`,\n    });\n  }\n}\n\n/**\n * Validates one storage value against its declared schema and returns the\n * schema's OUTPUT value (defaults and transforms applied). Throws\n * `StorageValidationError` on an undeclared key or a schema mismatch, with\n * the zod issues formatted into the remediation hint.\n */\nexport function parseStorageValue(args: {\n  scope: StorageScope;\n  key: string;\n  operation: 'read' | 'write';\n  schemas: StorageSchemaMap | undefined;\n  value: unknown;\n}): unknown {\n  const schema = assertStorageKeyDeclared(args);\n  const result = schema.safeParse(args.value);\n\n  if (!result.success) {\n    const issues = formatIssues(result.error.issues);\n    const hint =\n      args.operation === 'write'\n        ? `The value written to ${args.scope} storage key \"${args.key}\" fails ` +\n          `its declared schema. Fix the write payload to match the schema ` +\n          `declared in defineIntegration({ storage }):\\n${issues}`\n        : `The data stored at ${args.scope} storage key \"${args.key}\" no longer ` +\n          `matches its declared schema. Handle schema evolution explicitly: ` +\n          `widen the schema (z.union with the legacy shape) or migrate to a ` +\n          `versioned key, then rewrite the row via set(). Issues:\\n${issues}`;\n    throw new StorageValidationError({\n      scope: args.scope,\n      key: args.key,\n      hint,\n    });\n  }\n\n  return result.data;\n}\n"]}

package/dist/context/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The capability-context types now live in `@ekanos/integration-schema` (the
+ * dependency-pure package both `@ekanos/sdk` and `@kit/integrations-core`
+ * depend on) so the canonical integration-definition schema can reference
+ * `IntegrationContext` without a package cycle. This file re-exports them so
+ * every existing `@ekanos/sdk` import path (`./types`, `../context/types`,
+ * the root barrel) keeps resolving unchanged.
+ *
+ * Spec: docs/devex/capability-context-proposal.md (all six §7 rulings).
+ */
+export type { IntegrationActor, IntegrationContext, IntegrationStorage, ScopedStore, IntegrationSecrets, IntegrationFetch, IntegrationLogger, StorageEntry, StorageWriteOptions, StorageSchemas, StorageSchemaMap, StorageScopeSchemas, StorageKeyDeclaration, StorageKeyDeclarationInput, StorageKeySchema, } from '@ekanos/integration-schema';

package/dist/context/types.js

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

package/dist/context/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The capability-context types now live in `@ekanos/integration-schema` (the\n * dependency-pure package both `@ekanos/sdk` and `@kit/integrations-core`\n * depend on) so the canonical integration-definition schema can reference\n * `IntegrationContext` without a package cycle. This file re-exports them so\n * every existing `@ekanos/sdk` import path (`./types`, `../context/types`,\n * the root barrel) keeps resolving unchanged.\n *\n * Spec: docs/devex/capability-context-proposal.md (all six §7 rulings).\n */\nexport type {\n  IntegrationActor,\n  IntegrationContext,\n  IntegrationStorage,\n  ScopedStore,\n  IntegrationSecrets,\n  IntegrationFetch,\n  IntegrationLogger,\n  StorageEntry,\n  StorageWriteOptions,\n  StorageSchemas,\n  StorageSchemaMap,\n  StorageScopeSchemas,\n  StorageKeyDeclaration,\n  StorageKeyDeclarationInput,\n  StorageKeySchema,\n} from '@ekanos/integration-schema';\n"]}

package/dist/hooks/activation-actions-context.d.ts

@@ -0,0 +1,80 @@
+import { type ReactNode } from 'react';
+/**
+ * The host-injection seam for integration activation (the SDK inversion,
+ * DEVELOPER_EXPERIENCE_PLAN.md §5.1).
+ *
+ * A published SDK cannot import the host's `'use server'` activation actions
+ * — that import is what used to drag `server-only` (via `@kit/next/actions`)
+ * into every partner client graph and broke partner tests on day one
+ * (sdk-export-map.md, BLOCKER 2). Instead the HOST binds its real server
+ * actions once, at the root of its client tree:
+ *
+ * ```tsx
+ * // host chrome (e.g. @kit/integrations-core's bridge component)
+ * <IntegrationActivationProvider actions={{ activate, deactivate }}>
+ *   {children}
+ * </IntegrationActivationProvider>
+ * ```
+ *
+ * and `useActivateIntegration()` / `useDeactivateIntegration()` keep their
+ * zero-argument call signature everywhere — first-party integrations,
+ * examples, and partner code are byte-identical before and after the
+ * inversion. Server-action references are serializable client values in
+ * React 19, so passing them through context is sanctioned.
+ *
+ * Outside a provider the hooks reject AT CALL TIME with an actionable
+ * error (mirroring `useAskAssistant`'s no-op-outside-provider contract,
+ * but loud rather than silent — a swallowed activation would look like a
+ * hung form).
+ */
+/** Input accepted by the host's activate action (BaseActivationSchema). */
+export interface ActivateIntegrationInput {
+    accountId: string;
+    sourceId?: string;
+    productId?: string;
+    integrationSlug: string;
+    activationData?: unknown;
+    /**
+     * The TEAM account context the user activated within — separate from
+     * `accountId`, which for `scope: 'user'` integrations is the personal
+     * account. Optional; the host falls back to `accountId` when absent.
+     */
+    teamAccountId?: string;
+    /** The host schema is passthrough: extra integration fields ride along. */
+    [key: string]: unknown;
+}
+/** Input accepted by the host's deactivate action (DeactivationSchema). */
+export interface DeactivateIntegrationInput {
+    accountId: string;
+    productId?: string;
+    integrationSlug: string;
+    [key: string]: unknown;
+}
+/**
+ * The host action envelope. Host actions return richer payloads; the SDK
+ * only relies on the `success` / `errorMessage` pair.
+ */
+export type IntegrationActionResult = {
+    success?: boolean;
+    errorMessage?: string;
+} & Record<string, unknown>;
+export type ActivateIntegrationAction = (input: ActivateIntegrationInput) => Promise<IntegrationActionResult | undefined>;
+export type DeactivateIntegrationAction = (input: DeactivateIntegrationInput) => Promise<IntegrationActionResult | undefined>;
+export interface IntegrationActivationActions {
+    activate: ActivateIntegrationAction;
+    deactivate: DeactivateIntegrationAction;
+}
+/**
+ * Host-mounted provider that binds the real activation server actions.
+ * Mounted once at the root of the host's client tree (apps/web root
+ * providers; the harness mounts it with fixture actions).
+ */
+export declare function IntegrationActivationProvider({ actions, children, }: {
+    actions: IntegrationActivationActions;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Internal: resolve the host-bound actions, or a pair that rejects loudly.
+ * Not exported from the entrypoint — hooks and the OAuth form consume it.
+ */
+export declare function useIntegrationActivationActions(): IntegrationActivationActions;

package/dist/hooks/activation-actions-context.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useMemo } from 'react';
+const IntegrationActivationContext = createContext(null);
+/**
+ * Host-mounted provider that binds the real activation server actions.
+ * Mounted once at the root of the host's client tree (apps/web root
+ * providers; the harness mounts it with fixture actions).
+ */
+export function IntegrationActivationProvider({ actions, children, }) {
+    const value = useMemo(() => ({ activate: actions.activate, deactivate: actions.deactivate }), [actions.activate, actions.deactivate]);
+    return (_jsx(IntegrationActivationContext, { value: value, children: children }));
+}
+const MISSING_PROVIDER_MESSAGE = 'No IntegrationActivationProvider is mounted. The host application must ' +
+    'bind its activation server actions (see @ekanos/sdk/hooks ' +
+    'IntegrationActivationProvider) above any component that activates ' +
+    'integrations.';
+/**
+ * Internal: resolve the host-bound actions, or a pair that rejects loudly.
+ * Not exported from the entrypoint — hooks and the OAuth form consume it.
+ */
+export function useIntegrationActivationActions() {
+    const context = use(IntegrationActivationContext);
+    return useMemo(() => {
+        if (context)
+            return context;
+        const reject = () => Promise.reject(new Error(MISSING_PROVIDER_MESSAGE));
+        return { activate: reject, deactivate: reject };
+    }, [context]);
+}
+//# sourceMappingURL=activation-actions-context.js.map

package/dist/hooks/activation-actions-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-actions-context.js","sourceRoot":"","sources":["../../src/hooks/activation-actions-context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAkB,aAAa,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AA8EpE,MAAM,4BAA4B,GAChC,aAAa,CAAsC,IAAI,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,EAC5C,OAAO,EACP,QAAQ,GAIT;IACC,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,EACtE,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CACvC,CAAC;IAEF,OAAO,CACL,KAAC,4BAA4B,IAAC,KAAK,EAAE,KAAK,YACvC,QAAQ,GACoB,CAChC,CAAC;AACJ,CAAC;AAED,MAAM,wBAAwB,GAC5B,yEAAyE;IACzE,4DAA4D;IAC5D,oEAAoE;IACpE,eAAe,CAAC;AAElB;;;GAGG;AACH,MAAM,UAAU,+BAA+B;IAC7C,MAAM,OAAO,GAAG,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAElD,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;QAE5B,MAAM,MAAM,GAAG,GAAG,EAAE,CAClB,OAAO,CAAC,MAAM,CACZ,IAAI,KAAK,CAAC,wBAAwB,CAAC,CACpC,CAAC;QAEJ,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAClD,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;AAChB,CAAC","sourcesContent":["'use client';\n\nimport { type ReactNode, createContext, use, useMemo } from 'react';\n\n/**\n * The host-injection seam for integration activation (the SDK inversion,\n * DEVELOPER_EXPERIENCE_PLAN.md §5.1).\n *\n * A published SDK cannot import the host's `'use server'` activation actions\n * — that import is what used to drag `server-only` (via `@kit/next/actions`)\n * into every partner client graph and broke partner tests on day one\n * (sdk-export-map.md, BLOCKER 2). Instead the HOST binds its real server\n * actions once, at the root of its client tree:\n *\n * ```tsx\n * // host chrome (e.g. @kit/integrations-core's bridge component)\n * <IntegrationActivationProvider actions={{ activate, deactivate }}>\n *   {children}\n * </IntegrationActivationProvider>\n * ```\n *\n * and `useActivateIntegration()` / `useDeactivateIntegration()` keep their\n * zero-argument call signature everywhere — first-party integrations,\n * examples, and partner code are byte-identical before and after the\n * inversion. Server-action references are serializable client values in\n * React 19, so passing them through context is sanctioned.\n *\n * Outside a provider the hooks reject AT CALL TIME with an actionable\n * error (mirroring `useAskAssistant`'s no-op-outside-provider contract,\n * but loud rather than silent — a swallowed activation would look like a\n * hung form).\n */\n\n/** Input accepted by the host's activate action (BaseActivationSchema). */\nexport interface ActivateIntegrationInput {\n  accountId: string;\n  sourceId?: string;\n  productId?: string;\n  integrationSlug: string;\n  activationData?: unknown;\n  /**\n   * The TEAM account context the user activated within — separate from\n   * `accountId`, which for `scope: 'user'` integrations is the personal\n   * account. Optional; the host falls back to `accountId` when absent.\n   */\n  teamAccountId?: string;\n  /** The host schema is passthrough: extra integration fields ride along. */\n  [key: string]: unknown;\n}\n\n/** Input accepted by the host's deactivate action (DeactivationSchema). */\nexport interface DeactivateIntegrationInput {\n  accountId: string;\n  productId?: string;\n  integrationSlug: string;\n  [key: string]: unknown;\n}\n\n/**\n * The host action envelope. Host actions return richer payloads; the SDK\n * only relies on the `success` / `errorMessage` pair.\n */\nexport type IntegrationActionResult = {\n  success?: boolean;\n  errorMessage?: string;\n} & Record<string, unknown>;\n\nexport type ActivateIntegrationAction = (\n  input: ActivateIntegrationInput,\n) => Promise<IntegrationActionResult | undefined>;\n\nexport type DeactivateIntegrationAction = (\n  input: DeactivateIntegrationInput,\n) => Promise<IntegrationActionResult | undefined>;\n\nexport interface IntegrationActivationActions {\n  activate: ActivateIntegrationAction;\n  deactivate: DeactivateIntegrationAction;\n}\n\nconst IntegrationActivationContext =\n  createContext<IntegrationActivationActions | null>(null);\n\n/**\n * Host-mounted provider that binds the real activation server actions.\n * Mounted once at the root of the host's client tree (apps/web root\n * providers; the harness mounts it with fixture actions).\n */\nexport function IntegrationActivationProvider({\n  actions,\n  children,\n}: {\n  actions: IntegrationActivationActions;\n  children: ReactNode;\n}) {\n  const value = useMemo(\n    () => ({ activate: actions.activate, deactivate: actions.deactivate }),\n    [actions.activate, actions.deactivate],\n  );\n\n  return (\n    <IntegrationActivationContext value={value}>\n      {children}\n    </IntegrationActivationContext>\n  );\n}\n\nconst MISSING_PROVIDER_MESSAGE =\n  'No IntegrationActivationProvider is mounted. The host application must ' +\n  'bind its activation server actions (see @ekanos/sdk/hooks ' +\n  'IntegrationActivationProvider) above any component that activates ' +\n  'integrations.';\n\n/**\n * Internal: resolve the host-bound actions, or a pair that rejects loudly.\n * Not exported from the entrypoint — hooks and the OAuth form consume it.\n */\nexport function useIntegrationActivationActions(): IntegrationActivationActions {\n  const context = use(IntegrationActivationContext);\n\n  return useMemo(() => {\n    if (context) return context;\n\n    const reject = () =>\n      Promise.reject<IntegrationActionResult>(\n        new Error(MISSING_PROVIDER_MESSAGE),\n      );\n\n    return { activate: reject, deactivate: reject };\n  }, [context]);\n}\n"]}

package/dist/hooks/ask-assistant-context.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from 'react';
+import type { WidgetAskContext } from '../types/widget-ask-context.js';
+type AskAssistantHandler = (ctx: WidgetAskContext) => void;
+interface AskAssistantProviderProps {
+    children: ReactNode;
+}
+/**
+ * Hosts the bridge between widget ask-bars and the AI assistant dock.
+ *
+ * Widgets call `useAskAssistant()` to get a stable dispatcher. The dock
+ * registers its actual handler via `useRegisterAskAssistant()` once it
+ * has access to its chat hook. Until a handler is registered (e.g. on
+ * routes without a dock), calls are no-ops.
+ */
+export declare function AskAssistantProvider({ children }: AskAssistantProviderProps): import("react").JSX.Element;
+/**
+ * Returns a stable dispatcher widgets can call to send a question about
+ * themselves to the assistant. Outside an `AskAssistantProvider` (e.g.
+ * widget preview pages), this is a no-op.
+ */
+export declare function useAskAssistant(): AskAssistantHandler;
+/**
+ * Installs the dock-side handler that the widget dispatcher will call.
+ * Re-registers whenever `handler` changes; clears on unmount.
+ *
+ * Uses useLayoutEffect so the handler is wired up before the browser
+ * paints the dock — otherwise a chip click that fires during the first
+ * paint frame (e.g. user opens a drawer fast) finds a null handler and
+ * silently no-ops.
+ */
+export declare function useRegisterAskAssistant(handler: AskAssistantHandler): void;
+export {};

package/dist/hooks/ask-assistant-context.js

@@ -0,0 +1,56 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useLayoutEffect, useMemo, useRef, } from 'react';
+const AskAssistantContext = createContext(null);
+/**
+ * Hosts the bridge between widget ask-bars and the AI assistant dock.
+ *
+ * Widgets call `useAskAssistant()` to get a stable dispatcher. The dock
+ * registers its actual handler via `useRegisterAskAssistant()` once it
+ * has access to its chat hook. Until a handler is registered (e.g. on
+ * routes without a dock), calls are no-ops.
+ */
+export function AskAssistantProvider({ children }) {
+    const handlerRef = useRef(null);
+    const ask = useCallback((ctx) => {
+        var _a;
+        (_a = handlerRef.current) === null || _a === void 0 ? void 0 : _a.call(handlerRef, ctx);
+    }, []);
+    const registerHandler = useCallback((handler) => {
+        handlerRef.current = handler;
+    }, []);
+    const value = useMemo(() => ({ ask, registerHandler }), [ask, registerHandler]);
+    return _jsx(AskAssistantContext, { value: value, children: children });
+}
+const NOOP_ASK = () => { };
+/**
+ * Returns a stable dispatcher widgets can call to send a question about
+ * themselves to the assistant. Outside an `AskAssistantProvider` (e.g.
+ * widget preview pages), this is a no-op.
+ */
+export function useAskAssistant() {
+    var _a;
+    const context = use(AskAssistantContext);
+    return (_a = context === null || context === void 0 ? void 0 : context.ask) !== null && _a !== void 0 ? _a : NOOP_ASK;
+}
+/**
+ * Installs the dock-side handler that the widget dispatcher will call.
+ * Re-registers whenever `handler` changes; clears on unmount.
+ *
+ * Uses useLayoutEffect so the handler is wired up before the browser
+ * paints the dock — otherwise a chip click that fires during the first
+ * paint frame (e.g. user opens a drawer fast) finds a null handler and
+ * silently no-ops.
+ */
+export function useRegisterAskAssistant(handler) {
+    const context = use(AskAssistantContext);
+    useLayoutEffect(() => {
+        if (!context)
+            return;
+        context.registerHandler(handler);
+        return () => {
+            context.registerHandler(null);
+        };
+    }, [context, handler]);
+}
+//# sourceMappingURL=ask-assistant-context.js.map

package/dist/hooks/ask-assistant-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-assistant-context.js","sourceRoot":"","sources":["../../src/hooks/ask-assistant-context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAEL,aAAa,EACb,GAAG,EACH,WAAW,EACX,eAAe,EACf,OAAO,EACP,MAAM,GACP,MAAM,OAAO,CAAC;AAaf,MAAM,mBAAmB,GAAG,aAAa,CACvC,IAAI,CACL,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAE,QAAQ,EAA6B;IAC1E,MAAM,UAAU,GAAG,MAAM,CAA6B,IAAI,CAAC,CAAC;IAE5D,MAAM,GAAG,GAAG,WAAW,CAAsB,CAAC,GAAG,EAAE,EAAE;;QACnD,MAAA,UAAU,CAAC,OAAO,2DAAG,GAAG,CAAC,CAAC;IAC5B,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,eAAe,GAAG,WAAW,CAAC,CAAC,OAAmC,EAAE,EAAE;QAC1E,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAC/B,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,EAAE,CAAC,EAChC,CAAC,GAAG,EAAE,eAAe,CAAC,CACvB,CAAC;IAEF,OAAO,KAAC,mBAAmB,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAuB,CAAC;AAC7E,CAAC;AAED,MAAM,QAAQ,GAAwB,GAAG,EAAE,GAAE,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,eAAe;;IAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACzC,OAAO,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,GAAG,mCAAI,QAAQ,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAA4B;IAClE,MAAM,OAAO,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAEzC,eAAe,CAAC,GAAG,EAAE;QACnB,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACjC,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AACzB,CAAC","sourcesContent":["'use client';\n\nimport {\n  type ReactNode,\n  createContext,\n  use,\n  useCallback,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n} from 'react';\n\nimport type { WidgetAskContext } from '../types/widget-ask-context';\n\ntype AskAssistantHandler = (ctx: WidgetAskContext) => void;\n\ninterface AskAssistantContextValue {\n  /** Stable dispatcher widgets call. Routes to the registered handler at invocation time. */\n  ask: AskAssistantHandler;\n  /** Internal — used by the dock side of the bridge to install its handler. */\n  registerHandler: (handler: AskAssistantHandler | null) => void;\n}\n\nconst AskAssistantContext = createContext<AskAssistantContextValue | null>(\n  null,\n);\n\ninterface AskAssistantProviderProps {\n  children: ReactNode;\n}\n\n/**\n * Hosts the bridge between widget ask-bars and the AI assistant dock.\n *\n * Widgets call `useAskAssistant()` to get a stable dispatcher. The dock\n * registers its actual handler via `useRegisterAskAssistant()` once it\n * has access to its chat hook. Until a handler is registered (e.g. on\n * routes without a dock), calls are no-ops.\n */\nexport function AskAssistantProvider({ children }: AskAssistantProviderProps) {\n  const handlerRef = useRef<AskAssistantHandler | null>(null);\n\n  const ask = useCallback<AskAssistantHandler>((ctx) => {\n    handlerRef.current?.(ctx);\n  }, []);\n\n  const registerHandler = useCallback((handler: AskAssistantHandler | null) => {\n    handlerRef.current = handler;\n  }, []);\n\n  const value = useMemo<AskAssistantContextValue>(\n    () => ({ ask, registerHandler }),\n    [ask, registerHandler],\n  );\n\n  return <AskAssistantContext value={value}>{children}</AskAssistantContext>;\n}\n\nconst NOOP_ASK: AskAssistantHandler = () => {};\n\n/**\n * Returns a stable dispatcher widgets can call to send a question about\n * themselves to the assistant. Outside an `AskAssistantProvider` (e.g.\n * widget preview pages), this is a no-op.\n */\nexport function useAskAssistant(): AskAssistantHandler {\n  const context = use(AskAssistantContext);\n  return context?.ask ?? NOOP_ASK;\n}\n\n/**\n * Installs the dock-side handler that the widget dispatcher will call.\n * Re-registers whenever `handler` changes; clears on unmount.\n *\n * Uses useLayoutEffect so the handler is wired up before the browser\n * paints the dock — otherwise a chip click that fires during the first\n * paint frame (e.g. user opens a drawer fast) finds a null handler and\n * silently no-ops.\n */\nexport function useRegisterAskAssistant(handler: AskAssistantHandler): void {\n  const context = use(AskAssistantContext);\n\n  useLayoutEffect(() => {\n    if (!context) return;\n    context.registerHandler(handler);\n    return () => {\n      context.registerHandler(null);\n    };\n  }, [context, handler]);\n}\n"]}

package/dist/hooks/fetch-integration-storage.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The browser half of the generic storage bridge.
+ *
+ * `ctx.storage` is a server capability and widgets are client components, so
+ * a saved setting has to round-trip through HTTP. The host serves that
+ * round-trip once, generically, at
+ * `GET /api/integrations/[slug]/storage?accountId=…&keys=a,b`; this is the
+ * client that calls it, so an integration never hand-writes the URL, the
+ * query string, or the not-ok handling.
+ *
+ * Only keys whose declaration opted in with `clientReadable: true` come back.
+ * A key that did not opt in, was never declared, or simply has no stored row
+ * is ABSENT from the result — all three are indistinguishable by design, so
+ * callers must treat a missing key as "no value", never as an error.
+ *
+ * Values are returned raw and unvalidated: the integration owns the shape of
+ * its own storage, so it validates with the same zod schemas it declared.
+ * See the Open-Meteo example's `fetchWeatherSettings` for the pattern.
+ */
+export interface FetchIntegrationStorageOptions {
+    /** The account whose storage to read. Must be one the caller belongs to. */
+    accountId: string;
+    /** Declared, `clientReadable` account-scope keys, e.g. `['settings/units']`. */
+    keys: readonly string[];
+    signal?: AbortSignal;
+    /**
+     * Overrides the base path. Exists for harnesses and tests that serve the
+     * route from somewhere other than the host's own origin; production code
+     * should leave it alone.
+     */
+    baseUrl?: string;
+}
+/**
+ * Builds the host storage-route URL for one integration. Exported because a
+ * harness or a test double needs to recognize the exact URL this client will
+ * request.
+ */
+export declare function integrationStorageUrl(integrationSlug: string, options: Pick<FetchIntegrationStorageOptions, 'accountId' | 'keys'> & {
+    baseUrl?: string;
+}): string;
+/**
+ * Reads declared, client-readable account-scope storage for one integration.
+ *
+ * Throws when the request itself fails — a 403 (not signed in, not a member,
+ * not activated, or no such integration, all deliberately indistinguishable)
+ * or a transport error. It does NOT throw for a key that came back absent.
+ */
+export declare function fetchIntegrationStorage(integrationSlug: string, options: FetchIntegrationStorageOptions): Promise<Record<string, unknown>>;

package/dist/hooks/fetch-integration-storage.js

@@ -0,0 +1,68 @@
+/**
+ * The browser half of the generic storage bridge.
+ *
+ * `ctx.storage` is a server capability and widgets are client components, so
+ * a saved setting has to round-trip through HTTP. The host serves that
+ * round-trip once, generically, at
+ * `GET /api/integrations/[slug]/storage?accountId=…&keys=a,b`; this is the
+ * client that calls it, so an integration never hand-writes the URL, the
+ * query string, or the not-ok handling.
+ *
+ * Only keys whose declaration opted in with `clientReadable: true` come back.
+ * A key that did not opt in, was never declared, or simply has no stored row
+ * is ABSENT from the result — all three are indistinguishable by design, so
+ * callers must treat a missing key as "no value", never as an error.
+ *
+ * Values are returned raw and unvalidated: the integration owns the shape of
+ * its own storage, so it validates with the same zod schemas it declared.
+ * See the Open-Meteo example's `fetchWeatherSettings` for the pattern.
+ */
+/** Mirrors the host route's own per-request cap. */
+const MAX_KEYS_PER_REQUEST = 20;
+/**
+ * Builds the host storage-route URL for one integration. Exported because a
+ * harness or a test double needs to recognize the exact URL this client will
+ * request.
+ */
+export function integrationStorageUrl(integrationSlug, options) {
+    var _a;
+    const query = new URLSearchParams({
+        accountId: options.accountId,
+        keys: options.keys.join(','),
+    });
+    const base = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : '/api/integrations';
+    return `${base}/${integrationSlug}/storage?${query}`;
+}
+/**
+ * Reads declared, client-readable account-scope storage for one integration.
+ *
+ * Throws when the request itself fails — a 403 (not signed in, not a member,
+ * not activated, or no such integration, all deliberately indistinguishable)
+ * or a transport error. It does NOT throw for a key that came back absent.
+ */
+export async function fetchIntegrationStorage(integrationSlug, options) {
+    var _a;
+    if (options.keys.length === 0) {
+        throw new Error(`fetchIntegrationStorage('${integrationSlug}') needs at least one storage key.`);
+    }
+    if (options.keys.length > MAX_KEYS_PER_REQUEST) {
+        throw new Error(`fetchIntegrationStorage('${integrationSlug}') was asked for ${options.keys.length} keys; ` +
+            `the host route reads at most ${MAX_KEYS_PER_REQUEST} per request. Split the read.`);
+    }
+    const url = integrationStorageUrl(integrationSlug, options);
+    const response = await globalThis.fetch(url, {
+        signal: (_a = options.signal) !== null && _a !== void 0 ? _a : null,
+        headers: { accept: 'application/json' },
+    });
+    if (!response.ok) {
+        throw new Error(`Could not read '${integrationSlug}' storage (${response.status} ${response.statusText}).`);
+    }
+    const payload = await response.json();
+    if (payload === null ||
+        typeof payload !== 'object' ||
+        Array.isArray(payload)) {
+        throw new Error(`The '${integrationSlug}' storage route returned a non-object payload.`);
+    }
+    return payload;
+}
+//# sourceMappingURL=fetch-integration-storage.js.map