@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/server/types.d.ts

@@ -1,15 +1,15 @@
 import { z } from "zod";
 export declare const ConnectionModeSchema: z.ZodEnum<{
-    credentials: "credentials";
     none: "none";
+    credentials: "credentials";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
 }>;
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
     mode: z.ZodEnum<{
-        credentials: "credentials";
         none: "none";
+        credentials: "credentials";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
     }>;
@@ -21,11 +21,12 @@ export declare const OperationConnectionSchema: z.ZodObject<{
 export declare const OperationRequestSchema: z.ZodObject<{
     requestId: z.ZodString;
     input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    connectionId: z.ZodOptional<z.ZodString>;
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            credentials: "credentials";
             none: "none";
+            credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
         }>;
@@ -54,21 +55,21 @@ export declare const OperationSuccessResponseSchema: z.ZodObject<{
             stale: z.ZodBoolean;
             keys: z.ZodArray<z.ZodString>;
             source: z.ZodOptional<z.ZodEnum<{
-                loader: "loader";
-                memory: "memory";
                 mixed: "mixed";
                 redis: "redis";
+                memory: "memory";
+                loader: "loader";
             }>>;
         }, z.core.$strip>>;
         retry: z.ZodOptional<z.ZodObject<{
             attempts: z.ZodNumber;
             retries: z.ZodNumber;
             preset: z.ZodOptional<z.ZodEnum<{
-                aggressive_read: "aggressive_read";
                 off: "off";
-                rate_limit_aware: "rate_limit_aware";
-                safe_read: "safe_read";
                 transport_transient: "transport_transient";
+                safe_read: "safe_read";
+                aggressive_read: "aggressive_read";
+                rate_limit_aware: "rate_limit_aware";
             }>>;
             transport: z.ZodEnum<{
                 native: "native";
@@ -100,8 +101,8 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            credentials: "credentials";
             none: "none";
+            credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
         }>;

package/dist/server/types.js

@@ -1,11 +1,6 @@
 import { z } from "zod";
-import { HttpRetryPreset } from "../types";
-export const ConnectionModeSchema = z.enum([
-    "oauth2",
-    "credentials",
-    "platform-managed",
-    "none",
-]);
+import { HttpRetryPreset } from "../types.js";
+export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
 export const OperationConnectionSchema = z.object({
     id: z.string(),
     mode: ConnectionModeSchema,
@@ -17,6 +12,7 @@ export const OperationConnectionSchema = z.object({
 export const OperationRequestSchema = z.object({
     requestId: z.string(),
     input: z.record(z.string(), z.unknown()),
+    connectionId: z.string().optional(),
     connection: OperationConnectionSchema.optional(),
     headers: z.record(z.string(), z.string()).optional(),
     trace: z.record(z.string(), z.string()).optional(),

package/dist/stateful/errors.d.ts

@@ -0,0 +1,14 @@
+export type StatefulControlPlaneOperation = "resolve" | "acquire" | "renew" | "release";
+export declare class StatefulControlPlaneError extends Error {
+    readonly code: string;
+    readonly operation: StatefulControlPlaneOperation;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(input: {
+        readonly code: string;
+        readonly message: string;
+        readonly operation: StatefulControlPlaneOperation;
+        readonly status?: number;
+        readonly cause?: unknown;
+    });
+}

package/dist/stateful/errors.js

@@ -0,0 +1,14 @@
+export class StatefulControlPlaneError extends Error {
+    code;
+    operation;
+    status;
+    cause;
+    constructor(input) {
+        super(input.message);
+        this.name = "StatefulControlPlaneError";
+        this.code = input.code;
+        this.operation = input.operation;
+        this.status = input.status;
+        this.cause = input.cause;
+    }
+}

package/dist/stateful/http-provider-event-emitter.d.ts

@@ -0,0 +1,40 @@
+import type { ProviderEventDeliveryFailureRecorder } from "./provider-event-delivery-failures.js";
+import type { ProviderEventPublisher, ProviderEventPublishOptions, PublishAck } from "./provider-event-pipeline.js";
+import { type ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+import type { ProviderEvent } from "./provider-events.js";
+type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type HttpProviderEventEmitterOptions = {
+    readonly baseUrl: string;
+    readonly secret: string;
+    readonly fetch?: FetchTransport;
+    readonly clock?: () => Date;
+    readonly random?: () => number;
+    readonly metricEmitter?: ProviderEventMetricEmitter;
+    readonly failureRecorder?: ProviderEventDeliveryFailureRecorder;
+    readonly maxBufferedEvents?: number;
+    readonly retryBaseMs?: number;
+    readonly retryMaxMs?: number;
+    readonly maxAttempts?: number;
+    readonly jitterRatio?: number;
+};
+export type ProviderEventFlushReport = {
+    /** Events delivered during this emitter's lifetime. */
+    readonly delivered: number;
+    /** Events permanently dropped during this emitter's lifetime. */
+    readonly failed: number;
+    /** Events still buffered when flush returned. */
+    readonly pending: number;
+};
+/**
+ * Provider-pod HTTP publication with a bounded best-effort delivery guarantee and at-least-once
+ * transport retries. This is not durable at-least-once delivery: buffered events can be lost if
+ * the process is killed. Graceful shutdown should drain the in-memory buffer with flush().
+ */
+export declare class HttpProviderEventEmitter implements ProviderEventPublisher {
+    #private;
+    constructor(options: HttpProviderEventEmitterOptions);
+    publish(event: ProviderEvent, options: ProviderEventPublishOptions): PublishAck;
+    pendingCount(): number;
+    flush(timeoutMs?: number): Promise<ProviderEventFlushReport>;
+}
+export {};

package/dist/stateful/http-provider-event-emitter.js

@@ -0,0 +1,237 @@
+import { statefulSignedHeaders } from "../stateful-signing.js";
+import { NOOP_PROVIDER_EVENT_METRIC_EMITTER, providerEventMetricLabels, } from "./provider-event-pipeline-metrics.js";
+const DEFAULT_MAX_BUFFERED_EVENTS = 1_000;
+const DEFAULT_RETRY_BASE_MS = 500;
+const DEFAULT_RETRY_MAX_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_JITTER_RATIO = 0.2;
+const CONSOLE_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER = {
+    record(failure) {
+        console.error(JSON.stringify({
+            event: "provider_event_delivery_failed",
+            eventId: failure.eventId,
+            reason: failure.reason,
+            attempts: failure.attempts,
+        }));
+    },
+};
+/**
+ * Provider-pod HTTP publication with a bounded best-effort delivery guarantee and at-least-once
+ * transport retries. This is not durable at-least-once delivery: buffered events can be lost if
+ * the process is killed. Graceful shutdown should drain the in-memory buffer with flush().
+ */
+export class HttpProviderEventEmitter {
+    #baseUrl;
+    #secret;
+    #fetch;
+    #clock;
+    #random;
+    #metricEmitter;
+    #failureRecorder;
+    #maxBufferedEvents;
+    #retryBaseMs;
+    #retryMaxMs;
+    #maxAttempts;
+    #jitterRatio;
+    #queue = [];
+    #drainPromise;
+    #deliveredCount = 0;
+    #failedCount = 0;
+    constructor(options) {
+        if (options.baseUrl.trim().length === 0) {
+            throw new Error("Provider event ingest baseUrl is required.");
+        }
+        if (options.secret.trim().length === 0) {
+            throw new Error("Provider event ingest secret is required.");
+        }
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#secret = options.secret;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#clock = options.clock ?? (() => new Date());
+        this.#random = options.random ?? Math.random;
+        this.#metricEmitter = options.metricEmitter ?? NOOP_PROVIDER_EVENT_METRIC_EMITTER;
+        this.#failureRecorder =
+            options.failureRecorder ?? CONSOLE_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER;
+        this.#maxBufferedEvents = positiveInteger(options.maxBufferedEvents ?? DEFAULT_MAX_BUFFERED_EVENTS, "maxBufferedEvents");
+        this.#retryBaseMs = nonnegativeFinite(options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS, "retryBaseMs");
+        this.#retryMaxMs = nonnegativeFinite(options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS, "retryMaxMs");
+        this.#maxAttempts = positiveInteger(options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS, "maxAttempts");
+        this.#jitterRatio = boundedRatio(options.jitterRatio ?? DEFAULT_JITTER_RATIO, "jitterRatio");
+        if (this.#retryMaxMs < this.#retryBaseMs) {
+            throw new Error("Provider event retryMaxMs must be greater than or equal to retryBaseMs.");
+        }
+    }
+    publish(event, options) {
+        const accepted = this.#enqueue(event, options);
+        return { accepted, queued: this.#queue.length };
+    }
+    pendingCount() {
+        return this.#queue.length;
+    }
+    async flush(timeoutMs = 30_000) {
+        nonnegativeFinite(timeoutMs, "flush timeout");
+        this.#ensureDrain();
+        if (this.#queue.length === 0 || timeoutMs === 0)
+            return this.#flushReport();
+        let timeout;
+        const timedOut = new Promise((resolve) => {
+            timeout = setTimeout(resolve, timeoutMs);
+        });
+        await Promise.race([this.#drainPromise ?? Promise.resolve(), timedOut]);
+        if (timeout)
+            clearTimeout(timeout);
+        return this.#flushReport();
+    }
+    #flushReport() {
+        return {
+            delivered: this.#deliveredCount,
+            failed: this.#failedCount,
+            pending: this.#queue.length,
+        };
+    }
+    #enqueue(event, options) {
+        let rawBody;
+        try {
+            rawBody = JSON.stringify({
+                ...event,
+                ownerFence: options.ownerFence,
+            });
+        }
+        catch (error) {
+            this.#recordFailure(event, "attempts_exhausted", 0, error);
+            return false;
+        }
+        if (this.#queue.length >= this.#maxBufferedEvents) {
+            const oldest = this.#queue.shift();
+            if (oldest) {
+                oldest.dropped = true;
+                oldest.abortController?.abort();
+                this.#recordFailure(oldest.event, "buffer_overflow", oldest.attempts);
+            }
+        }
+        this.#queue.push({
+            event,
+            rawBody,
+            idempotencyKey: options.idempotencyKey ?? event.eventId,
+            attempts: 0,
+            dropped: false,
+        });
+        this.#ensureDrain();
+        return true;
+    }
+    #ensureDrain() {
+        if (this.#drainPromise || this.#queue.length === 0)
+            return;
+        this.#drainPromise = Promise.resolve()
+            .then(() => this.#drain())
+            .finally(() => {
+            this.#drainPromise = undefined;
+            if (this.#queue.length > 0)
+                this.#ensureDrain();
+        });
+    }
+    async #drain() {
+        while (this.#queue.length > 0) {
+            const current = this.#queue[0];
+            if (!current)
+                return;
+            current.attempts += 1;
+            const delivered = await this.#send(current);
+            if (current.dropped)
+                continue;
+            if (delivered) {
+                if (this.#queue[0] === current)
+                    this.#queue.shift();
+                this.#deliveredCount += 1;
+                continue;
+            }
+            if (current.attempts >= this.#maxAttempts) {
+                if (this.#queue[0] === current)
+                    this.#queue.shift();
+                this.#recordFailure(current.event, "attempts_exhausted", current.attempts);
+                continue;
+            }
+            await delay(this.#retryDelay(current.attempts));
+        }
+    }
+    async #send(buffered) {
+        const timestamp = this.#clock().toISOString();
+        const path = "/v1/stateful/events";
+        const abortController = new AbortController();
+        buffered.abortController = abortController;
+        try {
+            const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-apifuse-event-id": buffered.idempotencyKey,
+                    ...statefulSignedHeaders({
+                        secret: this.#secret,
+                        timestamp,
+                        rawBody: buffered.rawBody,
+                        method: "POST",
+                        path,
+                    }),
+                },
+                body: buffered.rawBody,
+                signal: abortController.signal,
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (buffered.abortController === abortController) {
+                buffered.abortController = undefined;
+            }
+        }
+    }
+    #retryDelay(attempts) {
+        const exponential = Math.min(this.#retryMaxMs, this.#retryBaseMs * 2 ** Math.max(0, attempts - 1));
+        const jitter = 1 + (this.#random() * 2 - 1) * this.#jitterRatio;
+        return Math.max(0, Math.round(exponential * jitter));
+    }
+    #recordFailure(event, reason, attempts, error) {
+        this.#failedCount += 1;
+        this.#incrementDropMetric(event);
+        try {
+            const recorded = this.#failureRecorder.record({
+                eventId: event.eventId,
+                reason,
+                attempts,
+                failedAt: this.#clock().toISOString(),
+                ...(error ? { error: "Provider event could not be serialized." } : {}),
+            });
+            void Promise.resolve(recorded).catch(() => { });
+        }
+        catch { }
+    }
+    #incrementDropMetric(event, emitter = this.#metricEmitter) {
+        try {
+            emitter.increment("apifuse_stateful_provider_event_drop_total", providerEventMetricLabels(event));
+        }
+        catch { }
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Provider event ${name} must be a positive integer.`);
+    }
+    return value;
+}
+function nonnegativeFinite(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`Provider event ${name} must be a non-negative finite number.`);
+    }
+    return value;
+}
+function boundedRatio(value, name) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`Provider event ${name} must be between 0 and 1.`);
+    }
+    return value;
+}

package/dist/stateful/http-session-owner-registry.d.ts

@@ -0,0 +1,44 @@
+import { StatefulControlPlaneError, type StatefulControlPlaneOperation } from "./errors.js";
+import { type SessionKey } from "./session-key.js";
+import type { AcquireSessionOwnerInput, AcquireSessionOwnerResult, ReleaseSessionOwnerInput, RenewSessionOwnerInput, SessionOwnerRecord, SessionOwnerRegistry } from "./stateful-provider-session-runtime.js";
+type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type SessionOwnerScope = {
+    readonly serviceAccountId: string;
+    readonly providerId: string;
+    readonly connectionId?: string;
+};
+export type HttpSessionOwnerRegistryOptions = {
+    readonly baseUrl: string;
+    readonly secret: string;
+    readonly scope?: SessionOwnerScope;
+    readonly fetch?: FetchTransport;
+    readonly clock?: () => Date;
+    readonly requestTimeoutMs?: number;
+};
+/**
+ * A mutating registry request failed after it may have reached the control plane. Callers must
+ * resolve the session owner and reconcile instead of blindly retrying the mutation.
+ */
+export declare class AmbiguousRegistryOperationError extends StatefulControlPlaneError {
+    readonly ambiguous = true;
+    constructor(input: {
+        readonly operation: Exclude<StatefulControlPlaneOperation, "resolve">;
+        readonly message: string;
+        readonly cause: unknown;
+    });
+}
+export type HttpSessionOwnerRecord = Omit<SessionOwnerRecord, "sessionKey"> & {
+    readonly sessionKey: SessionKey;
+};
+export type HttpAcquireSessionOwnerResult = Omit<AcquireSessionOwnerResult, "record"> & {
+    readonly record: HttpSessionOwnerRecord;
+};
+export declare class HttpSessionOwnerRegistry implements SessionOwnerRegistry {
+    #private;
+    constructor(options: HttpSessionOwnerRegistryOptions);
+    resolve(sessionKey: SessionKey, now?: Date, signal?: AbortSignal): Promise<HttpSessionOwnerRecord | null>;
+    acquire(input: AcquireSessionOwnerInput, signal?: AbortSignal): Promise<HttpAcquireSessionOwnerResult>;
+    renew(input: RenewSessionOwnerInput, signal?: AbortSignal): Promise<HttpSessionOwnerRecord | null>;
+    release(input: ReleaseSessionOwnerInput, signal?: AbortSignal): Promise<boolean>;
+}
+export {};

package/dist/stateful/http-session-owner-registry.js

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { statefulSignedHeaders } from "../stateful-signing.js";
+import { StatefulControlPlaneError } from "./errors.js";
+import { parseSessionKey } from "./session-key.js";
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * A mutating registry request failed after it may have reached the control plane. Callers must
+ * resolve the session owner and reconcile instead of blindly retrying the mutation.
+ */
+export class AmbiguousRegistryOperationError extends StatefulControlPlaneError {
+    ambiguous = true;
+    constructor(input) {
+        super({
+            code: "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+            message: input.message,
+            operation: input.operation,
+            cause: input.cause,
+        });
+        this.name = "AmbiguousRegistryOperationError";
+    }
+}
+const SessionKeySchema = z
+    .string()
+    .min(1)
+    .transform((value, context) => {
+    try {
+        parseSessionKey(value);
+        return value;
+    }
+    catch (error) {
+        context.addIssue({
+            code: "custom",
+            message: error instanceof Error ? error.message : "Invalid canonical session key.",
+        });
+        return z.NEVER;
+    }
+});
+const OwnerRecordSchema = z.object({
+    sessionKey: SessionKeySchema,
+    ownerPodId: z.string().min(1),
+    ownerEndpoint: z.string().min(1),
+    generation: z.number().int().positive(),
+    leaseExpiresAt: z.string().refine(isTimestamp),
+    status: z.enum(["acquiring", "connected", "draining", "expired"]),
+    lastUsedAt: z.string().refine(isTimestamp),
+});
+const AcquireResultSchema = z.object({
+    record: OwnerRecordSchema,
+    acquired: z.boolean(),
+});
+const ResolveResponseSchema = z.union([
+    OwnerRecordSchema,
+    z.object({ record: OwnerRecordSchema }).transform((value) => value.record),
+    z.object({ data: OwnerRecordSchema }).transform((value) => value.data),
+]);
+const AcquireResponseSchema = z.union([
+    AcquireResultSchema,
+    z.object({ data: AcquireResultSchema }).transform((value) => value.data),
+]);
+const RenewResponseSchema = z.union([
+    OwnerRecordSchema.nullable(),
+    z.object({ record: OwnerRecordSchema.nullable() }).transform((value) => value.record),
+    z.object({ data: OwnerRecordSchema.nullable() }).transform((value) => value.data),
+]);
+const ReleaseResponseSchema = z.union([
+    z.boolean(),
+    z.object({ released: z.boolean() }).transform((value) => value.released),
+    z.object({ data: z.boolean() }).transform((value) => value.data),
+]);
+export class HttpSessionOwnerRegistry {
+    #baseUrl;
+    #secret;
+    #scope;
+    #fetch;
+    #clock;
+    #requestTimeoutMs;
+    constructor(options) {
+        if (options.baseUrl.trim().length === 0) {
+            throw new Error("Stateful control-plane baseUrl is required.");
+        }
+        if (options.secret.trim().length === 0) {
+            throw new Error("Stateful control-plane secret is required.");
+        }
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#secret = options.secret;
+        this.#scope = options.scope;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#clock = options.clock ?? (() => new Date());
+        this.#requestTimeoutMs = positiveInteger(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, "requestTimeoutMs");
+    }
+    async resolve(sessionKey, now, signal) {
+        const response = await this.#post("resolve", {
+            ...this.#scope,
+            sessionKey,
+            ...(now ? { now: now.toISOString() } : {}),
+        }, signal);
+        if (response.status === 404)
+            return null;
+        return this.#parse(response, "resolve", ResolveResponseSchema);
+    }
+    async acquire(input, signal) {
+        const response = await this.#post("acquire", {
+            ...this.#scope,
+            ...input,
+            ...(input.now ? { now: input.now.toISOString() } : {}),
+        }, signal);
+        return this.#parse(response, "acquire", AcquireResponseSchema);
+    }
+    async renew(input, signal) {
+        const response = await this.#post("renew", {
+            ...this.#scope,
+            ...input,
+            ...(input.now ? { now: input.now.toISOString() } : {}),
+        }, signal);
+        return this.#parse(response, "renew", RenewResponseSchema);
+    }
+    async release(input, signal) {
+        const response = await this.#post("release", {
+            ...this.#scope,
+            ...input,
+        }, signal);
+        return this.#parse(response, "release", ReleaseResponseSchema);
+    }
+    async #post(operation, body, callerSignal) {
+        callerSignal?.throwIfAborted();
+        const rawBody = JSON.stringify(body);
+        const timestamp = this.#clock().toISOString();
+        const path = `/v1/stateful/sessions/owners/${operation}`;
+        const timeoutSignal = AbortSignal.timeout(this.#requestTimeoutMs);
+        const signal = AbortSignal.any(callerSignal ? [callerSignal, timeoutSignal] : [timeoutSignal]);
+        try {
+            return await this.#fetch(`${this.#baseUrl}${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...statefulSignedHeaders({
+                        secret: this.#secret,
+                        timestamp,
+                        rawBody,
+                        method: "POST",
+                        path,
+                    }),
+                },
+                body: rawBody,
+                signal,
+            });
+        }
+        catch (cause) {
+            const timedOut = timeoutSignal.aborted && !callerSignal?.aborted;
+            if (operation !== "resolve") {
+                throw new AmbiguousRegistryOperationError({
+                    operation,
+                    message: timedOut
+                        ? `Stateful control-plane ${operation} timed out after ${this.#requestTimeoutMs}ms; resolve the session owner and reconcile before retrying.`
+                        : `Stateful control-plane ${operation} request failed after it may have committed; resolve the session owner and reconcile before retrying.`,
+                    cause,
+                });
+            }
+            throw new StatefulControlPlaneError({
+                code: "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+                message: timedOut
+                    ? `Stateful control-plane resolve timed out after ${this.#requestTimeoutMs}ms; retry resolve or check control-plane availability.`
+                    : "Stateful control-plane resolve request failed.",
+                operation,
+                cause,
+            });
+        }
+    }
+    async #parse(response, operation, schema) {
+        if (!response.ok) {
+            throw new StatefulControlPlaneError({
+                code: "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+                message: `Stateful control-plane ${operation} returned status ${response.status}.`,
+                operation,
+                status: response.status,
+            });
+        }
+        const rawBody = await response.text();
+        let body;
+        try {
+            body = JSON.parse(rawBody);
+        }
+        catch (cause) {
+            throw invalidResponse(operation, response.status, cause);
+        }
+        const parsed = schema.safeParse(body);
+        if (!parsed.success) {
+            throw invalidResponse(operation, response.status, parsed.error);
+        }
+        return parsed.data;
+    }
+}
+function invalidResponse(operation, status, cause) {
+    return new StatefulControlPlaneError({
+        code: "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+        message: `Stateful control-plane ${operation} returned an invalid response.`,
+        operation,
+        status,
+        cause,
+    });
+}
+function isTimestamp(value) {
+    return Number.isFinite(Date.parse(value));
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Stateful control-plane ${name} must be a positive integer.`);
+    }
+    return value;
+}

package/dist/stateful/index.d.ts

@@ -0,0 +1,18 @@
+export * from "../stateful-signing.js";
+export * from "./errors.js";
+export * from "./http-provider-event-emitter.js";
+export * from "./http-session-owner-registry.js";
+export * from "./provider-event-delivery-failures.js";
+export * from "./provider-event-pipeline-metrics.js";
+export * from "./provider-event-pipeline.js";
+export * from "./provider-events.js";
+export * from "./session-key.js";
+export * from "./stateful-provider-adapter-context.js";
+export * from "./stateful-provider-adapter-metrics.js";
+export * from "./stateful-provider-adapter.js";
+export * from "./stateful-provider-observability.js";
+export * from "./stateful-provider-owner-forwarder.js";
+export * from "./stateful-provider-runtime-context.js";
+export * from "./stateful-provider-runtime-executor.js";
+export * from "./stateful-provider-session-routing.js";
+export * from "./stateful-provider-session-runtime.js";