@ekanos/sdk 0.1.0

package/dist/types/integration.d.ts

@@ -0,0 +1,258 @@
+import type { ComponentType } from 'react';
+import type { IconRenderer } from './icon.js';
+export interface IntegrationCapability {
+    label: string;
+    description: string;
+    icon?: IconRenderer;
+}
+export interface IntegrationPermission {
+    label: string;
+    detail: string;
+    type: 'read' | 'write';
+}
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
+/**
+ * Result returned by `BaseIntegration.healthCheck(accountId)`. Routed through
+ * `classifyHealth()` (server-side) before writing to
+ * `integration_health_status`.
+ */
+export interface HealthCheckResult {
+    status: HealthStatus;
+    errorCode?: string;
+    errorMessage?: string;
+    /** Rolling 24h error rate from `account_product_usage_events`, 0..100. */
+    errorRatePct?: number;
+    /** Sample size used to compute errorRatePct; if below threshold, treated as unknown. */
+    sampleSize?: number;
+    /** Whether the most recent observed call succeeded. */
+    lastObservationSucceeded?: boolean;
+    /** Token/credential expiry, if known. Drives token-expiry warnings. */
+    tokenExpiresAt?: string;
+    /** Free-form per-integration data carried to the dashboard. */
+    metadata?: Record<string, unknown>;
+}
+export interface ActivationResult {
+    success: boolean;
+    configData?: Record<string, unknown>;
+    externalId?: string;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+}
+interface BaseIntegrationComponentProps {
+    accountId: string;
+    sourceId?: string;
+    integrationConfig?: Record<string, unknown>;
+}
+type ProductReference = {
+    productId: string;
+    productSlug?: never;
+} | {
+    productSlug: string;
+    productId?: never;
+};
+export type IntegrationComponentProps = BaseIntegrationComponentProps & ProductReference;
+export type MarketplaceTileProps = IntegrationComponentProps & {
+    onActivate?: () => void;
+    isActivated?: boolean;
+    /** Navigation URL for the integration detail page */
+    href?: string;
+};
+export type ActivationFormProps = IntegrationComponentProps & {
+    onSuccess?: (result: ActivationResult) => void;
+    onCancel?: () => void;
+    isLoading?: boolean;
+    /** Render inline instead of in a dialog */
+    inline?: boolean;
+    /**
+     * The TEAM account context the user is activating within — separate from
+     * `accountId`, which for `scope: 'user'` integrations is collapsed to the
+     * personal account for activation storage/token purposes. Only consumed by
+     * workspace materialization (`materializeWorkspaceOnActivation`), never for
+     * activation/token storage itself (plan 009 Part A2). Optional: undefined
+     * for team-scoped integrations (their `accountId` already IS the team) and
+     * for any caller that hasn't threaded it yet — the server action falls back
+     * to `accountId` when absent.
+     */
+    teamAccountId?: string;
+};
+export interface IntegrationMetadata {
+    productId: string;
+    productSlug: string;
+    integrationName: string;
+    description: string;
+    category: string;
+    version: string;
+    icon?: string;
+    /** Bundled logo URL — overrides product.logo_path on the marketplace */
+    logoPath?: string;
+    /** When 'user', activation data is stored under the user's personal account (user.id) instead of the team account */
+    scope?: 'user' | 'team';
+    /**
+     * Set FALSE to assert this integration has NO self-serve activation surface —
+     * the marketplace detail page then renders no activation form at all.
+     *
+     * This is deliberately distinct from "has no CUSTOM activation form": an
+     * integration that omits `getActivationForm()` still gets the generic one, and
+     * six integrations depend on that. Use this flag only when submitting ANY
+     * activation form would be a dead end (e.g. Workflows, which is turned on by
+     * the `source_configs.enable_workflows` feature flag and whose `activate()`
+     * throws 'not implemented' — showing a form there hands the user a button that
+     * cannot work). Undefined/true = normal self-serve activation.
+     */
+    selfServeActivation?: boolean;
+    /**
+     * How this integration's MCP tools resolve credentials — the integration's
+     * SELF-DECLARATION of machine-executability, consumed dynamically by the
+     * workflow engine's fail-closed tool allowlist (isGatewayExposableTool).
+     *
+     *   'account' — credentials/identity resolve from team- or source-level
+     *     config via the ToolContext (`getAccountId(ctx)` + `ctx.supabase`).
+     *     Safe for durable machine-principal execution (workflows): eligible
+     *     tools (read + public/internal sensitivity) become workflow-callable.
+     *   'user' — credentials or identity are personal (ctx.user.id, personal
+     *     OAuth, session reads like getSupabaseServerClient()/requireUser()).
+     *     NEVER machine-executable: a workflow would silently ride one
+     *     employee's personal grant (N8N_INTEGRATION_PLAN adversarial #4).
+     *   'source' — platform-level credentials (diagnostics-class integrations).
+     *     Not exposed to account workflows.
+     *
+     * UNDECLARED = fail closed (treated as not machine-executable). Declaring
+     * 'account' is a security assertion: the integration's MCP run() handlers
+     * must use ctx-based resolution ONLY — no session clients, no personal
+     * grants. A guard test in @kit/integrations-workflows enforces the obvious
+     * violations (session-client reads in mcp/ code of 'account' declarers).
+     */
+    credentialModel?: 'account' | 'user' | 'source';
+    /**
+     * What KIND of thing this integration is — the platform's presentation and
+     * governance discriminant. Undefined means `'integration'`, which is what
+     * every third-party connector is; the field only ever needs setting to opt
+     * INTO feature treatment.
+     *
+     *   'integration' — connects Fusion to a third party. Has credentials, an
+     *     activation flow, and a marketplace presence. Its widgets live on
+     *     workspace dashboards and it declares its workspaces via
+     *     `getWorkspaceTargets()`.
+     *   'feature' — a Fusion-native capability with a bespoke experience: no
+     *     third-party credentials, its own route tree under
+     *     `/home/[account]/…`, and its own sidebar section declared via
+     *     `getSidebarNav()` (optionally rendered by its own
+     *     `getSidebarComponent()`).
+     *
+     * The two are mutually exclusive on the nav question. A `'feature'` MUST
+     * declare `getSidebarNav()` and MUST NOT declare `getWorkspaceTargets()` —
+     * its widgets are placed onto whatever workspace an admin chooses in the
+     * composer (`/admin/sources/[id]/layout`) rather than onto a workspace
+     * named after itself. `apps/web/lib/workspaces/__tests__/sidebar-nav-declarations.test.ts`
+     * fails the build on either violation.
+     */
+    kind?: 'integration' | 'feature';
+}
+export interface WidgetConfig {
+    id: string;
+    name: string;
+    component: ComponentType<IntegrationComponentProps>;
+    gridSize?: {
+        cols: number;
+        rows: number;
+    } | {
+        cols: number;
+        rows: number;
+    }[];
+    gridPosition?: {
+        col: number;
+        row: number;
+    };
+    widgetState: 'active' | 'inactive' | 'disabled';
+    layouts?: {
+        lg?: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            maxHeight?: number;
+        };
+        md?: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            maxHeight?: number;
+        };
+        sm?: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+            maxHeight?: number;
+        };
+    };
+    integrationMetadata?: IntegrationMetadata;
+    category?: {
+        id: string;
+        name: string;
+        slug: string;
+        icon: string | null;
+    };
+    productId?: string;
+    isCollapsible?: boolean;
+    collapsed?: boolean;
+    widgetConfigId?: string;
+    workspaceId?: string | null;
+    isPinnable?: boolean;
+    isPinned?: boolean;
+    aiFooterEnabled?: boolean;
+    health?: {
+        status: HealthStatus;
+        lastSuccessAt?: string | null;
+        errorMessage?: string | null;
+    };
+}
+export interface IntegrationConfig {
+    id: string;
+    account_id: string | null;
+    product_id: string;
+    config_type: 'api_credentials' | 'activation_data' | 'settings';
+    config_data: Record<string, unknown>;
+    status: 'active' | 'inactive' | 'pending' | 'error' | 'suspended';
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+    created_by: string | null;
+    updated_by: string | null;
+}
+/**
+ * The PARTNER-VISIBLE `data_type` values on `account_product_data` — a strict
+ * SUBSET of `@kit/integrations-core`'s union.
+ *
+ * `'secret'` is deliberately absent. Secret rows are host-managed (one row per
+ * secret name, value in Vault, `vault_secret_id` on the row), written only by
+ * the capability context's `persistSecret` and read only through
+ * `ctx.secrets`. Naming the kind here would advertise a row shape partner code
+ * must never address: `ctx.storage` rejects it, and core's generic accessors
+ * reject it too (`config-utils.ts`, `assertNotHostOnlyDataType`) precisely
+ * because a write there would land the plaintext in the `data` column.
+ *
+ * When you add an integration-specific kind, add it in BOTH places (core owns
+ * the full union) and keep this one partner-appropriate. Prefer `dataSubtype`
+ * for orthogonal slicing within a kind (e.g. `data_type='cache'`,
+ * `data_subtype='profile'`); reserve a new top-level kind for data that has a
+ * distinct lifecycle or is queried independently.
+ */
+export type AccountProductDataType = 'activation' | 'settings' | 'metrics_summary' | 'sync_state' | 'cache' | 'cash_forecast' | 'tax_config';
+export interface AccountProductData {
+    id: string;
+    account_id: string;
+    product_id: string;
+    data_type: AccountProductDataType;
+    data_subtype?: string;
+    data: Record<string, unknown>;
+    expires_at?: string;
+    integration_config_id?: string;
+    external_id?: string;
+    created_at: string;
+    updated_at: string;
+    created_by: string | null;
+    updated_by: string | null;
+}
+export {};

package/dist/types/integration.js

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

package/dist/types/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.js","sourceRoot":"","sources":["../../src/types/integration.ts"],"names":[],"mappings":"","sourcesContent":["import type { ComponentType } from 'react';\n\nimport type { IconRenderer } from './icon';\n\n// Capability shown on the integration detail page (numbered grid)\nexport interface IntegrationCapability {\n  label: string;\n  description: string;\n  icon?: IconRenderer;\n}\n\n// Permission scope shown on the integration detail page\nexport interface IntegrationPermission {\n  label: string;\n  detail: string;\n  type: 'read' | 'write';\n}\n\n// ---- Integration Health Monitoring (issue #474) -----------------------------\n\n// Higher = healthier. Used internally for \"least healthy wins\" merging.\nexport type HealthStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';\n\n/**\n * Result returned by `BaseIntegration.healthCheck(accountId)`. Routed through\n * `classifyHealth()` (server-side) before writing to\n * `integration_health_status`.\n */\nexport interface HealthCheckResult {\n  status: HealthStatus;\n  errorCode?: string;\n  errorMessage?: string;\n  /** Rolling 24h error rate from `account_product_usage_events`, 0..100. */\n  errorRatePct?: number;\n  /** Sample size used to compute errorRatePct; if below threshold, treated as unknown. */\n  sampleSize?: number;\n  /** Whether the most recent observed call succeeded. */\n  lastObservationSucceeded?: boolean;\n  /** Token/credential expiry, if known. Drives token-expiry warnings. */\n  tokenExpiresAt?: string;\n  /** Free-form per-integration data carried to the dashboard. */\n  metadata?: Record<string, unknown>;\n}\n\n// Activation result from integration\nexport interface ActivationResult {\n  success: boolean;\n  configData?: Record<string, unknown>;\n  externalId?: string;\n  errorMessage?: string;\n  metadata?: Record<string, unknown>;\n}\n\n// Base props that all integration components need\ninterface BaseIntegrationComponentProps {\n  accountId: string;\n  sourceId?: string;\n  integrationConfig?: Record<string, unknown>;\n}\n\n// Discriminated union for product reference - only one allowed\ntype ProductReference =\n  | { productId: string; productSlug?: never }\n  | { productSlug: string; productId?: never };\n\n// New base type using discriminated union\nexport type IntegrationComponentProps = BaseIntegrationComponentProps &\n  ProductReference;\n\n// Marketplace tile props\nexport type MarketplaceTileProps = IntegrationComponentProps & {\n  onActivate?: () => void;\n  isActivated?: boolean;\n  /** Navigation URL for the integration detail page */\n  href?: string;\n};\n\n// Activation form props\nexport type ActivationFormProps = IntegrationComponentProps & {\n  onSuccess?: (result: ActivationResult) => void;\n  onCancel?: () => void;\n  isLoading?: boolean;\n  /** Render inline instead of in a dialog */\n  inline?: boolean;\n  /**\n   * The TEAM account context the user is activating within — separate from\n   * `accountId`, which for `scope: 'user'` integrations is collapsed to the\n   * personal account for activation storage/token purposes. Only consumed by\n   * workspace materialization (`materializeWorkspaceOnActivation`), never for\n   * activation/token storage itself (plan 009 Part A2). Optional: undefined\n   * for team-scoped integrations (their `accountId` already IS the team) and\n   * for any caller that hasn't threaded it yet — the server action falls back\n   * to `accountId` when absent.\n   */\n  teamAccountId?: string;\n};\n\n// Integration metadata\nexport interface IntegrationMetadata {\n  productId: string;\n  productSlug: string;\n  integrationName: string;\n  description: string;\n  category: string;\n  version: string;\n  icon?: string;\n  /** Bundled logo URL — overrides product.logo_path on the marketplace */\n  logoPath?: string;\n  /** When 'user', activation data is stored under the user's personal account (user.id) instead of the team account */\n  scope?: 'user' | 'team';\n  /**\n   * Set FALSE to assert this integration has NO self-serve activation surface —\n   * the marketplace detail page then renders no activation form at all.\n   *\n   * This is deliberately distinct from \"has no CUSTOM activation form\": an\n   * integration that omits `getActivationForm()` still gets the generic one, and\n   * six integrations depend on that. Use this flag only when submitting ANY\n   * activation form would be a dead end (e.g. Workflows, which is turned on by\n   * the `source_configs.enable_workflows` feature flag and whose `activate()`\n   * throws 'not implemented' — showing a form there hands the user a button that\n   * cannot work). Undefined/true = normal self-serve activation.\n   */\n  selfServeActivation?: boolean;\n  /**\n   * How this integration's MCP tools resolve credentials — the integration's\n   * SELF-DECLARATION of machine-executability, consumed dynamically by the\n   * workflow engine's fail-closed tool allowlist (isGatewayExposableTool).\n   *\n   *   'account' — credentials/identity resolve from team- or source-level\n   *     config via the ToolContext (`getAccountId(ctx)` + `ctx.supabase`).\n   *     Safe for durable machine-principal execution (workflows): eligible\n   *     tools (read + public/internal sensitivity) become workflow-callable.\n   *   'user' — credentials or identity are personal (ctx.user.id, personal\n   *     OAuth, session reads like getSupabaseServerClient()/requireUser()).\n   *     NEVER machine-executable: a workflow would silently ride one\n   *     employee's personal grant (N8N_INTEGRATION_PLAN adversarial #4).\n   *   'source' — platform-level credentials (diagnostics-class integrations).\n   *     Not exposed to account workflows.\n   *\n   * UNDECLARED = fail closed (treated as not machine-executable). Declaring\n   * 'account' is a security assertion: the integration's MCP run() handlers\n   * must use ctx-based resolution ONLY — no session clients, no personal\n   * grants. A guard test in @kit/integrations-workflows enforces the obvious\n   * violations (session-client reads in mcp/ code of 'account' declarers).\n   */\n  credentialModel?: 'account' | 'user' | 'source';\n  /**\n   * What KIND of thing this integration is — the platform's presentation and\n   * governance discriminant. Undefined means `'integration'`, which is what\n   * every third-party connector is; the field only ever needs setting to opt\n   * INTO feature treatment.\n   *\n   *   'integration' — connects Fusion to a third party. Has credentials, an\n   *     activation flow, and a marketplace presence. Its widgets live on\n   *     workspace dashboards and it declares its workspaces via\n   *     `getWorkspaceTargets()`.\n   *   'feature' — a Fusion-native capability with a bespoke experience: no\n   *     third-party credentials, its own route tree under\n   *     `/home/[account]/…`, and its own sidebar section declared via\n   *     `getSidebarNav()` (optionally rendered by its own\n   *     `getSidebarComponent()`).\n   *\n   * The two are mutually exclusive on the nav question. A `'feature'` MUST\n   * declare `getSidebarNav()` and MUST NOT declare `getWorkspaceTargets()` —\n   * its widgets are placed onto whatever workspace an admin chooses in the\n   * composer (`/admin/sources/[id]/layout`) rather than onto a workspace\n   * named after itself. `apps/web/lib/workspaces/__tests__/sidebar-nav-declarations.test.ts`\n   * fails the build on either violation.\n   */\n  kind?: 'integration' | 'feature';\n}\n\n// Widget configuration\nexport interface WidgetConfig {\n  id: string;\n  name: string;\n  component: ComponentType<IntegrationComponentProps>;\n  gridSize?: { cols: number; rows: number } | { cols: number; rows: number }[];\n  gridPosition?: { col: number; row: number };\n  widgetState: 'active' | 'inactive' | 'disabled';\n  // React-grid-layout format\n  layouts?: {\n    lg?: { x: number; y: number; w: number; h: number; maxHeight?: number };\n    md?: { x: number; y: number; w: number; h: number; maxHeight?: number };\n    sm?: { x: number; y: number; w: number; h: number; maxHeight?: number };\n  };\n  // Integration metadata for widgets\n  integrationMetadata?: IntegrationMetadata;\n  category?: { id: string; name: string; slug: string; icon: string | null };\n  // Database product ID (UUID) from widget_config table\n  productId?: string;\n  isCollapsible?: boolean;\n  // For collapsed state persistence\n  collapsed?: boolean;\n  widgetConfigId?: string;\n  // Resolved workspace placement (explicit widget_config.workspace_id\n  // override, else the product's inheriting attachment). Populated by the\n  // dashboard widgets loader; null = no workspace (unscoped dashboard).\n  workspaceId?: string | null;\n  isPinnable?: boolean;\n  isPinned?: boolean;\n  // When true, the dashboard renders the \"Ask about this\" AI footer bar for\n  // this widget. The widget may still pass `askContext` to the wrapper for a\n  // rich snapshot; otherwise a minimal default is used.\n  aiFooterEnabled?: boolean;\n  // Integration health for this widget's product. `unhealthy` downgrades the\n  // widget to `disabled`; `degraded` surfaces a stale-data footer.\n  health?: {\n    status: HealthStatus;\n    lastSuccessAt?: string | null;\n    errorMessage?: string | null;\n  };\n}\n\n// Database types for integration tables.\n//\n// PARTNER-VISIBLE SUBSET: these row types deliberately OMIT `vault_secret_id`.\n// A vault id is a host handle to a decryptable secret; the partner surface\n// never exposes one (docs/devex/sdk-export-map.md, \"Vault access\" —\n// `ctx.secrets` fences it off). `@kit/integrations-core` keeps the full row\n// (host code needs the handle); `types/__tests__/core-parity.test-d.ts` pins\n// the SDK type as core's row minus exactly the host-only fields, so a new\n// core column cannot drift in here unnoticed.\nexport interface IntegrationConfig {\n  id: string;\n  account_id: string | null;\n  product_id: string;\n  config_type: 'api_credentials' | 'activation_data' | 'settings';\n  config_data: Record<string, unknown>;\n  status: 'active' | 'inactive' | 'pending' | 'error' | 'suspended';\n  is_active: boolean;\n  created_at: string;\n  updated_at: string;\n  created_by: string | null;\n  updated_by: string | null;\n}\n\n/**\n * The PARTNER-VISIBLE `data_type` values on `account_product_data` — a strict\n * SUBSET of `@kit/integrations-core`'s union.\n *\n * `'secret'` is deliberately absent. Secret rows are host-managed (one row per\n * secret name, value in Vault, `vault_secret_id` on the row), written only by\n * the capability context's `persistSecret` and read only through\n * `ctx.secrets`. Naming the kind here would advertise a row shape partner code\n * must never address: `ctx.storage` rejects it, and core's generic accessors\n * reject it too (`config-utils.ts`, `assertNotHostOnlyDataType`) precisely\n * because a write there would land the plaintext in the `data` column.\n *\n * When you add an integration-specific kind, add it in BOTH places (core owns\n * the full union) and keep this one partner-appropriate. Prefer `dataSubtype`\n * for orthogonal slicing within a kind (e.g. `data_type='cache'`,\n * `data_subtype='profile'`); reserve a new top-level kind for data that has a\n * distinct lifecycle or is queried independently.\n */\nexport type AccountProductDataType =\n  | 'activation'\n  | 'settings'\n  | 'metrics_summary'\n  | 'sync_state'\n  | 'cache'\n  // Integration-specific kinds — extend here when needed.\n  | 'cash_forecast' // quickbooks — user-supplied manual cash-forecast estimates\n  | 'tax_config'; // quickbooks — per-user federal/state tax rate config\n\nexport interface AccountProductData {\n  id: string;\n  account_id: string;\n  product_id: string;\n  data_type: AccountProductDataType;\n  data_subtype?: string;\n  data: Record<string, unknown>;\n  expires_at?: string;\n  integration_config_id?: string;\n  external_id?: string;\n  created_at: string;\n  updated_at: string;\n  created_by: string | null;\n  updated_by: string | null;\n}\n"]}

package/dist/types/widget-ask-context.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A widget snapshot is a JSON-serializable view of what the user currently
+ * sees in the widget. It MUST NOT contain React nodes, functions, class
+ * instances, credentials, tokens, or internal-only IDs. The chat API route
+ * validates the shape before injecting it into the system prompt.
+ */
+export type WidgetSnapshot = Record<string, unknown> | null;
+/**
+ * A pre-canned prompt rendered as a pill inside the expanded "Ask about this"
+ * footer. Clicking a suggestion dispatches the prompt to the assistant dock
+ * along with the widget's snapshot.
+ */
+export interface WidgetSuggestedPrompt {
+    label: string;
+    prompt: string;
+}
+/**
+ * Context a widget passes to the AI assistant when its "Ask about this"
+ * bar is submitted. The bridge in apps/web attaches `snapshot` to the user
+ * message as AI SDK message metadata (NOT as visible chat text). The chat
+ * API route injects the snapshot into the system instruction so the model
+ * has authoritative widget state; the dock UI renders a small attachment
+ * chip above the user bubble using `title` as the label.
+ */
+export interface WidgetAskContext {
+    widgetId: string;
+    title: string;
+    snapshot: WidgetSnapshot;
+    suggestedPrompt: string;
+    /**
+     * Optional pre-canned prompts shown as pills above the input in the
+     * expanded "Ask about this" footer. Use these to surface the same
+     * contextual prompts that previously sat on the widget body.
+     */
+    suggestedPrompts?: WidgetSuggestedPrompt[];
+}

package/dist/types/widget-ask-context.js

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

package/dist/types/widget-ask-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-ask-context.js","sourceRoot":"","sources":["../../src/types/widget-ask-context.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * A widget snapshot is a JSON-serializable view of what the user currently\n * sees in the widget. It MUST NOT contain React nodes, functions, class\n * instances, credentials, tokens, or internal-only IDs. The chat API route\n * validates the shape before injecting it into the system prompt.\n */\nexport type WidgetSnapshot = Record<string, unknown> | null;\n\n/**\n * A pre-canned prompt rendered as a pill inside the expanded \"Ask about this\"\n * footer. Clicking a suggestion dispatches the prompt to the assistant dock\n * along with the widget's snapshot.\n */\nexport interface WidgetSuggestedPrompt {\n  label: string;\n  prompt: string;\n}\n\n/**\n * Context a widget passes to the AI assistant when its \"Ask about this\"\n * bar is submitted. The bridge in apps/web attaches `snapshot` to the user\n * message as AI SDK message metadata (NOT as visible chat text). The chat\n * API route injects the snapshot into the system instruction so the model\n * has authoritative widget state; the dock UI renders a small attachment\n * chip above the user bubble using `title` as the label.\n */\nexport interface WidgetAskContext {\n  widgetId: string;\n  title: string;\n  snapshot: WidgetSnapshot;\n  suggestedPrompt: string;\n  /**\n   * Optional pre-canned prompts shown as pills above the input in the\n   * expanded \"Ask about this\" footer. Use these to surface the same\n   * contextual prompts that previously sat on the widget body.\n   */\n  suggestedPrompts?: WidgetSuggestedPrompt[];\n}\n"]}

package/dist/types/workspace-target.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The contract an integration uses to declare the workspaces it ships with
+ * (`BaseIntegration.getWorkspaceTargets()`).
+ *
+ * The host's canonical definition is `z.input<typeof WorkspaceTargetSchema>`
+ * (`@kit/integrations-core`, `schemas/workspace-target.schema.ts`) — the
+ * schema validates declarations in CI and at materialization time, including
+ * cross-field rules a type cannot carry (icon-name validity, slug format,
+ * `inheritsWidgets`/`includedWidgetIds` exclusivity, one inheriting target
+ * per set). This structural twin exists so the SDK's root entrypoint owns its
+ * types without importing the host schema; the parity test beside these types
+ * keeps the two shapes mutually assignable.
+ */
+export interface WorkspaceTargetDefinition {
+    /** Stable URL segment — `/workspace/<slug>` routes reference it. Lowercase
+     * alphanumeric with single hyphens between segments. */
+    slug: string;
+    name: string;
+    /** A Font Awesome class value, or a legacy lucide-react name the shared
+     * lucide→FA map can translate. Validated by the host at gate time. */
+    icon?: string;
+    description?: string;
+    /** Defaults to `'masonry'` when omitted. */
+    layout?: 'masonry' | 'two-column';
+    /**
+     * Whether this workspace receives the product's otherwise-unplaced
+     * widgets. Exactly one target per product must set it; mutually exclusive
+     * with `includedWidgetIds`.
+     */
+    inheritsWidgets?: boolean;
+    /** Limit this workspace to specific widget ids. */
+    includedWidgetIds?: string[];
+}

package/dist/types/workspace-target.js

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

package/dist/types/workspace-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-target.js","sourceRoot":"","sources":["../../src/types/workspace-target.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The contract an integration uses to declare the workspaces it ships with\n * (`BaseIntegration.getWorkspaceTargets()`).\n *\n * The host's canonical definition is `z.input<typeof WorkspaceTargetSchema>`\n * (`@kit/integrations-core`, `schemas/workspace-target.schema.ts`) — the\n * schema validates declarations in CI and at materialization time, including\n * cross-field rules a type cannot carry (icon-name validity, slug format,\n * `inheritsWidgets`/`includedWidgetIds` exclusivity, one inheriting target\n * per set). This structural twin exists so the SDK's root entrypoint owns its\n * types without importing the host schema; the parity test beside these types\n * keeps the two shapes mutually assignable.\n */\nexport interface WorkspaceTargetDefinition {\n  /** Stable URL segment — `/workspace/<slug>` routes reference it. Lowercase\n   * alphanumeric with single hyphens between segments. */\n  slug: string;\n  name: string;\n  /** A Font Awesome class value, or a legacy lucide-react name the shared\n   * lucide→FA map can translate. Validated by the host at gate time. */\n  icon?: string;\n  description?: string;\n  /** Defaults to `'masonry'` when omitted. */\n  layout?: 'masonry' | 'two-column';\n  /**\n   * Whether this workspace receives the product's otherwise-unplaced\n   * widgets. Exactly one target per product must set it; mutually exclusive\n   * with `includedWidgetIds`.\n   */\n  inheritsWidgets?: boolean;\n  /** Limit this workspace to specific widget ids. */\n  includedWidgetIds?: string[];\n}\n"]}

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "@ekanos/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The official SDK for building Ekanos integrations.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/companydotcom/fusion.git",
+    "directory": "packages/integration-sdk"
+  },
+  "homepage": "https://github.com/companydotcom/fusion/tree/dev/packages/integration-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/companydotcom/fusion/issues"
+  },
+  "sideEffects": [
+    "**/mcp/**"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "default": "./dist/hooks/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    },
+    "./context": {
+      "types": "./dist/context/index.d.ts",
+      "default": "./dist/context/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./integration": {
+      "types": "./dist/integration/index.d.ts",
+      "default": "./dist/integration/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "2.87.1",
+    "server-only": "^0.0.1",
+    "@ekanos/integration-schema": "0.1.0",
+    "@ekanos/ui": "0.1.0"
+  },
+  "peerDependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@tanstack/react-query": "^5.101.4",
+    "next": "^16.0.0",
+    "react": "^19.2.8",
+    "react-hook-form": "^7.68.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@tanstack/react-query": "5.101.4",
+    "@types/react": "19.2.18",
+    "next": "16.3.1",
+    "react": "19.2.8",
+    "react-hook-form": "^7.68.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.10",
+    "zod": "^3.25.74",
+    "@kit/tsconfig": "0.1.0",
+    "@kit/eslint-config": "0.2.0",
+    "@kit/prettier-config": "0.1.0"
+  },
+  "prettier": "@kit/prettier-config",
+  "typesVersions": {
+    "*": {
+      "context": [
+        "dist/context/index.d.ts"
+      ],
+      "testing": [
+        "dist/testing/index.d.ts"
+      ],
+      "integration": [
+        "dist/integration/index.d.ts"
+      ],
+      "*": [
+        "dist/*"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/rewrite-esm-specifiers.mjs",
+    "clean": "git clean -xdf .turbo node_modules dist",
+    "format": "prettier --check \"**/*.{ts,tsx}\"",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "api-report": "node scripts/api-report.mjs",
+    "api-report:check": "node scripts/api-report.mjs --check",
+    "pack:test": "node scripts/pack-test.mjs"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}