lemma-sdk 0.2.46 → 0.3.0

package/dist/run-utils.js

@@ -50,3 +50,57 @@ export function nextBackoffDelay(attempt, options = {}) {
     const delay = Math.round(baseMs * Math.pow(factor, safeAttempt));
     return Math.min(Math.max(baseMs, delay), maxMs);
 }
+/**
+ * Statuses worth retrying with backoff. Deliberately conservative: 429 is an
+ * explicit "back off", and 502/503/504 are gateway errors where the request
+ * usually never reached the handler — so retrying is safe even for writes.
+ * 500 is excluded (it may indicate a partial side effect).
+ */
+export const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+/** Parse a server `Retry-After` header (delta-seconds or HTTP-date) into ms,
+ *  capped at 30s. Returns null when the header is absent or unparseable. */
+export function serverRetryAfterMs(retryAfter) {
+    if (!retryAfter) {
+        return null;
+    }
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.min(seconds * 1000, 30_000);
+    }
+    const dateMs = Date.parse(retryAfter);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, Math.min(dateMs - Date.now(), 30_000));
+    }
+    return null;
+}
+/** Resolve a backoff delay, honoring a server `Retry-After` header when present. */
+export function retryAfterMs(retryAfter, attempt) {
+    return serverRetryAfterMs(retryAfter) ?? nextBackoffDelay(attempt);
+}
+/** Equal jitter: keep half the delay fixed and randomize the other half, so the
+ *  result lands in `[delay/2, delay]`. Spreads correlated retries (thundering
+ *  herd) without ever waiting longer than the computed backoff. */
+export function applyJitter(delayMs, random = Math.random) {
+    if (!Number.isFinite(delayMs) || delayMs <= 0) {
+        return 0;
+    }
+    const half = delayMs / 2;
+    return Math.round(half + random() * half);
+}
+/**
+ * Single source of truth for the retry decision shared by the hand-written
+ * `HttpClient` and the generated-client adapter. Returns the number of ms to
+ * wait before retrying, or `null` when the status is non-retryable or retries
+ * are exhausted. A server-advised `Retry-After` is honored verbatim (no jitter);
+ * the computed exponential backoff gets equal jitter.
+ */
+export function retryDelayForStatus(status, attempt, maxRetries, retryAfterHeader, random = Math.random) {
+    if (!RETRYABLE_STATUS.has(status) || attempt >= maxRetries) {
+        return null;
+    }
+    const serverMs = serverRetryAfterMs(retryAfterHeader);
+    if (serverMs !== null) {
+        return serverMs;
+    }
+    return applyJitter(nextBackoffDelay(attempt), random);
+}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+export declare const SDK_VERSION = "0.3.0";
+/** Sent as `X-Lemma-Client` on every request so the backend can log which client
+ *  + version hit an endpoint (User-Agent is a forbidden header in browser fetch). */
+export declare const CLIENT_HEADER_NAME = "X-Lemma-Client";
+export declare const CLIENT_HEADER_VALUE = "lemma-sdk-ts/0.3.0";

package/dist/version.js

@@ -0,0 +1,7 @@
+// Keep SDK_VERSION in sync with package.json "version". The CI codegen/drift
+// gate (workstream A) asserts they match so this can't silently drift.
+export const SDK_VERSION = "0.3.0";
+/** Sent as `X-Lemma-Client` on every request so the backend can log which client
+ *  + version hit an endpoint (User-Agent is a forbidden header in browser fetch). */
+export const CLIENT_HEADER_NAME = "X-Lemma-Client";
+export const CLIENT_HEADER_VALUE = `lemma-sdk-ts/${SDK_VERSION}`;

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "lemma-sdk",
-  "version": "0.2.46",
+  "version": "0.3.0",
   "description": "Official TypeScript SDK for Lemma APIs, optimized around pod-scoped workflows",
+  "license": "Apache-2.0",
+  "author": "Lemma",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,9 +46,9 @@
   ],
   "scripts": {
     "generate:client": "./scripts/generate_openapi_client.sh",
-    "generate:client:hey": "LEMMA_TS_GENERATOR=hey ./scripts/generate_openapi_client.sh",
     "build": "npm run clean && tsc -p tsconfig.json && npm run build:bundle",
-    "build:bundle": "tsc -p tsconfig.bundle.json && node ./scripts/build_browser_bundle.mjs",
+    "build:bundle": "node ./scripts/build_browser_bundle.mjs",
+    "test": "npm run build:bundle && vitest run",
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })\"",
     "registry:build": "shadcn build ./registry.json -o ./public/r",
     "registry:check": "npm run registry:build && node ./scripts/check_registry_blocks.mjs",
@@ -65,10 +67,13 @@
     "supertokens-web-js": "^0.16.0"
   },
   "devDependencies": {
-    "@hey-api/openapi-ts": "^0.73.0",
+    "@types/node": "^24.13.2",
     "@types/react": "^19.2.14",
+    "esbuild": "^0.28.1",
+    "jsdom": "^24.1.1",
     "openapi-typescript-codegen": "^0.29.0",
     "shadcn": "^4.2.0",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "vitest": "^2.0.5"
   }
 }

package/dist/hey_client/client/client.gen.d.ts

@@ -1,2 +0,0 @@
-import type { Client, Config } from './types.gen';
-export declare const createClient: (config?: Config) => Client;

package/dist/hey_client/client/client.gen.js

@@ -1,216 +0,0 @@
-// This file is auto-generated by @hey-api/openapi-ts
-import { createSseClient } from '../core/serverSentEvents.gen';
-import { getValidRequestBody } from '../core/utils.gen';
-import { buildUrl, createConfig, createInterceptors, getParseAs, mergeConfigs, mergeHeaders, setAuthParams, } from './utils.gen';
-export const createClient = (config = {}) => {
-    let _config = mergeConfigs(createConfig(), config);
-    const getConfig = () => ({ ..._config });
-    const setConfig = (config) => {
-        _config = mergeConfigs(_config, config);
-        return getConfig();
-    };
-    const interceptors = createInterceptors();
-    const beforeRequest = async (options) => {
-        const opts = {
-            ..._config,
-            ...options,
-            fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
-            headers: mergeHeaders(_config.headers, options.headers),
-            serializedBody: undefined,
-        };
-        if (opts.security) {
-            await setAuthParams(opts);
-        }
-        if (opts.requestValidator) {
-            await opts.requestValidator(opts);
-        }
-        if (opts.body !== undefined && opts.bodySerializer) {
-            opts.serializedBody = opts.bodySerializer(opts.body);
-        }
-        // remove Content-Type header if body is empty to avoid sending invalid requests
-        if (opts.body === undefined || opts.serializedBody === '') {
-            opts.headers.delete('Content-Type');
-        }
-        const resolvedOpts = opts;
-        const url = buildUrl(resolvedOpts);
-        return { opts: resolvedOpts, url };
-    };
-    const request = async (options) => {
-        const throwOnError = options.throwOnError ?? _config.throwOnError;
-        const responseStyle = options.responseStyle ?? _config.responseStyle;
-        let request;
-        let response;
-        try {
-            const { opts, url } = await beforeRequest(options);
-            const requestInit = {
-                redirect: 'follow',
-                ...opts,
-                body: getValidRequestBody(opts),
-            };
-            request = new Request(url, requestInit);
-            for (const fn of interceptors.request.fns) {
-                if (fn) {
-                    request = await fn(request, opts);
-                }
-            }
-            // fetch must be assigned here, otherwise it would throw the error:
-            // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
-            const _fetch = opts.fetch;
-            response = await _fetch(request);
-            for (const fn of interceptors.response.fns) {
-                if (fn) {
-                    response = await fn(response, request, opts);
-                }
-            }
-            const result = {
-                request,
-                response,
-            };
-            if (response.ok) {
-                const parseAs = (opts.parseAs === 'auto'
-                    ? getParseAs(response.headers.get('Content-Type'))
-                    : opts.parseAs) ?? 'json';
-                if (response.status === 204 || response.headers.get('Content-Length') === '0') {
-                    let emptyData;
-                    switch (parseAs) {
-                        case 'arrayBuffer':
-                        case 'blob':
-                        case 'text':
-                            emptyData = await response[parseAs]();
-                            break;
-                        case 'formData':
-                            emptyData = new FormData();
-                            break;
-                        case 'stream':
-                            emptyData = response.body;
-                            break;
-                        case 'json':
-                        default:
-                            emptyData = {};
-                            break;
-                    }
-                    return opts.responseStyle === 'data'
-                        ? emptyData
-                        : {
-                            data: emptyData,
-                            ...result,
-                        };
-                }
-                let data;
-                switch (parseAs) {
-                    case 'arrayBuffer':
-                    case 'blob':
-                    case 'formData':
-                    case 'text':
-                        data = await response[parseAs]();
-                        break;
-                    case 'json': {
-                        // Some servers return 200 with no Content-Length and empty body.
-                        // response.json() would throw; read as text and parse if non-empty.
-                        const text = await response.text();
-                        data = text ? JSON.parse(text) : {};
-                        break;
-                    }
-                    case 'stream':
-                        return opts.responseStyle === 'data'
-                            ? response.body
-                            : {
-                                data: response.body,
-                                ...result,
-                            };
-                }
-                if (parseAs === 'json') {
-                    if (opts.responseValidator) {
-                        await opts.responseValidator(data);
-                    }
-                    if (opts.responseTransformer) {
-                        data = await opts.responseTransformer(data);
-                    }
-                }
-                return opts.responseStyle === 'data'
-                    ? data
-                    : {
-                        data,
-                        ...result,
-                    };
-            }
-            const textError = await response.text();
-            let jsonError;
-            try {
-                jsonError = JSON.parse(textError);
-            }
-            catch {
-                // noop
-            }
-            throw jsonError ?? textError;
-        }
-        catch (error) {
-            let finalError = error;
-            for (const fn of interceptors.error.fns) {
-                if (fn) {
-                    finalError = await fn(finalError, response, request, options);
-                }
-            }
-            finalError = finalError || {};
-            if (throwOnError) {
-                throw finalError;
-            }
-            // TODO: we probably want to return error and improve types
-            return responseStyle === 'data'
-                ? undefined
-                : {
-                    error: finalError,
-                    request,
-                    response,
-                };
-        }
-    };
-    const makeMethodFn = (method) => (options) => request({ ...options, method });
-    const makeSseFn = (method) => async (options) => {
-        const { opts, url } = await beforeRequest(options);
-        return createSseClient({
-            ...opts,
-            body: opts.body,
-            method,
-            onRequest: async (url, init) => {
-                let request = new Request(url, init);
-                for (const fn of interceptors.request.fns) {
-                    if (fn) {
-                        request = await fn(request, opts);
-                    }
-                }
-                return request;
-            },
-            serializedBody: getValidRequestBody(opts),
-            url,
-        });
-    };
-    const _buildUrl = (options) => buildUrl({ ..._config, ...options });
-    return {
-        buildUrl: _buildUrl,
-        connect: makeMethodFn('CONNECT'),
-        delete: makeMethodFn('DELETE'),
-        get: makeMethodFn('GET'),
-        getConfig,
-        head: makeMethodFn('HEAD'),
-        interceptors,
-        options: makeMethodFn('OPTIONS'),
-        patch: makeMethodFn('PATCH'),
-        post: makeMethodFn('POST'),
-        put: makeMethodFn('PUT'),
-        request,
-        setConfig,
-        sse: {
-            connect: makeSseFn('CONNECT'),
-            delete: makeSseFn('DELETE'),
-            get: makeSseFn('GET'),
-            head: makeSseFn('HEAD'),
-            options: makeSseFn('OPTIONS'),
-            patch: makeSseFn('PATCH'),
-            post: makeSseFn('POST'),
-            put: makeSseFn('PUT'),
-            trace: makeSseFn('TRACE'),
-        },
-        trace: makeMethodFn('TRACE'),
-    };
-};

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

@@ -1,10 +0,0 @@
-export type { Auth } from '../core/auth.gen';
-export type { QuerySerializerOptions } from '../core/bodySerializer.gen';
-export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.gen';
-export { buildClientParams } from '../core/params.gen';
-export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen';
-export type { ServerSentEventsResult } from '../core/serverSentEvents.gen';
-export type { ClientMeta } from '../core/types.gen';
-export { createClient } from './client.gen';
-export type { Client, ClientOptions, Config, CreateClientConfig, Options, RequestOptions, RequestResult, ResolvedRequestOptions, ResponseStyle, TDataShape, } from './types.gen';
-export { createConfig, mergeHeaders } from './utils.gen';

package/dist/hey_client/client/index.js

@@ -1,6 +0,0 @@
-// This file is auto-generated by @hey-api/openapi-ts
-export { formDataBodySerializer, jsonBodySerializer, urlSearchParamsBodySerializer, } from '../core/bodySerializer.gen';
-export { buildClientParams } from '../core/params.gen';
-export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen';
-export { createClient } from './client.gen';
-export { createConfig, mergeHeaders } from './utils.gen';

package/dist/hey_client/client/types.gen.d.ts

@@ -1,120 +0,0 @@
-import type { Auth } from '../core/auth.gen';
-import type { ServerSentEventsOptions, ServerSentEventsResult } from '../core/serverSentEvents.gen';
-import type { Client as CoreClient, Config as CoreConfig } from '../core/types.gen';
-import type { Middleware } from './utils.gen';
-export type ResponseStyle = 'data' | 'fields';
-export interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, CoreConfig {
-    /**
-     * Base URL for all requests made by this client.
-     */
-    baseUrl?: T['baseUrl'];
-    /**
-     * Fetch API implementation. You can use this option to provide a custom
-     * fetch instance.
-     *
-     * @default globalThis.fetch
-     */
-    fetch?: typeof fetch;
-    /**
-     * Please don't use the Fetch client for Next.js applications. The `next`
-     * options won't have any effect.
-     *
-     * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
-     */
-    next?: never;
-    /**
-     * Return the response data parsed in a specified format. By default, `auto`
-     * will infer the appropriate method from the `Content-Type` response header.
-     * You can override this behavior with any of the {@link Body} methods.
-     * Select `stream` if you don't want to parse response data at all.
-     *
-     * @default 'auto'
-     */
-    parseAs?: 'arrayBuffer' | 'auto' | 'blob' | 'formData' | 'json' | 'stream' | 'text';
-    /**
-     * Should we return only data or multiple fields (data, error, response, etc.)?
-     *
-     * @default 'fields'
-     */
-    responseStyle?: ResponseStyle;
-    /**
-     * Throw an error instead of returning it in the response?
-     *
-     * @default false
-     */
-    throwOnError?: T['throwOnError'];
-}
-export interface RequestOptions<TData = unknown, TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
-    responseStyle: TResponseStyle;
-    throwOnError: ThrowOnError;
-}>, Pick<ServerSentEventsOptions<TData>, 'onRequest' | 'onSseError' | 'onSseEvent' | 'sseDefaultRetryDelay' | 'sseMaxRetryAttempts' | 'sseMaxRetryDelay'> {
-    /**
-     * Any body that you want to add to your request.
-     *
-     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
-     */
-    body?: unknown;
-    path?: Record<string, unknown>;
-    query?: Record<string, unknown>;
-    /**
-     * Security mechanism(s) to use for the request.
-     */
-    security?: ReadonlyArray<Auth>;
-    url: Url;
-}
-export interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
-    headers: Headers;
-    serializedBody?: string;
-}
-export type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = ThrowOnError extends true ? Promise<TResponseStyle extends 'data' ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
-    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
-    request: Request;
-    response: Response;
-}> : Promise<TResponseStyle extends 'data' ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
-    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
-    error: undefined;
-} | {
-    data: undefined;
-    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
-}) & {
-    /** request may be undefined, because error may be from building the request object itself */
-    request?: Request;
-    /** response may be undefined, because error may be from building the request object itself or from a network error */
-    response?: Response;
-}>;
-export interface ClientOptions {
-    baseUrl?: string;
-    responseStyle?: ResponseStyle;
-    throwOnError?: boolean;
-}
-type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
-type SseFn = <TData = unknown, _TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, 'method'>) => Promise<ServerSentEventsResult<TData>>;
-type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
-type BuildUrlFn = <TData extends {
-    body?: unknown;
-    path?: Record<string, unknown>;
-    query?: Record<string, unknown>;
-    url: string;
-}>(options: TData & Options<TData>) => string;
-export type Client = CoreClient<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
-    interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
-};
-/**
- * The `createClientConfig()` function will be called on client initialization
- * and the returned object will become the client's initial configuration.
- *
- * You may want to initialize your client this way instead of calling
- * `setConfig()`. This is useful for example if you're using Next.js
- * to ensure your client always has the correct values.
- */
-export type CreateClientConfig<T extends ClientOptions = ClientOptions> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
-export interface TDataShape {
-    body?: unknown;
-    headers?: unknown;
-    path?: unknown;
-    query?: unknown;
-    url: string;
-}
-type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
-export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
-export {};

package/dist/hey_client/client/types.gen.js

@@ -1,2 +0,0 @@
-// This file is auto-generated by @hey-api/openapi-ts
-export {};

package/dist/hey_client/client/utils.gen.d.ts

@@ -1,37 +0,0 @@
-import type { QuerySerializerOptions } from '../core/bodySerializer.gen';
-import type { Client, ClientOptions, Config, RequestOptions } from './types.gen';
-export declare const createQuerySerializer: <T = unknown>({ parameters, ...args }?: QuerySerializerOptions) => ((queryParams: T) => string);
-/**
- * Infers parseAs value from provided Content-Type header.
- */
-export declare const getParseAs: (contentType: string | null) => Exclude<Config["parseAs"], "auto">;
-export declare function setAuthParams(options: Pick<RequestOptions, 'auth' | 'query' | 'security'> & {
-    headers: Headers;
-}): Promise<void>;
-export declare const buildUrl: Client['buildUrl'];
-export declare const mergeConfigs: (a: Config, b: Config) => Config;
-export declare const mergeHeaders: (...headers: Array<Required<Config>["headers"] | undefined>) => Headers;
-type ErrInterceptor<Err, Res, Req, Options> = (error: Err, 
-/** response may be undefined due to a network error where no response object is produced */
-response: Res | undefined, 
-/** request may be undefined, because error may be from building the request object itself */
-request: Req | undefined, options: Options) => Err | Promise<Err>;
-type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
-type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
-declare class Interceptors<Interceptor> {
-    fns: Array<Interceptor | null>;
-    clear(): void;
-    eject(id: number | Interceptor): void;
-    exists(id: number | Interceptor): boolean;
-    getInterceptorIndex(id: number | Interceptor): number;
-    update(id: number | Interceptor, fn: Interceptor): number | Interceptor | false;
-    use(fn: Interceptor): number;
-}
-export interface Middleware<Req, Res, Err, Options> {
-    error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
-    request: Interceptors<ReqInterceptor<Req, Options>>;
-    response: Interceptors<ResInterceptor<Res, Req, Options>>;
-}
-export declare const createInterceptors: <Req, Res, Err, Options>() => Middleware<Req, Res, Err, Options>;
-export declare const createConfig: <T extends ClientOptions = ClientOptions>(override?: Config<Omit<ClientOptions, keyof T> & T>) => Config<Omit<ClientOptions, keyof T> & T>;
-export {};