@ekanos/sdk 0.1.3 → 0.1.5

package/README.md

@@ -501,6 +501,21 @@ export function CurrentWeatherWidget({ accountId }: IntegrationComponentProps) {
 }
 ```
 
+**`Widget.Active` is intentionally flush.** Its `CardContent` renders `p-0`
+with no padding, so a chart, table, or other full-bleed content can run
+edge-to-edge — existing widgets depend on this. `Widget.Header` stays inset
+(`px-5`), so ordinary content (text, rows, a KPI readout) rendered directly
+inside `Widget.Active` sits flush against the card edges while the header
+above it does not. For that case, wrap your content in `Widget.Body` — the
+standard padded body (`px-5 pt-4 pb-5`, matching the header's inset) — rather
+than hand-rolling a `px-*` wrapper:
+
+```tsx
+<Widget.Active>
+  <Widget.Body>{/* rows, text, a KPI readout */}</Widget.Body>
+</Widget.Active>
+```
+
 Declared like this:
 
 ```ts
@@ -911,6 +926,53 @@ host scheduler uses. Numeric values only, with `*`, lists (`1,15`), ranges
 day-of-month 1-31, month 1-12, day-of-week 0-7 (0 and 7 both Sunday). **No
 names** (`JAN`, `MON`), no `@daily` macros, no seconds field.
 
+### `onActivate` (activation)
+
+The gap this closes: the sanctioned widget-data path is schedule → writes
+`clientReadable` storage → widget reads it, and nothing server-side runs at
+connect time — so a cache-backed dashboard is EMPTY until the first schedule
+tick (up to a full interval), and stays STALE after an activation-data change
+until the next tick. `onActivate` is the fix: a hook that runs server-side (a)
+once after an activation is first persisted, and (b) again after
+activationData is updated.
+
+```ts
+import type { OnActivateHandler } from '@ekanos/sdk/integration';
+
+export const seedOnConnect: OnActivateHandler<MyStorage> = async (ctx) => {
+  const apiKey = await ctx.secrets.get(ACME_API_KEY);
+  if (!apiKey) return; // Nothing to seed yet — not an error.
+
+  const response = await ctx.fetch('https://api.acme.example/v1/summary', {
+    headers: { authorization: `Bearer ${apiKey}` },
+  });
+  if (!response.ok) {
+    throw new Error(`Acme returned ${response.status} while seeding the cache.`);
+  }
+
+  await ctx.storage.account.set('cache/summary', await response.json());
+};
+```
+
+Same `ctx`, same enforcement (egress, storage, secrets) as `schedules[].handler`.
+
+**v1 errors are NON-FATAL.** A throw is logged and shown to the user as a
+warning; the activation stays connected. This hook is for **cache seeding and
+eager validation**, not a connect gate — it cannot reject a connection. A
+fail-the-connect credential validator is a deliberately separate, not-yet-built
+field; do not repurpose `onActivate` as one.
+
+**Pair it with a fingerprint, or the cache still goes stale.** A cache
+invalidated only by age keeps serving the *previous* activation's values after
+(b) fires, until whatever `onActivate` writes lands. Store a fingerprint of the
+activation fields a cached value depended on — every field that changes the
+**values**, not just the ones that select which data to fetch (units, currency
+and locale leave a cache key untouched while making every number wrong) —
+alongside the value, and treat a mismatch (or an absent fingerprint) on read as
+a cache miss. Declare a new fingerprint field on a storage schema as
+`.optional()`: a required field throws `StorageValidationError` on every
+pre-existing row, which for a `clientReadable` key reaches the widget.
+
 ### `oauth`
 
 You declare the provider; **the transport owns the flow.** Authorize redirect,
@@ -1081,6 +1143,25 @@ 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`.
 
+`invokeActivate()` does the same for `onActivate` — no payload or invocation to
+build, just the handler against the definition-derived context:
+
+```ts
+import { invokeActivate } from '@ekanos/sdk/testing';
+
+const { ctx } = await invokeActivate(integration, {
+  contextOptions: { secrets: { account: { acme_api_key: 'test_key' } } },
+});
+
+expect(ctx.dumpStorage().account['cache/summary']).toBeDefined();
+```
+
+Throws if `onActivate` is not declared, or if the handler itself throws — this
+helper is a bare invoker, not the host. The v1 non-fatal handling
+(log-and-continue) is applied by whatever calls the hook in production or in
+the harness, so a test asserting that behavior should catch the rejection
+itself.
+
 ## Entrypoints
 
 | Import | Runs on | Contents |
@@ -1111,8 +1192,13 @@ and the host adapts the definition internally.
 `@ekanos/ui` components emit Tailwind class strings against Fusion's semantic
 tokens, and icons are Font Awesome glyphs the host loads. Import
 `@ekanos/ui/styles.css` (or the narrower `tokens.css` / `theme.css` /
-`base.css`) to get the token layer. Outside a host that loads Font Awesome,
-icons render as nothing at all — that is expected, not a bug in your code.
+`base.css`) to get the token layer — that also draws a `□` placeholder for
+icons if you load no Font Awesome at all, so "I forgot the icon font" doesn't
+look identical to "my code is broken". If the host DOES load Font Awesome but
+not the specific glyph you asked for (Free-only host, Pro-only name), the icon
+renders a circle-question disc instead, and `@ekanos/ui/icon` warns once per
+name in development. See `@ekanos/ui`'s README ("Icons: you must supply Font
+Awesome") for the Free-vs-Pro gap and how to size and re-family icons.
 
 ## Naming and validation rules, in one table
 
@@ -1128,6 +1214,7 @@ icons render as nothing at all — that is expected, not a bug in your code.
 | storage keys | `[a-z0-9_-]+` with at most one `/` | `settings/location` |
 | `egress[]` | https origin, optional one leading `*.`, optional port | `https://*.acme.example` |
 | OAuth endpoints | absolute https, no embedded credentials, origin in `egress` | — |
+| `onActivate` | must be a function `(ctx) => Promise<void>` | — |
 | `examplePayload`, `outputExample` | plain JSON only | — |
 
 Duplicate widget ids, tool names, webhook ids or schedule ids inside one
@@ -1146,6 +1233,11 @@ whether it is you or us costs an afternoon.
   context whose default is the browser's `fetch`. The `@ekanos/harness` README
   has the whole ~20-line pattern; the dev harness's live mode mounts it for you.
 - **No local OAuth loop.** See [`oauth`](#oauth) above.
+- **`onActivate` is declared and testable, but the host does not call it yet.**
+  It runs in the `@ekanos/harness` activation surface and under
+  `invokeActivate()`, but production has no wired call site as of this
+  writing — declare it, test it locally, and it starts running the moment host
+  wiring lands with no change on your side.
 - **`useActivateIntegration()` is inert without the host's provider.** It reads
   server actions out of `IntegrationActivationProvider`. Nothing warns you at
   build time.

package/api-report.md

@@ -9,7 +9,7 @@ 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: **146** across 7 entrypoints.
+Total exported names: **150** across 7 entrypoints.
 
 ## `@ekanos/sdk` (32 exports)
 
@@ -153,11 +153,13 @@ Total exported names: **146** across 7 entrypoints.
 | `requireContext` | function |
 | `resolveStorageKeyDeclaration` | function |
 
-## `@ekanos/sdk/testing` (13 exports)
+## `@ekanos/sdk/testing` (16 exports)
 
 | Export | Kind |
 | --- | --- |
+| `ActivateInvocationOutcome` | interface |
 | `DefinitionContextOptions` | type alias |
+| `InvokeActivateOptions` | type alias |
 | `InvokeScheduleOptions` | interface |
 | `InvokeWebhookOptions` | interface |
 | `MockContextOptions` | interface |
@@ -168,10 +170,11 @@ Total exported names: **146** across 7 entrypoints.
 | `ScheduleInvocationOutcome` | interface |
 | `WebhookInvocationOutcome` | interface |
 | `createMockContext` | function |
+| `invokeActivate` | function |
 | `invokeSchedule` | function |
 | `invokeWebhook` | function |
 
-## `@ekanos/sdk/integration` (25 exports)
+## `@ekanos/sdk/integration` (26 exports)
 
 | Export | Kind |
 | --- | --- |
@@ -185,6 +188,7 @@ Total exported names: **146** across 7 entrypoints.
 | `IntegrationProposals` | type alias |
 | `OAuthProviderDeclaration` | interface |
 | `OAuthTokens` | interface |
+| `OnActivateHandler` | type alias |
 | `PartnerOAuthDeclaration` | interface |
 | `PartnerScheduleDeclaration` | interface |
 | `PartnerToolModule` | interface |

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

@@ -12,6 +12,40 @@ declare function WidgetHeader({ title, subtitle, description, children, }: {
     description?: string;
     children?: ReactNode;
 }): import("react").JSX.Element | null;
+/**
+ * The standard padded body for content rendered inside `Widget.Active`.
+ *
+ * `Widget.Active`'s own `CardContent` renders `p-0` — deliberately, so a
+ * full-bleed chart or table can run edge-to-edge inside the card. That means
+ * ordinary content (text, rows, a KPI readout) is left flush against the
+ * card's sides while `Widget.Header` stays inset (`px-5`) unless the body
+ * supplies its own padding. `Widget.Body` is that padding: `px-5` matches
+ * the header's horizontal inset so header and body align, `pt-4 pb-5`
+ * balances the header's `pb-4`/card's bottom edge.
+ *
+ * Use it for any widget whose content is NOT already full-bleed:
+ *
+ * ```tsx
+ * <Widget.Active>
+ *   <Widget.Body>{/* rows, text, a KPI readout *\/}</Widget.Body>
+ * </Widget.Active>
+ * ```
+ *
+ * Skip it — render children directly inside `Widget.Active` — when the
+ * content itself needs to run flush to the card edges (a chart, a table with
+ * its own header row, an image).
+ */
+declare function WidgetBody({ className, children, }: {
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Renders `children` once the widget's state is `active`. Intentionally
+ * flush: its `CardContent` renders `p-0` (no horizontal/vertical inset) so a
+ * chart, table, or other full-bleed content can run edge-to-edge — existing
+ * widgets depend on this. For ordinary padded content, wrap `children` in
+ * `Widget.Body` rather than hand-rolling a `px-*` wrapper.
+ */
 declare function WidgetActive({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element | null;
@@ -79,6 +113,7 @@ export declare const Widget: {
     Header: typeof WidgetHeader;
     DataState: typeof WidgetDataState;
     Active: typeof WidgetActive;
+    Body: typeof WidgetBody;
     Loading: typeof WidgetLoading;
     Error: typeof WidgetError;
     Inactive: typeof WidgetInactive;

package/dist/components/widgets/widget.js

@@ -77,6 +77,39 @@ function StaticBody({ maxContentHeight, children, }) {
                 maxHeight: maxContentHeight !== null && maxContentHeight !== void 0 ? maxContentHeight : undefined,
             }, children: _jsx("div", { ref: innerRef, children: children }) }) }));
 }
+/**
+ * The standard padded body for content rendered inside `Widget.Active`.
+ *
+ * `Widget.Active`'s own `CardContent` renders `p-0` — deliberately, so a
+ * full-bleed chart or table can run edge-to-edge inside the card. That means
+ * ordinary content (text, rows, a KPI readout) is left flush against the
+ * card's sides while `Widget.Header` stays inset (`px-5`) unless the body
+ * supplies its own padding. `Widget.Body` is that padding: `px-5` matches
+ * the header's horizontal inset so header and body align, `pt-4 pb-5`
+ * balances the header's `pb-4`/card's bottom edge.
+ *
+ * Use it for any widget whose content is NOT already full-bleed:
+ *
+ * ```tsx
+ * <Widget.Active>
+ *   <Widget.Body>{/* rows, text, a KPI readout *\/}</Widget.Body>
+ * </Widget.Active>
+ * ```
+ *
+ * Skip it — render children directly inside `Widget.Active` — when the
+ * content itself needs to run flush to the card edges (a chart, a table with
+ * its own header row, an image).
+ */
+function WidgetBody({ className, children, }) {
+    return (_jsx("div", { className: cn('flex flex-1 flex-col gap-4 px-5 pt-4 pb-5', className), children: children }));
+}
+/**
+ * Renders `children` once the widget's state is `active`. Intentionally
+ * flush: its `CardContent` renders `p-0` (no horizontal/vertical inset) so a
+ * chart, table, or other full-bleed content can run edge-to-edge — existing
+ * widgets depend on this. For ordinary padded content, wrap `children` in
+ * `Widget.Body` rather than hand-rolling a `px-*` wrapper.
+ */
 function WidgetActive({ children }) {
     const { state, meta } = useWidget();
     if (state.state !== 'active')
@@ -196,6 +229,7 @@ export const Widget = {
     Header: WidgetHeader,
     DataState: WidgetDataState,
     Active: WidgetActive,
+    Body: WidgetBody,
     Loading: WidgetLoading,
     Error: WidgetError,
     Inactive: WidgetInactive,

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

@@ -1 +1 @@
-{"version":3,"file":"widget.js","sourceRoot":"","sources":["../../../src/components/widgets/widget.tsx"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { Component, type ReactNode, use, useMemo } from 'react';\n\nimport { Button } from '@ekanos/ui/button';\nimport {\n  Card,\n  CardContent,\n  CardFooter,\n  CardHeader,\n  CardTitle,\n} from '@ekanos/ui/card';\nimport { Icon } from '@ekanos/ui/icon';\nimport {\n  Tooltip,\n  TooltipContent,\n  TooltipProvider,\n  TooltipTrigger,\n} from '@ekanos/ui/tooltip';\nimport { Trans } from '@ekanos/ui/trans';\nimport { cn } from '@ekanos/ui/utils';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport { useAnimatedHeight } from './use-animated-height';\nimport { WidgetAskBar } from './widget-ask-bar';\nimport { WidgetContext, type WidgetRenderState } from './widget-context';\nimport {\n  WidgetDisabledState,\n  WidgetErrorState,\n  WidgetInactiveState,\n  WidgetLoadingState,\n} from './widget-state-components';\n\n// ─── Error Boundary ─────────────────────────────────────────────────────────\n\nclass WidgetErrorBoundary extends Component<\n  { widgetId: string; children: ReactNode },\n  { hasError: boolean }\n> {\n  state = { hasError: false };\n  static getDerivedStateFromError() {\n    return { hasError: true };\n  }\n  componentDidCatch(error: Error, info: React.ErrorInfo) {\n    console.error(`Widget \"${this.props.widgetId}\" crashed:`, error, info);\n  }\n  render() {\n    if (this.state.hasError) {\n      return (\n        <div className=\"flex flex-1 flex-col items-center justify-center gap-3 p-8\">\n          <div className=\"bg-destructive/10 flex h-16 w-16 items-center justify-center rounded-full\">\n            <Icon\n              name=\"fa-light fa-circle-exclamation\"\n              className=\"text-destructive h-8 w-8\"\n            />\n          </div>\n          <p className=\"text-muted-foreground text-base font-medium\">\n            <Trans\n              i18nKey=\"dashboard:widgetCrashedTitle\"\n              defaults=\"Something went wrong\"\n            />\n          </p>\n          <p className=\"text-muted-foreground max-w-xs text-center text-sm\">\n            <Trans\n              i18nKey=\"dashboard:widgetCrashedBody\"\n              defaults=\"This widget encountered an error. Try refreshing the page.\"\n            />\n          </p>\n        </div>\n      );\n    }\n    return this.props.children;\n  }\n}\n\n// ─── Hook ───────────────────────────────────────────────────────────────────\n\nfunction useWidget() {\n  const ctx = use(WidgetContext);\n  if (!ctx) {\n    throw new Error(\n      'Widget.* compound components must be rendered inside a widget provider. ' +\n        'On the Fusion dashboard the host supplies one. Anywhere else — your own ' +\n        'app, a story, a component test — wrap the widget in ' +\n        \"`WidgetPreviewProvider` from '@ekanos/sdk/components'.\",\n    );\n  }\n  return ctx;\n}\n\n// ─── Card ───────────────────────────────────────────────────────────────────\n\nfunction WidgetCard({ children }: { children: ReactNode }) {\n  const { meta } = useWidget();\n  return (\n    <Card\n      className={cn(\n        // Neutralize the shadcn card's own py-6/gap-6 box model — widget\n        // chrome owns all vertical spacing via its header/content/footer.\n        'shadow-widget relative flex h-full flex-col gap-0 overflow-hidden rounded-lg border-0 py-0',\n        meta.className,\n      )}\n      data-widget-id={meta.widgetId}\n    >\n      {children}\n    </Card>\n  );\n}\n\n// ─── Header ─────────────────────────────────────────────────────────────────\n\nfunction CollapseButton() {\n  const { state, actions, meta } = useWidget();\n  return (\n    <Button\n      variant=\"outline\"\n      size=\"icon\"\n      onClick={actions.toggleCollapsed}\n      disabled={state.pendingCollapse}\n      className=\"bg-background dark:bg-secondary relative h-6 w-6 rounded-full before:absolute before:top-1/2 before:left-1/2 before:h-11 before:w-11 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']\"\n      aria-expanded={!state.collapsed}\n      aria-controls={`widget-content-${meta.widgetId}`}\n      aria-label={\n        state.collapsed\n          ? `Expand ${meta.title ?? 'widget'}`\n          : `Collapse ${meta.title ?? 'widget'}`\n      }\n    >\n      <Icon\n        name=\"fa-light fa-chevron-right\"\n        className={cn(\n          'h-4 w-4 transition-transform duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n          !state.collapsed && 'rotate-90',\n        )}\n      />\n    </Button>\n  );\n}\n\nfunction WidgetHeader({\n  title,\n  subtitle,\n  description,\n  children,\n}: {\n  /** Override the provider's title — useful when the rendered name differs from the config name. */\n  title?: string;\n  /** Override the provider's subtitle — useful for widget-computed values. */\n  subtitle?: string;\n  /** Override the provider's description — useful for widget-computed values. */\n  description?: string;\n  children?: ReactNode;\n}) {\n  const { meta } = useWidget();\n  const effectiveTitle = title ?? meta.title;\n  const effectiveSubtitle = subtitle ?? meta.subtitle;\n  const effectiveDescription = description ?? meta.description;\n  if (!effectiveTitle) return null;\n  return (\n    <CardHeader className=\"flex-shrink-0 border-b pt-6 pb-4 [.border-b]:pb-4\">\n      <div className=\"flex items-start justify-between gap-2\">\n        <div className=\"flex items-center gap-2\">\n          {meta.isCollapsible ? <CollapseButton /> : null}\n          {effectiveDescription ? (\n            <>\n              <TooltipProvider>\n                <Tooltip>\n                  <TooltipTrigger\n                    render={\n                      <CardTitle className=\"cursor-help text-lg font-semibold\" />\n                    }\n                  >\n                    {effectiveTitle}\n                  </TooltipTrigger>\n                  <TooltipContent>\n                    <p>{effectiveDescription}</p>\n                  </TooltipContent>\n                </Tooltip>\n              </TooltipProvider>\n              <span className=\"sr-only\">{effectiveDescription}</span>\n            </>\n          ) : (\n            <CardTitle className=\"text-lg font-semibold\">\n              {effectiveTitle}\n            </CardTitle>\n          )}\n          {effectiveSubtitle && (\n            <span className=\"text-muted-foreground text-base font-medium\">\n              {effectiveSubtitle}\n            </span>\n          )}\n        </div>\n        {children && (\n          <div className=\"flex shrink-0 items-center gap-2\">{children}</div>\n        )}\n      </div>\n    </CardHeader>\n  );\n}\n\n// ─── State-gated content ────────────────────────────────────────────────────\n\nfunction CollapsibleBody({\n  collapsed,\n  maxContentHeight,\n  widgetId,\n  children,\n}: {\n  collapsed: boolean;\n  maxContentHeight?: string;\n  widgetId: string;\n  children: ReactNode;\n}) {\n  return (\n    <div\n      className={cn(\n        'grid min-h-0 flex-1 transition-[grid-template-rows] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n        collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]',\n      )}\n    >\n      <div className=\"min-h-0 overflow-hidden\">\n        <CardContent\n          id={`widget-content-${widgetId}`}\n          className={cn(\n            'flex h-full min-h-0 flex-1 flex-col overflow-y-auto p-0',\n            'transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n            collapsed ? 'opacity-0' : 'opacity-100',\n          )}\n          style={maxContentHeight ? { maxHeight: maxContentHeight } : undefined}\n        >\n          {children}\n        </CardContent>\n      </div>\n    </div>\n  );\n}\n\nfunction StaticBody({\n  maxContentHeight,\n  children,\n}: {\n  maxContentHeight?: string;\n  children: ReactNode;\n}) {\n  const { innerRef, height } = useAnimatedHeight();\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      <div\n        className=\"overflow-hidden transition-[height] duration-250 ease-out motion-reduce:transition-none\"\n        style={{\n          height: height === 'auto' ? ('auto' as const) : height,\n          maxHeight: maxContentHeight ?? undefined,\n        }}\n      >\n        <div ref={innerRef}>{children}</div>\n      </div>\n    </CardContent>\n  );\n}\n\nfunction WidgetActive({ children }: { children: ReactNode }) {\n  const { state, meta } = useWidget();\n  if (state.state !== 'active') return null;\n  const body = (\n    <WidgetErrorBoundary widgetId={meta.widgetId}>\n      {children}\n    </WidgetErrorBoundary>\n  );\n  return meta.isCollapsible ? (\n    <CollapsibleBody\n      collapsed={state.collapsed}\n      maxContentHeight={meta.maxContentHeight}\n      widgetId={meta.widgetId}\n    >\n      {body}\n    </CollapsibleBody>\n  ) : (\n    <StaticBody maxContentHeight={meta.maxContentHeight}>{body}</StaticBody>\n  );\n}\n\nfunction WidgetLoading({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'loading') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetLoadingState />}\n    </CardContent>\n  );\n}\n\nfunction WidgetError({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'error') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetErrorState />}\n    </CardContent>\n  );\n}\n\nfunction WidgetInactive({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'inactive') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetInactiveState />}\n    </CardContent>\n  );\n}\n\nfunction WidgetDisabled({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'disabled') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetDisabledState />}\n    </CardContent>\n  );\n}\n\n// ─── Footers ────────────────────────────────────────────────────────────────\n\nfunction WidgetFooter({ children }: { children: ReactNode }) {\n  const { state, meta } = useWidget();\n  if (state.state !== 'active') return null;\n  return (\n    <CardFooter\n      className={cn(\n        'flex-shrink-0 pb-6 transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n        meta.isCollapsible && state.collapsed\n          ? 'pointer-events-none opacity-0'\n          : 'opacity-100',\n      )}\n      aria-hidden={meta.isCollapsible && state.collapsed}\n    >\n      {children}\n    </CardFooter>\n  );\n}\n\nfunction WidgetActions({ children }: { children: ReactNode }) {\n  return (\n    <CardFooter className=\"bg-muted flex-shrink-0 justify-end border-t py-3\">\n      {children}\n    </CardFooter>\n  );\n}\n\nfunction WidgetAskFooter({ context }: { context?: WidgetAskContext }) {\n  const { state, meta } = useWidget();\n  const effectiveContext = context ?? meta.askContext;\n  const shouldShow =\n    (meta.aiFooterEnabled || !!effectiveContext) &&\n    state.state === 'active' &&\n    !state.collapsed;\n  if (!shouldShow) return null;\n  return (\n    <WidgetAskBar\n      context={\n        effectiveContext ?? {\n          widgetId: meta.widgetId,\n          title: meta.title ?? meta.widgetId,\n          snapshot: null,\n          suggestedPrompt: `Tell me about ${meta.title ?? 'this widget'}.`,\n        }\n      }\n    />\n  );\n}\n\n/**\n * Renders a subtle \"data may be stale\" banner when the widget's integration is\n * `degraded` (but still active). Unhealthy integrations route to `disabled`\n * instead, so this only fires for the degraded middle ground.\n */\nfunction WidgetHealthFooter() {\n  const { state, meta } = useWidget();\n  const shouldShow =\n    state.state === 'active' &&\n    !state.collapsed &&\n    meta.health?.status === 'degraded';\n  if (!shouldShow) return null;\n  return (\n    <div className=\"text-warning border-warning/30 bg-warning/5 flex items-center gap-2 border-t px-4 py-2 text-xs\">\n      <Icon\n        name=\"fa-light fa-circle-exclamation\"\n        className=\"h-4 w-4 shrink-0\"\n        aria-hidden\n      />\n      <span>\n        <Trans\n          i18nKey=\"common:integrationHealth.degradedWidgetNotice\"\n          defaults=\"This integration is degraded — data may be stale.\"\n        />\n      </span>\n    </div>\n  );\n}\n\n// ─── Data state override ────────────────────────────────────────────────────\n\n/**\n * Wraps children in a sub-provider that overrides the effective render state\n * with the widget's own data loading / error state. Only overrides when the\n * parent state is `active` — so the integration's `inactive` / `disabled` /\n * `loading` (initial) states still win.\n *\n * Read the parent integration state BEFORE wrapping in this component if you\n * need it to gate data fetching:\n *\n * ```tsx\n * const { state } = use(WidgetContext);\n * const integrationActive = state.state === 'active';\n * const { isLoading, isError } = useMyData(accountId, integrationActive);\n * return (\n *   <Widget.DataState loading={isLoading} error={isError}>\n *     <Widget.Card>…</Widget.Card>\n *   </Widget.DataState>\n * );\n * ```\n */\nfunction WidgetDataState({\n  loading,\n  error,\n  inactive,\n  children,\n}: {\n  loading?: boolean;\n  error?: boolean;\n  /**\n   * Force the `inactive` render state even though the integration itself is\n   * active. Use for widget-level \"not connected\" states (e.g. the product is\n   * activated but the upstream OAuth connection is missing). Takes priority\n   * over `loading` / `error`.\n   */\n  inactive?: boolean;\n  children: ReactNode;\n}) {\n  const parent = useWidget();\n  const overrideState: WidgetRenderState =\n    parent.state.state !== 'active'\n      ? parent.state.state\n      : inactive\n        ? 'inactive'\n        : loading\n          ? 'loading'\n          : error\n            ? 'error'\n            : 'active';\n  const value = useMemo(\n    () => ({\n      state: { ...parent.state, state: overrideState },\n      actions: parent.actions,\n      meta: parent.meta,\n    }),\n    [parent.state, parent.actions, parent.meta, overrideState],\n  );\n  return <WidgetContext value={value}>{children}</WidgetContext>;\n}\n\n// ─── Compound export ────────────────────────────────────────────────────────\n\nexport const Widget = {\n  Card: WidgetCard,\n  Header: WidgetHeader,\n  DataState: WidgetDataState,\n  Active: WidgetActive,\n  Loading: WidgetLoading,\n  Error: WidgetError,\n  Inactive: WidgetInactive,\n  Disabled: WidgetDisabled,\n  Footer: WidgetFooter,\n  Actions: WidgetActions,\n  AskFooter: WidgetAskFooter,\n  HealthFooter: WidgetHealthFooter,\n};\n"]}
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../../../src/components/widgets/widget.tsx"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { Component, type ReactNode, use, useMemo } from 'react';\n\nimport { Button } from '@ekanos/ui/button';\nimport {\n  Card,\n  CardContent,\n  CardFooter,\n  CardHeader,\n  CardTitle,\n} from '@ekanos/ui/card';\nimport { Icon } from '@ekanos/ui/icon';\nimport {\n  Tooltip,\n  TooltipContent,\n  TooltipProvider,\n  TooltipTrigger,\n} from '@ekanos/ui/tooltip';\nimport { Trans } from '@ekanos/ui/trans';\nimport { cn } from '@ekanos/ui/utils';\n\nimport type { WidgetAskContext } from '../../types/widget-ask-context';\nimport { useAnimatedHeight } from './use-animated-height';\nimport { WidgetAskBar } from './widget-ask-bar';\nimport { WidgetContext, type WidgetRenderState } from './widget-context';\nimport {\n  WidgetDisabledState,\n  WidgetErrorState,\n  WidgetInactiveState,\n  WidgetLoadingState,\n} from './widget-state-components';\n\n// ─── Error Boundary ─────────────────────────────────────────────────────────\n\nclass WidgetErrorBoundary extends Component<\n  { widgetId: string; children: ReactNode },\n  { hasError: boolean }\n> {\n  state = { hasError: false };\n  static getDerivedStateFromError() {\n    return { hasError: true };\n  }\n  componentDidCatch(error: Error, info: React.ErrorInfo) {\n    console.error(`Widget \"${this.props.widgetId}\" crashed:`, error, info);\n  }\n  render() {\n    if (this.state.hasError) {\n      return (\n        <div className=\"flex flex-1 flex-col items-center justify-center gap-3 p-8\">\n          <div className=\"bg-destructive/10 flex h-16 w-16 items-center justify-center rounded-full\">\n            <Icon\n              name=\"fa-light fa-circle-exclamation\"\n              className=\"text-destructive h-8 w-8\"\n            />\n          </div>\n          <p className=\"text-muted-foreground text-base font-medium\">\n            <Trans\n              i18nKey=\"dashboard:widgetCrashedTitle\"\n              defaults=\"Something went wrong\"\n            />\n          </p>\n          <p className=\"text-muted-foreground max-w-xs text-center text-sm\">\n            <Trans\n              i18nKey=\"dashboard:widgetCrashedBody\"\n              defaults=\"This widget encountered an error. Try refreshing the page.\"\n            />\n          </p>\n        </div>\n      );\n    }\n    return this.props.children;\n  }\n}\n\n// ─── Hook ───────────────────────────────────────────────────────────────────\n\nfunction useWidget() {\n  const ctx = use(WidgetContext);\n  if (!ctx) {\n    throw new Error(\n      'Widget.* compound components must be rendered inside a widget provider. ' +\n        'On the Fusion dashboard the host supplies one. Anywhere else — your own ' +\n        'app, a story, a component test — wrap the widget in ' +\n        \"`WidgetPreviewProvider` from '@ekanos/sdk/components'.\",\n    );\n  }\n  return ctx;\n}\n\n// ─── Card ───────────────────────────────────────────────────────────────────\n\nfunction WidgetCard({ children }: { children: ReactNode }) {\n  const { meta } = useWidget();\n  return (\n    <Card\n      className={cn(\n        // Neutralize the shadcn card's own py-6/gap-6 box model — widget\n        // chrome owns all vertical spacing via its header/content/footer.\n        'shadow-widget relative flex h-full flex-col gap-0 overflow-hidden rounded-lg border-0 py-0',\n        meta.className,\n      )}\n      data-widget-id={meta.widgetId}\n    >\n      {children}\n    </Card>\n  );\n}\n\n// ─── Header ─────────────────────────────────────────────────────────────────\n\nfunction CollapseButton() {\n  const { state, actions, meta } = useWidget();\n  return (\n    <Button\n      variant=\"outline\"\n      size=\"icon\"\n      onClick={actions.toggleCollapsed}\n      disabled={state.pendingCollapse}\n      className=\"bg-background dark:bg-secondary relative h-6 w-6 rounded-full before:absolute before:top-1/2 before:left-1/2 before:h-11 before:w-11 before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']\"\n      aria-expanded={!state.collapsed}\n      aria-controls={`widget-content-${meta.widgetId}`}\n      aria-label={\n        state.collapsed\n          ? `Expand ${meta.title ?? 'widget'}`\n          : `Collapse ${meta.title ?? 'widget'}`\n      }\n    >\n      <Icon\n        name=\"fa-light fa-chevron-right\"\n        className={cn(\n          'h-4 w-4 transition-transform duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n          !state.collapsed && 'rotate-90',\n        )}\n      />\n    </Button>\n  );\n}\n\nfunction WidgetHeader({\n  title,\n  subtitle,\n  description,\n  children,\n}: {\n  /** Override the provider's title — useful when the rendered name differs from the config name. */\n  title?: string;\n  /** Override the provider's subtitle — useful for widget-computed values. */\n  subtitle?: string;\n  /** Override the provider's description — useful for widget-computed values. */\n  description?: string;\n  children?: ReactNode;\n}) {\n  const { meta } = useWidget();\n  const effectiveTitle = title ?? meta.title;\n  const effectiveSubtitle = subtitle ?? meta.subtitle;\n  const effectiveDescription = description ?? meta.description;\n  if (!effectiveTitle) return null;\n  return (\n    <CardHeader className=\"flex-shrink-0 border-b pt-6 pb-4 [.border-b]:pb-4\">\n      <div className=\"flex items-start justify-between gap-2\">\n        <div className=\"flex items-center gap-2\">\n          {meta.isCollapsible ? <CollapseButton /> : null}\n          {effectiveDescription ? (\n            <>\n              <TooltipProvider>\n                <Tooltip>\n                  <TooltipTrigger\n                    render={\n                      <CardTitle className=\"cursor-help text-lg font-semibold\" />\n                    }\n                  >\n                    {effectiveTitle}\n                  </TooltipTrigger>\n                  <TooltipContent>\n                    <p>{effectiveDescription}</p>\n                  </TooltipContent>\n                </Tooltip>\n              </TooltipProvider>\n              <span className=\"sr-only\">{effectiveDescription}</span>\n            </>\n          ) : (\n            <CardTitle className=\"text-lg font-semibold\">\n              {effectiveTitle}\n            </CardTitle>\n          )}\n          {effectiveSubtitle && (\n            <span className=\"text-muted-foreground text-base font-medium\">\n              {effectiveSubtitle}\n            </span>\n          )}\n        </div>\n        {children && (\n          <div className=\"flex shrink-0 items-center gap-2\">{children}</div>\n        )}\n      </div>\n    </CardHeader>\n  );\n}\n\n// ─── State-gated content ────────────────────────────────────────────────────\n\nfunction CollapsibleBody({\n  collapsed,\n  maxContentHeight,\n  widgetId,\n  children,\n}: {\n  collapsed: boolean;\n  maxContentHeight?: string;\n  widgetId: string;\n  children: ReactNode;\n}) {\n  return (\n    <div\n      className={cn(\n        'grid min-h-0 flex-1 transition-[grid-template-rows] duration-300 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n        collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]',\n      )}\n    >\n      <div className=\"min-h-0 overflow-hidden\">\n        <CardContent\n          id={`widget-content-${widgetId}`}\n          className={cn(\n            'flex h-full min-h-0 flex-1 flex-col overflow-y-auto p-0',\n            'transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n            collapsed ? 'opacity-0' : 'opacity-100',\n          )}\n          style={maxContentHeight ? { maxHeight: maxContentHeight } : undefined}\n        >\n          {children}\n        </CardContent>\n      </div>\n    </div>\n  );\n}\n\nfunction StaticBody({\n  maxContentHeight,\n  children,\n}: {\n  maxContentHeight?: string;\n  children: ReactNode;\n}) {\n  const { innerRef, height } = useAnimatedHeight();\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      <div\n        className=\"overflow-hidden transition-[height] duration-250 ease-out motion-reduce:transition-none\"\n        style={{\n          height: height === 'auto' ? ('auto' as const) : height,\n          maxHeight: maxContentHeight ?? undefined,\n        }}\n      >\n        <div ref={innerRef}>{children}</div>\n      </div>\n    </CardContent>\n  );\n}\n\n/**\n * The standard padded body for content rendered inside `Widget.Active`.\n *\n * `Widget.Active`'s own `CardContent` renders `p-0` — deliberately, so a\n * full-bleed chart or table can run edge-to-edge inside the card. That means\n * ordinary content (text, rows, a KPI readout) is left flush against the\n * card's sides while `Widget.Header` stays inset (`px-5`) unless the body\n * supplies its own padding. `Widget.Body` is that padding: `px-5` matches\n * the header's horizontal inset so header and body align, `pt-4 pb-5`\n * balances the header's `pb-4`/card's bottom edge.\n *\n * Use it for any widget whose content is NOT already full-bleed:\n *\n * ```tsx\n * <Widget.Active>\n *   <Widget.Body>{/* rows, text, a KPI readout *\\/}</Widget.Body>\n * </Widget.Active>\n * ```\n *\n * Skip it — render children directly inside `Widget.Active` — when the\n * content itself needs to run flush to the card edges (a chart, a table with\n * its own header row, an image).\n */\nfunction WidgetBody({\n  className,\n  children,\n}: {\n  className?: string;\n  children: ReactNode;\n}) {\n  return (\n    <div className={cn('flex flex-1 flex-col gap-4 px-5 pt-4 pb-5', className)}>\n      {children}\n    </div>\n  );\n}\n\n/**\n * Renders `children` once the widget's state is `active`. Intentionally\n * flush: its `CardContent` renders `p-0` (no horizontal/vertical inset) so a\n * chart, table, or other full-bleed content can run edge-to-edge — existing\n * widgets depend on this. For ordinary padded content, wrap `children` in\n * `Widget.Body` rather than hand-rolling a `px-*` wrapper.\n */\nfunction WidgetActive({ children }: { children: ReactNode }) {\n  const { state, meta } = useWidget();\n  if (state.state !== 'active') return null;\n  const body = (\n    <WidgetErrorBoundary widgetId={meta.widgetId}>\n      {children}\n    </WidgetErrorBoundary>\n  );\n  return meta.isCollapsible ? (\n    <CollapsibleBody\n      collapsed={state.collapsed}\n      maxContentHeight={meta.maxContentHeight}\n      widgetId={meta.widgetId}\n    >\n      {body}\n    </CollapsibleBody>\n  ) : (\n    <StaticBody maxContentHeight={meta.maxContentHeight}>{body}</StaticBody>\n  );\n}\n\nfunction WidgetLoading({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'loading') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetLoadingState />}\n    </CardContent>\n  );\n}\n\nfunction WidgetError({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'error') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetErrorState />}\n    </CardContent>\n  );\n}\n\nfunction WidgetInactive({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'inactive') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetInactiveState />}\n    </CardContent>\n  );\n}\n\nfunction WidgetDisabled({ children }: { children?: ReactNode }) {\n  const { state } = useWidget();\n  if (state.state !== 'disabled') return null;\n  return (\n    <CardContent className=\"flex min-h-0 flex-1 flex-col p-0\">\n      {children ?? <WidgetDisabledState />}\n    </CardContent>\n  );\n}\n\n// ─── Footers ────────────────────────────────────────────────────────────────\n\nfunction WidgetFooter({ children }: { children: ReactNode }) {\n  const { state, meta } = useWidget();\n  if (state.state !== 'active') return null;\n  return (\n    <CardFooter\n      className={cn(\n        'flex-shrink-0 pb-6 transition-opacity duration-200 ease-[cubic-bezier(0.25,1,0.5,1)] motion-reduce:transition-none',\n        meta.isCollapsible && state.collapsed\n          ? 'pointer-events-none opacity-0'\n          : 'opacity-100',\n      )}\n      aria-hidden={meta.isCollapsible && state.collapsed}\n    >\n      {children}\n    </CardFooter>\n  );\n}\n\nfunction WidgetActions({ children }: { children: ReactNode }) {\n  return (\n    <CardFooter className=\"bg-muted flex-shrink-0 justify-end border-t py-3\">\n      {children}\n    </CardFooter>\n  );\n}\n\nfunction WidgetAskFooter({ context }: { context?: WidgetAskContext }) {\n  const { state, meta } = useWidget();\n  const effectiveContext = context ?? meta.askContext;\n  const shouldShow =\n    (meta.aiFooterEnabled || !!effectiveContext) &&\n    state.state === 'active' &&\n    !state.collapsed;\n  if (!shouldShow) return null;\n  return (\n    <WidgetAskBar\n      context={\n        effectiveContext ?? {\n          widgetId: meta.widgetId,\n          title: meta.title ?? meta.widgetId,\n          snapshot: null,\n          suggestedPrompt: `Tell me about ${meta.title ?? 'this widget'}.`,\n        }\n      }\n    />\n  );\n}\n\n/**\n * Renders a subtle \"data may be stale\" banner when the widget's integration is\n * `degraded` (but still active). Unhealthy integrations route to `disabled`\n * instead, so this only fires for the degraded middle ground.\n */\nfunction WidgetHealthFooter() {\n  const { state, meta } = useWidget();\n  const shouldShow =\n    state.state === 'active' &&\n    !state.collapsed &&\n    meta.health?.status === 'degraded';\n  if (!shouldShow) return null;\n  return (\n    <div className=\"text-warning border-warning/30 bg-warning/5 flex items-center gap-2 border-t px-4 py-2 text-xs\">\n      <Icon\n        name=\"fa-light fa-circle-exclamation\"\n        className=\"h-4 w-4 shrink-0\"\n        aria-hidden\n      />\n      <span>\n        <Trans\n          i18nKey=\"common:integrationHealth.degradedWidgetNotice\"\n          defaults=\"This integration is degraded — data may be stale.\"\n        />\n      </span>\n    </div>\n  );\n}\n\n// ─── Data state override ────────────────────────────────────────────────────\n\n/**\n * Wraps children in a sub-provider that overrides the effective render state\n * with the widget's own data loading / error state. Only overrides when the\n * parent state is `active` — so the integration's `inactive` / `disabled` /\n * `loading` (initial) states still win.\n *\n * Read the parent integration state BEFORE wrapping in this component if you\n * need it to gate data fetching:\n *\n * ```tsx\n * const { state } = use(WidgetContext);\n * const integrationActive = state.state === 'active';\n * const { isLoading, isError } = useMyData(accountId, integrationActive);\n * return (\n *   <Widget.DataState loading={isLoading} error={isError}>\n *     <Widget.Card>…</Widget.Card>\n *   </Widget.DataState>\n * );\n * ```\n */\nfunction WidgetDataState({\n  loading,\n  error,\n  inactive,\n  children,\n}: {\n  loading?: boolean;\n  error?: boolean;\n  /**\n   * Force the `inactive` render state even though the integration itself is\n   * active. Use for widget-level \"not connected\" states (e.g. the product is\n   * activated but the upstream OAuth connection is missing). Takes priority\n   * over `loading` / `error`.\n   */\n  inactive?: boolean;\n  children: ReactNode;\n}) {\n  const parent = useWidget();\n  const overrideState: WidgetRenderState =\n    parent.state.state !== 'active'\n      ? parent.state.state\n      : inactive\n        ? 'inactive'\n        : loading\n          ? 'loading'\n          : error\n            ? 'error'\n            : 'active';\n  const value = useMemo(\n    () => ({\n      state: { ...parent.state, state: overrideState },\n      actions: parent.actions,\n      meta: parent.meta,\n    }),\n    [parent.state, parent.actions, parent.meta, overrideState],\n  );\n  return <WidgetContext value={value}>{children}</WidgetContext>;\n}\n\n// ─── Compound export ────────────────────────────────────────────────────────\n\nexport const Widget = {\n  Card: WidgetCard,\n  Header: WidgetHeader,\n  DataState: WidgetDataState,\n  Active: WidgetActive,\n  Body: WidgetBody,\n  Loading: WidgetLoading,\n  Error: WidgetError,\n  Inactive: WidgetInactive,\n  Disabled: WidgetDisabled,\n  Footer: WidgetFooter,\n  Actions: WidgetActions,\n  AskFooter: WidgetAskFooter,\n  HealthFooter: WidgetHealthFooter,\n};\n"]}

package/dist/integration/index.d.ts

@@ -17,4 +17,4 @@
 export { defineIntegration } from './define-integration.js';
 export { parseCronExpression } from './cron.js';
 export { IntegrationDefinitionSchema, validateIntegrationDefinitions, } from '@ekanos/integration-schema';
-export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, DefinitionCollisionInput, FirstPartyInventory, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, } from '@ekanos/integration-schema';
+export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, DefinitionCollisionInput, FirstPartyInventory, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, OnActivateHandler, } from '@ekanos/integration-schema';

package/dist/integration/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/integration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,mEAAmE;AACnE,0EAA0E;AAC1E,0EAA0E;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC","sourcesContent":["/**\n * @ekanos/sdk/integration — the partner authoring contract.\n *\n * `defineIntegration()` is THE way a partner declares an integration\n * Partners never extend a base class.\n * The host adapts the returned definition internally via\n * `registerPartnerIntegration` in `@kit/integrations-core`, which re-parses\n * against the SAME canonical schema (`@ekanos/integration-schema`) at the\n * trust boundary — one contract, no structural twin (F3/F9).\n *\n * Dependency-pure and isomorphic: zod plus the schema package, no `@kit/*`,\n * no `server-only`.\n *\n * Surface discipline: additions require an entry in\n * api-report.md, regenerated by `pnpm --filter @ekanos/sdk api-report`.\n */\n\nexport { defineIntegration } from './define-integration';\n\n// Event-surface validation values: the 5-field cron parser backing\n// `defineIntegration()`'s schedule validation, exported so validators and\n// the harness can check/describe an expression the same way the SDK does.\nexport { parseCronExpression } from './cron';\n\nexport {\n  IntegrationDefinitionSchema,\n  validateIntegrationDefinitions,\n} from '@ekanos/integration-schema';\n\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  DefinitionCollisionInput,\n  FirstPartyInventory,\n  // Event surfaces (webhooks, schedules, OAuth): declared in the definition,\n  // executed locally by the harness/testing helpers today; the host's real\n  // transports (public ingress, scheduler, hosted OAuth callback) bind to\n  // these exact declarations later with no partner code change.\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n} from '@ekanos/integration-schema';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/integration/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,mEAAmE;AACnE,0EAA0E;AAC1E,0EAA0E;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC","sourcesContent":["/**\n * @ekanos/sdk/integration — the partner authoring contract.\n *\n * `defineIntegration()` is THE way a partner declares an integration\n * Partners never extend a base class.\n * The host adapts the returned definition internally via\n * `registerPartnerIntegration` in `@kit/integrations-core`, which re-parses\n * against the SAME canonical schema (`@ekanos/integration-schema`) at the\n * trust boundary — one contract, no structural twin (F3/F9).\n *\n * Dependency-pure and isomorphic: zod plus the schema package, no `@kit/*`,\n * no `server-only`.\n *\n * Surface discipline: additions require an entry in\n * api-report.md, regenerated by `pnpm --filter @ekanos/sdk api-report`.\n */\n\nexport { defineIntegration } from './define-integration';\n\n// Event-surface validation values: the 5-field cron parser backing\n// `defineIntegration()`'s schedule validation, exported so validators and\n// the harness can check/describe an expression the same way the SDK does.\nexport { parseCronExpression } from './cron';\n\nexport {\n  IntegrationDefinitionSchema,\n  validateIntegrationDefinitions,\n} from '@ekanos/integration-schema';\n\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  DefinitionCollisionInput,\n  FirstPartyInventory,\n  // Event surfaces (webhooks, schedules, OAuth): declared in the definition,\n  // executed locally by the harness/testing helpers today; the host's real\n  // transports (public ingress, scheduler, hosted OAuth callback) bind to\n  // these exact declarations later with no partner code change.\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n  // Activation lifecycle hook: cache seeding / eager validation at connect\n  // time. Runs after first persist and after every activationData update;\n  // v1 errors are non-fatal (logged as a warning, activation stays active).\n  OnActivateHandler,\n} from '@ekanos/integration-schema';\n"]}

package/dist/integration/types.d.ts

@@ -4,4 +4,4 @@
  * one contract and no structural twin — F9). This file re-exports them under
  * `@ekanos/sdk/integration`.
  */
-export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, } from '@ekanos/integration-schema';
+export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, OnActivateHandler, } from '@ekanos/integration-schema';

package/dist/integration/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/integration/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The partner authoring types are owned by `@ekanos/integration-schema` (the\n * dependency-pure package `@kit/integrations-core` also imports, so there is\n * one contract and no structural twin — F9). This file re-exports them under\n * `@ekanos/sdk/integration`.\n */\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n} from '@ekanos/integration-schema';\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/integration/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The partner authoring types are owned by `@ekanos/integration-schema` (the\n * dependency-pure package `@kit/integrations-core` also imports, so there is\n * one contract and no structural twin — F9). This file re-exports them under\n * `@ekanos/sdk/integration`.\n */\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n  OnActivateHandler,\n} from '@ekanos/integration-schema';\n"]}

package/dist/testing/index.d.ts

@@ -12,5 +12,5 @@
  */
 export { createMockContext } from './mock-context.js';
 export type { MockContextOptions, MockFetchHandler, MockIntegrationContext, RecordedFetchCall, RecordedLog, } from './mock-context.js';
-export { invokeWebhook, invokeSchedule } from './invoke.js';
-export type { DefinitionContextOptions, InvokeWebhookOptions, InvokeScheduleOptions, WebhookInvocationOutcome, ScheduleInvocationOutcome, } from './invoke.js';
+export { invokeWebhook, invokeSchedule, invokeActivate } from './invoke.js';
+export type { DefinitionContextOptions, InvokeWebhookOptions, InvokeScheduleOptions, InvokeActivateOptions, WebhookInvocationOutcome, ScheduleInvocationOutcome, ActivateInvocationOutcome, } from './invoke.js';

package/dist/testing/index.js

@@ -14,6 +14,7 @@ export { createMockContext } from './mock-context.js';
 // Event-surface invocation: run declared webhook/schedule handlers locally,
 // with the same payload-validation and context-derivation semantics the real
 // transports will have. Used by partner unit tests and the harness Triggers
-// panel alike.
-export { invokeWebhook, invokeSchedule } from './invoke.js';
+// panel alike. `invokeActivate` does the same for the `onActivate` lifecycle
+// hook, used by partner unit tests and the harness's activation surface.
+export { invokeWebhook, invokeSchedule, invokeActivate } from './invoke.js';
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

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

package/dist/testing/invoke.d.ts

@@ -4,6 +4,7 @@
  * transport would, against a `createMockContext()` built FROM the definition
  * (its slug, storage schemas, and egress list), so a handler unit test
  * exercises the same schemas and the same egress allowlist production will.
+ * `invokeActivate()` does the same for the `onActivate` lifecycle hook.
  *
  * Transport semantics reproduced here, so they cannot drift from the docs:
  *  - the payload is parsed against `payloadSchema` BEFORE the handler runs;
@@ -12,7 +13,14 @@
  *    logs it as skipped (one warn line on `ctx.logs`), it never verifies and
  *    the handler never does either;
  *  - a schedule invocation carries `{scheduledFor, invokedAt, trigger}` with
- *    `trigger: 'manual'` by default (a human pressed the button).
+ *    `trigger: 'manual'` by default (a human pressed the button);
+ *  - `invokeActivate()` simply awaits `onActivate(ctx)` and returns the
+ *    context it ran against — a throw PROPAGATES here. The non-fatal
+ *    (log-and-continue) handling described on `OnActivateHandler` is HOST
+ *    POLICY, applied by the transport that calls the hook in production
+ *    (and by the harness's activation surface locally); this helper is a
+ *    bare invoker; a test asserting the non-fatal behavior should catch its
+ *    own rejection.
  */
 import type { IntegrationDefinition, ScheduleInvocation, ScheduleResult, StorageSchemas, WebhookEvent, WebhookResult } from '@ekanos/integration-schema';
 import { type MockContextOptions, type MockIntegrationContext } from './mock-context.js';
@@ -48,6 +56,11 @@ export interface InvokeScheduleOptions<Schemas extends StorageSchemas = StorageS
     /** The tick this invocation stands for. Defaults to now. */
     scheduledFor?: string;
 }
+export type InvokeActivateOptions<Schemas extends StorageSchemas = StorageSchemas> = BaseInvokeOptions<Schemas>;
+export interface ActivateInvocationOutcome<Schemas extends StorageSchemas = StorageSchemas> {
+    /** The context the handler ran against — assert on its recordings. */
+    ctx: MockIntegrationContext<Schemas>;
+}
 export interface WebhookInvocationOutcome<Schemas extends StorageSchemas = StorageSchemas> {
     result: WebhookResult;
     /** The event the handler received (payload already schema-parsed). */
@@ -74,4 +87,15 @@ export declare function invokeWebhook<Schemas extends StorageSchemas = StorageSc
  * context it ran against.
  */
 export declare function invokeSchedule<Schemas extends StorageSchemas = StorageSchemas>(definition: IntegrationDefinition<Schemas>, scheduleId: string, options?: InvokeScheduleOptions<Schemas>): Promise<ScheduleInvocationOutcome<Schemas>>;
+/**
+ * Runs the definition's declared `onActivate` hook, the way the host would
+ * after an activation persists or activationData updates. Throws if the
+ * definition declares no `onActivate` — there is nothing to invoke, and a
+ * silent no-op would let a test believe it exercised a hook that does not
+ * exist. A throwing handler PROPAGATES from this helper: the non-fatal
+ * (log-a-warning, keep the activation) handling is host policy applied by
+ * whatever calls this in production/the harness, not by this bare invoker
+ * (see the module doc comment).
+ */
+export declare function invokeActivate<Schemas extends StorageSchemas = StorageSchemas>(definition: IntegrationDefinition<Schemas>, options?: InvokeActivateOptions<Schemas>): Promise<ActivateInvocationOutcome<Schemas>>;
 export {};

package/dist/testing/invoke.js

@@ -80,4 +80,23 @@ export async function invokeSchedule(definition, scheduleId, options = {}) {
     const result = await schedule.handler(ctx, invocation);
     return { result, invocation, ctx };
 }
+/**
+ * Runs the definition's declared `onActivate` hook, the way the host would
+ * after an activation persists or activationData updates. Throws if the
+ * definition declares no `onActivate` — there is nothing to invoke, and a
+ * silent no-op would let a test believe it exercised a hook that does not
+ * exist. A throwing handler PROPAGATES from this helper: the non-fatal
+ * (log-a-warning, keep the activation) handling is host policy applied by
+ * whatever calls this in production/the harness, not by this bare invoker
+ * (see the module doc comment).
+ */
+export async function invokeActivate(definition, options = {}) {
+    if (!definition.onActivate) {
+        throw new Error(`Integration "${definition.slug}" declares no onActivate hook — add ` +
+            `one to defineIntegration() before invoking it.`);
+    }
+    const ctx = contextFor(definition, options);
+    await definition.onActivate(ctx);
+    return { ctx };
+}
 //# sourceMappingURL=invoke.js.map

package/dist/testing/invoke.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "The official SDK for building Ekanos integrations.",
   "license": "MIT",
@@ -49,8 +49,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@ekanos/integration-schema": "0.1.3",
-    "@ekanos/ui": "0.1.3",
+    "@ekanos/integration-schema": "0.1.5",
+    "@ekanos/ui": "0.1.5",
     "@supabase/supabase-js": "2.87.1",
     "server-only": "^0.0.1"
   },