@mosano-product-framework/sdk 0.2.0

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

@@ -0,0 +1,138 @@
+import type { Middleware } from '../core/middleware.js';
+import type { RequestContext } from '../core/types.js';
+/**
+ * Options for the retry middleware.
+ */
+export interface RetryMiddlewareOptions {
+    /**
+     * Maximum number of retry attempts.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in milliseconds between retries.
+     * With exponential backoff, actual delay = retryDelay * (backoffFactor ^ attemptNumber)
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * HTTP status codes that trigger a retry.
+     * @default [408, 429, 500, 502, 503, 504]
+     */
+    retryOn?: number[];
+    /**
+     * Exponential backoff factor.
+     * Each retry waits: retryDelay * (backoffFactor ^ attemptNumber)
+     * @default 2
+     */
+    backoffFactor?: number;
+    /**
+     * Maximum delay in milliseconds between retries (caps exponential growth).
+     * @default 30000 (30 seconds)
+     */
+    maxDelay?: number;
+    /**
+     * Whether to add random jitter to retry delays (prevents thundering herd).
+     * When enabled, adds random jitter up to 25% of the calculated delay.
+     * @default true
+     */
+    jitter?: boolean;
+    /**
+     * Optional callback called before each retry attempt.
+     * Can be used for logging or metrics.
+     */
+    onRetry?: (attempt: number, error: Error, delay: number) => void | Promise<void>;
+    /**
+     * Custom function to determine if an error should trigger a retry.
+     * If provided, this takes precedence over retryOn status codes.
+     */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+}
+/**
+ * Creates a retry middleware with exponential backoff.
+ *
+ * The middleware:
+ * - Automatically retries failed requests based on HTTP status codes
+ * - Uses exponential backoff to space out retry attempts
+ * - Optionally adds jitter to prevent thundering herd problems
+ * - Respects Retry-After headers when present
+ *
+ * @param options - Configuration options for the retry middleware
+ * @returns A middleware instance
+ *
+ * @example
+ * ```typescript
+ * const retryMiddleware = createRetryMiddleware({
+ *   maxRetries: 3,
+ *   retryDelay: 1000,
+ *   retryOn: [500, 502, 503, 504],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom retry logic
+ * const retryMiddleware = createRetryMiddleware({
+ *   maxRetries: 5,
+ *   retryDelay: 500,
+ *   backoffFactor: 1.5,
+ *   jitter: true,
+ *   onRetry: (attempt, error, delay) => {
+ *     console.log(`Retry attempt ${attempt} after ${delay}ms:`, error.message);
+ *   },
+ *   shouldRetry: (error, attempt) => {
+ *     // Custom retry logic
+ *     if (error instanceof MPFError && error.status) {
+ *       return error.status >= 500 && attempt < 3;
+ *     }
+ *     return false;
+ *   }
+ * });
+ * ```
+ */
+export declare function createRetryMiddleware(options?: RetryMiddlewareOptions): Middleware;
+/**
+ * Check if a request context indicates a retry should be attempted.
+ * Used by `MPFClient.request()` to decide whether to run another attempt.
+ *
+ * Returns false when the request has been marked non-retryable, even if a
+ * middleware asked for a retry.
+ */
+export declare function shouldRetryRequest(ctx: RequestContext): boolean;
+/**
+ * Ask `MPFClient.request()` to run another attempt.
+ *
+ * The single writer of the retry flag. Any middleware that can recover from an
+ * error (the auth middleware's renew-and-retry, for instance) calls this from
+ * its `onError` and then rethrows.
+ *
+ * The client consults the flag unconditionally, so this works whether or not
+ * `createRetryMiddleware` is registered.
+ */
+export declare function requestRetry(ctx: RequestContext): void;
+/**
+ * Mark a request as non-retryable. Used for request bodies that cannot be
+ * re-sent (a `ReadableStream` is consumed by the first attempt).
+ */
+export declare function disableRetry(ctx: RequestContext): void;
+/**
+ * Whether the request has been marked non-retryable.
+ */
+export declare function isRetryDisabled(ctx: RequestContext): boolean;
+/**
+ * Whether a fetch body can be sent more than once.
+ *
+ * `FormData`, `Blob`, `ArrayBuffer`, `URLSearchParams` and strings are all
+ * re-readable, so retrying them is safe. A `ReadableStream` is consumed by the
+ * first attempt and must never be retried.
+ */
+export declare function isReplayableBody(body: BodyInit | null | undefined): boolean;
+/**
+ * Get the current retry attempt number from request context.
+ */
+export declare function getRetryAttempt(ctx: RequestContext): number;
+/**
+ * Clear the retry flag from the request context.
+ * Should be called after a successful retry or when giving up.
+ */
+export declare function clearRetryFlag(ctx: RequestContext): void;

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

@@ -0,0 +1,60 @@
+import type { Middleware } from '../core/middleware.js';
+import type { TenantSelectionStore } from '../../auth/tenant-selection.js';
+/** Header carrying the selected tenant id. */
+export declare const TENANT_HEADER = "X-MPF-Tenant";
+/** Header carrying the selected role within that tenant. */
+export declare const TENANT_ROLE_HEADER = "X-MPF-Tenant-Role";
+/**
+ * Options for the tenant middleware.
+ */
+export interface TenantMiddlewareOptions {
+    /**
+     * The shared tenant selection. Read per request, so a `set()` takes effect on
+     * the next request with no client reconstruction.
+     */
+    tenantProvider?: TenantSelectionStore;
+    /**
+     * Access-token getter, used ONLY for the under-scoping warning below. When
+     * omitted the warning is disabled.
+     *
+     * Decoding is LRU-cached, and the warning fires at most once per middleware,
+     * so this costs nothing in steady state.
+     */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /**
+     * Whether to warn once when a request goes out unscoped while the token holds
+     * tenants.
+     * @default true
+     */
+    warnOnUnscoped?: boolean;
+    /** Logger for the warning. Defaults to `console`. */
+    logger?: {
+        warn: (message: string, ...args: unknown[]) => void;
+    };
+}
+/**
+ * Creates a middleware that puts the selected tenant on the wire.
+ *
+ * Resolution order for the tenant, using the three states of
+ * `options.tenant`:
+ *
+ * | `options.tenant`  | meaning                                    |
+ * |-------------------|--------------------------------------------|
+ * | `undefined`       | inherit the client-wide selection          |
+ * | `null`            | deliberately unscoped for THIS request     |
+ * | `"<uuid>"`        | that tenant, for THIS request              |
+ *
+ * `options.skipTenant` bypasses the middleware entirely.
+ *
+ * Header rules:
+ * - The tenant header is **omitted entirely** when there is no tenant. An
+ *   empty-string header is a 400 server-side, deliberately, so that a bug
+ *   cannot masquerade as the no-tenant path.
+ * - The role header is omitted unless a role was specified, letting the server
+ *   apply that tenant's default role (its `dfr`, or `rls[0]` when it has
+ *   none).
+ * - A per-request tenant does NOT inherit the client-wide role: the role only
+ *   travels with the selection it belongs to. Selecting tenant B while tenant
+ *   A's role is selected must not send A's role to B.
+ */
+export declare function createTenantMiddleware(options?: TenantMiddlewareOptions): Middleware;

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

@@ -0,0 +1,41 @@
+import type { Middleware } from '../core/middleware.js';
+/**
+ * Options for the Turnstile middleware.
+ */
+export interface TurnstileMiddlewareOptions {
+    /**
+     * Async function that mints a fresh Turnstile token.
+     * Called once per protected request. Must return a valid token string.
+     * Should throw if token cannot be obtained.
+     */
+    getToken: () => Promise<string>;
+    /**
+     * URL path suffixes that require a Turnstile token.
+     * Matched against the end of the request URL path.
+     * Example: ['/sign-up-email-password', '/sign-in-email-password']
+     */
+    protectedPaths: string[];
+}
+/**
+ * Creates a Cloudflare Turnstile middleware that attaches `X-Turnstile-Token`
+ * headers to requests matching the configured protected paths.
+ *
+ * The middleware only calls `getToken()` for requests whose URL path ends
+ * with one of the `protectedPaths` entries — all other requests pass through
+ * untouched with zero overhead.
+ *
+ * @param options - Configuration options for the turnstile middleware
+ * @returns A middleware instance
+ *
+ * @example
+ * ```typescript
+ * const turnstileMiddleware = createTurnstileMiddleware({
+ *   getToken: async () => {
+ *     // Render Turnstile widget and return token
+ *     return await turnstile.execute(siteKey);
+ *   },
+ *   protectedPaths: ['/sign-up-email-password', '/sign-in-email-password'],
+ * });
+ * ```
+ */
+export declare function createTurnstileMiddleware(options: TurnstileMiddlewareOptions): Middleware;

package/dist/client/peer-free.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The part of `./client` that reaches NO optional peer dependency.
+ *
+ * This file exists so the root barrel can expose a `client` namespace without
+ * dragging `graphql-ws` into every consumer's module graph.
+ *
+ * `createGraphQLClient` (in `graphql/factory.ts`) and `createGraphQLWsTransport`
+ * (in `graphql/ws-client.ts`) reach `graphql-ws`. It is only ever loaded through
+ * a dynamic `import()`, so nothing breaks at runtime for an app that never
+ * subscribes — but a *static* export chain from `src/index.ts` still puts those
+ * modules (and the dynamic-import chunk a bundler emits for them) in the graph
+ * of every consumer, including plain-HTTP ones. So they are reachable from the
+ * `./client` subpath only, never from the root namespace.
+ *
+ * This is the same rule `./react` follows for its `react` peer. See
+ * `tests/module-boundaries.test.ts` ("depends on jose only") for the guard.
+ *
+ * @packageDocumentation
+ */
+export * from './core/index.js';
+export * from './middlewares/index.js';
+export * from './utils/url.js';
+export { MPFGraphQLClient, type GraphQLClientConfig } from './graphql/client.js';
+export type { TypedDocumentNode, GraphQLError, GraphQLResponse, GraphQLRequestOptions, } from './graphql/types.js';
+export { getOperationKind, isSubscription, type OperationKind } from './graphql/operation.js';

package/dist/client/utils/url.d.ts

@@ -0,0 +1,19 @@
+/**
+ * URL building utilities for the MPF SDK
+ */
+/**
+ * Build a URL with query parameters
+ *
+ * @param baseUrl - The base URL
+ * @param path - The path to append
+ * @param params - Optional query parameters
+ * @returns The full URL with query string
+ */
+export declare function buildUrl(baseUrl: string, path: string, params?: Record<string, string | number | boolean | undefined | null>): string;
+/**
+ * Join URL segments safely
+ *
+ * @param segments - URL segments to join
+ * @returns Joined URL path
+ */
+export declare function joinPath(...segments: string[]): string;

package/dist/identity/index.d.ts

@@ -0,0 +1,85 @@
+import type { ClientConfig, TokenProvider } from '../client/core/types.js';
+import { type AdminAuthMiddlewareOptions } from '../client/middlewares/admin-auth.js';
+import type { TenantSelectionStore } from '../auth/tenant-selection.js';
+import type { OAuthStateStore } from '../auth/oauth-state.js';
+import { AuthClientV0 } from './v0.js';
+/**
+ * Provider for minting single-use Cloudflare Turnstile tokens.
+ */
+export interface TurnstileProvider {
+    /** Mint a fresh single-use Turnstile token. */
+    getToken: () => Promise<string>;
+}
+/**
+ * Configuration options for the Auth client
+ */
+export interface AuthClientOptions extends Omit<ClientConfig, 'baseUrl'> {
+    /**
+     * Base URL for the Auth service
+     */
+    baseUrl: string;
+    /** Optional token provider. Auto-wires auth middleware when provided. */
+    tokenProvider?: TokenProvider;
+    /** Optional Turnstile token provider for bot protection. */
+    turnstileProvider?: TurnstileProvider;
+    /**
+     * Optional shared tenant selection. When provided, every request carries the
+     * selected tenant headers. Construct it with `createTenantSelection()` and
+     * share the same instance across identity/storage/graphql clients.
+     */
+    tenantProvider?: TenantSelectionStore;
+    /**
+     * Optional store for the OAuth CSRF state. When provided,
+     * `getGoogleOAuthURL` persists the minted state so it survives the redirect.
+     * Build one with `createOAuthStateStore()`.
+     */
+    oauthStateStore?: OAuthStateStore;
+}
+export declare function createAuthClient(options: AuthClientOptions): AuthClientV0;
+/**
+ * Configuration options for an admin-authenticated Auth client.
+ *
+ * SECURITY: Admin authentication uses the shared `ADMIN_JWT_SECRET`, which can
+ * impersonate any user. Only construct an admin client server-side / in trusted
+ * services. NEVER ship the secret to a browser.
+ */
+export interface AdminClientOptions extends Omit<ClientConfig, 'baseUrl'> {
+    /** Base URL for the Auth service. */
+    baseUrl: string;
+    /** Admin auth options: either a pre-minted `token` or a minting `config`. */
+    admin: AdminAuthMiddlewareOptions;
+}
+/**
+ * Creates an admin-authenticated Auth client for API v0.
+ *
+ * The returned client sends `Authorization: Admin <jwt>` on every request,
+ * acting on behalf of the configured principal. Mirrors {@link createAuthClient}
+ * but wires the admin auth middleware instead of the Bearer one.
+ *
+ * SECURITY: Requires the shared `ADMIN_JWT_SECRET` (when using a minting
+ * `config`). Server-side / trusted-service use ONLY — never expose the secret
+ * to a browser.
+ *
+ * @param options - Client configuration options.
+ * @returns AuthClientV0 instance authenticated as an admin.
+ *
+ * @example
+ * ```typescript
+ * import { createAdminClient } from '@mosano-product-framework/sdk/identity';
+ *
+ * // Mint a fresh admin token per request (server-side only).
+ * const admin = createAdminClient({
+ *   baseUrl: 'https://api.example.com/auth',
+ *   admin: {
+ *     config: {
+ *       secret: process.env.ADMIN_JWT_SECRET!,
+ *       actOnBehalfOf: { userId, onTenantId: tenantId },
+ *       ttlSeconds: 60,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createAdminClient(options: AdminClientOptions): AuthClientV0;
+export { AuthClientV0, type AuthClientV0Config } from './v0.js';
+export * from './types.js';

package/dist/identity/index.js

@@ -0,0 +1,6 @@
+export { AuthClientV0, createAdminClient, createAuthClient, isMFARequired, isMFASetupRequired } from '../chunk-XAXFIIRT.js';
+import '../chunk-K2ELAI2X.js';
+import '../chunk-LRM6JJ63.js';
+import '../chunk-AJWM5MDZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/identity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}