@ekanos/sdk 0.1.0

package/dist/hooks/use-widget-events.d.ts

@@ -0,0 +1,20 @@
+import type { WidgetEvent, WidgetEventFilter } from './widget-event-types.js';
+/**
+ * Subscribe to widget events with optional filtering.
+ *
+ * @example
+ * ```tsx
+ * const { latestEvent } = useWidgetEvents({
+ *   subtypes: ['deal_selected', 'deal_deselected'],
+ * });
+ *
+ * if (latestEvent?.subtype === 'deal_selected') {
+ *   const { contactId } = latestEvent.payload as { contactId: string };
+ * }
+ * ```
+ */
+export declare function useWidgetEvents(filter?: WidgetEventFilter): {
+    latestEvent: WidgetEvent | null;
+    events: WidgetEvent[];
+    clear: () => void;
+};

package/dist/hooks/use-widget-events.js

@@ -0,0 +1,51 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useWidgetEventBus } from './widget-event-context.js';
+const INITIAL_STATE = { latestEvent: null, events: [] };
+const MAX_EVENT_HISTORY = 50;
+/**
+ * Subscribe to widget events with optional filtering.
+ *
+ * @example
+ * ```tsx
+ * const { latestEvent } = useWidgetEvents({
+ *   subtypes: ['deal_selected', 'deal_deselected'],
+ * });
+ *
+ * if (latestEvent?.subtype === 'deal_selected') {
+ *   const { contactId } = latestEvent.payload as { contactId: string };
+ * }
+ * ```
+ */
+export function useWidgetEvents(filter) {
+    const { subscribe } = useWidgetEventBus();
+    const [state, setState] = useState(INITIAL_STATE);
+    // Stabilize filter reference to avoid re-subscribing on every render
+    const filterRef = useRef(filter);
+    // Effect is required: synchronizing a ref from render props for use in a stable callback
+    useEffect(() => {
+        filterRef.current = filter;
+    });
+    const handleEvent = useCallback((event) => {
+        const f = filterRef.current;
+        if ((f === null || f === void 0 ? void 0 : f.subtypes) && !f.subtypes.includes(event.subtype))
+            return;
+        if ((f === null || f === void 0 ? void 0 : f.sourceProducts) && !f.sourceProducts.includes(event.sourceProduct))
+            return;
+        if ((f === null || f === void 0 ? void 0 : f.sourceWidgets) && !f.sourceWidgets.includes(event.sourceWidget))
+            return;
+        setState((prev) => ({
+            latestEvent: event,
+            events: [event, ...prev.events].slice(0, MAX_EVENT_HISTORY),
+        }));
+    }, []);
+    // Effect is required: subscribing to an external event source (the bus) on mount
+    useEffect(() => {
+        return subscribe(handleEvent);
+    }, [subscribe, handleEvent]);
+    const clear = useCallback(() => {
+        setState(INITIAL_STATE);
+    }, []);
+    return { latestEvent: state.latestEvent, events: state.events, clear };
+}
+//# sourceMappingURL=use-widget-events.js.map

package/dist/hooks/use-widget-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-widget-events.js","sourceRoot":"","sources":["../../src/hooks/use-widget-events.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAQ3D,MAAM,aAAa,GAAqB,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC1E,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,MAA0B;IAKxD,MAAM,EAAE,SAAS,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAC1C,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAmB,aAAa,CAAC,CAAC;IAEpE,qEAAqE;IACrE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjC,yFAAyF;IACzF,SAAS,CAAC,GAAG,EAAE;QACb,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,KAAkB,EAAE,EAAE;QACrD,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC;QAE5B,IAAI,CAAA,CAAC,aAAD,CAAC,uBAAD,CAAC,CAAE,QAAQ,KAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,OAAO;QAC/D,IAAI,CAAA,CAAC,aAAD,CAAC,uBAAD,CAAC,CAAE,cAAc,KAAI,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;YACtE,OAAO;QACT,IAAI,CAAA,CAAC,aAAD,CAAC,uBAAD,CAAC,CAAE,aAAa,KAAI,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;YACnE,OAAO;QAET,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAClB,WAAW,EAAE,KAAK;YAClB,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC;SAC5D,CAAC,CAAC,CAAC;IACN,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,iFAAiF;IACjF,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,SAAS,CAAC,WAAW,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IAE7B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1B,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;AACzE,CAAC","sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\nimport { useWidgetEventBus } from './widget-event-context';\nimport type { WidgetEvent, WidgetEventFilter } from './widget-event-types';\n\ninterface WidgetEventState {\n  latestEvent: WidgetEvent | null;\n  events: WidgetEvent[];\n}\n\nconst INITIAL_STATE: WidgetEventState = { latestEvent: null, events: [] };\nconst MAX_EVENT_HISTORY = 50;\n\n/**\n * Subscribe to widget events with optional filtering.\n *\n * @example\n * ```tsx\n * const { latestEvent } = useWidgetEvents({\n *   subtypes: ['deal_selected', 'deal_deselected'],\n * });\n *\n * if (latestEvent?.subtype === 'deal_selected') {\n *   const { contactId } = latestEvent.payload as { contactId: string };\n * }\n * ```\n */\nexport function useWidgetEvents(filter?: WidgetEventFilter): {\n  latestEvent: WidgetEvent | null;\n  events: WidgetEvent[];\n  clear: () => void;\n} {\n  const { subscribe } = useWidgetEventBus();\n  const [state, setState] = useState<WidgetEventState>(INITIAL_STATE);\n\n  // Stabilize filter reference to avoid re-subscribing on every render\n  const filterRef = useRef(filter);\n\n  // Effect is required: synchronizing a ref from render props for use in a stable callback\n  useEffect(() => {\n    filterRef.current = filter;\n  });\n\n  const handleEvent = useCallback((event: WidgetEvent) => {\n    const f = filterRef.current;\n\n    if (f?.subtypes && !f.subtypes.includes(event.subtype)) return;\n    if (f?.sourceProducts && !f.sourceProducts.includes(event.sourceProduct))\n      return;\n    if (f?.sourceWidgets && !f.sourceWidgets.includes(event.sourceWidget))\n      return;\n\n    setState((prev) => ({\n      latestEvent: event,\n      events: [event, ...prev.events].slice(0, MAX_EVENT_HISTORY),\n    }));\n  }, []);\n\n  // Effect is required: subscribing to an external event source (the bus) on mount\n  useEffect(() => {\n    return subscribe(handleEvent);\n  }, [subscribe, handleEvent]);\n\n  const clear = useCallback(() => {\n    setState(INITIAL_STATE);\n  }, []);\n\n  return { latestEvent: state.latestEvent, events: state.events, clear };\n}\n"]}

package/dist/hooks/widget-event-context.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+import type { PublishEventInput, WidgetEventSubscriber } from './widget-event-types.js';
+interface WidgetEventBusContextValue {
+    publish: (input: PublishEventInput) => void;
+    subscribe: (callback: WidgetEventSubscriber) => () => void;
+}
+interface WidgetEventProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provides the widget event bus to the dashboard tree.
+ * Wrap around DashboardGrid so all widgets can publish and subscribe.
+ */
+export declare function WidgetEventProvider({ children }: WidgetEventProviderProps): import("react").JSX.Element;
+/**
+ * Access the raw event bus for publishing and subscribing.
+ * Returns a no-op bus when used outside a WidgetEventProvider
+ * (e.g., admin widget preview panel).
+ * Prefer `useWidgetEvents` for subscribing with filters.
+ */
+export declare function useWidgetEventBus(): WidgetEventBusContextValue;
+export {};

package/dist/hooks/widget-event-context.js

@@ -0,0 +1,75 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useRef } from 'react';
+const WidgetEventBusContext = createContext(null);
+/**
+ * Provides the widget event bus to the dashboard tree.
+ * Wrap around DashboardGrid so all widgets can publish and subscribe.
+ */
+export function WidgetEventProvider({ children }) {
+    const subscribersRef = useRef(new Set());
+    // Latest REPLAYABLE event per subtype, replayed to late subscribers so a
+    // widget that mounts AFTER a producer published (e.g. Deal Alerts mounting
+    // after My Pipeline already loaded) still receives the most recent event
+    // instead of hanging forever waiting for one that already fired. Only sticky
+    // state events opt in via `replayable`; transient commands are never retained
+    // here so a late mount / remount can't re-trigger them against stale state.
+    const latestBySubtypeRef = useRef(new Map());
+    const subscribe = useCallback((callback) => {
+        subscribersRef.current.add(callback);
+        // Replay the latest retained event for each subtype to the new subscriber.
+        // The subscriber's own filter decides what it keeps.
+        for (const event of latestBySubtypeRef.current.values()) {
+            try {
+                callback(event);
+            }
+            catch (err) {
+                console.error('[WidgetEventBus] Replay subscriber error:', err);
+            }
+        }
+        return () => {
+            subscribersRef.current.delete(callback);
+        };
+    }, []);
+    const publish = useCallback((input) => {
+        var _a;
+        const event = {
+            id: crypto.randomUUID(),
+            subtype: input.subtype,
+            sourceWidget: input.sourceWidget,
+            sourceProduct: input.sourceProduct,
+            payload: input.payload,
+            timestamp: Date.now(),
+            tier: 'client',
+            replayable: (_a = input.replayable) !== null && _a !== void 0 ? _a : false,
+        };
+        // Only sticky state events are retained for replay to late subscribers.
+        if (event.replayable) {
+            latestBySubtypeRef.current.set(event.subtype, event);
+        }
+        for (const subscriber of subscribersRef.current) {
+            try {
+                subscriber(event);
+            }
+            catch (err) {
+                console.error('[WidgetEventBus] Subscriber error:', err);
+            }
+        }
+    }, []);
+    return (_jsx(WidgetEventBusContext, { value: { publish, subscribe }, children: children }));
+}
+const NOOP_BUS = {
+    publish: () => { },
+    subscribe: () => () => { },
+};
+/**
+ * Access the raw event bus for publishing and subscribing.
+ * Returns a no-op bus when used outside a WidgetEventProvider
+ * (e.g., admin widget preview panel).
+ * Prefer `useWidgetEvents` for subscribing with filters.
+ */
+export function useWidgetEventBus() {
+    const context = use(WidgetEventBusContext);
+    return context !== null && context !== void 0 ? context : NOOP_BUS;
+}
+//# sourceMappingURL=widget-event-context.js.map

package/dist/hooks/widget-event-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-event-context.js","sourceRoot":"","sources":["../../src/hooks/widget-event-context.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAa,aAAa,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAa3E,MAAM,qBAAqB,GAAG,aAAa,CACzC,IAAI,CACL,CAAC;AAMF;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAE,QAAQ,EAA4B;IACxE,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,GAAG,EAAyB,CAAC,CAAC;IAChE,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,GAAG,EAAuB,CAAC,CAAC;IAElE,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,QAA+B,EAAE,EAAE;QAChE,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAErC,2EAA2E;QAC3E,qDAAqD;QACrD,KAAK,MAAM,KAAK,IAAI,kBAAkB,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACxD,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,GAAG,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAED,OAAO,GAAG,EAAE;YACV,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,KAAwB,EAAE,EAAE;;QACvD,MAAM,KAAK,GAAgB;YACzB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,MAAA,KAAK,CAAC,UAAU,mCAAI,KAAK;SACtC,CAAC;QAEF,wEAAwE;QACxE,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACrB,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;QAED,KAAK,MAAM,UAAU,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;YAChD,IAAI,CAAC;gBACH,UAAU,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,CACL,KAAC,qBAAqB,IAAC,KAAK,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,YACjD,QAAQ,GACa,CACzB,CAAC;AACJ,CAAC;AAED,MAAM,QAAQ,GAA+B;IAC3C,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC;IACjB,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAE3C,OAAO,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,QAAQ,CAAC;AAC7B,CAAC","sourcesContent":["'use client';\n\nimport { ReactNode, createContext, use, useCallback, useRef } from 'react';\n\nimport type {\n  PublishEventInput,\n  WidgetEvent,\n  WidgetEventSubscriber,\n} from './widget-event-types';\n\ninterface WidgetEventBusContextValue {\n  publish: (input: PublishEventInput) => void;\n  subscribe: (callback: WidgetEventSubscriber) => () => void;\n}\n\nconst WidgetEventBusContext = createContext<WidgetEventBusContextValue | null>(\n  null,\n);\n\ninterface WidgetEventProviderProps {\n  children: ReactNode;\n}\n\n/**\n * Provides the widget event bus to the dashboard tree.\n * Wrap around DashboardGrid so all widgets can publish and subscribe.\n */\nexport function WidgetEventProvider({ children }: WidgetEventProviderProps) {\n  const subscribersRef = useRef(new Set<WidgetEventSubscriber>());\n  // Latest REPLAYABLE event per subtype, replayed to late subscribers so a\n  // widget that mounts AFTER a producer published (e.g. Deal Alerts mounting\n  // after My Pipeline already loaded) still receives the most recent event\n  // instead of hanging forever waiting for one that already fired. Only sticky\n  // state events opt in via `replayable`; transient commands are never retained\n  // here so a late mount / remount can't re-trigger them against stale state.\n  const latestBySubtypeRef = useRef(new Map<string, WidgetEvent>());\n\n  const subscribe = useCallback((callback: WidgetEventSubscriber) => {\n    subscribersRef.current.add(callback);\n\n    // Replay the latest retained event for each subtype to the new subscriber.\n    // The subscriber's own filter decides what it keeps.\n    for (const event of latestBySubtypeRef.current.values()) {\n      try {\n        callback(event);\n      } catch (err) {\n        console.error('[WidgetEventBus] Replay subscriber error:', err);\n      }\n    }\n\n    return () => {\n      subscribersRef.current.delete(callback);\n    };\n  }, []);\n\n  const publish = useCallback((input: PublishEventInput) => {\n    const event: WidgetEvent = {\n      id: crypto.randomUUID(),\n      subtype: input.subtype,\n      sourceWidget: input.sourceWidget,\n      sourceProduct: input.sourceProduct,\n      payload: input.payload,\n      timestamp: Date.now(),\n      tier: 'client',\n      replayable: input.replayable ?? false,\n    };\n\n    // Only sticky state events are retained for replay to late subscribers.\n    if (event.replayable) {\n      latestBySubtypeRef.current.set(event.subtype, event);\n    }\n\n    for (const subscriber of subscribersRef.current) {\n      try {\n        subscriber(event);\n      } catch (err) {\n        console.error('[WidgetEventBus] Subscriber error:', err);\n      }\n    }\n  }, []);\n\n  return (\n    <WidgetEventBusContext value={{ publish, subscribe }}>\n      {children}\n    </WidgetEventBusContext>\n  );\n}\n\nconst NOOP_BUS: WidgetEventBusContextValue = {\n  publish: () => {},\n  subscribe: () => () => {},\n};\n\n/**\n * Access the raw event bus for publishing and subscribing.\n * Returns a no-op bus when used outside a WidgetEventProvider\n * (e.g., admin widget preview panel).\n * Prefer `useWidgetEvents` for subscribing with filters.\n */\nexport function useWidgetEventBus() {\n  const context = use(WidgetEventBusContext);\n\n  return context ?? NOOP_BUS;\n}\n"]}

package/dist/hooks/widget-event-types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Widget Event Bus — Type Definitions
+ *
+ * Generic event system for cross-widget communication.
+ * Events flow through a client-side pub/sub bus (Tier 1)
+ * and optionally through Supabase Realtime (Tier 2, future).
+ */
+/** A widget event flowing through the bus */
+export interface WidgetEvent {
+    /** Unique event ID */
+    id: string;
+    /** Event name, e.g. 'deal_selected', 'document_uploaded' */
+    subtype: string;
+    /** Widget ID that published this event */
+    sourceWidget: string;
+    /** Product slug that owns the source widget */
+    sourceProduct: string;
+    /** Event-specific data */
+    payload: Record<string, unknown>;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Which tier produced this event */
+    tier: 'client' | 'database';
+    /**
+     * When true, the bus retains this event as the latest for its subtype and
+     * replays it to subscribers that mount afterward (sticky state). Leave false
+     * for transient commands (e.g. open-dialog, preview) so they are never
+     * re-delivered on a late mount / remount and re-executed against stale state.
+     */
+    replayable: boolean;
+}
+/** Input for publishing an event (id, timestamp, and tier are auto-generated) */
+export interface PublishEventInput {
+    subtype: string;
+    sourceWidget: string;
+    sourceProduct: string;
+    payload: Record<string, unknown>;
+    /**
+     * Mark this event as sticky so late subscribers receive the most recent one.
+     * Only set for events that represent durable state (e.g. a loaded list),
+     * never for one-shot commands. Defaults to false.
+     */
+    replayable?: boolean;
+}
+/** Filter options for subscribing to events */
+export interface WidgetEventFilter {
+    /** Only receive events with these subtypes */
+    subtypes?: string[];
+    /** Only receive events from these product slugs */
+    sourceProducts?: string[];
+    /** Only receive events from these widget IDs */
+    sourceWidgets?: string[];
+}
+/** Subscriber callback */
+export type WidgetEventSubscriber = (event: WidgetEvent) => void;

package/dist/hooks/widget-event-types.js

@@ -0,0 +1,9 @@
+/**
+ * Widget Event Bus — Type Definitions
+ *
+ * Generic event system for cross-widget communication.
+ * Events flow through a client-side pub/sub bus (Tier 1)
+ * and optionally through Supabase Realtime (Tier 2, future).
+ */
+export {};
+//# sourceMappingURL=widget-event-types.js.map

package/dist/hooks/widget-event-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-event-types.js","sourceRoot":"","sources":["../../src/hooks/widget-event-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Widget Event Bus — Type Definitions\n *\n * Generic event system for cross-widget communication.\n * Events flow through a client-side pub/sub bus (Tier 1)\n * and optionally through Supabase Realtime (Tier 2, future).\n */\n\n/** A widget event flowing through the bus */\nexport interface WidgetEvent {\n  /** Unique event ID */\n  id: string;\n  /** Event name, e.g. 'deal_selected', 'document_uploaded' */\n  subtype: string;\n  /** Widget ID that published this event */\n  sourceWidget: string;\n  /** Product slug that owns the source widget */\n  sourceProduct: string;\n  /** Event-specific data */\n  payload: Record<string, unknown>;\n  /** Unix timestamp in milliseconds */\n  timestamp: number;\n  /** Which tier produced this event */\n  tier: 'client' | 'database';\n  /**\n   * When true, the bus retains this event as the latest for its subtype and\n   * replays it to subscribers that mount afterward (sticky state). Leave false\n   * for transient commands (e.g. open-dialog, preview) so they are never\n   * re-delivered on a late mount / remount and re-executed against stale state.\n   */\n  replayable: boolean;\n}\n\n/** Input for publishing an event (id, timestamp, and tier are auto-generated) */\nexport interface PublishEventInput {\n  subtype: string;\n  sourceWidget: string;\n  sourceProduct: string;\n  payload: Record<string, unknown>;\n  /**\n   * Mark this event as sticky so late subscribers receive the most recent one.\n   * Only set for events that represent durable state (e.g. a loaded list),\n   * never for one-shot commands. Defaults to false.\n   */\n  replayable?: boolean;\n}\n\n/** Filter options for subscribing to events */\nexport interface WidgetEventFilter {\n  /** Only receive events with these subtypes */\n  subtypes?: string[];\n  /** Only receive events from these product slugs */\n  sourceProducts?: string[];\n  /** Only receive events from these widget IDs */\n  sourceWidgets?: string[];\n}\n\n/** Subscriber callback */\nexport type WidgetEventSubscriber = (event: WidgetEvent) => void;\n"]}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @ekanos/sdk — the integration contract.
+ *
+ * Types only. This entrypoint is importable from any module, client or
+ * server, and must stay that way: every export below is a `type` re-export,
+ * so nothing here can pull runtime code into a client bundle. Runtime lives
+ * in `@ekanos/sdk/components`, `@ekanos/sdk/hooks`, and `@ekanos/sdk/mcp`.
+ *
+ * The SDK OWNS these definitions (`./types` — nothing imported from `@kit/*`);
+ * `@kit/integrations-core` keeps copies of some for now, and the parity guard
+ * (`packages/integrations/core/src/core/__tests__/sdk-parity.test-d.ts` —
+ * core-side since the inversion, because the dependency arrow is core → SDK)
+ * fails core's typecheck on any drift.
+ *
+ * Surface discipline: additions require a second consumer and a line in
+ * docs/devex/sdk-export-map.md. Keep the whole surface readable in one pass.
+ */
+export type { IntegrationMetadata, IntegrationCapability, IntegrationPermission, IntegrationConfig, IntegrationComponentProps, ActivationFormProps, ActivationResult, MarketplaceTileProps, WidgetConfig, WorkspaceTargetDefinition, WidgetAskContext, WidgetSnapshot, WidgetSuggestedPrompt, HealthCheckResult, HealthStatus, AccountProductData, AccountProductDataType, } from './types/index.js';
+export type { IntegrationContext, IntegrationActor, IntegrationStorage, ScopedStore, IntegrationSecrets, IntegrationFetch, IntegrationLogger, StorageEntry, StorageWriteOptions, StorageSchemas, StorageSchemaMap, StorageScopeSchemas, StorageKeyDeclaration, StorageKeyDeclarationInput, StorageKeySchema, } from './context/types.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @ekanos/sdk — the integration contract.
+ *
+ * Types only. This entrypoint is importable from any module, client or
+ * server, and must stay that way: every export below is a `type` re-export,
+ * so nothing here can pull runtime code into a client bundle. Runtime lives
+ * in `@ekanos/sdk/components`, `@ekanos/sdk/hooks`, and `@ekanos/sdk/mcp`.
+ *
+ * The SDK OWNS these definitions (`./types` — nothing imported from `@kit/*`);
+ * `@kit/integrations-core` keeps copies of some for now, and the parity guard
+ * (`packages/integrations/core/src/core/__tests__/sdk-parity.test-d.ts` —
+ * core-side since the inversion, because the dependency arrow is core → SDK)
+ * fails core's typecheck on any drift.
+ *
+ * Surface discipline: additions require a second consumer and a line in
+ * docs/devex/sdk-export-map.md. Keep the whole surface readable in one pass.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG","sourcesContent":["/**\n * @ekanos/sdk — the integration contract.\n *\n * Types only. This entrypoint is importable from any module, client or\n * server, and must stay that way: every export below is a `type` re-export,\n * so nothing here can pull runtime code into a client bundle. Runtime lives\n * in `@ekanos/sdk/components`, `@ekanos/sdk/hooks`, and `@ekanos/sdk/mcp`.\n *\n * The SDK OWNS these definitions (`./types` — nothing imported from `@kit/*`);\n * `@kit/integrations-core` keeps copies of some for now, and the parity guard\n * (`packages/integrations/core/src/core/__tests__/sdk-parity.test-d.ts` —\n * core-side since the inversion, because the dependency arrow is core → SDK)\n * fails core's typecheck on any drift.\n *\n * Surface discipline: additions require a second consumer and a line in\n * docs/devex/sdk-export-map.md. Keep the whole surface readable in one pass.\n */\n\nexport type {\n  // The integration definition\n  IntegrationMetadata,\n  IntegrationCapability,\n  IntegrationPermission,\n  IntegrationConfig,\n\n  // Component contracts\n  IntegrationComponentProps,\n  ActivationFormProps,\n  ActivationResult,\n  MarketplaceTileProps,\n  WidgetConfig,\n  WorkspaceTargetDefinition,\n\n  // AI ask-footer contract\n  WidgetAskContext,\n  WidgetSnapshot,\n  WidgetSuggestedPrompt,\n\n  // Health contract (required to implement checkHealth)\n  HealthCheckResult,\n  HealthStatus,\n\n  // Account-scoped data seam\n  AccountProductData,\n  AccountProductDataType,\n} from './types';\n\nexport type {\n  // The capability context (docs/devex/capability-context-proposal.md) —\n  // handed to MCP tool run() and server handlers; the mock lives in\n  // @ekanos/sdk/testing, the shared runtime values in @ekanos/sdk/context.\n  IntegrationContext,\n  IntegrationActor,\n  IntegrationStorage,\n  ScopedStore,\n  IntegrationSecrets,\n  IntegrationFetch,\n  IntegrationLogger,\n  StorageEntry,\n  StorageWriteOptions,\n\n  // Storage schema declaration (ruling 1) — consumed by defineIntegration()\n  // and createMockContext()\n  StorageSchemas,\n  StorageSchemaMap,\n  StorageScopeSchemas,\n\n  // Per-key declaration form carrying exposure flags. `clientReadable`\n  // (default false) is what opts a key in to the generic browser-readable\n  // storage route — see StorageKeyDeclaration for the full rationale.\n  StorageKeyDeclaration,\n  StorageKeyDeclarationInput,\n  StorageKeySchema,\n} from './context/types';\n"]}

package/dist/integration/cron.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A tiny, dependency-free 5-field cron validator.
+ *
+ * Lives at the SDK layer on purpose: the dependency-pure schema package
+ * checks only that `schedules[].cron` is a non-empty string, and
+ * `defineIntegration()` layers full syntax validation on top — the same
+ * split the workspace-target host rules use. The HOST scheduler binds to
+ * the same 5-field grammar later, so an expression this parser accepts is
+ * an expression the platform will run.
+ *
+ * Grammar (numeric, standard cron):
+ *   field     := element ("," element)*
+ *   element   := "*" | value | range        — each optionally "/" step
+ *   range     := value "-" value
+ * Fields and bounds: minute 0-59, hour 0-23, day-of-month 1-31, month 1-12,
+ * day-of-week 0-7 (both 0 and 7 mean Sunday). No names (JAN/MON), no
+ * @-macros, no seconds field — declare what a plain cron daemon runs.
+ */
+export interface CronField {
+    name: string;
+    min: number;
+    max: number;
+}
+/**
+ * Validates a 5-field cron expression, throwing a `TypeError` whose message
+ * is a remediation instruction. Returns the expression's fields (trimmed)
+ * so callers can display them.
+ */
+export declare function parseCronExpression(expression: string): string[];

package/dist/integration/cron.js

@@ -0,0 +1,102 @@
+/**
+ * A tiny, dependency-free 5-field cron validator.
+ *
+ * Lives at the SDK layer on purpose: the dependency-pure schema package
+ * checks only that `schedules[].cron` is a non-empty string, and
+ * `defineIntegration()` layers full syntax validation on top — the same
+ * split the workspace-target host rules use. The HOST scheduler binds to
+ * the same 5-field grammar later, so an expression this parser accepts is
+ * an expression the platform will run.
+ *
+ * Grammar (numeric, standard cron):
+ *   field     := element ("," element)*
+ *   element   := "*" | value | range        — each optionally "/" step
+ *   range     := value "-" value
+ * Fields and bounds: minute 0-59, hour 0-23, day-of-month 1-31, month 1-12,
+ * day-of-week 0-7 (both 0 and 7 mean Sunday). No names (JAN/MON), no
+ * @-macros, no seconds field — declare what a plain cron daemon runs.
+ */
+const CRON_FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day-of-month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12 },
+    { name: 'day-of-week', min: 0, max: 7 },
+];
+function fail(expression, detail) {
+    throw new TypeError(`Cron expression "${expression}" is invalid: ${detail}. Expected 5 ` +
+        `space-separated fields (minute hour day-of-month month day-of-week), ` +
+        `numeric values only, with "*", lists ("1,15"), ranges ("1-5"), and ` +
+        `steps ("*/15", "0-30/5") — e.g. "0 6 * * *" for 06:00 daily.`);
+}
+function parseValue(expression, field, raw) {
+    if (!/^\d+$/.test(raw)) {
+        fail(expression, `"${raw}" in the ${field.name} field is not a number (names and macros are not supported)`);
+    }
+    const value = Number(raw);
+    if (value < field.min || value > field.max) {
+        fail(expression, `${value} is out of range for the ${field.name} field (${field.min}-${field.max})`);
+    }
+    return value;
+}
+function parseElement(expression, field, element) {
+    if (element === '') {
+        fail(expression, `the ${field.name} field has an empty list element`);
+    }
+    const [base, step, ...extra] = element.split('/');
+    if (extra.length > 0 || step === '') {
+        fail(expression, `"${element}" in the ${field.name} field has a malformed step`);
+    }
+    if (step !== undefined) {
+        if (!/^\d+$/.test(step) || Number(step) === 0) {
+            fail(expression, `step "/${step}" in the ${field.name} field must be a positive number`);
+        }
+    }
+    if (base === '*')
+        return;
+    if (base === undefined || base === '') {
+        fail(expression, `the ${field.name} field is missing a value`);
+    }
+    const rangeParts = base.split('-');
+    if (rangeParts.length > 2) {
+        fail(expression, `"${base}" in the ${field.name} field is not a value or a range`);
+    }
+    if (rangeParts.length === 2) {
+        const [fromRaw, toRaw] = rangeParts;
+        const from = parseValue(expression, field, fromRaw);
+        const to = parseValue(expression, field, toRaw);
+        if (from > to) {
+            fail(expression, `range "${base}" in the ${field.name} field runs backwards (${from} > ${to})`);
+        }
+        return;
+    }
+    const value = parseValue(expression, field, base);
+    if (step !== undefined) {
+        // "5/15"-style stepped single values are a non-portable vixie-cron
+        // extension; require an explicit range or "*" so the declaration reads
+        // the same everywhere.
+        fail(expression, `"${element}" in the ${field.name} field applies a step to the single value ${value} — use "*/${step}" or a range like "${field.min}-${field.max}/${step}"`);
+    }
+}
+/**
+ * Validates a 5-field cron expression, throwing a `TypeError` whose message
+ * is a remediation instruction. Returns the expression's fields (trimmed)
+ * so callers can display them.
+ */
+export function parseCronExpression(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        fail(expression, `it has ${fields.length} field${fields.length === 1 ? '' : 's'}, not 5` +
+            (fields.length === 6
+                ? ' (a seconds field is not supported — drop it)'
+                : ''));
+    }
+    fields.forEach((field, index) => {
+        const spec = CRON_FIELDS[index];
+        for (const element of field.split(',')) {
+            parseElement(expression, spec, element);
+        }
+    });
+    return fields;
+}
+//# sourceMappingURL=cron.js.map

package/dist/integration/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../../src/integration/cron.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A tiny, dependency-free 5-field cron validator.\n *\n * Lives at the SDK layer on purpose: the dependency-pure schema package\n * checks only that `schedules[].cron` is a non-empty string, and\n * `defineIntegration()` layers full syntax validation on top — the same\n * split the workspace-target host rules use. The HOST scheduler binds to\n * the same 5-field grammar later, so an expression this parser accepts is\n * an expression the platform will run.\n *\n * Grammar (numeric, standard cron):\n *   field     := element (\",\" element)*\n *   element   := \"*\" | value | range        — each optionally \"/\" step\n *   range     := value \"-\" value\n * Fields and bounds: minute 0-59, hour 0-23, day-of-month 1-31, month 1-12,\n * day-of-week 0-7 (both 0 and 7 mean Sunday). No names (JAN/MON), no\n * @-macros, no seconds field — declare what a plain cron daemon runs.\n */\n\nexport interface CronField {\n  name: string;\n  min: number;\n  max: number;\n}\n\nconst CRON_FIELDS: readonly CronField[] = [\n  { name: 'minute', min: 0, max: 59 },\n  { name: 'hour', min: 0, max: 23 },\n  { name: 'day-of-month', min: 1, max: 31 },\n  { name: 'month', min: 1, max: 12 },\n  { name: 'day-of-week', min: 0, max: 7 },\n];\n\nfunction fail(expression: string, detail: string): never {\n  throw new TypeError(\n    `Cron expression \"${expression}\" is invalid: ${detail}. Expected 5 ` +\n      `space-separated fields (minute hour day-of-month month day-of-week), ` +\n      `numeric values only, with \"*\", lists (\"1,15\"), ranges (\"1-5\"), and ` +\n      `steps (\"*/15\", \"0-30/5\") — e.g. \"0 6 * * *\" for 06:00 daily.`,\n  );\n}\n\nfunction parseValue(expression: string, field: CronField, raw: string): number {\n  if (!/^\\d+$/.test(raw)) {\n    fail(\n      expression,\n      `\"${raw}\" in the ${field.name} field is not a number (names and macros are not supported)`,\n    );\n  }\n  const value = Number(raw);\n  if (value < field.min || value > field.max) {\n    fail(\n      expression,\n      `${value} is out of range for the ${field.name} field (${field.min}-${field.max})`,\n    );\n  }\n  return value;\n}\n\nfunction parseElement(\n  expression: string,\n  field: CronField,\n  element: string,\n): void {\n  if (element === '') {\n    fail(expression, `the ${field.name} field has an empty list element`);\n  }\n\n  const [base, step, ...extra] = element.split('/');\n  if (extra.length > 0 || step === '') {\n    fail(\n      expression,\n      `\"${element}\" in the ${field.name} field has a malformed step`,\n    );\n  }\n  if (step !== undefined) {\n    if (!/^\\d+$/.test(step) || Number(step) === 0) {\n      fail(\n        expression,\n        `step \"/${step}\" in the ${field.name} field must be a positive number`,\n      );\n    }\n  }\n\n  if (base === '*') return;\n\n  if (base === undefined || base === '') {\n    fail(expression, `the ${field.name} field is missing a value`);\n  }\n\n  const rangeParts = base.split('-');\n  if (rangeParts.length > 2) {\n    fail(\n      expression,\n      `\"${base}\" in the ${field.name} field is not a value or a range`,\n    );\n  }\n\n  if (rangeParts.length === 2) {\n    const [fromRaw, toRaw] = rangeParts as [string, string];\n    const from = parseValue(expression, field, fromRaw);\n    const to = parseValue(expression, field, toRaw);\n    if (from > to) {\n      fail(\n        expression,\n        `range \"${base}\" in the ${field.name} field runs backwards (${from} > ${to})`,\n      );\n    }\n    return;\n  }\n\n  const value = parseValue(expression, field, base);\n  if (step !== undefined) {\n    // \"5/15\"-style stepped single values are a non-portable vixie-cron\n    // extension; require an explicit range or \"*\" so the declaration reads\n    // the same everywhere.\n    fail(\n      expression,\n      `\"${element}\" in the ${field.name} field applies a step to the single value ${value} — use \"*/${step}\" or a range like \"${field.min}-${field.max}/${step}\"`,\n    );\n  }\n}\n\n/**\n * Validates a 5-field cron expression, throwing a `TypeError` whose message\n * is a remediation instruction. Returns the expression's fields (trimmed)\n * so callers can display them.\n */\nexport function parseCronExpression(expression: string): string[] {\n  const fields = expression.trim().split(/\\s+/);\n\n  if (fields.length !== 5) {\n    fail(\n      expression,\n      `it has ${fields.length} field${fields.length === 1 ? '' : 's'}, not 5` +\n        (fields.length === 6\n          ? ' (a seconds field is not supported — drop it)'\n          : ''),\n    );\n  }\n\n  fields.forEach((field, index) => {\n    const spec = CRON_FIELDS[index]!;\n    for (const element of field.split(',')) {\n      parseElement(expression, spec, element);\n    }\n  });\n\n  return fields;\n}\n"]}

package/dist/integration/define-integration.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `defineIntegration()` — the v1 partner authoring contract
+ * (sdk-export-map.md, adversarial review outcome 3: partners never extend
+ * `BaseIntegration`; they hand the host a validated, frozen definition and
+ * the host adapts it internally).
+ *
+ * The validation logic and the schema itself live in the dependency-pure
+ * `@ekanos/integration-schema` (F3/F9): `defineIntegration()` validates at
+ * authoring time and `registerPartnerIntegration()` re-validates against the
+ * SAME schema at the host trust boundary, so there is one contract with no
+ * hand-written twin. This function adds only the generic authoring type;
+ * `IntegrationDefinitionSchema` is re-exported for the promote gate and
+ * dev-mcp validators.
+ */
+import { type IntegrationDefinition, type StorageSchemas } from '@ekanos/integration-schema';
+/**
+ * Validates a partner integration definition and returns it deep-frozen.
+ *
+ * `parseIntegrationDefinition` performs the validation AND the deep-freeze
+ * (F4: the canonical parser freezes so both this and
+ * `registerPartnerIntegration()` return immutable output). Throws with a
+ * remediation-instruction message on invalid input. The declared `Schemas`
+ * generic threads through to `ctx.storage` typing in each tool's `run`
+ * handler and is preserved by `registerPartnerIntegration()`.
+ * Cross-DEFINITION collisions (two packages, one slug) are
+ * `validateIntegrationDefinitions()`'s job.
+ */
+export declare function defineIntegration<Schemas extends StorageSchemas = StorageSchemas>(definition: IntegrationDefinition<Schemas>): IntegrationDefinition<Schemas>;

package/dist/integration/define-integration.js

@@ -0,0 +1,41 @@
+/**
+ * `defineIntegration()` — the v1 partner authoring contract
+ * (sdk-export-map.md, adversarial review outcome 3: partners never extend
+ * `BaseIntegration`; they hand the host a validated, frozen definition and
+ * the host adapts it internally).
+ *
+ * The validation logic and the schema itself live in the dependency-pure
+ * `@ekanos/integration-schema` (F3/F9): `defineIntegration()` validates at
+ * authoring time and `registerPartnerIntegration()` re-validates against the
+ * SAME schema at the host trust boundary, so there is one contract with no
+ * hand-written twin. This function adds only the generic authoring type;
+ * `IntegrationDefinitionSchema` is re-exported for the promote gate and
+ * dev-mcp validators.
+ */
+import { parseIntegrationDefinition, } from '@ekanos/integration-schema';
+import { assertEventSurfacesValid } from './event-surfaces.js';
+/**
+ * Validates a partner integration definition and returns it deep-frozen.
+ *
+ * `parseIntegrationDefinition` performs the validation AND the deep-freeze
+ * (F4: the canonical parser freezes so both this and
+ * `registerPartnerIntegration()` return immutable output). Throws with a
+ * remediation-instruction message on invalid input. The declared `Schemas`
+ * generic threads through to `ctx.storage` typing in each tool's `run`
+ * handler and is preserved by `registerPartnerIntegration()`.
+ * Cross-DEFINITION collisions (two packages, one slug) are
+ * `validateIntegrationDefinitions()`'s job.
+ */
+export function defineIntegration(definition) {
+    // parseIntegrationDefinition returns the loose (default-generic) shape; the
+    // storage/tool generic cannot be recovered from a runtime parse, but the
+    // parsed value IS the same definition, so re-narrowing to the caller's
+    // declared Schemas is sound.
+    const parsed = parseIntegrationDefinition(definition);
+    // SDK-layer event-surface rules the zod-only schema package cannot own:
+    // 5-field cron syntax on every schedule, and OAuth endpoint origins covered
+    // by the definition's own egress list.
+    assertEventSurfacesValid(parsed);
+    return parsed;
+}
+//# sourceMappingURL=define-integration.js.map

package/dist/integration/define-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-integration.js","sourceRoot":"","sources":["../../src/integration/define-integration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAGL,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAE/B,UAA0C;IAC1C,4EAA4E;IAC5E,yEAAyE;IACzE,uEAAuE;IACvE,6BAA6B;IAC7B,MAAM,MAAM,GAAG,0BAA0B,CAAC,UAAU,CAAC,CAAC;IAEtD,wEAAwE;IACxE,4EAA4E;IAC5E,uCAAuC;IACvC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO,MAAmD,CAAC;AAC7D,CAAC","sourcesContent":["/**\n * `defineIntegration()` — the v1 partner authoring contract\n * (sdk-export-map.md, adversarial review outcome 3: partners never extend\n * `BaseIntegration`; they hand the host a validated, frozen definition and\n * the host adapts it internally).\n *\n * The validation logic and the schema itself live in the dependency-pure\n * `@ekanos/integration-schema` (F3/F9): `defineIntegration()` validates at\n * authoring time and `registerPartnerIntegration()` re-validates against the\n * SAME schema at the host trust boundary, so there is one contract with no\n * hand-written twin. This function adds only the generic authoring type;\n * `IntegrationDefinitionSchema` is re-exported for the promote gate and\n * dev-mcp validators.\n */\nimport {\n  type IntegrationDefinition,\n  type StorageSchemas,\n  parseIntegrationDefinition,\n} from '@ekanos/integration-schema';\n\nimport { assertEventSurfacesValid } from './event-surfaces';\n\n/**\n * Validates a partner integration definition and returns it deep-frozen.\n *\n * `parseIntegrationDefinition` performs the validation AND the deep-freeze\n * (F4: the canonical parser freezes so both this and\n * `registerPartnerIntegration()` return immutable output). Throws with a\n * remediation-instruction message on invalid input. The declared `Schemas`\n * generic threads through to `ctx.storage` typing in each tool's `run`\n * handler and is preserved by `registerPartnerIntegration()`.\n * Cross-DEFINITION collisions (two packages, one slug) are\n * `validateIntegrationDefinitions()`'s job.\n */\nexport function defineIntegration<\n  Schemas extends StorageSchemas = StorageSchemas,\n>(definition: IntegrationDefinition<Schemas>): IntegrationDefinition<Schemas> {\n  // parseIntegrationDefinition returns the loose (default-generic) shape; the\n  // storage/tool generic cannot be recovered from a runtime parse, but the\n  // parsed value IS the same definition, so re-narrowing to the caller's\n  // declared Schemas is sound.\n  const parsed = parseIntegrationDefinition(definition);\n\n  // SDK-layer event-surface rules the zod-only schema package cannot own:\n  // 5-field cron syntax on every schedule, and OAuth endpoint origins covered\n  // by the definition's own egress list.\n  assertEventSurfacesValid(parsed);\n\n  return parsed as unknown as IntegrationDefinition<Schemas>;\n}\n"]}

package/dist/integration/event-surfaces.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SDK-layer validation of the three event surfaces (webhooks, schedules,
+ * OAuth) — the cross-field rules the dependency-pure schema package cannot
+ * own, layered on top of the canonical parse the same way
+ * `parsePartnerIntegration` layers host workspace rules:
+ *
+ *  - every `schedules[].cron` must be valid 5-field cron syntax
+ *    (`parseCronExpression`);
+ *  - the OAuth endpoints' origins must be covered by the definition's own
+ *    `egress` list, because the code exchange runs through the integration's
+ *    declared egress — an origin the reviewer never saw is an origin the
+ *    exchange must not reach.
+ */
+import type { IntegrationDefinition } from '@ekanos/integration-schema';
+export declare function assertEventSurfacesValid(definition: IntegrationDefinition): void;

package/dist/integration/event-surfaces.js

@@ -0,0 +1,45 @@
+import { isEgressAllowed } from '../context/egress.js';
+import { parseCronExpression } from './cron.js';
+export function assertEventSurfacesValid(definition) {
+    var _a, _b;
+    const problems = [];
+    for (const schedule of (_a = definition.schedules) !== null && _a !== void 0 ? _a : []) {
+        try {
+            parseCronExpression(schedule.cron);
+        }
+        catch (error) {
+            problems.push(`schedules["${schedule.id}"]: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (definition.oauth) {
+        const egress = (_b = definition.egress) !== null && _b !== void 0 ? _b : [];
+        const endpoints = [
+            ['authorizationUrl', definition.oauth.provider.authorizationUrl],
+            ['tokenUrl', definition.oauth.provider.tokenUrl],
+        ];
+        for (const [field, url] of endpoints) {
+            let covered = false;
+            try {
+                covered = isEgressAllowed(url, egress);
+            }
+            catch (error) {
+                problems.push(`oauth.provider.${field}: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            if (!covered) {
+                const origin = new URL(url).origin;
+                problems.push(`oauth.provider.${field}: its origin ${origin} is not covered by ` +
+                    `this definition's egress list ${JSON.stringify(egress)}. The ` +
+                    `OAuth code exchange runs through the integration's declared ` +
+                    `egress, so add "${origin}" (or a covering "*." wildcard entry) ` +
+                    `to \`egress\` — widening egress is a security-posture change ` +
+                    `reviewed at promotion.`);
+            }
+        }
+    }
+    if (problems.length > 0) {
+        throw new Error(`Invalid integration definition for "${definition.slug}":\n` +
+            problems.map((line) => `  - ${line}`).join('\n'));
+    }
+}
+//# sourceMappingURL=event-surfaces.js.map

package/dist/integration/event-surfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-surfaces.js","sourceRoot":"","sources":["../../src/integration/event-surfaces.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAE7C,MAAM,UAAU,wBAAwB,CACtC,UAAiC;;IAEjC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,QAAQ,IAAI,MAAA,UAAU,CAAC,SAAS,mCAAI,EAAE,EAAE,CAAC;QAClD,IAAI,CAAC;YACH,mBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,IAAI,CACX,cAAc,QAAQ,CAAC,EAAE,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAA,UAAU,CAAC,MAAM,mCAAI,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG;YAChB,CAAC,kBAAkB,EAAE,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAChE,CAAC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;SACxC,CAAC;QAEX,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,SAAS,EAAE,CAAC;YACrC,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,IAAI,CAAC;gBACH,OAAO,GAAG,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,CAAC,IAAI,CACX,kBAAkB,KAAK,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACrF,CAAC;gBACF,SAAS;YACX,CAAC;YACD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;gBACnC,QAAQ,CAAC,IAAI,CACX,kBAAkB,KAAK,gBAAgB,MAAM,qBAAqB;oBAChE,iCAAiC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ;oBAC/D,8DAA8D;oBAC9D,mBAAmB,MAAM,wCAAwC;oBACjE,+DAA+D;oBAC/D,wBAAwB,CAC3B,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,uCAAuC,UAAU,CAAC,IAAI,MAAM;YAC1D,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CACnD,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["/**\n * SDK-layer validation of the three event surfaces (webhooks, schedules,\n * OAuth) — the cross-field rules the dependency-pure schema package cannot\n * own, layered on top of the canonical parse the same way\n * `parsePartnerIntegration` layers host workspace rules:\n *\n *  - every `schedules[].cron` must be valid 5-field cron syntax\n *    (`parseCronExpression`);\n *  - the OAuth endpoints' origins must be covered by the definition's own\n *    `egress` list, because the code exchange runs through the integration's\n *    declared egress — an origin the reviewer never saw is an origin the\n *    exchange must not reach.\n */\nimport type { IntegrationDefinition } from '@ekanos/integration-schema';\n\nimport { isEgressAllowed } from '../context/egress';\nimport { parseCronExpression } from './cron';\n\nexport function assertEventSurfacesValid(\n  definition: IntegrationDefinition,\n): void {\n  const problems: string[] = [];\n\n  for (const schedule of definition.schedules ?? []) {\n    try {\n      parseCronExpression(schedule.cron);\n    } catch (error) {\n      problems.push(\n        `schedules[\"${schedule.id}\"]: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  if (definition.oauth) {\n    const egress = definition.egress ?? [];\n    const endpoints = [\n      ['authorizationUrl', definition.oauth.provider.authorizationUrl],\n      ['tokenUrl', definition.oauth.provider.tokenUrl],\n    ] as const;\n\n    for (const [field, url] of endpoints) {\n      let covered = false;\n      try {\n        covered = isEgressAllowed(url, egress);\n      } catch (error) {\n        problems.push(\n          `oauth.provider.${field}: ${error instanceof Error ? error.message : String(error)}`,\n        );\n        continue;\n      }\n      if (!covered) {\n        const origin = new URL(url).origin;\n        problems.push(\n          `oauth.provider.${field}: its origin ${origin} is not covered by ` +\n            `this definition's egress list ${JSON.stringify(egress)}. The ` +\n            `OAuth code exchange runs through the integration's declared ` +\n            `egress, so add \"${origin}\" (or a covering \"*.\" wildcard entry) ` +\n            `to \\`egress\\` — widening egress is a security-posture change ` +\n            `reviewed at promotion.`,\n        );\n      }\n    }\n  }\n\n  if (problems.length > 0) {\n    throw new Error(\n      `Invalid integration definition for \"${definition.slug}\":\\n` +\n        problems.map((line) => `  - ${line}`).join('\\n'),\n    );\n  }\n}\n"]}