@ekanos/sdk 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-integration-storage.js","sourceRoot":"","sources":["../../src/hooks/fetch-integration-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,oDAAoD;AACpD,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAgBhC;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,eAAuB,EACvB,OAEC;;IAED,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;KAC7B,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAA,OAAO,CAAC,OAAO,mCAAI,mBAAmB,CAAC;IAEpD,OAAO,GAAG,IAAI,IAAI,eAAe,YAAY,KAAK,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,eAAuB,EACvB,OAAuC;;IAEvC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,4BAA4B,eAAe,oCAAoC,CAChF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,4BAA4B,eAAe,oBAAoB,OAAO,CAAC,IAAI,CAAC,MAAM,SAAS;YACzF,gCAAgC,oBAAoB,+BAA+B,CACtF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,qBAAqB,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE;QAC3C,MAAM,EAAE,MAAA,OAAO,CAAC,MAAM,mCAAI,IAAI;QAC9B,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;KACxC,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,mBAAmB,eAAe,cAAc,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,IAAI,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAE/C,IACE,OAAO,KAAK,IAAI;QAChB,OAAO,OAAO,KAAK,QAAQ;QAC3B,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EACtB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,QAAQ,eAAe,gDAAgD,CACxE,CAAC;IACJ,CAAC;IAED,OAAO,OAAkC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * The browser half of the generic storage bridge.\n *\n * `ctx.storage` is a server capability and widgets are client components, so\n * a saved setting has to round-trip through HTTP. The host serves that\n * round-trip once, generically, at\n * `GET /api/integrations/[slug]/storage?accountId=…&keys=a,b`; this is the\n * client that calls it, so an integration never hand-writes the URL, the\n * query string, or the not-ok handling.\n *\n * Only keys whose declaration opted in with `clientReadable: true` come back.\n * A key that did not opt in, was never declared, or simply has no stored row\n * is ABSENT from the result — all three are indistinguishable by design, so\n * callers must treat a missing key as \"no value\", never as an error.\n *\n * Values are returned raw and unvalidated: the integration owns the shape of\n * its own storage, so it validates with the same zod schemas it declared.\n * See the Open-Meteo example's `fetchWeatherSettings` for the pattern.\n */\n\n/** Mirrors the host route's own per-request cap. */\nconst MAX_KEYS_PER_REQUEST = 20;\n\nexport interface FetchIntegrationStorageOptions {\n  /** The account whose storage to read. Must be one the caller belongs to. */\n  accountId: string;\n  /** Declared, `clientReadable` account-scope keys, e.g. `['settings/units']`. */\n  keys: readonly string[];\n  signal?: AbortSignal;\n  /**\n   * Overrides the base path. Exists for harnesses and tests that serve the\n   * route from somewhere other than the host's own origin; production code\n   * should leave it alone.\n   */\n  baseUrl?: string;\n}\n\n/**\n * Builds the host storage-route URL for one integration. Exported because a\n * harness or a test double needs to recognize the exact URL this client will\n * request.\n */\nexport function integrationStorageUrl(\n  integrationSlug: string,\n  options: Pick<FetchIntegrationStorageOptions, 'accountId' | 'keys'> & {\n    baseUrl?: string;\n  },\n): string {\n  const query = new URLSearchParams({\n    accountId: options.accountId,\n    keys: options.keys.join(','),\n  });\n\n  const base = options.baseUrl ?? '/api/integrations';\n\n  return `${base}/${integrationSlug}/storage?${query}`;\n}\n\n/**\n * Reads declared, client-readable account-scope storage for one integration.\n *\n * Throws when the request itself fails — a 403 (not signed in, not a member,\n * not activated, or no such integration, all deliberately indistinguishable)\n * or a transport error. It does NOT throw for a key that came back absent.\n */\nexport async function fetchIntegrationStorage(\n  integrationSlug: string,\n  options: FetchIntegrationStorageOptions,\n): Promise<Record<string, unknown>> {\n  if (options.keys.length === 0) {\n    throw new Error(\n      `fetchIntegrationStorage('${integrationSlug}') needs at least one storage key.`,\n    );\n  }\n\n  if (options.keys.length > MAX_KEYS_PER_REQUEST) {\n    throw new Error(\n      `fetchIntegrationStorage('${integrationSlug}') was asked for ${options.keys.length} keys; ` +\n        `the host route reads at most ${MAX_KEYS_PER_REQUEST} per request. Split the read.`,\n    );\n  }\n\n  const url = integrationStorageUrl(integrationSlug, options);\n\n  const response = await globalThis.fetch(url, {\n    signal: options.signal ?? null,\n    headers: { accept: 'application/json' },\n  });\n\n  if (!response.ok) {\n    throw new Error(\n      `Could not read '${integrationSlug}' storage (${response.status} ${response.statusText}).`,\n    );\n  }\n\n  const payload: unknown = await response.json();\n\n  if (\n    payload === null ||\n    typeof payload !== 'object' ||\n    Array.isArray(payload)\n  ) {\n    throw new Error(\n      `The '${integrationSlug}' storage route returned a non-object payload.`,\n    );\n  }\n\n  return payload as Record<string, unknown>;\n}\n"]}

package/dist/hooks/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @ekanos/sdk/hooks — client-side hooks.
+ *
+ * Import from client components only. The SDK OWNS these implementations;
+ * `@kit/integrations-core/hooks` re-exports them for first-party code, so
+ * there is one source of truth with two consumption paths
+ * (DEVELOPER_EXPERIENCE_PLAN.md §5.1).
+ *
+ * Server seam: nothing here imports a server module. The activation hooks
+ * reach the host's `'use server'` actions ONLY through the
+ * `IntegrationActivationProvider` injection seam
+ * (activation-actions-context.tsx) — that is what keeps this entrypoint free
+ * of `server-only` in a partner's module graph.
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("`@ekanos/sdk/hooks`").
+ */
+export { useActivateIntegration, useDeactivateIntegration, } from './use-activate-integration.js';
+export { IntegrationActivationProvider } from './activation-actions-context.js';
+export type { ActivateIntegrationAction, ActivateIntegrationInput, DeactivateIntegrationAction, DeactivateIntegrationInput, IntegrationActionResult, IntegrationActivationActions, } from './activation-actions-context.js';
+export { fetchIntegrationStorage, integrationStorageUrl, } from './fetch-integration-storage.js';
+export type { FetchIntegrationStorageOptions } from './fetch-integration-storage.js';
+export { useOAuthConnectionStatus, useOAuthWidgetGate, } from './use-oauth-connection-status.js';
+export type { ConnectionCheckAction, ConnectionCheckResult, OAuthErrorParam, UseOAuthConnectionStatusOptions, } from './use-oauth-connection-status.js';
+export { WidgetEventProvider, useWidgetEventBus } from './widget-event-context.js';
+export { useWidgetEvents } from './use-widget-events.js';
+export type { PublishEventInput, WidgetEvent, WidgetEventFilter, WidgetEventSubscriber, } from './widget-event-types.js';
+export { AskAssistantProvider, useAskAssistant, useRegisterAskAssistant, } from './ask-assistant-context.js';

package/dist/hooks/index.js

@@ -0,0 +1,32 @@
+/**
+ * @ekanos/sdk/hooks — client-side hooks.
+ *
+ * Import from client components only. The SDK OWNS these implementations;
+ * `@kit/integrations-core/hooks` re-exports them for first-party code, so
+ * there is one source of truth with two consumption paths
+ * (DEVELOPER_EXPERIENCE_PLAN.md §5.1).
+ *
+ * Server seam: nothing here imports a server module. The activation hooks
+ * reach the host's `'use server'` actions ONLY through the
+ * `IntegrationActivationProvider` injection seam
+ * (activation-actions-context.tsx) — that is what keeps this entrypoint free
+ * of `server-only` in a partner's module graph.
+ *
+ * Surface discipline: additions require an entry in
+ * docs/devex/sdk-export-map.md ("`@ekanos/sdk/hooks`").
+ */
+// Activation (host-injected server actions)
+export { useActivateIntegration, useDeactivateIntegration, } from './use-activate-integration.js';
+export { IntegrationActivationProvider } from './activation-actions-context.js';
+// Generic client-side storage bridge (host route:
+// GET /api/integrations/[slug]/storage). Serves only keys declared
+// `clientReadable: true`; a key that did not opt in reads as absent.
+export { fetchIntegrationStorage, integrationStorageUrl, } from './fetch-integration-storage.js';
+// OAuth connection status
+export { useOAuthConnectionStatus, useOAuthWidgetGate, } from './use-oauth-connection-status.js';
+// Widget Event Bus
+export { WidgetEventProvider, useWidgetEventBus } from './widget-event-context.js';
+export { useWidgetEvents } from './use-widget-events.js';
+// Widget Ask-Bar Bridge
+export { AskAssistantProvider, useAskAssistant, useRegisterAskAssistant, } from './ask-assistant-context.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4CAA4C;AAC5C,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAU7E,kDAAkD;AAClD,mEAAmE;AACnE,qEAAqE;AACrE,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAGrC,0BAA0B;AAC1B,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAQvC,mBAAmB;AACnB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAQtD,wBAAwB;AACxB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,uBAAuB,GACxB,MAAM,yBAAyB,CAAC","sourcesContent":["/**\n * @ekanos/sdk/hooks — client-side hooks.\n *\n * Import from client components only. The SDK OWNS these implementations;\n * `@kit/integrations-core/hooks` re-exports them for first-party code, so\n * there is one source of truth with two consumption paths\n * (DEVELOPER_EXPERIENCE_PLAN.md §5.1).\n *\n * Server seam: nothing here imports a server module. The activation hooks\n * reach the host's `'use server'` actions ONLY through the\n * `IntegrationActivationProvider` injection seam\n * (activation-actions-context.tsx) — that is what keeps this entrypoint free\n * of `server-only` in a partner's module graph.\n *\n * Surface discipline: additions require an entry in\n * docs/devex/sdk-export-map.md (\"`@ekanos/sdk/hooks`\").\n */\n\n// Activation (host-injected server actions)\nexport {\n  useActivateIntegration,\n  useDeactivateIntegration,\n} from './use-activate-integration';\nexport { IntegrationActivationProvider } from './activation-actions-context';\nexport type {\n  ActivateIntegrationAction,\n  ActivateIntegrationInput,\n  DeactivateIntegrationAction,\n  DeactivateIntegrationInput,\n  IntegrationActionResult,\n  IntegrationActivationActions,\n} from './activation-actions-context';\n\n// Generic client-side storage bridge (host route:\n// GET /api/integrations/[slug]/storage). Serves only keys declared\n// `clientReadable: true`; a key that did not opt in reads as absent.\nexport {\n  fetchIntegrationStorage,\n  integrationStorageUrl,\n} from './fetch-integration-storage';\nexport type { FetchIntegrationStorageOptions } from './fetch-integration-storage';\n\n// OAuth connection status\nexport {\n  useOAuthConnectionStatus,\n  useOAuthWidgetGate,\n} from './use-oauth-connection-status';\nexport type {\n  ConnectionCheckAction,\n  ConnectionCheckResult,\n  OAuthErrorParam,\n  UseOAuthConnectionStatusOptions,\n} from './use-oauth-connection-status';\n\n// Widget Event Bus\nexport { WidgetEventProvider, useWidgetEventBus } from './widget-event-context';\nexport { useWidgetEvents } from './use-widget-events';\nexport type {\n  PublishEventInput,\n  WidgetEvent,\n  WidgetEventFilter,\n  WidgetEventSubscriber,\n} from './widget-event-types';\n\n// Widget Ask-Bar Bridge\nexport {\n  AskAssistantProvider,\n  useAskAssistant,\n  useRegisterAskAssistant,\n} from './ask-assistant-context';\n"]}

package/dist/hooks/use-activate-integration.d.ts

@@ -0,0 +1,15 @@
+import { type ActivateIntegrationInput, type DeactivateIntegrationInput } from './activation-actions-context.js';
+/**
+ * Hook to activate an integration.
+ *
+ * The actual activation server action is host-injected via
+ * `IntegrationActivationProvider` (see activation-actions-context.tsx) — the
+ * hook itself never imports host server modules, which is what keeps
+ * `@ekanos/sdk/hooks` importable from a plain client (or test) module graph.
+ */
+export declare function useActivateIntegration(): import("@tanstack/react-query").UseMutationResult<import("./activation-actions-context.js").IntegrationActionResult, Error, ActivateIntegrationInput, unknown>;
+/**
+ * Hook to deactivate an integration. Same host-injection contract as
+ * `useActivateIntegration`.
+ */
+export declare function useDeactivateIntegration(): import("@tanstack/react-query").UseMutationResult<import("./activation-actions-context.js").IntegrationActionResult | undefined, Error, DeactivateIntegrationInput, unknown>;

package/dist/hooks/use-activate-integration.js

@@ -0,0 +1,61 @@
+'use client';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useIntegrationActivationActions, } from './activation-actions-context.js';
+/**
+ * Hook to activate an integration.
+ *
+ * The actual activation server action is host-injected via
+ * `IntegrationActivationProvider` (see activation-actions-context.tsx) — the
+ * hook itself never imports host server modules, which is what keeps
+ * `@ekanos/sdk/hooks` importable from a plain client (or test) module graph.
+ */
+export function useActivateIntegration() {
+    const { activate } = useIntegrationActivationActions();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: async (input) => {
+            const res = await activate(input);
+            if (!res || res.success === false) {
+                throw new Error((res === null || res === void 0 ? void 0 : res.errorMessage) || 'Activation failed');
+            }
+            return res;
+        },
+        onSuccess: (_data, variables) => {
+            // Invalidate ALL integration-status queries for this account
+            queryClient.invalidateQueries({
+                queryKey: ['integration-status', variables.accountId],
+                exact: false, // This will invalidate all queries that start with this key
+            });
+            // Invalidate any integration data queries
+            queryClient.invalidateQueries({
+                queryKey: ['integration-data', variables.accountId],
+                exact: false,
+            });
+        },
+    });
+}
+/**
+ * Hook to deactivate an integration. Same host-injection contract as
+ * `useActivateIntegration`.
+ */
+export function useDeactivateIntegration() {
+    const { deactivate } = useIntegrationActivationActions();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (input) => deactivate(input),
+        onSuccess: (_data, variables) => {
+            // Invalidate ALL integration-status queries for this account
+            queryClient.invalidateQueries({
+                queryKey: ['integration-status', variables.accountId],
+                exact: false, // This will invalidate all queries that start with this key
+            });
+            // Remove integration data queries to prevent stale cache
+            // (invalidate keeps stale data; remove clears it so remounted queries start fresh)
+            queryClient.removeQueries({
+                queryKey: ['integration-data', variables.accountId],
+                exact: false,
+            });
+        },
+    });
+}
+//# sourceMappingURL=use-activate-integration.js.map

package/dist/hooks/use-activate-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-activate-integration.js","sourceRoot":"","sources":["../../src/hooks/use-activate-integration.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,EAGL,+BAA+B,GAChC,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,EAAE,QAAQ,EAAE,GAAG,+BAA+B,EAAE,CAAC;IACvD,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IAErC,OAAO,WAAW,CAAC;QACjB,UAAU,EAAE,KAAK,EAAE,KAA+B,EAAE,EAAE;YACpD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;YAElC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,CAAA,GAAG,aAAH,GAAG,uBAAH,GAAG,CAAE,YAAY,KAAI,mBAAmB,CAAC,CAAC;YAC5D,CAAC;YAED,OAAO,GAAG,CAAC;QACb,CAAC;QACD,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;YAC9B,6DAA6D;YAC7D,WAAW,CAAC,iBAAiB,CAAC;gBAC5B,QAAQ,EAAE,CAAC,oBAAoB,EAAE,SAAS,CAAC,SAAS,CAAC;gBACrD,KAAK,EAAE,KAAK,EAAE,4DAA4D;aAC3E,CAAC,CAAC;YAEH,0CAA0C;YAC1C,WAAW,CAAC,iBAAiB,CAAC;gBAC5B,QAAQ,EAAE,CAAC,kBAAkB,EAAE,SAAS,CAAC,SAAS,CAAC;gBACnD,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,MAAM,EAAE,UAAU,EAAE,GAAG,+BAA+B,EAAE,CAAC;IACzD,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IAErC,OAAO,WAAW,CAAC;QACjB,UAAU,EAAE,CAAC,KAAiC,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;QACpE,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;YAC9B,6DAA6D;YAC7D,WAAW,CAAC,iBAAiB,CAAC;gBAC5B,QAAQ,EAAE,CAAC,oBAAoB,EAAE,SAAS,CAAC,SAAS,CAAC;gBACrD,KAAK,EAAE,KAAK,EAAE,4DAA4D;aAC3E,CAAC,CAAC;YAEH,yDAAyD;YACzD,mFAAmF;YACnF,WAAW,CAAC,aAAa,CAAC;gBACxB,QAAQ,EAAE,CAAC,kBAAkB,EAAE,SAAS,CAAC,SAAS,CAAC;gBACnD,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC","sourcesContent":["'use client';\n\nimport { useMutation, useQueryClient } from '@tanstack/react-query';\n\nimport {\n  type ActivateIntegrationInput,\n  type DeactivateIntegrationInput,\n  useIntegrationActivationActions,\n} from './activation-actions-context';\n\n/**\n * Hook to activate an integration.\n *\n * The actual activation server action is host-injected via\n * `IntegrationActivationProvider` (see activation-actions-context.tsx) — the\n * hook itself never imports host server modules, which is what keeps\n * `@ekanos/sdk/hooks` importable from a plain client (or test) module graph.\n */\nexport function useActivateIntegration() {\n  const { activate } = useIntegrationActivationActions();\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn: async (input: ActivateIntegrationInput) => {\n      const res = await activate(input);\n\n      if (!res || res.success === false) {\n        throw new Error(res?.errorMessage || 'Activation failed');\n      }\n\n      return res;\n    },\n    onSuccess: (_data, variables) => {\n      // Invalidate ALL integration-status queries for this account\n      queryClient.invalidateQueries({\n        queryKey: ['integration-status', variables.accountId],\n        exact: false, // This will invalidate all queries that start with this key\n      });\n\n      // Invalidate any integration data queries\n      queryClient.invalidateQueries({\n        queryKey: ['integration-data', variables.accountId],\n        exact: false,\n      });\n    },\n  });\n}\n\n/**\n * Hook to deactivate an integration. Same host-injection contract as\n * `useActivateIntegration`.\n */\nexport function useDeactivateIntegration() {\n  const { deactivate } = useIntegrationActivationActions();\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn: (input: DeactivateIntegrationInput) => deactivate(input),\n    onSuccess: (_data, variables) => {\n      // Invalidate ALL integration-status queries for this account\n      queryClient.invalidateQueries({\n        queryKey: ['integration-status', variables.accountId],\n        exact: false, // This will invalidate all queries that start with this key\n      });\n\n      // Remove integration data queries to prevent stale cache\n      // (invalidate keeps stale data; remove clears it so remounted queries start fresh)\n      queryClient.removeQueries({\n        queryKey: ['integration-data', variables.accountId],\n        exact: false,\n      });\n    },\n  });\n}\n"]}

package/dist/hooks/use-oauth-connection-status.d.ts

@@ -0,0 +1,360 @@
+/**
+ * Result shape of an integration's check-connection server action
+ * (the standard enhanceAction envelope).
+ */
+export interface ConnectionCheckResult {
+    success: boolean;
+    data?: {
+        obtainedAt?: string | null;
+    } | null;
+    error?: string;
+}
+export type ConnectionCheckAction = (input: {
+    accountId: string;
+}) => Promise<ConnectionCheckResult>;
+/**
+ * Optional OAuth failure query param an integration's connect route may
+ * append on redirect (e.g. dropbox_error=credentials_not_configured).
+ */
+export interface OAuthErrorParam {
+    name: string;
+    /** Map the raw param value to a user-facing message; return null to ignore. */
+    toMessage: (value: string) => string | null;
+}
+export interface UseOAuthConnectionStatusOptions {
+    /**
+     * Cache key segment, by convention `<slug>-connection`. The full query key
+     * is ['integration-data', accountId, connectionKey] so all widgets and the
+     * activation form share one deduped request per dashboard load.
+     */
+    connectionKey: string;
+    checkConnection: ConnectionCheckAction;
+    /** Gate the query (e.g. on integration-active state). Defaults to true. */
+    enabled?: boolean;
+    errorParam?: OAuthErrorParam;
+}
+/**
+ * Shared OAuth connection-status hook. Detects the `oauth_success=true`
+ * return from an integration's connect route, strips the transient params
+ * from the URL, and invalidates the cached status so dependent UI flips to
+ * connected without a manual refresh.
+ */
+export declare function useOAuthConnectionStatus(accountId: string, options: UseOAuthConnectionStatusOptions): {
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+    data: NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    promise: Promise<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>>;
+} | {
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+    data: NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>;
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    promise: Promise<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>>;
+} | {
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+    data: undefined;
+    error: Error;
+    isError: true;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: true;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "error";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    promise: Promise<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>>;
+} | {
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    promise: Promise<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>>;
+} | {
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+    data: undefined;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: "pending";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    promise: Promise<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>>;
+} | {
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+    data: NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>;
+    isError: false;
+    error: null;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: "success";
+    dataUpdatedAt: number;
+    errorUpdatedAt: number;
+    failureCount: number;
+    failureReason: Error | null;
+    errorUpdateCount: number;
+    isFetched: boolean;
+    isFetchedAfterMount: boolean;
+    isFetching: boolean;
+    isInitialLoading: boolean;
+    isPaused: boolean;
+    isRefetching: boolean;
+    isStale: boolean;
+    isEnabled: boolean;
+    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>, Error>>;
+    fetchStatus: import("@tanstack/react-query").FetchStatus;
+    promise: Promise<NoInfer<{
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+        error?: undefined;
+    }>>;
+};
+/**
+ * Resolves the gating booleans every OAuth-backed dashboard widget needs:
+ *
+ * - `enabled` — the integration is active and an account id is present.
+ * - `isConnected` — a live OAuth connection exists (access token).
+ * - `dataEnabled` — safe to fire the widget's data query (active + connected).
+ * - `connectionPending` — still resolving the connection status.
+ * - `connectionError` — the connection check itself failed (network/5xx).
+ *   Distinct from `notConnected`: a transient failure should surface as an
+ *   error, not as a misleading "connect X" prompt.
+ * - `notConnected` — activated, resolved without error, but no OAuth
+ *   connection. The widget should render its "connect X" inactive state.
+ *
+ * The underlying connection check shares one query key across all widgets,
+ * so react-query dedupes it to a single request per dashboard load.
+ */
+export declare function useOAuthWidgetGate(accountId: string | undefined, integrationActive: boolean, options: Pick<UseOAuthConnectionStatusOptions, 'connectionKey' | 'checkConnection'>): {
+    enabled: boolean;
+    isConnected: boolean;
+    connectionPending: boolean;
+    connectionError: boolean;
+    dataEnabled: boolean;
+    notConnected: boolean;
+};

package/dist/hooks/use-oauth-connection-status.js

@@ -0,0 +1,108 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+/**
+ * Shared OAuth connection-status hook. Detects the `oauth_success=true`
+ * return from an integration's connect route, strips the transient params
+ * from the URL, and invalidates the cached status so dependent UI flips to
+ * connected without a manual refresh.
+ */
+export function useOAuthConnectionStatus(accountId, options) {
+    const { connectionKey, checkConnection, enabled = true, errorParam, } = options;
+    const queryClient = useQueryClient();
+    // Read the OAuth return params synchronously on mount (not in an effect)
+    // so the first render already knows whether we just came back from OAuth.
+    const [oauthJustCompleted] = useState(() => {
+        if (typeof window === 'undefined')
+            return false;
+        const params = new URLSearchParams(window.location.search);
+        return params.get('oauth_success') === 'true';
+    });
+    const [oauthError] = useState(() => {
+        if (!errorParam || typeof window === 'undefined')
+            return null;
+        const value = new URLSearchParams(window.location.search).get(errorParam.name);
+        return value ? errorParam.toMessage(value) : null;
+    });
+    const query = useQuery({
+        queryKey: ['integration-data', accountId, connectionKey],
+        queryFn: async () => {
+            var _a;
+            const result = await checkConnection({ accountId });
+            if (!result.success) {
+                return { isConnected: false, error: result.error };
+            }
+            return {
+                isConnected: true,
+                obtainedAt: (_a = result.data) === null || _a === void 0 ? void 0 : _a.obtainedAt,
+            };
+        },
+        enabled: enabled && !!accountId,
+        staleTime: 5 * 60 * 1000,
+        refetchOnWindowFocus: false,
+    });
+    const errorParamName = errorParam === null || errorParam === void 0 ? void 0 : errorParam.name;
+    // Justified useEffect (per CLAUDE.md): after the OAuth redirect lands back
+    // on this page with `?oauth_success=true`, we must (1) strip the transient
+    // query params from the URL and (2) invalidate the cached connection status
+    // so widgets flip to connected without a manual refresh. Both are
+    // post-render side effects on external systems (history API + query
+    // cache), not derivable during render.
+    useEffect(() => {
+        if (!oauthJustCompleted)
+            return;
+        const url = new URL(window.location.href);
+        url.searchParams.delete('oauth_success');
+        if (errorParamName) {
+            url.searchParams.delete(errorParamName);
+        }
+        window.history.replaceState({}, '', url.pathname + url.search);
+        queryClient.invalidateQueries({
+            queryKey: ['integration-data', accountId, connectionKey],
+        });
+    }, [
+        oauthJustCompleted,
+        accountId,
+        connectionKey,
+        errorParamName,
+        queryClient,
+    ]);
+    return Object.assign(Object.assign({}, query), { oauthJustCompleted, oauthError });
+}
+/**
+ * Resolves the gating booleans every OAuth-backed dashboard widget needs:
+ *
+ * - `enabled` — the integration is active and an account id is present.
+ * - `isConnected` — a live OAuth connection exists (access token).
+ * - `dataEnabled` — safe to fire the widget's data query (active + connected).
+ * - `connectionPending` — still resolving the connection status.
+ * - `connectionError` — the connection check itself failed (network/5xx).
+ *   Distinct from `notConnected`: a transient failure should surface as an
+ *   error, not as a misleading "connect X" prompt.
+ * - `notConnected` — activated, resolved without error, but no OAuth
+ *   connection. The widget should render its "connect X" inactive state.
+ *
+ * The underlying connection check shares one query key across all widgets,
+ * so react-query dedupes it to a single request per dashboard load.
+ */
+export function useOAuthWidgetGate(accountId, integrationActive, options) {
+    var _a;
+    const enabled = integrationActive && !!accountId;
+    const query = useOAuthConnectionStatus(accountId !== null && accountId !== void 0 ? accountId : '', Object.assign(Object.assign({}, options), { enabled }));
+    const connectionPending = enabled && query.isPending;
+    const connectionError = enabled && query.isError;
+    const isConnected = ((_a = query.data) === null || _a === void 0 ? void 0 : _a.isConnected) === true;
+    const dataEnabled = enabled && isConnected;
+    // Only treat as "not connected" when the check resolved successfully with
+    // no token — a query error is an error state, not a disconnected account.
+    const notConnected = enabled && !connectionPending && !connectionError && !isConnected;
+    return {
+        enabled,
+        isConnected,
+        connectionPending,
+        connectionError,
+        dataEnabled,
+        notConnected,
+    };
+}
+//# sourceMappingURL=use-oauth-connection-status.js.map

package/dist/hooks/use-oauth-connection-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-oauth-connection-status.js","sourceRoot":"","sources":["../../src/hooks/use-oauth-connection-status.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { useEffect, useState } from 'react';\n\nimport { useQuery, useQueryClient } from '@tanstack/react-query';\n\n/**\n * Result shape of an integration's check-connection server action\n * (the standard enhanceAction envelope).\n */\nexport interface ConnectionCheckResult {\n  success: boolean;\n  data?: { obtainedAt?: string | null } | null;\n  error?: string;\n}\n\nexport type ConnectionCheckAction = (input: {\n  accountId: string;\n}) => Promise<ConnectionCheckResult>;\n\n/**\n * Optional OAuth failure query param an integration's connect route may\n * append on redirect (e.g. dropbox_error=credentials_not_configured).\n */\nexport interface OAuthErrorParam {\n  name: string;\n  /** Map the raw param value to a user-facing message; return null to ignore. */\n  toMessage: (value: string) => string | null;\n}\n\nexport interface UseOAuthConnectionStatusOptions {\n  /**\n   * Cache key segment, by convention `<slug>-connection`. The full query key\n   * is ['integration-data', accountId, connectionKey] so all widgets and the\n   * activation form share one deduped request per dashboard load.\n   */\n  connectionKey: string;\n  checkConnection: ConnectionCheckAction;\n  /** Gate the query (e.g. on integration-active state). Defaults to true. */\n  enabled?: boolean;\n  errorParam?: OAuthErrorParam;\n}\n\n/**\n * Shared OAuth connection-status hook. Detects the `oauth_success=true`\n * return from an integration's connect route, strips the transient params\n * from the URL, and invalidates the cached status so dependent UI flips to\n * connected without a manual refresh.\n */\nexport function useOAuthConnectionStatus(\n  accountId: string,\n  options: UseOAuthConnectionStatusOptions,\n) {\n  const {\n    connectionKey,\n    checkConnection,\n    enabled = true,\n    errorParam,\n  } = options;\n  const queryClient = useQueryClient();\n\n  // Read the OAuth return params synchronously on mount (not in an effect)\n  // so the first render already knows whether we just came back from OAuth.\n  const [oauthJustCompleted] = useState(() => {\n    if (typeof window === 'undefined') return false;\n    const params = new URLSearchParams(window.location.search);\n    return params.get('oauth_success') === 'true';\n  });\n\n  const [oauthError] = useState<string | null>(() => {\n    if (!errorParam || typeof window === 'undefined') return null;\n    const value = new URLSearchParams(window.location.search).get(\n      errorParam.name,\n    );\n    return value ? errorParam.toMessage(value) : null;\n  });\n\n  const query = useQuery({\n    queryKey: ['integration-data', accountId, connectionKey],\n    queryFn: async () => {\n      const result = await checkConnection({ accountId });\n\n      if (!result.success) {\n        return { isConnected: false, error: result.error };\n      }\n\n      return {\n        isConnected: true,\n        obtainedAt: result.data?.obtainedAt,\n      };\n    },\n    enabled: enabled && !!accountId,\n    staleTime: 5 * 60 * 1000,\n    refetchOnWindowFocus: false,\n  });\n\n  const errorParamName = errorParam?.name;\n\n  // Justified useEffect (per CLAUDE.md): after the OAuth redirect lands back\n  // on this page with `?oauth_success=true`, we must (1) strip the transient\n  // query params from the URL and (2) invalidate the cached connection status\n  // so widgets flip to connected without a manual refresh. Both are\n  // post-render side effects on external systems (history API + query\n  // cache), not derivable during render.\n  useEffect(() => {\n    if (!oauthJustCompleted) return;\n\n    const url = new URL(window.location.href);\n    url.searchParams.delete('oauth_success');\n\n    if (errorParamName) {\n      url.searchParams.delete(errorParamName);\n    }\n\n    window.history.replaceState({}, '', url.pathname + url.search);\n\n    queryClient.invalidateQueries({\n      queryKey: ['integration-data', accountId, connectionKey],\n    });\n  }, [\n    oauthJustCompleted,\n    accountId,\n    connectionKey,\n    errorParamName,\n    queryClient,\n  ]);\n\n  return { ...query, oauthJustCompleted, oauthError };\n}\n\n/**\n * Resolves the gating booleans every OAuth-backed dashboard widget needs:\n *\n * - `enabled` — the integration is active and an account id is present.\n * - `isConnected` — a live OAuth connection exists (access token).\n * - `dataEnabled` — safe to fire the widget's data query (active + connected).\n * - `connectionPending` — still resolving the connection status.\n * - `connectionError` — the connection check itself failed (network/5xx).\n *   Distinct from `notConnected`: a transient failure should surface as an\n *   error, not as a misleading \"connect X\" prompt.\n * - `notConnected` — activated, resolved without error, but no OAuth\n *   connection. The widget should render its \"connect X\" inactive state.\n *\n * The underlying connection check shares one query key across all widgets,\n * so react-query dedupes it to a single request per dashboard load.\n */\nexport function useOAuthWidgetGate(\n  accountId: string | undefined,\n  integrationActive: boolean,\n  options: Pick<\n    UseOAuthConnectionStatusOptions,\n    'connectionKey' | 'checkConnection'\n  >,\n) {\n  const enabled = integrationActive && !!accountId;\n  const query = useOAuthConnectionStatus(accountId ?? '', {\n    ...options,\n    enabled,\n  });\n\n  const connectionPending = enabled && query.isPending;\n  const connectionError = enabled && query.isError;\n  const isConnected = query.data?.isConnected === true;\n  const dataEnabled = enabled && isConnected;\n  // Only treat as \"not connected\" when the check resolved successfully with\n  // no token — a query error is an error state, not a disconnected account.\n  const notConnected =\n    enabled && !connectionPending && !connectionError && !isConnected;\n\n  return {\n    enabled,\n    isConnected,\n    connectionPending,\n    connectionError,\n    dataEnabled,\n    notConnected,\n  };\n}\n"]}