@mosano-product-framework/sdk 0.2.0

package/dist/client/core/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Core types for the MPF SDK
+ */
+/** Token provider interface for SDK consumers */
+export interface TokenProvider {
+    getAccessToken: () => string | null | Promise<string | null>;
+    /**
+     * Called when a 401 is final — a token was attached and renewal was not
+     * possible or already failed. The "log out" hook.
+     */
+    onTokenExpired?: () => void | Promise<void>;
+    /**
+     * Called on the first 401 of a request that carried a token. Attempt a
+     * renewal; resolve `true` to have the request retried once with a fresh
+     * token. Wire this to `SessionManager.renew()`.
+     */
+    onUnauthorized?: () => Promise<boolean>;
+}
+/**
+ * Request context passed through the middleware chain
+ */
+export interface RequestContext {
+    /** The full URL being requested */
+    url: string;
+    /** The fetch RequestInit options */
+    init: RequestInit;
+    /** Custom metadata that middlewares can use to pass data */
+    metadata: Record<string, unknown>;
+    /** The original request options, available for middleware inspection */
+    options?: RequestOptions;
+}
+/**
+ * Response context passed through the middleware chain
+ */
+export interface ResponseContext<T = unknown> {
+    /** The raw fetch Response object */
+    response: Response;
+    /** The parsed response data */
+    data: T;
+    /** Custom metadata that middlewares can use to pass data */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Configuration options for the MPF client
+ */
+export interface ClientConfig {
+    /** Base URL for all API requests (e.g., "https://api.example.com") */
+    baseUrl: string;
+    /** Default headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Middlewares to apply to all requests */
+    middlewares?: import('./middleware.js').Middleware[];
+}
+/**
+ * Options for individual requests
+ */
+export interface RequestOptions {
+    /** Additional headers for this specific request */
+    headers?: Record<string, string>;
+    /** AbortSignal for request cancellation */
+    signal?: AbortSignal;
+    /** Query parameters to append to the URL */
+    params?: Record<string, string | number | boolean | undefined>;
+    /** When true, the auth middleware will skip injecting the Authorization header */
+    skipAuth?: boolean;
+    /**
+     * Tenant scope for this request. Three meaningful states:
+     *
+     * - `undefined` — inherit the client-wide tenant selection (the default).
+     * - `null` — deliberately unscoped: send no tenant header for this request.
+     * - a string — use that tenant for this request only.
+     *
+     * The `undefined` vs `null` distinction matters: without it, "I did not say"
+     * and "I said no tenant" collapse into the same value and a deliberately
+     * unscoped call would silently pick up the ambient selection.
+     */
+    tenant?: string | null;
+    /**
+     * Role to select within the tenant. Omit to let the server apply that
+     * tenant's default role — its `tnts[].dfr` when the token carries one, else
+     * `tnts[].rls[0]`.
+     */
+    tenantRole?: string;
+    /** When true, the tenant middleware sends no tenant headers at all. */
+    skipTenant?: boolean;
+}
+/**
+ * Standard API error response shape
+ */
+export interface APIErrorResponse {
+    /** Error code identifier */
+    code?: string;
+    /** Human-readable error message */
+    message?: string;
+    /** Error string from Go backend */
+    error?: string;
+    /** Additional error details */
+    details?: unknown;
+}

package/dist/client/graphql/client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * GraphQL client that extends the base MPF client
+ */
+import { MPFClient } from '../core/client.js';
+import type { ClientConfig } from '../core/types.js';
+import type { TypedDocumentNode, GraphQLRequestOptions } from './types.js';
+/**
+ * Configuration options for the GraphQL client
+ */
+export interface GraphQLClientConfig extends ClientConfig {
+    /**
+     * GraphQL endpoint path (default: '/graphql')
+     */
+    endpoint?: string;
+}
+/**
+ * GraphQL client for MPF services
+ *
+ * Supports both raw query strings and typed document nodes for type-safe operations.
+ *
+ * @example
+ * ```typescript
+ * const client = new MPFGraphQLClient({ baseUrl: 'https://api.example.com' });
+ *
+ * // Using raw query string
+ * const result = await client.query(`
+ *   query GetUser($id: ID!) {
+ *     user(id: $id) { id name email }
+ *   }
+ * `, { id: '123' });
+ *
+ * // Using typed document node (from codegen)
+ * const typedResult = await client.query(GetUserDocument, { id: '123' });
+ * ```
+ */
+export declare class MPFGraphQLClient extends MPFClient {
+    /** The GraphQL endpoint path */
+    protected graphqlEndpoint: string;
+    constructor(config: GraphQLClientConfig);
+    /**
+     * Execute a GraphQL query operation
+     *
+     * @param document - The GraphQL query (string or typed document node)
+     * @param variables - Optional variables for the query
+     * @param options - Optional request options (headers, signal)
+     * @returns The query result data
+     * @throws {MPFAPIError} When GraphQL errors occur or no data is returned
+     */
+    query<TData, TVariables = Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables> | string, variables?: TVariables, options?: GraphQLRequestOptions): Promise<TData>;
+    /**
+     * Execute a GraphQL mutation operation
+     *
+     * @param document - The GraphQL mutation (string or typed document node)
+     * @param variables - Optional variables for the mutation
+     * @param options - Optional request options (headers, signal)
+     * @returns The mutation result data
+     * @throws {MPFAPIError} When GraphQL errors occur or no data is returned
+     */
+    mutate<TData, TVariables = Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables> | string, variables?: TVariables, options?: GraphQLRequestOptions): Promise<TData>;
+    /**
+     * Execute a GraphQL operation (query or mutation)
+     *
+     * @internal
+     */
+    private executeOperation;
+}

package/dist/client/graphql/factory.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `createGraphQLClient` — the GraphQL counterpart to `createAuthClient` /
+ * `createStorageClient`, built on the same `attachStandardMiddlewares`
+ * wiring (see `core/client-factory.ts`) so it shares one `tokenProvider` /
+ * `tenantProvider` with every other client an app constructs.
+ *
+ * Adds one more axis specific to GraphQL: `mode`, which decides HTTP vs
+ * `graphql-ws` per operation. This is a deliberately small stand-in for an
+ * Apollo-Link-style split link — enough to route by operation kind, not a
+ * general link-chaining system. If usage grows past "route by operation
+ * kind" (retry links, batching links, etc.) that is the point to reach for
+ * an actual link abstraction; this does not try to anticipate that.
+ */
+import { type HttpClientOptions } from '../core/client-factory.js';
+import { type GraphQLWsCreateClientParams, type GraphQLWsClientLike } from './ws-client.js';
+import type { TypedDocumentNode, GraphQLRequestOptions, GraphQLResponse } from './types.js';
+/**
+ * How a `createGraphQLClient` routes operations.
+ *
+ * - `'individual-requests'` — every operation (query/mutation) goes over
+ *   plain HTTP POST. No socket is ever opened; `subscribe()` throws.
+ * - `'websocket'` — every operation, including query/mutation, goes over one
+ *   `graphql-ws` connection.
+ * - `'hybrid'` (default) — starts in `'individual-requests'` behavior.
+ *   Query/mutation always stay on HTTP (cheaper: no connection to keep
+ *   alive for the common case). The FIRST `subscribe()` call lazily opens
+ *   the `graphql-ws` connection; every subscription after that reuses it.
+ */
+export type GraphQLConnectionMode = 'individual-requests' | 'websocket' | 'hybrid';
+export interface GraphQLClientOptions extends HttpClientOptions {
+    /** GraphQL HTTP endpoint path. @default '/graphql' */
+    endpoint?: string;
+    /** @default 'hybrid' */
+    mode?: GraphQLConnectionMode;
+    /**
+     * `ws://`/`wss://` endpoint for the `graphql-ws` transport. Defaults to
+     * `baseUrl` with `http(s)` swapped for `ws(s)` and `endpoint` appended —
+     * correct for Hasura, which serves GraphQL-over-HTTP and `graphql-ws` on
+     * the same path. Override for a service that splits them.
+     */
+    wsUrl?: string;
+    /** `WebSocket` implementation for non-browser runtimes (e.g. the `ws` package in Node). */
+    webSocketImpl?: unknown;
+    /** `graphql-ws` reconnect attempts. @default 5 */
+    wsRetryAttempts?: number;
+    /**
+     * Injectable `graphql-ws` `createClient`, forwarded to
+     * {@link createGraphQLWsTransport}. Lets tests exercise `'websocket'`/
+     * `'hybrid'` routing with a fake socket instead of a real one — see
+     * `ws-client.ts`'s `GraphQLWsClientOptions.createClient` doc.
+     */
+    wsCreateClient?: (params: GraphQLWsCreateClientParams) => GraphQLWsClientLike;
+}
+export interface GraphQLSubscriptionHandlers<TData> {
+    onData: (result: GraphQLResponse<TData>) => void;
+    onError?: (error: unknown) => void;
+    onComplete?: () => void;
+}
+export interface MPFGraphQLHybridClient {
+    query<TData, TVariables = Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables> | string, variables?: TVariables, options?: GraphQLRequestOptions): Promise<TData>;
+    mutate<TData, TVariables = Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables> | string, variables?: TVariables, options?: GraphQLRequestOptions): Promise<TData>;
+    /**
+     * Subscribe to a `subscription` document. Throws synchronously in
+     * `'individual-requests'` mode — that mode has no transport for it.
+     *
+     * @returns An unsubscribe function.
+     */
+    subscribe<TData, TVariables = Record<string, unknown>>(document: TypedDocumentNode<TData, TVariables> | string, variables: TVariables | undefined, handlers: GraphQLSubscriptionHandlers<TData>): () => void;
+    /**
+     * Force the `graphql-ws` socket closed; it reopens with a fresh token and
+     * resubscribes every live subscription. Wire this to fire on every token
+     * renewal — e.g. from `SessionManagerOptions.onTokensChanged` — so a
+     * subscription never outlives the token it was opened with. A no-op if no
+     * socket has been opened yet (nothing to reconnect).
+     */
+    reconnectWebSocket(): void;
+    /** Release the HTTP client's resources (none currently) and close any open socket. */
+    dispose(): void;
+}
+/**
+ * Create a GraphQL client with the standard auth/tenant middlewares wired in
+ * and a `mode`-selected HTTP/`graphql-ws` transport.
+ */
+export declare function createGraphQLClient(options: GraphQLClientOptions): MPFGraphQLHybridClient;

package/dist/client/graphql/operation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cheap operation-kind detection — no `graphql` parser dependency.
+ *
+ * The hybrid client only needs ONE bit: "is this a subscription". A full AST
+ * parse (`graphql`'s `parse()` + `getOperationAST()`) would answer that too,
+ * but it drags `graphql` into the HTTP-only path as a hard dependency, which
+ * defeats the point of `graphql` staying an optional peer (see
+ * `graphql/ws-client.ts`). A GraphQL document's operation keyword is always
+ * the first non-trivia token — `query`/`mutation`/`subscription`, or omitted
+ * entirely for the anonymous-query shorthand (`{ ... }`) — so a regex over the
+ * leading trivia is exact, not a heuristic.
+ */
+/** The three GraphQL operation kinds, plus `unknown` for an unparseable document. */
+export type OperationKind = 'query' | 'mutation' | 'subscription' | 'unknown';
+/**
+ * Determine a GraphQL document's operation kind from its source text.
+ *
+ * `{ ... }` (no keyword) is the anonymous-query shorthand and is always a
+ * `query` — a `subscription` document is never allowed to omit its keyword,
+ * per the GraphQL spec, so this cannot misclassify a subscription as a query.
+ */
+export declare function getOperationKind(document: string): OperationKind;
+/** Whether a GraphQL document is a subscription. */
+export declare function isSubscription(document: string): boolean;

package/dist/client/graphql/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * GraphQL-specific types for the MPF SDK
+ */
+/**
+ * Minimal typed document representation
+ * Compatible with graphql-request, urql, Apollo, and other GraphQL clients
+ */
+export interface TypedDocumentNode<TData = unknown, TVariables = unknown> {
+    /** Type brand for compile-time type inference */
+    __apiType?: (variables: TVariables) => TData;
+    /** Returns the GraphQL query string */
+    toString(): string;
+}
+/**
+ * Represents a single GraphQL error from the response
+ */
+export interface GraphQLError {
+    /** Human-readable error message */
+    message: string;
+    /** Locations in the GraphQL document where the error occurred */
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    /** Path to the field that caused the error */
+    path?: Array<string | number>;
+    /** Additional error metadata */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Standard GraphQL response structure
+ */
+export interface GraphQLResponse<T = unknown> {
+    /** The data returned from the operation */
+    data?: T;
+    /** Any errors that occurred during execution */
+    errors?: GraphQLError[];
+}
+/**
+ * Options for individual GraphQL requests
+ */
+export interface GraphQLRequestOptions {
+    /** Additional headers for this request */
+    headers?: Record<string, string>;
+    /** AbortSignal for request cancellation */
+    signal?: AbortSignal;
+    /**
+     * Tenant scope for this operation. `undefined` inherits the client-wide
+     * selection, `null` is deliberately unscoped, a string selects that tenant.
+     *
+     * @see {@link import('../core/types.js').RequestOptions.tenant}
+     */
+    tenant?: string | null;
+    /** Role within the tenant. Omit to let the server apply the tenant default. */
+    tenantRole?: string;
+    /** When true, send no tenant headers for this operation. */
+    skipTenant?: boolean;
+    /** When true, send no Authorization header for this operation. */
+    skipAuth?: boolean;
+}

package/dist/client/graphql/ws-client.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `graphql-ws` transport, wired to the SAME `tokenProvider`/`tenantProvider`
+ * every REST and HTTP-GraphQL client uses.
+ *
+ * This is meant to be a project-wide standard, not a go-hasura special case:
+ * any microservice exposing `graphql-ws` subscriptions (Hasura's, or a Go
+ * service's own) authenticates the same way every other MPF client does —
+ * `connectionParams` carries the identical `Authorization: Bearer <jwt>` (plus
+ * `X-MPF-Tenant`/`X-MPF-Tenant-Role` when a tenant is selected) that the HTTP
+ * middlewares put on REST/GraphQL-over-HTTP requests. A service just needs to
+ * read those three keys off the `connection_init` payload at its own webhook
+ * auth boundary — no new token format.
+ *
+ * They are carried under a `headers` key of the `connection_init` payload —
+ * `{ headers: { Authorization, 'X-MPF-Tenant', ... } }` — NOT flat at the top
+ * level. That is what Hasura reads: over the websocket path it takes
+ * `payload.headers` and replays those as the request headers it hands to the
+ * auth webhook (hasura-authd). Flat top-level keys are silently ignored, so
+ * the socket connects and every subscription then fails as unauthenticated —
+ * verified end-to-end against a live stack in
+ * `e2e/tests/go-identity/graphql-subscriptions.e2e.test.ts`. It is also the
+ * shape the wider `graphql-ws` ecosystem uses for header-style auth, so a Go
+ * service reading `payload.headers` stays consistent with both.
+ */
+import type { TokenProvider } from '../core/types.js';
+import type { TenantSelectionStore } from '../../auth/tenant-selection.js';
+import type { GraphQLResponse } from './types.js';
+/**
+ * The subset of a `graphql-ws` `Client` this module uses. Kept as our own
+ * interface (not `import type { Client } from 'graphql-ws'`) so this file
+ * never has a hard, non-dynamic dependency on the `graphql-ws` types either —
+ * matches `cross-tab.ts`'s `LockManagerLike`/`BroadcastChannelLike` pattern.
+ */
+export interface GraphQLWsClientLike {
+    subscribe<TData = unknown>(payload: {
+        query: string;
+        variables?: Record<string, unknown>;
+    }, sink: {
+        next: (value: {
+            data?: TData | null;
+            errors?: readonly unknown[];
+        }) => void;
+        error: (err: unknown) => void;
+        complete: () => void;
+    }): () => void;
+    terminate(): void;
+    dispose(): void | Promise<void>;
+}
+/** Options `createGraphQLWsTransport` forwards to `graphql-ws`'s `createClient`. */
+export interface GraphQLWsCreateClientParams {
+    url: string;
+    lazy: boolean;
+    retryAttempts: number;
+    webSocketImpl?: unknown;
+    /**
+     * Resolved per connection attempt. Shape is `{ headers: { ... } }` — see
+     * the module doc for why the auth headers are nested rather than flat.
+     */
+    connectionParams: () => Promise<{
+        headers: Record<string, string>;
+    }>;
+}
+export interface GraphQLWsClientOptions {
+    /** `ws://` or `wss://` endpoint. */
+    url: string;
+    /** Same token provider passed to the HTTP transport — see module docs. */
+    tokenProvider?: TokenProvider;
+    /** Same tenant provider passed to the HTTP transport. */
+    tenantProvider?: TenantSelectionStore;
+    /**
+     * `WebSocket` implementation for non-browser environments (Node has no
+     * global `WebSocket` before v22). Pass the `ws` package's export there.
+     */
+    webSocketImpl?: unknown;
+    /** Reconnect attempts before giving up on a dropped socket. @default 5 */
+    retryAttempts?: number;
+    /**
+     * Open the socket only when the first subscription starts, close it when
+     * the last one ends. @default true — matches `hybrid` mode's "no socket
+     * until a subscription shows up" contract.
+     */
+    lazy?: boolean;
+    /**
+     * Injectable `graphql-ws` `createClient`. Defaults to a dynamic
+     * `import('graphql-ws')`. Tests supply a fake here to exercise the full
+     * subscribe/reconnect/dispose contract without a real socket or the
+     * `graphql-ws` package — same reason `cross-tab.ts` takes an injectable
+     * `locks`/`channelFactory`.
+     */
+    createClient?: (params: GraphQLWsCreateClientParams) => GraphQLWsClientLike;
+}
+export interface GraphQLSubscriptionSink<TData> {
+    next: (result: GraphQLResponse<TData>) => void;
+    error: (error: unknown) => void;
+    complete: () => void;
+}
+export interface GraphQLWsTransport {
+    /** Subscribe; returns an unsubscribe function. */
+    subscribe<TData = unknown, TVariables = Record<string, unknown>>(document: {
+        toString(): string;
+    } | string, variables: TVariables | undefined, sink: GraphQLSubscriptionSink<TData>): () => void;
+    /**
+     * Force the current socket closed. `graphql-ws`'s own retry logic reopens
+     * it with a FRESH `connectionParams` call (so a rotated token is picked up)
+     * and resubscribes every still-registered operation automatically.
+     *
+     * Call this right after a `SessionManager` renewal — see
+     * `createGraphQLClient`'s `mode: 'websocket' | 'hybrid'` wiring — so a live
+     * subscription is never carried on a token past its renewal point.
+     */
+    reconnect(): void;
+    /** Close the socket and release it for good. Registered subscriptions end. */
+    dispose(): void;
+}
+/** Create a `graphql-ws`-backed subscription transport. */
+export declare function createGraphQLWsTransport(options: GraphQLWsClientOptions): GraphQLWsTransport;

package/dist/client/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@mosano-product-framework/sdk/client` — the generic transport layer.
+ *
+ * Everything here is service-agnostic: the HTTP client, the middleware
+ * machinery and the built-in middlewares, the error types, and the GraphQL
+ * clients (HTTP, WebSocket and hybrid).
+ *
+ * The root barrel re-exports this module as a `client` namespace, but only the
+ * `./peer-free.js` half of it — `createGraphQLClient` and
+ * `createGraphQLWsTransport` are subpath-only because they reach the optional
+ * `graphql-ws` peer. See the comment at the top of `peer-free.ts`.
+ *
+ * @packageDocumentation
+ */
+export * from './peer-free.js';
+export { createGraphQLClient, type GraphQLClientOptions, type GraphQLConnectionMode, type MPFGraphQLHybridClient, type GraphQLSubscriptionHandlers, } from './graphql/factory.js';
+export { createGraphQLWsTransport, type GraphQLWsClientLike, type GraphQLWsCreateClientParams, type GraphQLWsClientOptions, type GraphQLWsTransport, type GraphQLSubscriptionSink, } from './graphql/ws-client.js';