@ekanos/sdk 0.5.0 → 0.7.0

package/README.md

@@ -30,7 +30,7 @@ one. Each has its own README.
   - [`webhooks`](#webhooks)
   - [`schedules`](#schedules)
   - [`oauth`](#oauth)
-  - [`proposes` — what you suggest, the host decides](#proposes)
+  - [`proposes` — your credential model and tool classifications](#proposes)
   - [`workspaceTargets`](#workspacetargets)
 - [Testing](#testing)
 - [Entrypoints](#entrypoints)
@@ -190,7 +190,7 @@ There is no raw database client, no Supabase, and no request object.
 | `ctx.secrets` | `get(name)`, `names()`, `set(name, value)` over the resolved credential set |
 | `ctx.fetch` | `fetch`, refusing anything outside `egress` before it opens a socket |
 | `ctx.logger` | `debug`/`info`/`warn`/`error`, each `(context: object, message: string)` — pino-style, pre-bound with `{integration, accountId, actor}` |
-| `ctx.actor` | `{ kind: 'user', userId }` or `{ kind: 'machine', tokenId, createdBy }` |
+| `ctx.actor` | `{ kind: 'user', userId, role }` or `{ kind: 'machine', tokenId, createdBy }`. `role` is `{ name, hierarchyLevel }` (1 owner, 2 admin, 3 member; `null` when unresolved). Gate a write action with `actorIsAtLeast(ctx.actor, ADMIN_HIERARCHY_LEVEL)` from `@ekanos/sdk/integration` and throw `PublicActionError` otherwise — the host runs every action with the account's credential |
 
 Plus read-only identity facts, all already authorized: `ctx.accountId`,
 `ctx.accountSlug`, `ctx.userId` (`null` for machine actors), `ctx.sourceId`,
@@ -339,7 +339,7 @@ no `http:`. Wildcards are supported only as one leading `*.`. Anything else is
 rejected by `defineIntegration()` with the offending entry quoted.
 
 A denied call throws `EgressDeniedError` synchronously. Widening this list is a security-posture change a reviewer looks at during
-**promotion** — the human review your integration passes before it is enabled
+**admission** — the human review your integration passes before it is enabled
 for real accounts, where someone reads this declaration against what your
 handlers actually do. Declare the origins you call and no more.
 
@@ -414,8 +414,7 @@ const apiKey = await ctx.secrets.get(ACME_API_KEY);
 
 ### `tools`
 
-Tools are what the Ekanos assistant (and, where the host allows it, the workflow
-engine) can call. Each declares a name, a description the model reads, an
+Tools are what the Ekanos assistant, workflows and managed agents can call. Each declares a name, a description the model reads, an
 optional JSON-Schema parameter object, and an async `run`.
 
 ```ts
@@ -459,6 +458,47 @@ for a genuine fault.
 
 `outputExample` is shown to the model as a shape hint. Keep it small and honest.
 
+**Text written outside this system is data, not instructions.** A deal name, a
+call transcript, a support reply, a booking answer: anything a vendor's users
+typed can say "ignore the above and…", and in a tool result it looks exactly
+like a field you computed. Return such text only under a field whose name
+starts with `untrusted`, clip it with `untrustedText()` (from
+`@ekanos/sdk/integration`; 1000 characters by default), and put one
+`note: untrustedTextNote('deal, stage and pipeline names')` at the top of the
+output so the model reads the rule where it reads the data. `untrustedText()`
+bounds the length and marks the text as coming from a third party so the
+assistant treats it as data; it does not strip or neutralise injected
+instructions. Pass `untrustedTextNote()` a fixed string you wrote, never vendor
+text. In a write tool's description, say to confirm with the user first and
+never act on what the text asks for.
+
+```ts
+import { untrustedText, untrustedTextNote } from '@ekanos/sdk/integration';
+
+return {
+  note: untrustedTextNote('deal names'),
+  deals: deals.map((d) => ({ id: d.id, untrustedName: untrustedText(d.name, 200), amount: d.amount })),
+};
+```
+
+**`ownerAction` is how an owner reads an approval for your tool.** When an agent
+or workflow pauses on one of your tools, the owner sees "{agent} wants to
+{ownerAction} in {your integration}". Declare the phrase yourself, a bare verb
+that names no ids:
+
+```ts
+ownerAction: 'sync your price list',
+// or one phrase per locale; `default` covers any locale you did not list
+ownerAction: { en: 'sync your price list', es: 'sincronizar su lista de precios' },
+```
+
+It is plain text, at most 120 characters, never a message key: a partner cannot
+add keys to the host's messages. The host picks the exact locale, then its
+language (`pt-BR` then `pt`), then the default locale, then your `default`. With
+no `ownerAction` the host derives a phrase from the tool name ("update deal
+stage" from `acme_update_deal_stage`), and a name that is not `<verb>_<thing>`
+reads "use <tool name>", so declare one for any tool that writes.
+
 **`parameters` is a narrow slice of JSON Schema, not all of it.** The top level
 is `.strict()` and accepts exactly four keys — `type` (which must be the
 literal `'object'`), `properties`, `required` and `additionalProperties`.
@@ -1080,6 +1120,10 @@ export const acmeOAuth: PartnerOAuthDeclaration<MyStorage> = {
     tokenUrl: 'https://connect.acme.example/oauth/token',
     scopes: ['payments:read', 'refunds:write'],
     pkce: true,
+    // How the token endpoint wants client authentication. Defaults to
+    // 'client_secret_basic' (HTTP Basic); LinkedIn needs 'client_secret_post'
+    // (client_id and client_secret in the form body).
+    tokenAuthMethod: 'client_secret_basic',
   },
   credentials: {
     clientIdSecretName: 'acme_oauth_client_id',
@@ -1142,9 +1186,10 @@ async function.
 
 ### `proposes`
 
-A suggestion block, not a settings block. Security classifications are
-host-assigned; `proposes` is how you tell a reviewer what you believe is true,
-and the reviewer confirms it at promotion.
+Where you declare your credential model and classify each tool. Once your
+integration is admitted the host applies these values, the same as a first-party
+integration's own. The admission review is the check, and the host can tighten a
+declaration (never loosen it).
 
 ```ts
 proposes: {
@@ -1155,22 +1200,32 @@ proposes: {
   tools: {
     list_recent_payments: { effect: 'read',  sensitivity: 'financial' },
     // Honest classification: this moves money. Marking it 'read' or
-    // 'internal' to get past a gate is what promotion review exists to catch.
+    // 'internal' to get past a gate is a review failure at admission.
     refund_payment:       { effect: 'write', sensitivity: 'financial' },
   },
 },
 ```
 
 `effect` is `'read' | 'write'`. `sensitivity` is `'public' | 'internal' | 'pii'
-| 'financial'`. Both are optional per tool.
+| 'financial'`. Classify every tool: a field you leave out falls back to
+`effect: 'write'` and `sensitivity: 'pii'`, and a tool treated that way will not
+run in a team workflow.
 
 The keys of `proposes.tools` must match declared tool names exactly — a
 proposal for a tool you did not declare is a validation error, so a rename
 cannot leave a stale classification behind.
 
-Why it matters: an undeclared `credentialModel` fails closed. The workflow
-engine's tool allowlist treats it as not machine-executable, so a tool you
-believe is workflow-callable will not be until this is declared and confirmed.
+What the host does with it:
+
+- `credentialModel` decides which workflows may call your tools. Team workflows
+  (a machine actor) admit `'account'` and `'source'`; personal workflows (the
+  user) admit `'user'` and `'account'`. Undeclared means workflows cannot use
+  your tools.
+- Team workflows never expose `pii` or `financial` tools, and a `write` tool
+  needs an approval step in the workflow. Agents use their per-tool approval
+  policy. Personal workflows and the chat assistant apply no sensitivity gate.
+- `ctx.storage.user` still throws for machine actors, and partner OAuth tokens
+  stay account-scoped.
 
 ### `workspaceTargets`
 
@@ -1240,6 +1295,37 @@ Both throw if the id is not declared, and `invokeWebhook` throws if the payload
 fails `payloadSchema` — the handler never runs. The local transport records the
 signature skip as one `warn` line on `ctx.logs`.
 
+`invokeWebhook` never verifies a signature — that is the transport's job — so a
+wrong header name or signed-payload template in your declaration would first
+show up as rejected deliveries on the host. `verifyDeclaredWebhookSignature()`
+closes that gap: it runs the host's own verifier against one declaration. Sign
+a payload in the test the way the VENDOR documents it and assert the
+declaration accepts it:
+
+```ts
+import { createHmac } from 'node:crypto';
+import { verifyDeclaredWebhookSignature } from '@ekanos/sdk/testing';
+
+const body = JSON.stringify(payload);
+const t = String(Math.floor(Date.now() / 1000));
+const v1 = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
+
+await expect(
+  verifyDeclaredWebhookSignature(integration, 'payment-updated', {
+    headers: { 'Stripe-Signature': `t=${t},v1=${v1}` },
+    rawBody: body,
+    secret,
+  }),
+).resolves.toEqual({ ok: true });
+```
+
+A failure reports the same reason the host would log (`missing-header`,
+`malformed-header`, `missing-timestamp`, `malformed-timestamp`,
+`stale-timestamp`, `missing-secret`, `mismatch`). An empty secret fails closed
+with `missing-secret`. It throws for an undeclared id and for a
+declaration with `signature: 'none'`. The verifier itself is also exported as
+`verifyWebhookSignature()` for a test that wants to drive it directly.
+
 `invokeActivate()` does the same for `onActivate` — no payload or invocation to
 build, just the handler against the definition-derived context:
 

package/api-report.md

@@ -9,9 +9,9 @@ This is the complete surface of every entrypoint. The authoring guide
 for these symbols is README.md. Entrypoints marked WORKSPACE-ONLY are
 not reachable from a published install — see the note in each section.
 
-Total exported names: **172** across 7 entrypoints.
+Total exported names: **212** across 8 entrypoints.
 
-## `@ekanos/sdk` (32 exports)
+## `@ekanos/sdk` (35 exports)
 
 | Export | Kind |
 | --- | --- |
@@ -19,6 +19,7 @@ Total exported names: **172** across 7 entrypoints.
 | `AccountProductDataType` | type alias |
 | `ActivationFormProps` | type alias |
 | `ActivationResult` | interface |
+| `AttentionSignal` | interface |
 | `HealthCheckResult` | interface |
 | `HealthStatus` | type alias |
 | `IntegrationActor` | type alias |
@@ -46,9 +47,11 @@ Total exported names: **172** across 7 entrypoints.
 | `WidgetConfig` | interface |
 | `WidgetSnapshot` | type alias |
 | `WidgetSuggestedPrompt` | interface |
+| `WidgetVerdict` | interface |
+| `WidgetVerdictTone` | type alias |
 | `WorkspaceTargetDefinition` | interface |
 
-## `@ekanos/sdk/components` (25 exports)
+## `@ekanos/sdk/components` (34 exports)
 
 | Export | Kind |
 | --- | --- |
@@ -70,15 +73,24 @@ Total exported names: **172** across 7 entrypoints.
 | `WidgetContextValue` | interface |
 | `WidgetData` | interface |
 | `WidgetDataLoading` | function |
+| `WidgetEmptyStateProps` | interface |
+| `WidgetHeaderTrailing` | type alias |
 | `WidgetHealth` | interface |
+| `WidgetInactiveReason` | type alias |
+| `WidgetInactiveState` | function |
+| `WidgetInactiveStateProps` | interface |
 | `WidgetMeta` | interface |
 | `WidgetPreviewProvider` | function |
 | `WidgetPreviewProviderProps` | interface |
 | `WidgetRenderState` | type alias |
+| `WidgetSkeletonVariant` | type alias |
+| `WidgetSource` | interface |
 | `WidgetState` | interface |
+| `WidgetStateAction` | interface |
 | `currentReturnPath` | function |
+| `useWidgetVerdict` | function |
 
-## `@ekanos/sdk/hooks` (43 exports)
+## `@ekanos/sdk/hooks` (45 exports)
 
 | Export | Kind |
 | --- | --- |
@@ -99,6 +111,7 @@ Total exported names: **172** across 7 entrypoints.
 | `IntegrationActivationProvider` | function |
 | `IntegrationFetchProvider` | function |
 | `OAuthErrorParam` | interface |
+| `OAuthWidgetGateOptions` | type alias |
 | `PartnerOAuthPathOptions` | interface |
 | `PublishEventInput` | interface |
 | `UseIntegrationActionOptions` | interface |
@@ -111,6 +124,7 @@ Total exported names: **172** across 7 entrypoints.
 | `fetchIntegrationStorage` | function |
 | `integrationActionUrl` | function |
 | `integrationStorageUrl` | function |
+| `oauthWidgetGateOptionsFor` | function |
 | `partnerOAuthConnectPath` | function |
 | `partnerOAuthErrorParam` | function |
 | `partnerOAuthStatusUrl` | function |
@@ -169,7 +183,7 @@ Total exported names: **172** across 7 entrypoints.
 | `requireContext` | function |
 | `resolveStorageKeyDeclaration` | function |
 
-## `@ekanos/sdk/testing` (17 exports)
+## `@ekanos/sdk/testing` (22 exports)
 
 | Export | Kind |
 | --- | --- |
@@ -184,18 +198,27 @@ Total exported names: **172** across 7 entrypoints.
 | `RecordedFetchCall` | interface |
 | `RecordedLog` | interface |
 | `ScheduleInvocationOutcome` | interface |
+| `SignatureVerification` | type alias |
+| `VerifyDeclaredWebhookSignatureOptions` | interface |
+| `VerifyWebhookSignatureArgs` | interface |
 | `WebhookInvocationOutcome` | interface |
 | `createMockContext` | function |
 | `createMockFetchProvider` | function |
 | `invokeActivate` | function |
 | `invokeSchedule` | function |
 | `invokeWebhook` | function |
+| `verifyDeclaredWebhookSignature` | function |
+| `verifyWebhookSignature` | function |
 
-## `@ekanos/sdk/integration` (31 exports)
+## `@ekanos/sdk/integration` (41 exports)
 
 | Export | Kind |
 | --- | --- |
+| `ADMIN_HIERARCHY_LEVEL` | variable |
+| `AttentionHandler` | type alias |
+| `AttentionSignal` | interface |
 | `DEFAULT_SIGNATURE_TOLERANCE_SECONDS` | variable |
+| `DEFAULT_UNTRUSTED_TEXT_MAX_CHARS` | variable |
 | `DefinitionCollisionInput` | interface |
 | `FirstPartyInventory` | interface |
 | `IntegrationCapabilityDeclaration` | type alias |
@@ -206,6 +229,7 @@ Total exported names: **172** across 7 entrypoints.
 | `IntegrationProposals` | type alias |
 | `OAuthProviderDeclaration` | interface |
 | `OAuthTokens` | interface |
+| `OWNER_HIERARCHY_LEVEL` | variable |
 | `OnActivateHandler` | type alias |
 | `PARTNER_STORAGE_LIMITS` | variable |
 | `PartnerActionDeclaration` | interface |
@@ -223,6 +247,27 @@ Total exported names: **172** across 7 entrypoints.
 | `WebhookResult` | interface |
 | `WebhookSignatureDeclaration` | type alias |
 | `WebhookSignatureScheme` | interface |
+| `WidgetVerdict` | interface |
+| `WidgetVerdictTone` | type alias |
+| `actorIsAtLeast` | function |
 | `defineIntegration` | function |
 | `parseCronExpression` | function |
+| `untrustedText` | function |
+| `untrustedTextNote` | function |
 | `validateIntegrationDefinitions` | function |
+
+## `@ekanos/sdk/layout` (11 exports)
+
+| Export | Kind |
+| --- | --- |
+| `COMPACT_FROM_WIDTH` | variable |
+| `SizedWidget` | interface |
+| `WidgetRowGroup` | type alias |
+| `WidgetSize` | type alias |
+| `buildRowGroups` | function |
+| `getColSpan` | function |
+| `hasTrailingGap` | function |
+| `pairRows` | function |
+| `resolveWidgetSize` | function |
+| `snapFullWidthToRowBoundary` | function |
+| `splitBalanced` | function |

package/dist/components/index.d.ts

@@ -25,14 +25,14 @@
  * Surface discipline: additions require an entry in
  * api-report.md, regenerated by `pnpm --filter @ekanos/sdk api-report`.
  */
-export { Widget } from './widgets/widget.js';
-export { WidgetContext, type WidgetActions, type WidgetContextValue, type WidgetData, type WidgetHealth, type WidgetMeta, type WidgetRenderState, type WidgetState, } from './widgets/widget-context.js';
+export { Widget, useWidgetVerdict, type WidgetHeaderTrailing, } from './widgets/widget.js';
+export { WidgetContext, type WidgetActions, type WidgetContextValue, type WidgetData, type WidgetHealth, type WidgetMeta, type WidgetRenderState, type WidgetSource, type WidgetState, } from './widgets/widget-context.js';
 export { WidgetPreviewProvider } from './widgets/widget-preview-provider.js';
 export type { WidgetPreviewProviderProps } from './widgets/widget-preview-provider.js';
 export { AiPromptChip } from './widgets/ai-prompt-chip.js';
 export { AskIcon } from './widgets/ask-icon.js';
 export { WidgetAskBar } from './widgets/widget-ask-bar.js';
-export { WidgetDataLoading } from './widgets/widget-state-components.js';
+export { WidgetDataLoading, type WidgetEmptyStateProps, WidgetInactiveState, type WidgetInactiveReason, type WidgetInactiveStateProps, type WidgetSkeletonVariant, type WidgetStateAction, } from './widgets/widget-state-components.js';
 export { BaseActivationForm } from './base-activation-form.js';
 export type { BaseActivationFormProps } from './base-activation-form.js';
 export { ActivationDialog, ActivationInline, BaseActivationDialog, } from './base-activation-dialog.js';

package/dist/components/index.js

@@ -25,13 +25,13 @@
  * Surface discipline: additions require an entry in
  * api-report.md, regenerated by `pnpm --filter @ekanos/sdk api-report`.
  */
-export { Widget } from './widgets/widget.js';
+export { Widget, useWidgetVerdict, } from './widgets/widget.js';
 export { WidgetContext, } from './widgets/widget-context.js';
 export { WidgetPreviewProvider } from './widgets/widget-preview-provider.js';
 export { AiPromptChip } from './widgets/ai-prompt-chip.js';
 export { AskIcon } from './widgets/ask-icon.js';
 export { WidgetAskBar } from './widgets/widget-ask-bar.js';
-export { WidgetDataLoading } from './widgets/widget-state-components.js';
+export { WidgetDataLoading, WidgetInactiveState, } from './widgets/widget-state-components.js';
 export { BaseActivationForm } from './base-activation-form.js';
 export { ActivationDialog, ActivationInline, BaseActivationDialog, } from './base-activation-dialog.js';
 export { BaseMarketplaceTile } from './base-marketplace-tile.js';

package/dist/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EACL,aAAa,GAQd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["/**\n * @ekanos/sdk/components — client-side building blocks.\n *\n * Import from client components only. `Widget` is the compound API every\n * dashboard widget renders through; the activation forms are the two\n * sanctioned activation UX bases (credential-style and OAuth-style), and\n * `BaseMarketplaceTile` is the matching base for the marketplace tile.\n *\n * The SDK OWNS these implementations — the pre-inversion re-exports through\n * `@kit/integrations-core/components/*` are gone; core now re-exports FROM\n * here for first-party code (one source of truth, two consumption paths —\n * one source of truth with two consumption paths. UI primitives come from\n * `@ekanos/ui`\n * (the published slice of the host design system), never `@kit/ui`.\n *\n * Server seam: nothing here imports a server module. `OAuthActivationForm`\n * performs activation through the host-injected actions seam\n * (`IntegrationActivationProvider`, @ekanos/sdk/hooks) — a server-action\n * REFERENCE bound by the host, not server code shipped to the browser.\n *\n * `WidgetContext` is the single context identity both sides share: the\n * host's `DashboardWidgetProvider` (host chrome — persistence callbacks,\n * config hierarchy) provides it, the SDK's `Widget.*` reads it.\n *\n * Surface discipline: additions require an entry in\n * api-report.md, regenerated by `pnpm --filter @ekanos/sdk api-report`.\n */\n\nexport { Widget } from './widgets/widget';\nexport {\n  WidgetContext,\n  type WidgetActions,\n  type WidgetContextValue,\n  type WidgetData,\n  type WidgetHealth,\n  type WidgetMeta,\n  type WidgetRenderState,\n  type WidgetState,\n} from './widgets/widget-context';\nexport { WidgetPreviewProvider } from './widgets/widget-preview-provider';\nexport type { WidgetPreviewProviderProps } from './widgets/widget-preview-provider';\nexport { AiPromptChip } from './widgets/ai-prompt-chip';\nexport { AskIcon } from './widgets/ask-icon';\nexport { WidgetAskBar } from './widgets/widget-ask-bar';\nexport { WidgetDataLoading } from './widgets/widget-state-components';\n\nexport { BaseActivationForm } from './base-activation-form';\nexport type { BaseActivationFormProps } from './base-activation-form';\nexport {\n  ActivationDialog,\n  ActivationInline,\n  BaseActivationDialog,\n} from './base-activation-dialog';\n\nexport { BaseMarketplaceTile } from './base-marketplace-tile';\nexport type { BaseMarketplaceTileProps } from './base-marketplace-tile';\n\nexport { OAuthActivationForm } from './oauth-activation-form';\nexport type { OAuthActivationFormConfig } from './oauth-activation-form';\n\nexport { currentReturnPath } from './current-return-path';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,MAAM,EACN,gBAAgB,GAEjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,GASd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EACL,iBAAiB,EAEjB,mBAAmB,GAKpB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["/**\n * @ekanos/sdk/components — client-side building blocks.\n *\n * Import from client components only. `Widget` is the compound API every\n * dashboard widget renders through; the activation forms are the two\n * sanctioned activation UX bases (credential-style and OAuth-style), and\n * `BaseMarketplaceTile` is the matching base for the marketplace tile.\n *\n * The SDK OWNS these implementations — the pre-inversion re-exports through\n * `@kit/integrations-core/components/*` are gone; core now re-exports FROM\n * here for first-party code (one source of truth, two consumption paths —\n * one source of truth with two consumption paths. UI primitives come from\n * `@ekanos/ui`\n * (the published slice of the host design system), never `@kit/ui`.\n *\n * Server seam: nothing here imports a server module. `OAuthActivationForm`\n * performs activation through the host-injected actions seam\n * (`IntegrationActivationProvider`, @ekanos/sdk/hooks) — a server-action\n * REFERENCE bound by the host, not server code shipped to the browser.\n *\n * `WidgetContext` is the single context identity both sides share: the\n * host's `DashboardWidgetProvider` (host chrome — persistence callbacks,\n * config hierarchy) provides it, the SDK's `Widget.*` reads it.\n *\n * Surface discipline: additions require an entry in\n * api-report.md, regenerated by `pnpm --filter @ekanos/sdk api-report`.\n */\n\nexport {\n  Widget,\n  useWidgetVerdict,\n  type WidgetHeaderTrailing,\n} from './widgets/widget';\nexport {\n  WidgetContext,\n  type WidgetActions,\n  type WidgetContextValue,\n  type WidgetData,\n  type WidgetHealth,\n  type WidgetMeta,\n  type WidgetRenderState,\n  type WidgetSource,\n  type WidgetState,\n} from './widgets/widget-context';\nexport { WidgetPreviewProvider } from './widgets/widget-preview-provider';\n\nexport type { WidgetPreviewProviderProps } from './widgets/widget-preview-provider';\nexport { AiPromptChip } from './widgets/ai-prompt-chip';\nexport { AskIcon } from './widgets/ask-icon';\nexport { WidgetAskBar } from './widgets/widget-ask-bar';\nexport {\n  WidgetDataLoading,\n  type WidgetEmptyStateProps,\n  WidgetInactiveState,\n  type WidgetInactiveReason,\n  type WidgetInactiveStateProps,\n  type WidgetSkeletonVariant,\n  type WidgetStateAction,\n} from './widgets/widget-state-components';\n\nexport { BaseActivationForm } from './base-activation-form';\nexport type { BaseActivationFormProps } from './base-activation-form';\nexport {\n  ActivationDialog,\n  ActivationInline,\n  BaseActivationDialog,\n} from './base-activation-dialog';\n\nexport { BaseMarketplaceTile } from './base-marketplace-tile';\nexport type { BaseMarketplaceTileProps } from './base-marketplace-tile';\n\nexport { OAuthActivationForm } from './oauth-activation-form';\nexport type { OAuthActivationFormConfig } from './oauth-activation-form';\n\nexport { currentReturnPath } from './current-return-path';\n"]}

package/dist/components/widgets/widget-context.d.ts

@@ -1,4 +1,5 @@
 import type { WidgetAskContext } from '../../types/widget-ask-context.js';
+import type { WidgetVerdict } from '../../types/widget-verdict.js';
 export type WidgetRenderState = 'active' | 'disabled' | 'loading' | 'error' | 'inactive';
 export interface WidgetState {
     state: WidgetRenderState;
@@ -35,6 +36,16 @@ export interface WidgetMeta {
      * page; the header menu shows "Open in workspace" when present.
      */
     openHref?: string;
+    /**
+     * Whose data the widget shows: the integration's name and bundled logo.
+     * `Widget.Header` draws the logo left of the title (the design system's widget rules).
+     */
+    source?: WidgetSource;
+}
+export interface WidgetSource {
+    name: string;
+    /** A logo URL; the header shows the name's first letter without one. */
+    logoPath?: string;
 }
 /**
  * What the widget's own data layer reports through `Widget.DataState`. The
@@ -49,6 +60,12 @@ export interface WidgetData {
     refreshing: boolean;
     /** Reloads the widget's data. */
     refresh?: () => void;
+    /**
+     * The widget's own conclusion about its data (the design system's widget rules): the
+     * header shows it in place of the context line, and the "Ask about this"
+     * snapshot carries it.
+     */
+    verdict?: WidgetVerdict;
 }
 export interface WidgetContextValue {
     state: WidgetState;

package/dist/components/widgets/widget-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget-context.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-context.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAyEtC,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAA4B,IAAI,CAAC,CAAC","sourcesContent":["'use client';\n\nimport { createContext } from 'react';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\n\nexport type WidgetRenderState =\n  | 'active'\n  | 'disabled'\n  | 'loading'\n  | 'error'\n  | 'inactive';\n\nexport interface WidgetState {\n  state: WidgetRenderState;\n  collapsed: boolean;\n  pinned: boolean;\n  pendingCollapse: boolean;\n  pendingPin: boolean;\n}\n\nexport interface WidgetActions {\n  toggleCollapsed: () => void;\n  togglePinned: () => void;\n}\n\nexport interface WidgetHealth {\n  status: 'healthy' | 'degraded' | 'unhealthy' | 'unknown';\n  lastSuccessAt?: string | null;\n  errorMessage?: string | null;\n}\n\nexport interface WidgetMeta {\n  widgetId: string;\n  title?: string;\n  subtitle?: string;\n  description?: string;\n  maxContentHeight?: string;\n  isCollapsible: boolean;\n  isPinnable: boolean;\n  askContext?: WidgetAskContext;\n  aiFooterEnabled: boolean;\n  className?: string;\n  /** Integration health for this widget's product, if known. */\n  health?: WidgetHealth;\n  /**\n   * Where the widget's full surface lives, e.g. the workspace a pinned widget\n   * came from. Set by the host only where following it leaves the current\n   * page; the header menu shows \"Open in workspace\" when present.\n   */\n  openHref?: string;\n}\n\n/**\n * What the widget's own data layer reports through `Widget.DataState`. The\n * host cannot see a widget's queries, so every field is opt-in: the header\n * menu's Refresh, the error view's Try again, and the \"Updated …\" footer each\n * appear only when the widget supplies what they need.\n */\nexport interface WidgetData {\n  /** Epoch milliseconds of the last successful load; absent when unknown. */\n  updatedAt?: number;\n  /** A reload is in flight while data is already on screen. */\n  refreshing: boolean;\n  /** Reloads the widget's data. */\n  refresh?: () => void;\n}\n\nexport interface WidgetContextValue {\n  state: WidgetState;\n  actions: WidgetActions;\n  meta: WidgetMeta;\n  data?: WidgetData;\n}\n\nexport const WidgetContext = createContext<WidgetContextValue | null>(null);\n"]}
+{"version":3,"file":"widget-context.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-context.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AA2FtC,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAA4B,IAAI,CAAC,CAAC","sourcesContent":["'use client';\n\nimport { createContext } from 'react';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport type { WidgetVerdict } from '../../types/widget-verdict';\n\nexport type WidgetRenderState =\n  | 'active'\n  | 'disabled'\n  | 'loading'\n  | 'error'\n  | 'inactive';\n\nexport interface WidgetState {\n  state: WidgetRenderState;\n  collapsed: boolean;\n  pinned: boolean;\n  pendingCollapse: boolean;\n  pendingPin: boolean;\n}\n\nexport interface WidgetActions {\n  toggleCollapsed: () => void;\n  togglePinned: () => void;\n}\n\nexport interface WidgetHealth {\n  status: 'healthy' | 'degraded' | 'unhealthy' | 'unknown';\n  lastSuccessAt?: string | null;\n  errorMessage?: string | null;\n}\n\nexport interface WidgetMeta {\n  widgetId: string;\n  title?: string;\n  subtitle?: string;\n  description?: string;\n  maxContentHeight?: string;\n  isCollapsible: boolean;\n  isPinnable: boolean;\n  askContext?: WidgetAskContext;\n  aiFooterEnabled: boolean;\n  className?: string;\n  /** Integration health for this widget's product, if known. */\n  health?: WidgetHealth;\n  /**\n   * Where the widget's full surface lives, e.g. the workspace a pinned widget\n   * came from. Set by the host only where following it leaves the current\n   * page; the header menu shows \"Open in workspace\" when present.\n   */\n  openHref?: string;\n  /**\n   * Whose data the widget shows: the integration's name and bundled logo.\n   * `Widget.Header` draws the logo left of the title (the design system's widget rules).\n   */\n  source?: WidgetSource;\n}\n\nexport interface WidgetSource {\n  name: string;\n  /** A logo URL; the header shows the name's first letter without one. */\n  logoPath?: string;\n}\n\n/**\n * What the widget's own data layer reports through `Widget.DataState`. The\n * host cannot see a widget's queries, so every field is opt-in: the header\n * menu's Refresh, the error view's Try again, and the \"Updated …\" footer each\n * appear only when the widget supplies what they need.\n */\nexport interface WidgetData {\n  /** Epoch milliseconds of the last successful load; absent when unknown. */\n  updatedAt?: number;\n  /** A reload is in flight while data is already on screen. */\n  refreshing: boolean;\n  /** Reloads the widget's data. */\n  refresh?: () => void;\n  /**\n   * The widget's own conclusion about its data (the design system's widget rules): the\n   * header shows it in place of the context line, and the \"Ask about this\"\n   * snapshot carries it.\n   */\n  verdict?: WidgetVerdict;\n}\n\nexport interface WidgetContextValue {\n  state: WidgetState;\n  actions: WidgetActions;\n  meta: WidgetMeta;\n  data?: WidgetData;\n}\n\nexport const WidgetContext = createContext<WidgetContextValue | null>(null);\n"]}

package/dist/components/widgets/widget-preview-provider.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react';
 import type { WidgetAskContext } from '../../types/widget-ask-context.js';
-import { type WidgetHealth, type WidgetRenderState } from './widget-context.js';
+import { type WidgetHealth, type WidgetRenderState, type WidgetSource } from './widget-context.js';
 export interface WidgetPreviewProviderProps {
     widgetId: string;
     title?: string;
@@ -17,6 +17,8 @@ export interface WidgetPreviewProviderProps {
     askContext?: WidgetAskContext;
     aiFooterEnabled?: boolean;
     health?: WidgetHealth;
+    /** Whose data the widget shows; the header draws its logo. */
+    source?: WidgetSource;
     children: ReactNode;
 }
 /**
@@ -38,4 +40,4 @@ export interface WidgetPreviewProviderProps {
  * Flip `state` to walk every branch your widget renders (`'loading'`,
  * `'error'`, `'inactive'`, `'disabled'`) without faking a network condition.
  */
-export declare function WidgetPreviewProvider({ widgetId, title, subtitle, description, className, state, isCollapsible, isPinnable, defaultCollapsed, defaultPinned, maxContentHeight, askContext, aiFooterEnabled, health, children, }: WidgetPreviewProviderProps): import("react").JSX.Element;
+export declare function WidgetPreviewProvider({ widgetId, title, subtitle, description, className, state, isCollapsible, isPinnable, defaultCollapsed, defaultPinned, maxContentHeight, askContext, aiFooterEnabled, health, source, children, }: WidgetPreviewProviderProps): import("react").JSX.Element;

package/dist/components/widgets/widget-preview-provider.js

@@ -21,7 +21,7 @@ import { WidgetContext, } from './widget-context.js';
  * Flip `state` to walk every branch your widget renders (`'loading'`,
  * `'error'`, `'inactive'`, `'disabled'`) without faking a network condition.
  */
-export function WidgetPreviewProvider({ widgetId, title, subtitle, description, className, state = 'active', isCollapsible = false, isPinnable = false, defaultCollapsed = false, defaultPinned = false, maxContentHeight, askContext, aiFooterEnabled = false, health, children, }) {
+export function WidgetPreviewProvider({ widgetId, title, subtitle, description, className, state = 'active', isCollapsible = false, isPinnable = false, defaultCollapsed = false, defaultPinned = false, maxContentHeight, askContext, aiFooterEnabled = false, health, source, children, }) {
     const [collapsed, setCollapsed] = useState(defaultCollapsed);
     const [pinned, setPinned] = useState(defaultPinned);
     const toggleCollapsed = useCallback(() => setCollapsed((previous) => !previous), []);
@@ -47,6 +47,7 @@ export function WidgetPreviewProvider({ widgetId, title, subtitle, description,
             askContext,
             aiFooterEnabled,
             health,
+            source,
         },
     }), [
         aiFooterEnabled,
@@ -59,6 +60,7 @@ export function WidgetPreviewProvider({ widgetId, title, subtitle, description,
         isPinnable,
         maxContentHeight,
         pinned,
+        source,
         state,
         subtitle,
         title,

package/dist/components/widgets/widget-preview-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget-preview-provider.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-preview-provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAkB,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGvE,OAAO,EACL,aAAa,GAId,MAAM,kBAAkB,CAAC;AAqB1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,WAAW,EACX,SAAS,EACT,KAAK,GAAG,QAAQ,EAChB,aAAa,GAAG,KAAK,EACrB,UAAU,GAAG,KAAK,EAClB,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,KAAK,EACrB,gBAAgB,EAChB,UAAU,EACV,eAAe,GAAG,KAAK,EACvB,MAAM,EACN,QAAQ,GACmB;IAC3B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAEpD,MAAM,eAAe,GAAG,WAAW,CACjC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAC3C,EAAE,CACH,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAC9B,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EACxC,EAAE,CACH,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC;QACL,KAAK,EAAE;YACL,KAAK;YACL,SAAS;YACT,MAAM;YACN,eAAe,EAAE,KAAK;YACtB,UAAU,EAAE,KAAK;SAClB;QACD,OAAO,EAAE,EAAE,eAAe,EAAE,YAAY,EAAE;QAC1C,IAAI,EAAE;YACJ,QAAQ;YACR,KAAK;YACL,QAAQ;YACR,WAAW;YACX,SAAS;YACT,gBAAgB;YAChB,aAAa;YACb,UAAU;YACV,UAAU;YACV,eAAe;YACf,MAAM;SACP;KACF,CAAC,EACF;QACE,eAAe;QACf,UAAU;QACV,SAAS;QACT,SAAS;QACT,WAAW;QACX,MAAM;QACN,aAAa;QACb,UAAU;QACV,gBAAgB;QAChB,MAAM;QACN,KAAK;QACL,QAAQ;QACR,KAAK;QACL,eAAe;QACf,YAAY;QACZ,QAAQ;KACT,CACF,CAAC;IAEF,OAAO,KAAC,aAAa,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAiB,CAAC;AACjE,CAAC","sourcesContent":["'use client';\n\nimport { type ReactNode, useCallback, useMemo, useState } from 'react';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport {\n  WidgetContext,\n  type WidgetContextValue,\n  type WidgetHealth,\n  type WidgetRenderState,\n} from './widget-context';\n\nexport interface WidgetPreviewProviderProps {\n  widgetId: string;\n  title?: string;\n  subtitle?: string;\n  description?: string;\n  className?: string;\n  /** Defaults to `'active'` — the state you almost always want to look at. */\n  state?: WidgetRenderState;\n  isCollapsible?: boolean;\n  isPinnable?: boolean;\n  defaultCollapsed?: boolean;\n  defaultPinned?: boolean;\n  maxContentHeight?: string;\n  askContext?: WidgetAskContext;\n  aiFooterEnabled?: boolean;\n  health?: WidgetHealth;\n  children: ReactNode;\n}\n\n/**\n * Renders a widget outside the Ekanos dashboard.\n *\n * `Widget.*` reads everything — render state, collapse/pin, title — from\n * `WidgetContext`, which in production is filled by the host's\n * `DashboardWidgetProvider` (config hierarchy, persistence callbacks, health\n * resolution). None of that exists in a partner's own app, a Storybook story,\n * or a component test, and without SOME provider every `Widget.*` throws. This\n * is that provider: same context value, local state only, nothing persisted.\n *\n * ```tsx\n * <WidgetPreviewProvider widgetId=\"my-widget\" title=\"My widget\">\n *   <MyWidget accountId={accountId} productSlug=\"my-integration\" />\n * </WidgetPreviewProvider>\n * ```\n *\n * Flip `state` to walk every branch your widget renders (`'loading'`,\n * `'error'`, `'inactive'`, `'disabled'`) without faking a network condition.\n */\nexport function WidgetPreviewProvider({\n  widgetId,\n  title,\n  subtitle,\n  description,\n  className,\n  state = 'active',\n  isCollapsible = false,\n  isPinnable = false,\n  defaultCollapsed = false,\n  defaultPinned = false,\n  maxContentHeight,\n  askContext,\n  aiFooterEnabled = false,\n  health,\n  children,\n}: WidgetPreviewProviderProps) {\n  const [collapsed, setCollapsed] = useState(defaultCollapsed);\n  const [pinned, setPinned] = useState(defaultPinned);\n\n  const toggleCollapsed = useCallback(\n    () => setCollapsed((previous) => !previous),\n    [],\n  );\n\n  const togglePinned = useCallback(\n    () => setPinned((previous) => !previous),\n    [],\n  );\n\n  const value = useMemo<WidgetContextValue>(\n    () => ({\n      state: {\n        state,\n        collapsed,\n        pinned,\n        pendingCollapse: false,\n        pendingPin: false,\n      },\n      actions: { toggleCollapsed, togglePinned },\n      meta: {\n        widgetId,\n        title,\n        subtitle,\n        description,\n        className,\n        maxContentHeight,\n        isCollapsible,\n        isPinnable,\n        askContext,\n        aiFooterEnabled,\n        health,\n      },\n    }),\n    [\n      aiFooterEnabled,\n      askContext,\n      className,\n      collapsed,\n      description,\n      health,\n      isCollapsible,\n      isPinnable,\n      maxContentHeight,\n      pinned,\n      state,\n      subtitle,\n      title,\n      toggleCollapsed,\n      togglePinned,\n      widgetId,\n    ],\n  );\n\n  return <WidgetContext value={value}>{children}</WidgetContext>;\n}\n"]}
+{"version":3,"file":"widget-preview-provider.js","sourceRoot":"","sources":["../../../src/components/widgets/widget-preview-provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAkB,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGvE,OAAO,EACL,aAAa,GAKd,MAAM,kBAAkB,CAAC;AAuB1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,WAAW,EACX,SAAS,EACT,KAAK,GAAG,QAAQ,EAChB,aAAa,GAAG,KAAK,EACrB,UAAU,GAAG,KAAK,EAClB,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,KAAK,EACrB,gBAAgB,EAChB,UAAU,EACV,eAAe,GAAG,KAAK,EACvB,MAAM,EACN,MAAM,EACN,QAAQ,GACmB;IAC3B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;IAEpD,MAAM,eAAe,GAAG,WAAW,CACjC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAC3C,EAAE,CACH,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAC9B,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EACxC,EAAE,CACH,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC;QACL,KAAK,EAAE;YACL,KAAK;YACL,SAAS;YACT,MAAM;YACN,eAAe,EAAE,KAAK;YACtB,UAAU,EAAE,KAAK;SAClB;QACD,OAAO,EAAE,EAAE,eAAe,EAAE,YAAY,EAAE;QAC1C,IAAI,EAAE;YACJ,QAAQ;YACR,KAAK;YACL,QAAQ;YACR,WAAW;YACX,SAAS;YACT,gBAAgB;YAChB,aAAa;YACb,UAAU;YACV,UAAU;YACV,eAAe;YACf,MAAM;YACN,MAAM;SACP;KACF,CAAC,EACF;QACE,eAAe;QACf,UAAU;QACV,SAAS;QACT,SAAS;QACT,WAAW;QACX,MAAM;QACN,aAAa;QACb,UAAU;QACV,gBAAgB;QAChB,MAAM;QACN,MAAM;QACN,KAAK;QACL,QAAQ;QACR,KAAK;QACL,eAAe;QACf,YAAY;QACZ,QAAQ;KACT,CACF,CAAC;IAEF,OAAO,KAAC,aAAa,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAiB,CAAC;AACjE,CAAC","sourcesContent":["'use client';\n\nimport { type ReactNode, useCallback, useMemo, useState } from 'react';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport {\n  WidgetContext,\n  type WidgetContextValue,\n  type WidgetHealth,\n  type WidgetRenderState,\n  type WidgetSource,\n} from './widget-context';\n\nexport interface WidgetPreviewProviderProps {\n  widgetId: string;\n  title?: string;\n  subtitle?: string;\n  description?: string;\n  className?: string;\n  /** Defaults to `'active'` — the state you almost always want to look at. */\n  state?: WidgetRenderState;\n  isCollapsible?: boolean;\n  isPinnable?: boolean;\n  defaultCollapsed?: boolean;\n  defaultPinned?: boolean;\n  maxContentHeight?: string;\n  askContext?: WidgetAskContext;\n  aiFooterEnabled?: boolean;\n  health?: WidgetHealth;\n  /** Whose data the widget shows; the header draws its logo. */\n  source?: WidgetSource;\n  children: ReactNode;\n}\n\n/**\n * Renders a widget outside the Ekanos dashboard.\n *\n * `Widget.*` reads everything — render state, collapse/pin, title — from\n * `WidgetContext`, which in production is filled by the host's\n * `DashboardWidgetProvider` (config hierarchy, persistence callbacks, health\n * resolution). None of that exists in a partner's own app, a Storybook story,\n * or a component test, and without SOME provider every `Widget.*` throws. This\n * is that provider: same context value, local state only, nothing persisted.\n *\n * ```tsx\n * <WidgetPreviewProvider widgetId=\"my-widget\" title=\"My widget\">\n *   <MyWidget accountId={accountId} productSlug=\"my-integration\" />\n * </WidgetPreviewProvider>\n * ```\n *\n * Flip `state` to walk every branch your widget renders (`'loading'`,\n * `'error'`, `'inactive'`, `'disabled'`) without faking a network condition.\n */\nexport function WidgetPreviewProvider({\n  widgetId,\n  title,\n  subtitle,\n  description,\n  className,\n  state = 'active',\n  isCollapsible = false,\n  isPinnable = false,\n  defaultCollapsed = false,\n  defaultPinned = false,\n  maxContentHeight,\n  askContext,\n  aiFooterEnabled = false,\n  health,\n  source,\n  children,\n}: WidgetPreviewProviderProps) {\n  const [collapsed, setCollapsed] = useState(defaultCollapsed);\n  const [pinned, setPinned] = useState(defaultPinned);\n\n  const toggleCollapsed = useCallback(\n    () => setCollapsed((previous) => !previous),\n    [],\n  );\n\n  const togglePinned = useCallback(\n    () => setPinned((previous) => !previous),\n    [],\n  );\n\n  const value = useMemo<WidgetContextValue>(\n    () => ({\n      state: {\n        state,\n        collapsed,\n        pinned,\n        pendingCollapse: false,\n        pendingPin: false,\n      },\n      actions: { toggleCollapsed, togglePinned },\n      meta: {\n        widgetId,\n        title,\n        subtitle,\n        description,\n        className,\n        maxContentHeight,\n        isCollapsible,\n        isPinnable,\n        askContext,\n        aiFooterEnabled,\n        health,\n        source,\n      },\n    }),\n    [\n      aiFooterEnabled,\n      askContext,\n      className,\n      collapsed,\n      description,\n      health,\n      isCollapsible,\n      isPinnable,\n      maxContentHeight,\n      pinned,\n      source,\n      state,\n      subtitle,\n      title,\n      toggleCollapsed,\n      togglePinned,\n      widgetId,\n    ],\n  );\n\n  return <WidgetContext value={value}>{children}</WidgetContext>;\n}\n"]}

package/dist/components/widgets/widget-state-components.d.ts

@@ -1,8 +1,64 @@
-export declare function WidgetLoadingState(): import("react").JSX.Element;
-export declare function WidgetErrorState({ onRetry, retrying, }: {
+import type { ReactNode } from 'react';
+/**
+ * The one action a state view offers: "Connect QuickBooks", "Ask an admin",
+ * "Create a deal". A link with `href`, otherwise a button running `onClick`.
+ */
+export interface WidgetStateAction {
+    label: ReactNode;
+    href?: string;
+    /** Open `href` in a new tab. */
+    external?: boolean;
+    onClick?: () => void;
+}
+/** The body shape a loading skeleton stands in for. */
+export type WidgetSkeletonVariant = 'rows' | 'stat' | 'chart' | 'schedule';
+/** Why an active integration still can't show this widget's data. */
+export type WidgetInactiveReason = 'not-connected' | 'no-access' | 'setup-needed';
+export interface WidgetEmptyStateProps {
+    /**
+     * `positive` (the default) says nothing needs the owner: "You're all caught
+     * up". `neutral` is for an empty list that isn't good news, like a search
+     * with no results.
+     */
+    tone?: 'positive' | 'neutral';
+    title?: ReactNode;
+    description?: ReactNode;
+    action?: WidgetStateAction;
+}
+export interface WidgetInactiveStateProps {
+    reason?: WidgetInactiveReason;
+    /** The integration's name, for the default copy ("Connect QuickBooks"). */
+    integrationName?: string;
+    title?: ReactNode;
+    /** One sentence on what connecting or access gives the owner. */
+    description?: ReactNode;
+    action?: WidgetStateAction;
+}
+/**
+ * The empty state for a widget with nothing to show. Positive by default:
+ * an empty review queue is good news, so it reassures instead of apologizing.
+ */
+export declare function WidgetEmptyState({ tone, title, description, action, }: WidgetEmptyStateProps): import("react").JSX.Element;
+/**
+ * Why the widget can't show data. `not-connected` offers one Connect button;
+ * `no-access` is a calm note that points to an admin, never a lock screen;
+ * `setup-needed` points to the integration's settings. Without a `reason` it
+ * keeps the original one-line "Widget inactive".
+ */
+export declare function WidgetInactiveState({ reason, integrationName, title, description, action, }?: WidgetInactiveStateProps): import("react").JSX.Element;
+/**
+ * Loading, drawn as the body it stands in for so the card doesn't jump when
+ * data lands. Rows suit lists and feeds, `stat` a headline figure, `chart` a
+ * chart, `schedule` a day of events.
+ */
+export declare function WidgetLoadingSkeleton({ variant, }: {
+    variant?: WidgetSkeletonVariant;
+}): import("react").JSX.Element;
+export declare function WidgetErrorState({ title, description, onRetry, retrying, }: {
+    title?: ReactNode;
+    description?: ReactNode;
     onRetry?: () => void;
     retrying?: boolean;
 }): import("react").JSX.Element;
-export declare function WidgetInactiveState(): import("react").JSX.Element;
 export declare function WidgetDataLoading(): import("react").JSX.Element;
 export declare function WidgetDisabledState(): import("react").JSX.Element;