@timardex/cluemart-shared 1.7.0 → 1.7.2

package/dist/apollo/index.d.ts

@@ -0,0 +1,323 @@
+import * as _apollo_client from '@apollo/client';
+import { ApolloLink } from '@apollo/client';
+import { Client } from 'graphql-ws';
+
+/**
+ * Optional auth-recovery telemetry for shared Apollo factories.
+ * Apps map this to Sentry breadcrumbs (mobile) or console (admin).
+ * Omitted adapter = no-op (zero behavior change).
+ */
+type AuthRecoveryEvent = {
+    type: "refresh_succeeded";
+} | {
+    type: "refresh_failed";
+    reason: string;
+    errorCode?: string;
+    retryable?: boolean;
+} | {
+    type: "stale_clear_skipped";
+    reason: string;
+} | {
+    type: "logout_scheduled";
+    reason: string;
+} | {
+    type: "reset_client";
+};
+type OnAuthRecoveryEvent = (event: AuthRecoveryEvent) => void;
+
+type ApolloManager = {
+    resetClient: () => void;
+    setResetClient: (fn: (() => void) | null) => void;
+};
+type CreateApolloManagerAdapters = {
+    /** Optional recovery telemetry when resetClient runs (default: no-op). */
+    onAuthRecoveryEvent?: OnAuthRecoveryEvent;
+};
+/**
+ * Lets logout recreate the Apollo client without importing React hooks.
+ * Apps register a reset handler (mobile: useApolloRecovery).
+ */
+declare function createApolloManager(adapters?: CreateApolloManagerAdapters): ApolloManager;
+
+type RefreshErrorCode = "UNAUTHENTICATED" | "TOKEN_EXPIRED" | "FORBIDDEN";
+type RefreshAccessTokenResult = {
+    hadRefreshToken: boolean;
+    token: string | null;
+    /**
+     * True when refresh failed due to transient issues and callers should NOT
+     * log the user out yet.
+     */
+    retryable?: boolean;
+    /** Set when refresh failed due to GraphQL errors. */
+    errorCode?: string;
+};
+type ApolloTokenStorage = {
+    getAccessToken: () => Promise<string | null>;
+    getRefreshToken: () => Promise<string | null>;
+    setTokens: (access: string, refresh: string) => Promise<void>;
+    clearTokens: () => Promise<void>;
+};
+/**
+ * Optional cross-realm refresh serialization (e.g. admin multi-tab via Web Locks).
+ * When omitted, behavior is single-realm coalescing only (mobile).
+ */
+type RefreshCoordination = {
+    withLock: <T>(fn: () => Promise<T>) => Promise<T>;
+};
+type CreateRefreshAccessTokenAdapters = {
+    apiUrl: string;
+    storage: ApolloTokenStorage;
+    /** Called after tokens are persisted (mobile: tokenManager + wsManager). */
+    onTokensUpdated?: (accessToken: string) => void;
+    /** Called after tokens are cleared (mobile: tokenManager.clear + wsManager.close). */
+    onTokensCleared?: (reason: string) => void;
+    onError?: (error: unknown, meta: {
+        action: string;
+        [key: string]: unknown;
+    }) => void;
+    /** Optional debug logging (mobile may gate with __DEV__). */
+    onDebug?: (message: string, meta?: Record<string, unknown>) => void;
+    /**
+     * Optional multi-tab / cross-context lock. Mobile should omit this.
+     * Admin may supply Web Locks (`navigator.locks`).
+     */
+    refreshCoordination?: RefreshCoordination;
+    /** Optional recovery telemetry (default: no-op). */
+    onAuthRecoveryEvent?: OnAuthRecoveryEvent;
+};
+type CreateAuthLinkAdapters = {
+    /** Wait until tokens are loaded (mobile tokenManager.awaitReady). */
+    awaitReady?: () => Promise<void>;
+    getAccessToken: () => string | null | Promise<string | null>;
+    onError?: (error: unknown, meta: {
+        action: string;
+    }) => void;
+    onDebug?: (message: string, meta?: Record<string, unknown>) => void;
+};
+type CreateErrorLinkAdapters = {
+    refreshAccessToken: () => Promise<RefreshAccessTokenResult>;
+    /** Clear in-memory access token before logout (mobile tokenManager.clear). */
+    clearAccessToken?: (reason: string) => void;
+    logout: () => Promise<void>;
+    onError?: (error: unknown, meta: {
+        action: string;
+    }) => void;
+    onDebug?: (message: string, meta?: Record<string, unknown>) => void;
+    /** Optional recovery telemetry (default: no-op). */
+    onAuthRecoveryEvent?: OnAuthRecoveryEvent;
+};
+type GraphQLErrorLike = {
+    extensions?: {
+        code?: string;
+        retryable?: unknown;
+        [key: string]: unknown;
+    };
+    locations?: ReadonlyArray<{
+        line: number;
+        column: number;
+    }>;
+    message?: string;
+    path?: ReadonlyArray<string | number>;
+};
+
+/**
+ * Auth link that attaches Bearer token after optional awaitReady.
+ * Does not overwrite an Authorization header already set on the operation.
+ */
+declare function createAuthLink(adapters: CreateAuthLinkAdapters): ApolloLink;
+
+/**
+ * Error link with mobile auth recovery: refresh once, retry op, or deferred logout.
+ */
+declare function createErrorLink(adapters: CreateErrorLinkAdapters): _apollo_client.ApolloLink;
+
+/**
+ * Creates a coalesced refreshAccessToken() using mobile multi-attempt behavior.
+ * Storage and token/WS side effects are injected via adapters.
+ *
+ * Optional `refreshCoordination` serializes refresh across realms (admin tabs).
+ * Before clearing credentials on terminal failure, skips wipe if storage already
+ * holds a newer access token (another actor recovered).
+ */
+declare function createRefreshAccessToken(adapters: CreateRefreshAccessTokenAdapters): () => Promise<RefreshAccessTokenResult>;
+
+type ApolloErrorLogLevel = "debug" | "info" | "warn" | "error";
+type CreateApolloErrorLoggingLinkAdapters = {
+    /** When true, variables/extensions are redacted but still included. */
+    isDev: boolean | (() => boolean);
+    onLog: (level: ApolloErrorLogLevel, scope: string, message: string, details?: Record<string, unknown>) => void;
+};
+/**
+ * Logging-only Apollo `onError` link with secret redaction.
+ * Does not retry or forward — place before auth recovery links.
+ */
+declare function createApolloErrorLoggingLink(adapters: CreateApolloErrorLoggingLinkAdapters): _apollo_client.ApolloLink;
+
+type CreateNetworkRecoveryLinkAdapters = {
+    forceRefreshIsOnline: () => Promise<boolean> | boolean;
+    subscribeIsOnline: (listener: (online: boolean) => void) => () => void;
+};
+/**
+ * Apollo link that pauses and retries **queries** after transient network failures.
+ * Mutations and subscriptions pass through unchanged.
+ */
+declare function createNetworkRecoveryLink(adapters: CreateNetworkRecoveryLinkAdapters): ApolloLink;
+
+type NetworkLogLevel = "debug" | "info" | "warn" | "error";
+type CreateNetworkLogAdapters = {
+    enabled: boolean | (() => boolean);
+};
+/**
+ * Structured network/auth/WS console logger (mobile format: prefix + JSON payload).
+ */
+declare function createNetworkLog(adapters: CreateNetworkLogAdapters): (level: NetworkLogLevel, scope: string, message: string, details?: Record<string, unknown>) => void;
+
+type CreateWsManagerAdapters = {
+    getWsUrl: () => string;
+    awaitReady: () => Promise<void>;
+    getAccessToken: () => string | null;
+    isActive: () => boolean;
+    /** Subscribe to inactive/active transitions; return unsubscribe. */
+    subscribeLifecycle: (handlers: {
+        onInactive: () => void;
+        onActive: () => void;
+    }) => () => void;
+    onLog?: (level: NetworkLogLevel, scope: string, message: string, details?: Record<string, unknown>) => void;
+    isDev?: boolean | (() => boolean);
+};
+type WsManager = {
+    initLifecycleListener: () => void;
+    getClient: () => Client;
+    ensureConnected: (reason: string) => void;
+    onAuthTokenChanged: (reason: string) => void;
+    close: (reason: string) => void;
+    dispose: () => void;
+};
+/**
+ * Platform-agnostic graphql-ws client manager (mobile-shaped).
+ * Apps supply lifecycle (AppState / visibility), token access, and logging.
+ */
+declare function createWsManager(adapters: CreateWsManagerAdapters): WsManager;
+
+type CreateRecoveryCoreAdapters = {
+    /** Refresh tokens / user; `true` = schedule active-query refetch. */
+    refreshSession: () => Promise<boolean>;
+    ensureWsConnected: (reason: string) => void;
+    disposeWs: () => void;
+    refetchActiveQueries: () => void;
+    /** Foreground / visible check (AppState active, document visible, …). */
+    isActive: () => boolean;
+    /**
+     * Optional online check. When omitted, treated as online (current app behavior —
+     * query pause is handled by networkRecoveryLink).
+     */
+    isOnline?: () => boolean;
+    /** Same shape as createWsManager lifecycle adapter. */
+    subscribeLifecycle: (handlers: {
+        onInactive: () => void;
+        onActive: () => void;
+    }) => () => void;
+    /** WS ensureConnected reason after a short background hop. */
+    shortBackgroundWsReason?: string;
+    /** WS ensureConnected reason after full recovery. */
+    recoverWsReason?: string;
+    now?: () => number;
+    schedule?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    cancelSchedule?: (id: ReturnType<typeof setTimeout>) => void;
+};
+type RecoveryCore = {
+    /** Subscribe to lifecycle; idempotent. */
+    start: () => void;
+    /** Unsubscribe + clear timers; does not dispose WS (hook cleanup does). */
+    stop: () => void;
+    /** Full recovery: refresh → WS → deferred refetch. */
+    recoverApollo: () => Promise<void>;
+    /**
+     * Call at the start of client reset/logout: bump generation, clear timers,
+     * drop recovering guard so in-flight recovery cannot touch the new client.
+     */
+    prepareClientReset: () => void;
+};
+/**
+ * Platform-agnostic Apollo idle recovery orchestration (mobile/admin parity).
+ *
+ * Apps supply lifecycle (AppState / visibility), session refresh, and WS/query
+ * side effects. React client ownership stays in each app's useApolloRecovery.
+ */
+declare function createRecoveryCore(adapters: CreateRecoveryCoreAdapters): RecoveryCore;
+
+/**
+ * Idle / background thresholds for Apollo recovery after the app or tab
+ * returns to the foreground.
+ *
+ * These are **independent of the server access-token TTL** (currently 15
+ * minutes on the ClueMart auth service). Recovery is driven by how long the
+ * client was backgrounded/hidden, not by JWT `exp`.
+ *
+ * Any future proactive refresh-near-expiry logic is a separate mechanism and
+ * must not reuse these constants as a stand-in for token lifetime.
+ */
+declare const MIN_BACKGROUND_MS = 30000;
+/**
+ * Delay after a successful long-background recovery before refetching active
+ * Apollo queries (gives networking a moment to stabilize, especially on iOS).
+ *
+ * Independent of the server's access-token TTL (see `MIN_BACKGROUND_MS`).
+ */
+declare const REFETCH_DELAY_MS = 500;
+
+/**
+ * Reads AC3 ErrorResponse fields via property access instead of destructuring
+ * (`graphQLErrors`, `networkError`, `response`) to avoid Apollo Client warnings.
+ */
+declare function readErrorResponseFields(errorResponse: unknown): {
+    graphQLErrors: GraphQLErrorLike[] | undefined;
+    networkError: unknown;
+    response: unknown;
+};
+
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * JSON.stringify that tolerates circular refs, Errors, bigint, and functions.
+ * Always returns a string — top-level `undefined` / `symbol` become `"null"`
+ * (native `JSON.stringify` would return `undefined`).
+ */
+declare function safeJsonStringify(value: unknown): string;
+/** Best-effort JSON-safe shape for logging network / GraphQL / WS errors. */
+declare function toStructuredError(err: unknown): Json;
+
+declare function getStatusCode(networkError: unknown): number | null;
+declare function isUnauthenticatedGraphQLError(graphQLErrors?: ReadonlyArray<GraphQLErrorLike> | null): boolean;
+/**
+ * True when GraphQL unauth signals and/or HTTP 401/403 indicate auth recovery is needed.
+ */
+declare function isUnauthenticatedError(input: {
+    graphQLErrors?: ReadonlyArray<GraphQLErrorLike> | null;
+    networkError?: unknown;
+}): boolean;
+declare const NON_RETRYABLE_REFRESH_AUTH_CODES: ReadonlySet<string>;
+declare function isRefreshAuthFailureMessage(message: string | undefined): boolean;
+declare function getRefreshErrorCode(errors: ReadonlyArray<GraphQLErrorLike>): string | undefined;
+declare function isExpectedRefreshAuthFailure(errors: ReadonlyArray<GraphQLErrorLike>, errorCode: string | undefined): boolean;
+/**
+ * Whether GraphQL `errors` from the refresh mutation warrant another HTTP attempt.
+ */
+declare function refreshGraphqlErrorsWarrantRetry(errors: ReadonlyArray<GraphQLErrorLike>): boolean;
+type RefreshDecision = {
+    kind: "complete";
+} | {
+    kind: "logout";
+} | {
+    kind: "retry";
+    token: string;
+};
+/** Maps refresh outcome to error-link next step (mobile behavior). */
+declare function decideRefreshNextStep(result: {
+    hadRefreshToken?: boolean;
+    token: string | null;
+    retryable?: boolean;
+}): RefreshDecision;
+
+export { type ApolloErrorLogLevel, type ApolloManager, type ApolloTokenStorage, type AuthRecoveryEvent, type CreateApolloErrorLoggingLinkAdapters, type CreateApolloManagerAdapters, type CreateAuthLinkAdapters, type CreateErrorLinkAdapters, type CreateNetworkLogAdapters, type CreateNetworkRecoveryLinkAdapters, type CreateRecoveryCoreAdapters, type CreateRefreshAccessTokenAdapters, type CreateWsManagerAdapters, type GraphQLErrorLike, MIN_BACKGROUND_MS, NON_RETRYABLE_REFRESH_AUTH_CODES, type NetworkLogLevel, type OnAuthRecoveryEvent, REFETCH_DELAY_MS, type RecoveryCore, type RefreshAccessTokenResult, type RefreshCoordination, type RefreshDecision, type RefreshErrorCode, type WsManager, createApolloErrorLoggingLink, createApolloManager, createAuthLink, createErrorLink, createNetworkLog, createNetworkRecoveryLink, createRecoveryCore, createRefreshAccessToken, createWsManager, decideRefreshNextStep, getRefreshErrorCode, getStatusCode, isExpectedRefreshAuthFailure, isRefreshAuthFailureMessage, isUnauthenticatedError, isUnauthenticatedGraphQLError, readErrorResponseFields, refreshGraphqlErrorsWarrantRetry, safeJsonStringify, toStructuredError };