@mosano-product-framework/sdk 0.2.0

package/dist/client/index.js

@@ -0,0 +1,227 @@
+import { MPFGraphQLClient, isSubscription } from '../chunk-GQJ3QQPH.js';
+export { MPFGraphQLClient, buildUrl, createLoggingMiddleware, getOperationKind, isSubscription, joinPath } from '../chunk-GQJ3QQPH.js';
+export { AdminEmptySecretError, AdminEmptyUserIDError, createAdminAuthMiddleware, createTurnstileMiddleware, issueAdminToken } from '../chunk-K2ELAI2X.js';
+import { attachStandardMiddlewares } from '../chunk-LRM6JJ63.js';
+export { MAX_REQUEST_ATTEMPTS, MPFClient, TENANT_HEADER, TENANT_ROLE_HEADER, attachStandardMiddlewares, clearRetryFlag, createAuthMiddleware, createHttpClient, createRetryMiddleware, createTenantMiddleware, disableRetry, executeErrorMiddlewares, executeRequestMiddlewares, executeResponseMiddlewares, getRetryAttempt, isReplayableBody, isRetryDisabled, requestRetry, shouldRetryRequest } from '../chunk-LRM6JJ63.js';
+import { MPFAPIError } from '../chunk-AJWM5MDZ.js';
+export { MPFAPIError, MPFAuthError, MPFError, MPFNetworkError, MPFTimeoutError, MPFValidationError, isMPFAPIError, isMPFAuthError, isMPFError, isMPFNetworkError, isMPFValidationError } from '../chunk-AJWM5MDZ.js';
+
+// src/client/graphql/ws-client.ts
+async function loadCreateClient() {
+  try {
+    const mod = await import('graphql-ws');
+    return mod.createClient;
+  } catch (error) {
+    throw new Error(
+      "[MPF SDK] GraphQL 'websocket'/'hybrid' mode requires the optional 'graphql-ws' and 'graphql' packages. Install them: pnpm add graphql-ws graphql",
+      { cause: error instanceof Error ? error : void 0 }
+    );
+  }
+}
+function createGraphQLWsTransport(options) {
+  const {
+    url,
+    tokenProvider,
+    tenantProvider,
+    webSocketImpl,
+    retryAttempts = 5,
+    lazy = true,
+    createClient: injectedCreateClient
+  } = options;
+  let clientPromise = null;
+  async function buildClient() {
+    const createClient = injectedCreateClient ?? await loadCreateClient();
+    return createClient({
+      url,
+      lazy,
+      retryAttempts,
+      ...webSocketImpl ? { webSocketImpl } : {},
+      connectionParams: async () => {
+        const token = tokenProvider ? await tokenProvider.getAccessToken() : null;
+        const selection = tenantProvider?.get();
+        return {
+          headers: {
+            ...token ? { Authorization: `Bearer ${token}` } : {},
+            ...selection?.tenant ? { "X-MPF-Tenant": selection.tenant } : {},
+            ...selection?.role ? { "X-MPF-Tenant-Role": selection.role } : {}
+          }
+        };
+      }
+    });
+  }
+  function getClient() {
+    if (!clientPromise) {
+      clientPromise = buildClient();
+    }
+    return clientPromise;
+  }
+  return {
+    subscribe(document, variables, sink) {
+      let unsubscribed = false;
+      let disposer;
+      getClient().then(
+        (client) => {
+          if (unsubscribed) {
+            return;
+          }
+          disposer = client.subscribe(
+            {
+              query: typeof document === "string" ? document : document.toString(),
+              variables
+            },
+            {
+              next: (msg) => {
+                sink.next({
+                  data: msg.data ?? void 0,
+                  errors: msg.errors
+                });
+              },
+              error: (err) => sink.error(err),
+              complete: () => sink.complete()
+            }
+          );
+        },
+        (err) => sink.error(err)
+      );
+      return () => {
+        unsubscribed = true;
+        disposer?.();
+      };
+    },
+    reconnect() {
+      if (!clientPromise) {
+        return;
+      }
+      void clientPromise.then((client) => client.terminate());
+    },
+    dispose() {
+      const promise = clientPromise;
+      clientPromise = null;
+      void promise?.then((client) => client.dispose());
+    }
+  };
+}
+
+// src/client/graphql/factory.ts
+function deriveWsUrl(baseUrl, endpoint) {
+  const httpUrl = new URL(`${baseUrl.replace(/\/+$/, "")}${endpoint}`);
+  httpUrl.protocol = httpUrl.protocol === "https:" ? "wss:" : "ws:";
+  return httpUrl.toString();
+}
+function createGraphQLClient(options) {
+  const {
+    tokenProvider,
+    tenantProvider,
+    endpoint = "/graphql",
+    mode = "hybrid",
+    wsUrl,
+    webSocketImpl,
+    wsRetryAttempts,
+    wsCreateClient,
+    ...clientConfig
+  } = options;
+  const httpConfig = { ...clientConfig, endpoint };
+  const httpClient = new MPFGraphQLClient(httpConfig);
+  attachStandardMiddlewares(httpClient, { tokenProvider, tenantProvider });
+  let wsTransport = null;
+  function getWsTransport() {
+    if (mode === "individual-requests") {
+      throw new Error(
+        "[MPF SDK] subscribe() requires mode: 'websocket' or 'hybrid' \u2014 this client was created with mode: 'individual-requests', which has no transport for subscriptions."
+      );
+    }
+    if (!wsTransport) {
+      wsTransport = createGraphQLWsTransport({
+        url: wsUrl ?? deriveWsUrl(clientConfig.baseUrl, endpoint),
+        tokenProvider,
+        tenantProvider,
+        webSocketImpl,
+        ...wsRetryAttempts !== void 0 ? { retryAttempts: wsRetryAttempts } : {},
+        ...wsCreateClient ? { createClient: wsCreateClient } : {},
+        // 'hybrid' must not open a socket until subscribe() is called; the
+        // transport's own laziness gives us that for free either way.
+        lazy: true
+      });
+    }
+    return wsTransport;
+  }
+  function executeOverWs(document, variables) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let unsubscribe = () => {
+      };
+      unsubscribe = getWsTransport().subscribe(document, variables, {
+        next: (result) => {
+          if (settled) return;
+          settled = true;
+          unsubscribe();
+          if (result.errors && result.errors.length > 0) {
+            const first = result.errors[0];
+            reject(
+              new MPFAPIError(
+                first.message,
+                first.extensions?.code ?? "GRAPHQL_ERROR",
+                200,
+                result.errors
+              )
+            );
+            return;
+          }
+          if (result.data === void 0 || result.data === null) {
+            reject(new MPFAPIError("No data returned from GraphQL operation", "NO_DATA", 200));
+            return;
+          }
+          resolve(result.data);
+        },
+        error: (err) => {
+          if (settled) return;
+          settled = true;
+          reject(err);
+        },
+        complete: () => {
+          if (settled) return;
+          settled = true;
+          reject(new MPFAPIError("Operation completed with no result", "NO_DATA", 200));
+        }
+      });
+    });
+  }
+  return {
+    async query(document, variables, requestOptions) {
+      if (mode === "websocket") {
+        return executeOverWs(document, variables);
+      }
+      return httpClient.query(document, variables, requestOptions);
+    },
+    async mutate(document, variables, requestOptions) {
+      if (mode === "websocket") {
+        return executeOverWs(document, variables);
+      }
+      return httpClient.mutate(document, variables, requestOptions);
+    },
+    subscribe(document, variables, handlers) {
+      const query = typeof document === "string" ? document : document.toString();
+      if (!isSubscription(query)) {
+        throw new Error(
+          "[MPF SDK] subscribe() was called with a document whose operation is not a 'subscription'. Use query()/mutate() for those."
+        );
+      }
+      return getWsTransport().subscribe(document, variables, {
+        next: handlers.onData,
+        error: (err) => handlers.onError?.(err),
+        complete: () => handlers.onComplete?.()
+      });
+    },
+    reconnectWebSocket() {
+      wsTransport?.reconnect();
+    },
+    dispose() {
+      wsTransport?.dispose();
+      wsTransport = null;
+    }
+  };
+}
+
+export { createGraphQLClient, createGraphQLWsTransport };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/graphql/ws-client.ts","../../src/client/graphql/factory.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * `graphql-ws` transport, wired to the SAME `tokenProvider`/`tenantProvider`\n * every REST and HTTP-GraphQL client uses.\n *\n * This is meant to be a project-wide standard, not a go-hasura special case:\n * any microservice exposing `graphql-ws` subscriptions (Hasura's, or a Go\n * service's own) authenticates the same way every other MPF client does —\n * `connectionParams` carries the identical `Authorization: Bearer <jwt>` (plus\n * `X-MPF-Tenant`/`X-MPF-Tenant-Role` when a tenant is selected) that the HTTP\n * middlewares put on REST/GraphQL-over-HTTP requests. A service just needs to\n * read those three keys off the `connection_init` payload at its own webhook\n * auth boundary — no new token format.\n *\n * They are carried under a `headers` key of the `connection_init` payload —\n * `{ headers: { Authorization, 'X-MPF-Tenant', ... } }` — NOT flat at the top\n * level. That is what Hasura reads: over the websocket path it takes\n * `payload.headers` and replays those as the request headers it hands to the\n * auth webhook (hasura-authd). Flat top-level keys are silently ignored, so\n * the socket connects and every subscription then fails as unauthenticated —\n * verified end-to-end against a live stack in\n * `e2e/tests/go-identity/graphql-subscriptions.e2e.test.ts`. It is also the\n * shape the wider `graphql-ws` ecosystem uses for header-style auth, so a Go\n * service reading `payload.headers` stays consistent with both.\n */\n\nimport type { TokenProvider } from '../core/types.js';\nimport type { TenantSelectionStore } from '../../auth/tenant-selection.js';\nimport type { GraphQLError, GraphQLResponse } from './types.js';\n\n/**\n * The subset of a `graphql-ws` `Client` this module uses. Kept as our own\n * interface (not `import type { Client } from 'graphql-ws'`) so this file\n * never has a hard, non-dynamic dependency on the `graphql-ws` types either —\n * matches `cross-tab.ts`'s `LockManagerLike`/`BroadcastChannelLike` pattern.\n */\nexport interface GraphQLWsClientLike {\n  subscribe<TData = unknown>(\n    payload: { query: string; variables?: Record<string, unknown> },\n    sink: {\n      next: (value: { data?: TData | null; errors?: readonly unknown[] }) => void;\n      error: (err: unknown) => void;\n      complete: () => void;\n    },\n  ): () => void;\n  terminate(): void;\n  dispose(): void | Promise<void>;\n}\n\n/** Options `createGraphQLWsTransport` forwards to `graphql-ws`'s `createClient`. */\nexport interface GraphQLWsCreateClientParams {\n  url: string;\n  lazy: boolean;\n  retryAttempts: number;\n  webSocketImpl?: unknown;\n  /**\n   * Resolved per connection attempt. Shape is `{ headers: { ... } }` — see\n   * the module doc for why the auth headers are nested rather than flat.\n   */\n  connectionParams: () => Promise<{ headers: Record<string, string> }>;\n}\n\nexport interface GraphQLWsClientOptions {\n  /** `ws://` or `wss://` endpoint. */\n  url: string;\n  /** Same token provider passed to the HTTP transport — see module docs. */\n  tokenProvider?: TokenProvider;\n  /** Same tenant provider passed to the HTTP transport. */\n  tenantProvider?: TenantSelectionStore;\n  /**\n   * `WebSocket` implementation for non-browser environments (Node has no\n   * global `WebSocket` before v22). Pass the `ws` package's export there.\n   */\n  webSocketImpl?: unknown;\n  /** Reconnect attempts before giving up on a dropped socket. @default 5 */\n  retryAttempts?: number;\n  /**\n   * Open the socket only when the first subscription starts, close it when\n   * the last one ends. @default true — matches `hybrid` mode's \"no socket\n   * until a subscription shows up\" contract.\n   */\n  lazy?: boolean;\n  /**\n   * Injectable `graphql-ws` `createClient`. Defaults to a dynamic\n   * `import('graphql-ws')`. Tests supply a fake here to exercise the full\n   * subscribe/reconnect/dispose contract without a real socket or the\n   * `graphql-ws` package — same reason `cross-tab.ts` takes an injectable\n   * `locks`/`channelFactory`.\n   */\n  createClient?: (params: GraphQLWsCreateClientParams) => GraphQLWsClientLike;\n}\n\nexport interface GraphQLSubscriptionSink<TData> {\n  next: (result: GraphQLResponse<TData>) => void;\n  error: (error: unknown) => void;\n  complete: () => void;\n}\n\nexport interface GraphQLWsTransport {\n  /** Subscribe; returns an unsubscribe function. */\n  subscribe<TData = unknown, TVariables = Record<string, unknown>>(\n    document: { toString(): string } | string,\n    variables: TVariables | undefined,\n    sink: GraphQLSubscriptionSink<TData>,\n  ): () => void;\n  /**\n   * Force the current socket closed. `graphql-ws`'s own retry logic reopens\n   * it with a FRESH `connectionParams` call (so a rotated token is picked up)\n   * and resubscribes every still-registered operation automatically.\n   *\n   * Call this right after a `SessionManager` renewal — see\n   * `createGraphQLClient`'s `mode: 'websocket' | 'hybrid'` wiring — so a live\n   * subscription is never carried on a token past its renewal point.\n   */\n  reconnect(): void;\n  /** Close the socket and release it for good. Registered subscriptions end. */\n  dispose(): void;\n}\n\n/**\n * Lazily import `graphql-ws`. Kept dynamic so an app that never opens a\n * subscription never pays for the dependency: `graphql-ws` (and its `graphql`\n * peer) are optional peers of this package, the same way `react` is.\n */\nasync function loadCreateClient(): Promise<\n  (params: GraphQLWsCreateClientParams) => GraphQLWsClientLike\n> {\n  try {\n    const mod = await import('graphql-ws');\n    return mod.createClient as unknown as (\n      params: GraphQLWsCreateClientParams,\n    ) => GraphQLWsClientLike;\n  } catch (error) {\n    throw new Error(\n      \"[MPF SDK] GraphQL 'websocket'/'hybrid' mode requires the optional \" +\n        \"'graphql-ws' and 'graphql' packages. Install them: pnpm add graphql-ws graphql\",\n      { cause: error instanceof Error ? error : undefined },\n    );\n  }\n}\n\n/** Create a `graphql-ws`-backed subscription transport. */\nexport function createGraphQLWsTransport(options: GraphQLWsClientOptions): GraphQLWsTransport {\n  const {\n    url,\n    tokenProvider,\n    tenantProvider,\n    webSocketImpl,\n    retryAttempts = 5,\n    lazy = true,\n    createClient: injectedCreateClient,\n  } = options;\n\n  let clientPromise: Promise<GraphQLWsClientLike> | null = null;\n\n  async function buildClient(): Promise<GraphQLWsClientLike> {\n    const createClient = injectedCreateClient ?? (await loadCreateClient());\n    return createClient({\n      url,\n      lazy,\n      retryAttempts,\n      ...(webSocketImpl ? { webSocketImpl } : {}),\n      connectionParams: async () => {\n        const token = tokenProvider ? await tokenProvider.getAccessToken() : null;\n        const selection = tenantProvider?.get();\n        return {\n          headers: {\n            ...(token ? { Authorization: `Bearer ${token}` } : {}),\n            ...(selection?.tenant ? { 'X-MPF-Tenant': selection.tenant } : {}),\n            ...(selection?.role ? { 'X-MPF-Tenant-Role': selection.role } : {}),\n          },\n        };\n      },\n    });\n  }\n\n  function getClient(): Promise<GraphQLWsClientLike> {\n    if (!clientPromise) {\n      clientPromise = buildClient();\n    }\n    return clientPromise;\n  }\n\n  return {\n    subscribe<TData, TVariables>(\n      document: { toString(): string } | string,\n      variables: TVariables | undefined,\n      sink: GraphQLSubscriptionSink<TData>,\n    ) {\n      let unsubscribed = false;\n      let disposer: (() => void) | undefined;\n\n      getClient().then(\n        (client) => {\n          if (unsubscribed) {\n            return;\n          }\n          disposer = client.subscribe<TData>(\n            {\n              query: typeof document === 'string' ? document : document.toString(),\n              variables: variables as Record<string, unknown> | undefined,\n            },\n            {\n              next: (msg) => {\n                sink.next({\n                  data: msg.data ?? undefined,\n                  errors: msg.errors as GraphQLError[] | undefined,\n                });\n              },\n              error: (err) => sink.error(err),\n              complete: () => sink.complete(),\n            },\n          );\n        },\n        (err: unknown) => sink.error(err),\n      );\n\n      return () => {\n        unsubscribed = true;\n        disposer?.();\n      };\n    },\n\n    reconnect() {\n      // No-op if no socket has ever been opened: there is nothing to force\n      // closed, and building one just to immediately terminate it would be\n      // wasteful (and, for 'hybrid' mode, would defeat the \"no socket until a\n      // subscription shows up\" contract).\n      if (!clientPromise) {\n        return;\n      }\n      void clientPromise.then((client) => client.terminate());\n    },\n\n    dispose() {\n      const promise = clientPromise;\n      clientPromise = null;\n      void promise?.then((client) => client.dispose());\n    },\n  };\n}\n","/**\n * `createGraphQLClient` — the GraphQL counterpart to `createAuthClient` /\n * `createStorageClient`, built on the same `attachStandardMiddlewares`\n * wiring (see `core/client-factory.ts`) so it shares one `tokenProvider` /\n * `tenantProvider` with every other client an app constructs.\n *\n * Adds one more axis specific to GraphQL: `mode`, which decides HTTP vs\n * `graphql-ws` per operation. This is a deliberately small stand-in for an\n * Apollo-Link-style split link — enough to route by operation kind, not a\n * general link-chaining system. If usage grows past \"route by operation\n * kind\" (retry links, batching links, etc.) that is the point to reach for\n * an actual link abstraction; this does not try to anticipate that.\n */\n\nimport { attachStandardMiddlewares, type HttpClientOptions } from '../core/client-factory.js';\nimport { MPFAPIError } from '../core/errors.js';\nimport { MPFGraphQLClient, type GraphQLClientConfig } from './client.js';\nimport {\n  createGraphQLWsTransport,\n  type GraphQLWsTransport,\n  type GraphQLWsCreateClientParams,\n  type GraphQLWsClientLike,\n} from './ws-client.js';\nimport { isSubscription } from './operation.js';\nimport type {\n  TypedDocumentNode,\n  GraphQLRequestOptions,\n  GraphQLResponse,\n  GraphQLError,\n} from './types.js';\n\n/**\n * How a `createGraphQLClient` routes operations.\n *\n * - `'individual-requests'` — every operation (query/mutation) goes over\n *   plain HTTP POST. No socket is ever opened; `subscribe()` throws.\n * - `'websocket'` — every operation, including query/mutation, goes over one\n *   `graphql-ws` connection.\n * - `'hybrid'` (default) — starts in `'individual-requests'` behavior.\n *   Query/mutation always stay on HTTP (cheaper: no connection to keep\n *   alive for the common case). The FIRST `subscribe()` call lazily opens\n *   the `graphql-ws` connection; every subscription after that reuses it.\n */\nexport type GraphQLConnectionMode = 'individual-requests' | 'websocket' | 'hybrid';\n\nexport interface GraphQLClientOptions extends HttpClientOptions {\n  /** GraphQL HTTP endpoint path. @default '/graphql' */\n  endpoint?: string;\n  /** @default 'hybrid' */\n  mode?: GraphQLConnectionMode;\n  /**\n   * `ws://`/`wss://` endpoint for the `graphql-ws` transport. Defaults to\n   * `baseUrl` with `http(s)` swapped for `ws(s)` and `endpoint` appended —\n   * correct for Hasura, which serves GraphQL-over-HTTP and `graphql-ws` on\n   * the same path. Override for a service that splits them.\n   */\n  wsUrl?: string;\n  /** `WebSocket` implementation for non-browser runtimes (e.g. the `ws` package in Node). */\n  webSocketImpl?: unknown;\n  /** `graphql-ws` reconnect attempts. @default 5 */\n  wsRetryAttempts?: number;\n  /**\n   * Injectable `graphql-ws` `createClient`, forwarded to\n   * {@link createGraphQLWsTransport}. Lets tests exercise `'websocket'`/\n   * `'hybrid'` routing with a fake socket instead of a real one — see\n   * `ws-client.ts`'s `GraphQLWsClientOptions.createClient` doc.\n   */\n  wsCreateClient?: (params: GraphQLWsCreateClientParams) => GraphQLWsClientLike;\n}\n\nexport interface GraphQLSubscriptionHandlers<TData> {\n  onData: (result: GraphQLResponse<TData>) => void;\n  onError?: (error: unknown) => void;\n  onComplete?: () => void;\n}\n\nexport interface MPFGraphQLHybridClient {\n  query<TData, TVariables = Record<string, unknown>>(\n    document: TypedDocumentNode<TData, TVariables> | string,\n    variables?: TVariables,\n    options?: GraphQLRequestOptions,\n  ): Promise<TData>;\n  mutate<TData, TVariables = Record<string, unknown>>(\n    document: TypedDocumentNode<TData, TVariables> | string,\n    variables?: TVariables,\n    options?: GraphQLRequestOptions,\n  ): Promise<TData>;\n  /**\n   * Subscribe to a `subscription` document. Throws synchronously in\n   * `'individual-requests'` mode — that mode has no transport for it.\n   *\n   * @returns An unsubscribe function.\n   */\n  subscribe<TData, TVariables = Record<string, unknown>>(\n    document: TypedDocumentNode<TData, TVariables> | string,\n    variables: TVariables | undefined,\n    handlers: GraphQLSubscriptionHandlers<TData>,\n  ): () => void;\n  /**\n   * Force the `graphql-ws` socket closed; it reopens with a fresh token and\n   * resubscribes every live subscription. Wire this to fire on every token\n   * renewal — e.g. from `SessionManagerOptions.onTokensChanged` — so a\n   * subscription never outlives the token it was opened with. A no-op if no\n   * socket has been opened yet (nothing to reconnect).\n   */\n  reconnectWebSocket(): void;\n  /** Release the HTTP client's resources (none currently) and close any open socket. */\n  dispose(): void;\n}\n\nfunction deriveWsUrl(baseUrl: string, endpoint: string): string {\n  const httpUrl = new URL(`${baseUrl.replace(/\\/+$/, '')}${endpoint}`);\n  httpUrl.protocol = httpUrl.protocol === 'https:' ? 'wss:' : 'ws:';\n  return httpUrl.toString();\n}\n\n/**\n * Create a GraphQL client with the standard auth/tenant middlewares wired in\n * and a `mode`-selected HTTP/`graphql-ws` transport.\n */\nexport function createGraphQLClient(options: GraphQLClientOptions): MPFGraphQLHybridClient {\n  const {\n    tokenProvider,\n    tenantProvider,\n    endpoint = '/graphql',\n    mode = 'hybrid',\n    wsUrl,\n    webSocketImpl,\n    wsRetryAttempts,\n    wsCreateClient,\n    ...clientConfig\n  } = options;\n\n  const httpConfig: GraphQLClientConfig = { ...clientConfig, endpoint };\n  const httpClient = new MPFGraphQLClient(httpConfig);\n  attachStandardMiddlewares(httpClient, { tokenProvider, tenantProvider });\n\n  let wsTransport: GraphQLWsTransport | null = null;\n\n  function getWsTransport(): GraphQLWsTransport {\n    if (mode === 'individual-requests') {\n      throw new Error(\n        \"[MPF SDK] subscribe() requires mode: 'websocket' or 'hybrid' — this client was \" +\n          \"created with mode: 'individual-requests', which has no transport for subscriptions.\",\n      );\n    }\n    if (!wsTransport) {\n      wsTransport = createGraphQLWsTransport({\n        url: wsUrl ?? deriveWsUrl(clientConfig.baseUrl, endpoint),\n        tokenProvider,\n        tenantProvider,\n        webSocketImpl,\n        ...(wsRetryAttempts !== undefined ? { retryAttempts: wsRetryAttempts } : {}),\n        ...(wsCreateClient ? { createClient: wsCreateClient } : {}),\n        // 'hybrid' must not open a socket until subscribe() is called; the\n        // transport's own laziness gives us that for free either way.\n        lazy: true,\n      });\n    }\n    return wsTransport;\n  }\n\n  function executeOverWs<TData, TVariables>(\n    document: TypedDocumentNode<TData, TVariables> | string,\n    variables: TVariables | undefined,\n  ): Promise<TData> {\n    return new Promise<TData>((resolve, reject) => {\n      let settled = false;\n      let unsubscribe: () => void = () => {};\n      unsubscribe = getWsTransport().subscribe<TData, TVariables>(document, variables, {\n        next: (result) => {\n          if (settled) return;\n          settled = true;\n          unsubscribe();\n          if (result.errors && result.errors.length > 0) {\n            const first: GraphQLError = result.errors[0];\n            reject(\n              new MPFAPIError(\n                first.message,\n                (first.extensions?.code as string | undefined) ?? 'GRAPHQL_ERROR',\n                200,\n                result.errors,\n              ),\n            );\n            return;\n          }\n          if (result.data === undefined || result.data === null) {\n            reject(new MPFAPIError('No data returned from GraphQL operation', 'NO_DATA', 200));\n            return;\n          }\n          resolve(result.data);\n        },\n        error: (err) => {\n          if (settled) return;\n          settled = true;\n          reject(err);\n        },\n        complete: () => {\n          if (settled) return;\n          settled = true;\n          reject(new MPFAPIError('Operation completed with no result', 'NO_DATA', 200));\n        },\n      });\n    });\n  }\n\n  return {\n    async query(document, variables, requestOptions) {\n      if (mode === 'websocket') {\n        return executeOverWs(document, variables);\n      }\n      return httpClient.query(document, variables, requestOptions);\n    },\n\n    async mutate(document, variables, requestOptions) {\n      if (mode === 'websocket') {\n        return executeOverWs(document, variables);\n      }\n      return httpClient.mutate(document, variables, requestOptions);\n    },\n\n    subscribe(document, variables, handlers) {\n      const query = typeof document === 'string' ? document : document.toString();\n      if (!isSubscription(query)) {\n        throw new Error(\n          '[MPF SDK] subscribe() was called with a document whose operation is not a ' +\n            \"'subscription'. Use query()/mutate() for those.\",\n        );\n      }\n      return getWsTransport().subscribe(document, variables, {\n        next: handlers.onData,\n        error: (err) => handlers.onError?.(err),\n        complete: () => handlers.onComplete?.(),\n      });\n    },\n\n    reconnectWebSocket() {\n      wsTransport?.reconnect();\n    },\n\n    dispose() {\n      wsTransport?.dispose();\n      wsTransport = null;\n    },\n  };\n}\n"]}

package/dist/client/middlewares/admin-auth.d.ts

@@ -0,0 +1,90 @@
+import type { Middleware } from '../core/middleware.js';
+/**
+ * Impersonation payload embedded in an admin token.
+ *
+ * Mirrors the Go `ActOnBehalfOf` struct
+ * (`internal/go-chi-middleware-auth/types.go`), which the Go verifier reads
+ * from the `act_on_behalf_of` JWT claim.
+ */
+export interface AdminActOnBehalfOf {
+    /** The subject (user) the admin token acts on behalf of. Required. */
+    userId: string;
+    /** Optionally scopes the impersonation to a tenant. */
+    onTenantId?: string;
+}
+/** Error thrown when an admin token is minted without a signing secret. */
+export declare class AdminEmptySecretError extends Error {
+    constructor();
+}
+/** Error thrown when an admin token is minted without a subject user id. */
+export declare class AdminEmptyUserIDError extends Error {
+    constructor();
+}
+/**
+ * Mints an HS256-signed Admin JWT that impersonates `actOnBehalfOf`.
+ *
+ * The minted token interoperates byte-for-byte with the Go verifier in
+ * `internal/go-chi-middleware-auth/auth.go` (`parseAdmin`):
+ *   - Protected header `{ alg: 'HS256' }`.
+ *   - Required `exp` claim (`now + ttlSeconds`), which the Go side enforces via
+ *     `jwt.WithExpirationRequired()`.
+ *   - An `iat` claim of `now`.
+ *   - An `act_on_behalf_of` object claim with `user_id` (required) and an
+ *     optional `on_tenant_id`, matching the Go `ActOnBehalfOf` JSON tags.
+ *
+ * SECURITY: Minting an admin token requires the shared `ADMIN_JWT_SECRET`.
+ * This secret grants the ability to impersonate ANY user, so it MUST ONLY be
+ * used server-side or by trusted backend services. NEVER ship the secret to a
+ * browser or any untrusted client, and never embed it in frontend bundles.
+ *
+ * @param secret - The shared HS256 signing secret (`ADMIN_JWT_SECRET`).
+ * @param actOnBehalfOf - The principal to impersonate.
+ * @param ttlSeconds - Token lifetime in seconds (added to the current time).
+ * @returns The signed compact JWT string.
+ * @throws {AdminEmptySecretError} when `secret` is empty.
+ * @throws {AdminEmptyUserIDError} when `actOnBehalfOf.userId` is empty.
+ */
+export declare function issueAdminToken(secret: string, actOnBehalfOf: AdminActOnBehalfOf, ttlSeconds: number): Promise<string>;
+/**
+ * Options for the admin auth middleware.
+ *
+ * Exactly one of `token` (pre-minted) or `config` (mint-per-request) must be
+ * provided.
+ */
+export type AdminAuthMiddlewareOptions = {
+    /** A pre-minted admin JWT to attach as `Authorization: Admin <token>`. */
+    token: string;
+    config?: never;
+} | {
+    token?: never;
+    /**
+     * Per-request minting config (analogous to Go's `AdminRoundTripper`):
+     * a fresh admin token is minted for every request.
+     */
+    config: {
+        /** The shared HS256 signing secret (`ADMIN_JWT_SECRET`). */
+        secret: string;
+        /** The principal to impersonate. */
+        actOnBehalfOf: AdminActOnBehalfOf;
+        /** Token lifetime in seconds. */
+        ttlSeconds: number;
+    };
+};
+/**
+ * Creates an admin authentication middleware that stamps an
+ * `Authorization: Admin <token>` header on outgoing requests.
+ *
+ * Reuses {@link createAuthMiddleware} with `tokenType: 'Admin'`. Two ergonomics
+ * are supported:
+ *   - `{ token }`: attach a pre-minted admin token.
+ *   - `{ config }`: mint a fresh admin token per request (like Go's
+ *     `AdminRoundTripper`).
+ *
+ * SECURITY: When using `config`, the `ADMIN_JWT_SECRET` is held in memory and
+ * used to mint tokens. Only construct this middleware server-side / in trusted
+ * services. NEVER ship the secret to a browser.
+ *
+ * @param options - Either a pre-minted `token` or a minting `config`.
+ * @returns A middleware instance.
+ */
+export declare function createAdminAuthMiddleware(options: AdminAuthMiddlewareOptions): Middleware;

package/dist/client/middlewares/auth.d.ts

@@ -0,0 +1,81 @@
+import type { Middleware } from '../core/middleware.js';
+/**
+ * Options for the auth middleware.
+ */
+export interface AuthMiddlewareOptions {
+    /**
+     * Function to get the current access token.
+     * Can be sync or async (e.g., reading from localStorage or refreshing token).
+     *
+     * @returns The access token, or null if not authenticated
+     */
+    getAccessToken: () => string | null | Promise<string | null>;
+    /**
+     * Called when a 401 is final — i.e. a token WAS attached and renewal either
+     * was not possible, failed, or had already been tried for this request.
+     *
+     * This is the "log the user out" hook. It is deliberately NOT called for a
+     * 401 on a request that carried no token (a wrong password must not log you
+     * out of a session you do have), nor for the first 401 when `onUnauthorized`
+     * successfully renews.
+     */
+    onTokenExpired?: () => void | Promise<void>;
+    /**
+     * Called on the first 401 of a request that DID carry a token.
+     *
+     * Should attempt a session renewal and resolve `true` when a fresh token is
+     * now available, `false` otherwise. On `true` the request is retried once,
+     * with headers rebuilt so the new token is picked up.
+     *
+     * Capped at one call per logical request by `__authRenewAttempted`, so a
+     * second 401 falls through to `onTokenExpired` instead of looping.
+     */
+    onUnauthorized?: () => Promise<boolean>;
+    /**
+     * The token type prefix for the Authorization header.
+     * @default 'Bearer'
+     */
+    tokenType?: string;
+    /**
+     * Custom header name for the authorization token.
+     * @default 'Authorization'
+     */
+    headerName?: string;
+}
+/**
+ * Creates an authentication middleware that adds authorization headers to requests.
+ *
+ * The middleware:
+ * - Adds an Authorization header with the token from getAccessToken()
+ * - Calls onTokenExpired() when a 401 response is received
+ *
+ * @param options - Configuration options for the auth middleware
+ * @returns A middleware instance
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware = createAuthMiddleware({
+ *   getAccessToken: () => localStorage.getItem('accessToken'),
+ *   onTokenExpired: () => {
+ *     // Redirect to login or refresh token
+ *     window.location.href = '/login';
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With async token retrieval
+ * const authMiddleware = createAuthMiddleware({
+ *   getAccessToken: async () => {
+ *     const session = await authService.getSession();
+ *     return session?.accessToken ?? null;
+ *   },
+ *   tokenType: 'Bearer',
+ *   onTokenExpired: async () => {
+ *     await authService.refreshToken();
+ *   }
+ * });
+ * ```
+ */
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): Middleware;

package/dist/client/middlewares/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in middlewares for the MPF SDK.
+ *
+ * @packageDocumentation
+ */
+export { createAuthMiddleware, type AuthMiddlewareOptions } from './auth.js';
+export { createAdminAuthMiddleware, issueAdminToken, AdminEmptySecretError, AdminEmptyUserIDError, type AdminActOnBehalfOf, type AdminAuthMiddlewareOptions, } from './admin-auth.js';
+export { createRetryMiddleware, shouldRetryRequest, getRetryAttempt, clearRetryFlag, disableRetry, isRetryDisabled, isReplayableBody, type RetryMiddlewareOptions, } from './retry.js';
+export { createLoggingMiddleware, type LoggingMiddlewareOptions, type Logger, } from './logging.js';
+export { requestRetry } from './retry.js';
+export { createTurnstileMiddleware, type TurnstileMiddlewareOptions } from './turnstile.js';
+export { createTenantMiddleware, TENANT_HEADER, TENANT_ROLE_HEADER, type TenantMiddlewareOptions, } from './tenant.js';

package/dist/client/middlewares/logging.d.ts

@@ -0,0 +1,102 @@
+import type { Middleware } from '../core/middleware.js';
+import type { RequestContext, ResponseContext } from '../core/types.js';
+/**
+ * Logger interface compatible with console and custom loggers.
+ */
+export interface Logger {
+    log: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/**
+ * Options for the logging middleware.
+ */
+export interface LoggingMiddlewareOptions {
+    /**
+     * Logger instance to use for output.
+     * Defaults to console.
+     */
+    logger?: Logger;
+    /**
+     * Whether to log request/response bodies.
+     * Default is false for security (bodies may contain sensitive data).
+     * @default false
+     */
+    logBody?: boolean;
+    /**
+     * Prefix for all log messages.
+     * @default '[MPF SDK]'
+     */
+    prefix?: string;
+    /**
+     * Whether to log request headers.
+     * Sensitive headers like Authorization are always redacted.
+     * @default false
+     */
+    logHeaders?: boolean;
+    /**
+     * List of header names to redact from logs (case-insensitive).
+     * @default ['authorization', 'cookie', 'x-api-key', 'x-auth-token']
+     */
+    redactHeaders?: string[];
+    /**
+     * Minimum duration in ms to log. Requests faster than this are not logged.
+     * Useful for reducing log volume in high-traffic scenarios.
+     * @default 0 (log all requests)
+     */
+    minDuration?: number;
+    /**
+     * Whether to include timestamp in log messages.
+     * @default true
+     */
+    includeTimestamp?: boolean;
+    /**
+     * Custom log formatter for requests.
+     * If provided, overrides the default request logging format.
+     */
+    formatRequest?: (ctx: RequestContext) => string;
+    /**
+     * Custom log formatter for responses.
+     * If provided, overrides the default response logging format.
+     */
+    formatResponse?: <T>(ctx: ResponseContext<T>) => string;
+    /**
+     * Custom log formatter for errors.
+     * If provided, overrides the default error logging format.
+     */
+    formatError?: (error: Error, ctx: RequestContext) => string;
+}
+/**
+ * Creates a logging middleware for debugging and monitoring.
+ *
+ * The middleware logs:
+ * - Request method, URL, and optionally body/headers
+ * - Response status, URL, and duration
+ * - Errors with context
+ *
+ * Sensitive headers (Authorization, Cookie, etc.) are automatically redacted.
+ *
+ * @param options - Configuration options for the logging middleware
+ * @returns A middleware instance
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware = createLoggingMiddleware({
+ *   prefix: '[MyApp API]',
+ *   logBody: false,
+ *   logHeaders: true,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom logger
+ * const loggingMiddleware = createLoggingMiddleware({
+ *   logger: {
+ *     log: (msg, ...args) => myLogger.info(msg, ...args),
+ *     error: (msg, ...args) => myLogger.error(msg, ...args),
+ *   },
+ *   minDuration: 100, // Only log requests taking > 100ms
+ * });
+ * ```
+ */
+export declare function createLoggingMiddleware(options?: LoggingMiddlewareOptions): Middleware;