@ekanos/sdk 0.2.0 → 0.4.0

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

@@ -0,0 +1,105 @@
+/**
+ * The browser half of the widget-actions transport.
+ *
+ * A partner's `actions` declaration on `IntegrationDefinition` is a
+ * record of named, deterministic server handlers —
+ * `(ctx, input) => Promise<unknown>` — invoked by a widget's own UI (a Save
+ * button), never synthesized by the AI assistant. The host serves one
+ * generic route per action:
+ *
+ *   POST /api/integrations/[slug]/actions/[actionName]
+ *
+ * and this hook is the only place a partner package should build that
+ * request, so a route move is one SDK change rather than a hunt through
+ * every widget — the same discipline `partnerOAuthConnectPath`/
+ * `fetchIntegrationStorage` already apply to their own routes.
+ *
+ * ```tsx
+ * const createRecord = useIntegrationAction<CreateRecordInput, CreateRecordOutput>(
+ *   'acme-crm',
+ *   'create-record',
+ *   { accountId },
+ * );
+ *
+ * <Button onClick={() => createRecord.mutate(formValues)}>Save</Button>
+ * ```
+ *
+ * ── Typing is a convention, not a cross-package mechanism ───────────────────
+ *
+ * `@ekanos/sdk` is a separately published package — it cannot see a specific
+ * partner's `z.ZodTypeAny` instance, since that object lives in the
+ * partner's own server bundle and never ships to the browser, let alone into
+ * the SDK's own compiled types. `TInput`/`TOutput` are generic parameters
+ * the CALLER supplies by hand at the call site — typically by also exporting
+ * `type CreateRecordInput = z.infer<typeof createRecordSchema>` from the same
+ * package that declares the action and importing it into the widget. This
+ * hook treats the wire payload as `unknown` at runtime — it never parses it
+ * against the partner's own zod schema, only against the success/error
+ * envelope shape — so drift between the declared action and the widget's
+ * type import is a partner-package refactor problem, not a network-boundary
+ * one. Same discipline `fetchIntegrationStorage` already documents for
+ * storage ("Values are returned raw and unvalidated").
+ *
+ * ── Errors are typed, never raw fetch/transport exceptions ──────────────────
+ *
+ * A rejected mutation's `error` is always an `IntegrationActionError` —
+ * never a bare `Error`, a `Response`, or an unwrapped parse/network
+ * exception. `status` and `code` are always present; `issues` (the partner's
+ * own zod issues) is present only for the route's 400 `invalid_input`
+ * response, so a form can map failures back onto fields without
+ * string-matching a message.
+ */
+import { type UseMutationResult } from '@tanstack/react-query';
+export interface UseIntegrationActionOptions {
+    /** The account the action runs against. Must be one the caller belongs to. */
+    accountId: string;
+    /**
+     * Overrides the base path. Exists for harnesses and tests that serve the
+     * route from somewhere other than the host's own origin; production code
+     * should leave it alone.
+     */
+    baseUrl?: string;
+}
+/**
+ * Builds the host actions-route URL for one integration/action pair.
+ * Exported because a harness or a test double needs to recognize the exact
+ * URL this hook will request.
+ */
+export declare function integrationActionUrl(integrationSlug: string, actionName: string, options?: {
+    baseUrl?: string;
+}): string;
+/**
+ * Route-defined failure codes the host actions route answers with, plus two
+ * transport-level codes this hook assigns itself when the response never
+ * reaches a valid envelope: `'network_error'` (the request itself failed —
+ * offline, DNS, aborted) and `'invalid_response'` (a response came back but
+ * its body isn't the envelope shape this transport expects).
+ */
+export type IntegrationActionErrorCode = 'action_not_found' | 'rate_limited' | 'invalid_input' | 'handler_error' | 'network_error' | 'invalid_response' | (string & {});
+export interface IntegrationActionErrorDetails {
+    /** HTTP status; `0` means the request never reached the server. */
+    status: number;
+    code: IntegrationActionErrorCode;
+    /** The partner's own zod issues — present only for a 400 `invalid_input` response. */
+    issues?: unknown[];
+}
+/**
+ * The typed failure a rejected `useIntegrationAction` mutation always throws.
+ * `status`/`code` let a caller branch without string-matching `message`;
+ * `issues` lets a form map the partner's own validation failures back onto
+ * fields.
+ */
+export declare class IntegrationActionError extends Error {
+    readonly status: number;
+    readonly code: IntegrationActionErrorCode;
+    readonly issues?: unknown[];
+    constructor(message: string, details: IntegrationActionErrorDetails);
+}
+/**
+ * Invokes a declared partner action from a widget. `mutate`/`mutateAsync`
+ * take the action's `TInput` directly — the caller's own already-validated
+ * values, no assistant and no natural-language round trip in between. A
+ * resolved mutation's `data` is `TOutput`; a rejected one's `error` is always
+ * an `IntegrationActionError` (see the module doc comment above).
+ */
+export declare function useIntegrationAction<TInput = unknown, TOutput = unknown>(integrationSlug: string, actionName: string, options: UseIntegrationActionOptions): UseMutationResult<TOutput, IntegrationActionError, TInput>;

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

@@ -0,0 +1,134 @@
+'use client';
+/**
+ * The browser half of the widget-actions transport.
+ *
+ * A partner's `actions` declaration on `IntegrationDefinition` is a
+ * record of named, deterministic server handlers —
+ * `(ctx, input) => Promise<unknown>` — invoked by a widget's own UI (a Save
+ * button), never synthesized by the AI assistant. The host serves one
+ * generic route per action:
+ *
+ *   POST /api/integrations/[slug]/actions/[actionName]
+ *
+ * and this hook is the only place a partner package should build that
+ * request, so a route move is one SDK change rather than a hunt through
+ * every widget — the same discipline `partnerOAuthConnectPath`/
+ * `fetchIntegrationStorage` already apply to their own routes.
+ *
+ * ```tsx
+ * const createRecord = useIntegrationAction<CreateRecordInput, CreateRecordOutput>(
+ *   'acme-crm',
+ *   'create-record',
+ *   { accountId },
+ * );
+ *
+ * <Button onClick={() => createRecord.mutate(formValues)}>Save</Button>
+ * ```
+ *
+ * ── Typing is a convention, not a cross-package mechanism ───────────────────
+ *
+ * `@ekanos/sdk` is a separately published package — it cannot see a specific
+ * partner's `z.ZodTypeAny` instance, since that object lives in the
+ * partner's own server bundle and never ships to the browser, let alone into
+ * the SDK's own compiled types. `TInput`/`TOutput` are generic parameters
+ * the CALLER supplies by hand at the call site — typically by also exporting
+ * `type CreateRecordInput = z.infer<typeof createRecordSchema>` from the same
+ * package that declares the action and importing it into the widget. This
+ * hook treats the wire payload as `unknown` at runtime — it never parses it
+ * against the partner's own zod schema, only against the success/error
+ * envelope shape — so drift between the declared action and the widget's
+ * type import is a partner-package refactor problem, not a network-boundary
+ * one. Same discipline `fetchIntegrationStorage` already documents for
+ * storage ("Values are returned raw and unvalidated").
+ *
+ * ── Errors are typed, never raw fetch/transport exceptions ──────────────────
+ *
+ * A rejected mutation's `error` is always an `IntegrationActionError` —
+ * never a bare `Error`, a `Response`, or an unwrapped parse/network
+ * exception. `status` and `code` are always present; `issues` (the partner's
+ * own zod issues) is present only for the route's 400 `invalid_input`
+ * response, so a form can map failures back onto fields without
+ * string-matching a message.
+ */
+import { useMutation } from '@tanstack/react-query';
+const DEFAULT_BASE_URL = '/api/integrations';
+/**
+ * Builds the host actions-route URL for one integration/action pair.
+ * Exported because a harness or a test double needs to recognize the exact
+ * URL this hook will request.
+ */
+export function integrationActionUrl(integrationSlug, actionName, options = {}) {
+    var _a;
+    const base = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : DEFAULT_BASE_URL;
+    return `${base}/${integrationSlug}/actions/${actionName}`;
+}
+/**
+ * The typed failure a rejected `useIntegrationAction` mutation always throws.
+ * `status`/`code` let a caller branch without string-matching `message`;
+ * `issues` lets a form map the partner's own validation failures back onto
+ * fields.
+ */
+export class IntegrationActionError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.name = 'IntegrationActionError';
+        this.status = details.status;
+        this.code = details.code;
+        this.issues = details.issues;
+    }
+}
+function isSuccessEnvelope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.success === true &&
+        'data' in value);
+}
+function isErrorEnvelope(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.success === false &&
+        typeof value.error === 'string');
+}
+async function runIntegrationAction(integrationSlug, actionName, input, options) {
+    var _a;
+    const url = integrationActionUrl(integrationSlug, actionName, options);
+    let response;
+    try {
+        response = await globalThis.fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+            },
+            body: JSON.stringify({ accountId: options.accountId, input }),
+        });
+    }
+    catch (error) {
+        throw new IntegrationActionError(`Could not reach '${integrationSlug}/${actionName}' (${error instanceof Error ? error.message : 'network error'}).`, { status: 0, code: 'network_error' });
+    }
+    const payload = await response.json().catch(() => null);
+    if (response.ok && isSuccessEnvelope(payload)) {
+        return payload.data;
+    }
+    if (isErrorEnvelope(payload)) {
+        throw new IntegrationActionError(payload.error, {
+            status: response.status,
+            code: (_a = payload.code) !== null && _a !== void 0 ? _a : 'handler_error',
+            issues: payload.issues,
+        });
+    }
+    throw new IntegrationActionError(`Could not run '${integrationSlug}/${actionName}' (${response.status} ${response.statusText}).`, { status: response.status, code: 'invalid_response' });
+}
+/**
+ * Invokes a declared partner action from a widget. `mutate`/`mutateAsync`
+ * take the action's `TInput` directly — the caller's own already-validated
+ * values, no assistant and no natural-language round trip in between. A
+ * resolved mutation's `data` is `TOutput`; a rejected one's `error` is always
+ * an `IntegrationActionError` (see the module doc comment above).
+ */
+export function useIntegrationAction(integrationSlug, actionName, options) {
+    return useMutation({
+        mutationFn: (input) => runIntegrationAction(integrationSlug, actionName, input, options),
+    });
+}
+//# sourceMappingURL=use-integration-action.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-integration-action.js","sourceRoot":"","sources":["../../src/hooks/use-integration-action.ts"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\n/**\n * The browser half of the widget-actions transport.\n *\n * A partner's `actions` declaration on `IntegrationDefinition` is a\n * record of named, deterministic server handlers —\n * `(ctx, input) => Promise<unknown>` — invoked by a widget's own UI (a Save\n * button), never synthesized by the AI assistant. The host serves one\n * generic route per action:\n *\n *   POST /api/integrations/[slug]/actions/[actionName]\n *\n * and this hook is the only place a partner package should build that\n * request, so a route move is one SDK change rather than a hunt through\n * every widget — the same discipline `partnerOAuthConnectPath`/\n * `fetchIntegrationStorage` already apply to their own routes.\n *\n * ```tsx\n * const createRecord = useIntegrationAction<CreateRecordInput, CreateRecordOutput>(\n *   'acme-crm',\n *   'create-record',\n *   { accountId },\n * );\n *\n * <Button onClick={() => createRecord.mutate(formValues)}>Save</Button>\n * ```\n *\n * ── Typing is a convention, not a cross-package mechanism ───────────────────\n *\n * `@ekanos/sdk` is a separately published package — it cannot see a specific\n * partner's `z.ZodTypeAny` instance, since that object lives in the\n * partner's own server bundle and never ships to the browser, let alone into\n * the SDK's own compiled types. `TInput`/`TOutput` are generic parameters\n * the CALLER supplies by hand at the call site — typically by also exporting\n * `type CreateRecordInput = z.infer<typeof createRecordSchema>` from the same\n * package that declares the action and importing it into the widget. This\n * hook treats the wire payload as `unknown` at runtime — it never parses it\n * against the partner's own zod schema, only against the success/error\n * envelope shape — so drift between the declared action and the widget's\n * type import is a partner-package refactor problem, not a network-boundary\n * one. Same discipline `fetchIntegrationStorage` already documents for\n * storage (\"Values are returned raw and unvalidated\").\n *\n * ── Errors are typed, never raw fetch/transport exceptions ──────────────────\n *\n * A rejected mutation's `error` is always an `IntegrationActionError` —\n * never a bare `Error`, a `Response`, or an unwrapped parse/network\n * exception. `status` and `code` are always present; `issues` (the partner's\n * own zod issues) is present only for the route's 400 `invalid_input`\n * response, so a form can map failures back onto fields without\n * string-matching a message.\n */\nimport { type UseMutationResult, useMutation } from '@tanstack/react-query';\n\nconst DEFAULT_BASE_URL = '/api/integrations';\n\nexport interface UseIntegrationActionOptions {\n  /** The account the action runs against. Must be one the caller belongs to. */\n  accountId: string;\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 actions-route URL for one integration/action pair.\n * Exported because a harness or a test double needs to recognize the exact\n * URL this hook will request.\n */\nexport function integrationActionUrl(\n  integrationSlug: string,\n  actionName: string,\n  options: { baseUrl?: string } = {},\n): string {\n  const base = options.baseUrl ?? DEFAULT_BASE_URL;\n  return `${base}/${integrationSlug}/actions/${actionName}`;\n}\n\n/**\n * Route-defined failure codes the host actions route answers with, plus two\n * transport-level codes this hook assigns itself when the response never\n * reaches a valid envelope: `'network_error'` (the request itself failed —\n * offline, DNS, aborted) and `'invalid_response'` (a response came back but\n * its body isn't the envelope shape this transport expects).\n */\nexport type IntegrationActionErrorCode =\n  | 'action_not_found'\n  | 'rate_limited'\n  | 'invalid_input'\n  | 'handler_error'\n  | 'network_error'\n  | 'invalid_response'\n  | (string & {});\n\nexport interface IntegrationActionErrorDetails {\n  /** HTTP status; `0` means the request never reached the server. */\n  status: number;\n  code: IntegrationActionErrorCode;\n  /** The partner's own zod issues — present only for a 400 `invalid_input` response. */\n  issues?: unknown[];\n}\n\n/**\n * The typed failure a rejected `useIntegrationAction` mutation always throws.\n * `status`/`code` let a caller branch without string-matching `message`;\n * `issues` lets a form map the partner's own validation failures back onto\n * fields.\n */\nexport class IntegrationActionError extends Error {\n  readonly status: number;\n  readonly code: IntegrationActionErrorCode;\n  readonly issues?: unknown[];\n\n  constructor(message: string, details: IntegrationActionErrorDetails) {\n    super(message);\n    this.name = 'IntegrationActionError';\n    this.status = details.status;\n    this.code = details.code;\n    this.issues = details.issues;\n  }\n}\n\ninterface ActionSuccessEnvelope {\n  success: true;\n  data: unknown;\n}\n\ninterface ActionErrorEnvelope {\n  success: false;\n  error: string;\n  code?: string;\n  issues?: unknown[];\n}\n\nfunction isSuccessEnvelope(value: unknown): value is ActionSuccessEnvelope {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { success?: unknown }).success === true &&\n    'data' in value\n  );\n}\n\nfunction isErrorEnvelope(value: unknown): value is ActionErrorEnvelope {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as { success?: unknown }).success === false &&\n    typeof (value as { error?: unknown }).error === 'string'\n  );\n}\n\nasync function runIntegrationAction<TInput, TOutput>(\n  integrationSlug: string,\n  actionName: string,\n  input: TInput,\n  options: UseIntegrationActionOptions,\n): Promise<TOutput> {\n  const url = integrationActionUrl(integrationSlug, actionName, options);\n\n  let response: Response;\n  try {\n    response = await globalThis.fetch(url, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        accept: 'application/json',\n      },\n      body: JSON.stringify({ accountId: options.accountId, input }),\n    });\n  } catch (error) {\n    throw new IntegrationActionError(\n      `Could not reach '${integrationSlug}/${actionName}' (${\n        error instanceof Error ? error.message : 'network error'\n      }).`,\n      { status: 0, code: 'network_error' },\n    );\n  }\n\n  const payload: unknown = await response.json().catch(() => null);\n\n  if (response.ok && isSuccessEnvelope(payload)) {\n    return payload.data as TOutput;\n  }\n\n  if (isErrorEnvelope(payload)) {\n    throw new IntegrationActionError(payload.error, {\n      status: response.status,\n      code: payload.code ?? 'handler_error',\n      issues: payload.issues,\n    });\n  }\n\n  throw new IntegrationActionError(\n    `Could not run '${integrationSlug}/${actionName}' (${response.status} ${response.statusText}).`,\n    { status: response.status, code: 'invalid_response' },\n  );\n}\n\n/**\n * Invokes a declared partner action from a widget. `mutate`/`mutateAsync`\n * take the action's `TInput` directly — the caller's own already-validated\n * values, no assistant and no natural-language round trip in between. A\n * resolved mutation's `data` is `TOutput`; a rejected one's `error` is always\n * an `IntegrationActionError` (see the module doc comment above).\n */\nexport function useIntegrationAction<TInput = unknown, TOutput = unknown>(\n  integrationSlug: string,\n  actionName: string,\n  options: UseIntegrationActionOptions,\n): UseMutationResult<TOutput, IntegrationActionError, TInput> {\n  return useMutation({\n    mutationFn: (input: TInput) =>\n      runIntegrationAction<TInput, TOutput>(\n        integrationSlug,\n        actionName,\n        input,\n        options,\n      ),\n  });\n}\n"]}

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

@@ -1,6 +1,6 @@
 /**
  * Result shape of an integration's check-connection server action
- * (the standard enhanceAction envelope).
+ * (the standard server-action envelope).
  */
 export interface ConnectionCheckResult {
     success: boolean;
@@ -40,26 +40,6 @@ export interface UseOAuthConnectionStatusOptions {
  * connected without a manual refresh.
  */
 export declare function useOAuthConnectionStatus(accountId: string, options: UseOAuthConnectionStatusOptions): {
-    oauthJustCompleted: boolean;
-    oauthError: string | null;
-    data: {
-        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;
@@ -78,32 +58,24 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     }, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-} | {
-    oauthJustCompleted: boolean;
-    oauthError: string | null;
-    data: {
-        isConnected: boolean;
-        error: string | undefined;
-        obtainedAt?: undefined;
-    } | {
-        isConnected: boolean;
-        obtainedAt: string | null | undefined;
-        error?: undefined;
-    };
-    error: null;
-    isError: false;
+    data: undefined;
+    error: Error;
+    isError: true;
     isPending: false;
     isLoading: false;
-    isLoadingError: false;
+    isLoadingError: true;
     isRefetchError: false;
-    isSuccess: true;
+    isSuccess: false;
     isPlaceholderData: false;
-    status: "success";
+    status: 'error';
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+} | {
     dataUpdatedAt: number;
     errorUpdatedAt: number;
     failureCount: number;
@@ -122,24 +94,24 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     }, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-} | {
-    oauthJustCompleted: boolean;
-    oauthError: string | null;
     data: undefined;
-    error: Error;
-    isError: true;
-    isPending: false;
-    isLoading: false;
-    isLoadingError: true;
+    error: null;
+    isError: false;
+    isPending: true;
+    isLoading: true;
+    isLoadingError: false;
     isRefetchError: false;
     isSuccess: false;
     isPlaceholderData: false;
-    status: "error";
+    status: 'pending';
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+} | {
     dataUpdatedAt: number;
     errorUpdatedAt: number;
     failureCount: number;
@@ -148,6 +120,7 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
     isFetched: boolean;
     isFetchedAfterMount: boolean;
     isFetching: boolean;
+    isLoading: boolean;
     isInitialLoading: boolean;
     isPaused: boolean;
     isRefetching: boolean;
@@ -158,24 +131,23 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     }, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-} | {
-    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";
+    status: 'pending';
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+} | {
     dataUpdatedAt: number;
     errorUpdatedAt: number;
     failureCount: number;
@@ -194,23 +166,32 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     }, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-} | {
-    oauthJustCompleted: boolean;
-    oauthError: string | null;
-    data: undefined;
-    error: null;
+    data: {
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        error?: undefined;
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+    };
     isError: false;
-    isPending: true;
+    error: null;
+    isPending: false;
+    isLoading: false;
     isLoadingError: false;
     isRefetchError: false;
-    isSuccess: false;
-    isPlaceholderData: false;
-    status: "pending";
+    isSuccess: true;
+    isPlaceholderData: true;
+    status: 'success';
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+} | {
     dataUpdatedAt: number;
     errorUpdatedAt: number;
     failureCount: number;
@@ -219,7 +200,6 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
     isFetched: boolean;
     isFetchedAfterMount: boolean;
     isFetching: boolean;
-    isLoading: boolean;
     isInitialLoading: boolean;
     isPaused: boolean;
     isRefetching: boolean;
@@ -230,32 +210,32 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     }, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-} | {
-    oauthJustCompleted: boolean;
-    oauthError: string | null;
     data: {
         isConnected: boolean;
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     };
-    isError: false;
-    error: null;
+    error: Error;
+    isError: true;
     isPending: false;
     isLoading: false;
     isLoadingError: false;
-    isRefetchError: false;
-    isSuccess: true;
-    isPlaceholderData: true;
-    status: "success";
+    isRefetchError: true;
+    isSuccess: false;
+    isPlaceholderData: false;
+    status: 'error';
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
+} | {
     dataUpdatedAt: number;
     errorUpdatedAt: number;
     failureCount: number;
@@ -274,11 +254,31 @@ export declare function useOAuthConnectionStatus(accountId: string, options: Use
         error: string | undefined;
         obtainedAt?: undefined;
     } | {
+        error?: undefined;
         isConnected: boolean;
         obtainedAt: string | null | undefined;
-        error?: undefined;
     }, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
+    data: {
+        isConnected: boolean;
+        error: string | undefined;
+        obtainedAt?: undefined;
+    } | {
+        error?: undefined;
+        isConnected: boolean;
+        obtainedAt: string | null | undefined;
+    };
+    error: null;
+    isError: false;
+    isPending: false;
+    isLoading: false;
+    isLoadingError: false;
+    isRefetchError: false;
+    isSuccess: true;
+    isPlaceholderData: false;
+    status: 'success';
+    oauthJustCompleted: boolean;
+    oauthError: string | null;
 };
 /**
  * Resolves the gating booleans every OAuth-backed dashboard widget needs:

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

@@ -42,14 +42,18 @@ export function useOAuthConnectionStatus(accountId, options) {
         refetchOnWindowFocus: false,
     });
     const errorParamName = errorParam === null || errorParam === void 0 ? void 0 : errorParam.name;
-    // Justified useEffect: 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.
+    const returnedWithError = oauthError !== null;
+    // Justified useEffect: after the OAuth redirect lands back on this page —
+    // with `?oauth_success=true` OR with the integration's error param — we
+    // must (1) strip the transient query params from the URL, so a reload does
+    // not re-announce a stale success or re-show a stale error, and (2) on
+    // success 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. The error itself stays in state for this render, so the alert
+    // still shows once.
     useEffect(() => {
-        if (!oauthJustCompleted)
+        if (!oauthJustCompleted && !returnedWithError)
             return;
         const url = new URL(window.location.href);
         url.searchParams.delete('oauth_success');
@@ -57,11 +61,14 @@ export function useOAuthConnectionStatus(accountId, options) {
             url.searchParams.delete(errorParamName);
         }
         window.history.replaceState({}, '', url.pathname + url.search);
-        queryClient.invalidateQueries({
-            queryKey: ['integration-data', accountId, connectionKey],
-        });
+        if (oauthJustCompleted) {
+            queryClient.invalidateQueries({
+                queryKey: ['integration-data', accountId, connectionKey],
+            });
+        }
     }, [
         oauthJustCompleted,
+        returnedWithError,
         accountId,
         connectionKey,
         errorParamName,

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

@@ -1 +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: 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"]}
+{"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 server-action 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  const returnedWithError = oauthError !== null;\n\n  // Justified useEffect: after the OAuth redirect lands back on this page —\n  // with `?oauth_success=true` OR with the integration's error param — we\n  // must (1) strip the transient query params from the URL, so a reload does\n  // not re-announce a stale success or re-show a stale error, and (2) on\n  // success invalidate the cached connection status so widgets flip to\n  // connected without a manual refresh. Both are post-render side effects\n  // on external systems (history API + query cache), not derivable during\n  // render. The error itself stays in state for this render, so the alert\n  // still shows once.\n  useEffect(() => {\n    if (!oauthJustCompleted && !returnedWithError) 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    if (oauthJustCompleted) {\n      queryClient.invalidateQueries({\n        queryKey: ['integration-data', accountId, connectionKey],\n      });\n    }\n  }, [\n    oauthJustCompleted,\n    returnedWithError,\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"]}