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

package/dist/stateful/index.js

@@ -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";

package/dist/stateful/provider-event-delivery-failures.d.ts

@@ -0,0 +1,32 @@
+export type ProviderWebhookFailureTotals = {
+    retryingCount: number;
+    failedCount: number;
+    deadLetteredCount: number;
+};
+export declare function failureForStatus(statusCode: number): {
+    readonly statusCode: number;
+    readonly error?: string;
+};
+export declare function failureForError(error: unknown): {
+    readonly statusCode?: number;
+    readonly error: string;
+};
+export declare function countProviderWebhookFailure(totals: ProviderWebhookFailureTotals, status: string): void;
+export type ProviderEventDeliveryFailureReason = "buffer_overflow" | "attempts_exhausted";
+export type ProviderEventDeliveryFailure = {
+    readonly eventId: string;
+    readonly reason: ProviderEventDeliveryFailureReason;
+    readonly attempts: number;
+    readonly failedAt: string;
+    readonly error?: string;
+};
+export interface ProviderEventDeliveryFailureRecorder {
+    record(failure: ProviderEventDeliveryFailure): void | Promise<void>;
+}
+export declare const NOOP_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER: {
+    record(): void;
+};
+export declare class RecordingProviderEventDeliveryFailureRecorder implements ProviderEventDeliveryFailureRecorder {
+    readonly failures: ProviderEventDeliveryFailure[];
+    record(failure: ProviderEventDeliveryFailure): void;
+}

package/dist/stateful/provider-event-delivery-failures.js

@@ -0,0 +1,43 @@
+export function failureForStatus(statusCode) {
+    if (statusCode >= 300 && statusCode < 400) {
+        return { statusCode, error: "Webhook redirects are not followed." };
+    }
+    return { statusCode };
+}
+export function failureForError(error) {
+    if (isPublicValidationError(error)) {
+        return { statusCode: 400, error: error.message };
+    }
+    return { error: publicWorkerError(error) };
+}
+export function countProviderWebhookFailure(totals, status) {
+    if (status === "retrying") {
+        totals.retryingCount += 1;
+        return;
+    }
+    if (status === "dead_lettered") {
+        totals.deadLetteredCount += 1;
+        return;
+    }
+    totals.failedCount += 1;
+}
+export const NOOP_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER = {
+    record() { },
+};
+export class RecordingProviderEventDeliveryFailureRecorder {
+    failures = [];
+    record(failure) {
+        this.failures.push(failure);
+    }
+}
+function publicWorkerError(error) {
+    if (isPublicValidationError(error))
+        return error.message;
+    if (error instanceof Error && error.message) {
+        return "Webhook delivery request failed.";
+    }
+    return "Webhook delivery failed.";
+}
+function isPublicValidationError(error) {
+    return error instanceof Error && error.name.endsWith("ValidationError");
+}

package/dist/stateful/provider-event-pipeline-metrics.d.ts

@@ -0,0 +1,46 @@
+import type { ProviderEvent } from "./provider-events.js";
+export declare const PROVIDER_EVENT_METRIC_NAMES: readonly ["apifuse_stateful_provider_event_append_total", "apifuse_stateful_provider_event_dedupe_total", "apifuse_stateful_provider_event_drop_total", "apifuse_stateful_provider_webhook_enqueue_total", "apifuse_stateful_provider_webhook_fanout_recovered_total", "apifuse_stateful_provider_webhook_delivered_total", "apifuse_stateful_provider_webhook_retry_total", "apifuse_stateful_provider_webhook_dead_letter_total", "apifuse_stateful_provider_webhook_canceled_total", "apifuse_stateful_provider_webhook_latency_ms"];
+export type ProviderEventMetricName = (typeof PROVIDER_EVENT_METRIC_NAMES)[number];
+export type ProviderEventMetricLabelInput = {
+    readonly eventId?: string;
+    readonly deliveryId?: string;
+    readonly providerId?: string;
+    readonly connectionId?: string;
+    readonly serviceAccountId?: string;
+    readonly eventType?: string;
+    readonly subjectKind?: string;
+    readonly subjectId?: string;
+    readonly sessionKey?: string;
+    readonly generation?: number | string;
+};
+export interface ProviderEventMetricEmitter {
+    increment(name: ProviderEventMetricName, labels?: ProviderEventMetricLabelInput, value?: number): void;
+    observe(name: ProviderEventMetricName, labels: ProviderEventMetricLabelInput, value: number): void;
+}
+export declare const NOOP_PROVIDER_EVENT_METRIC_EMITTER: {
+    increment(): void;
+    observe(): void;
+};
+export declare function providerEventMetricLabels(event: ProviderEvent): {
+    eventId: string;
+    providerId: string;
+    connectionId: string | undefined;
+    serviceAccountId: string | undefined;
+    eventType: string;
+    subjectKind: string | undefined;
+    subjectId: string | undefined;
+    sessionKey: string;
+    generation: number;
+};
+export declare function providerWebhookDeliveryMetricLabels(delivery: {
+    readonly deliveryId: string;
+}): {
+    deliveryId: string;
+};
+export declare function emitProviderWebhookDeliveryFailureMetric(metricEmitter: ProviderEventMetricEmitter, delivery: {
+    readonly deliveryId: string;
+}, status: string): void;
+export declare function providerWebhookDeliveryLatencyMs(delivery: {
+    readonly lastAttemptAt?: string;
+    readonly nextAttemptAt: string;
+}, now: string): number;

package/dist/stateful/provider-event-pipeline-metrics.js

@@ -0,0 +1,48 @@
+export const PROVIDER_EVENT_METRIC_NAMES = [
+    "apifuse_stateful_provider_event_append_total",
+    "apifuse_stateful_provider_event_dedupe_total",
+    "apifuse_stateful_provider_event_drop_total",
+    "apifuse_stateful_provider_webhook_enqueue_total",
+    "apifuse_stateful_provider_webhook_fanout_recovered_total",
+    "apifuse_stateful_provider_webhook_delivered_total",
+    "apifuse_stateful_provider_webhook_retry_total",
+    "apifuse_stateful_provider_webhook_dead_letter_total",
+    "apifuse_stateful_provider_webhook_canceled_total",
+    "apifuse_stateful_provider_webhook_latency_ms",
+];
+export const NOOP_PROVIDER_EVENT_METRIC_EMITTER = {
+    increment() { },
+    observe() { },
+};
+export function providerEventMetricLabels(event) {
+    return {
+        eventId: event.eventId,
+        providerId: event.providerId,
+        connectionId: event.connectionId,
+        serviceAccountId: event.serviceAccountId,
+        eventType: event.eventType,
+        subjectKind: event.subject?.kind,
+        subjectId: event.subject?.id,
+        sessionKey: event.session.sessionKey,
+        generation: event.session.generation,
+    };
+}
+export function providerWebhookDeliveryMetricLabels(delivery) {
+    return { deliveryId: delivery.deliveryId };
+}
+export function emitProviderWebhookDeliveryFailureMetric(metricEmitter, delivery, status) {
+    if (status === "retrying") {
+        metricEmitter.increment("apifuse_stateful_provider_webhook_retry_total", providerWebhookDeliveryMetricLabels(delivery));
+        return;
+    }
+    if (status === "dead_lettered") {
+        metricEmitter.increment("apifuse_stateful_provider_webhook_dead_letter_total", providerWebhookDeliveryMetricLabels(delivery));
+    }
+}
+export function providerWebhookDeliveryLatencyMs(delivery, now) {
+    const startedAt = Date.parse(delivery.lastAttemptAt ?? delivery.nextAttemptAt);
+    const completedAt = Date.parse(now);
+    if (!Number.isFinite(startedAt) || !Number.isFinite(completedAt))
+        return 0;
+    return Math.max(0, completedAt - startedAt);
+}

package/dist/stateful/provider-event-pipeline.d.ts

@@ -0,0 +1,50 @@
+import type { ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+import type { ProviderEvent } from "./provider-events.js";
+import type { SessionKey } from "./session-key.js";
+export type { ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+export type ProviderEventOwnerFence = {
+    readonly ownerPodId: string;
+    readonly ownerEndpoint: string;
+    readonly sessionKey: SessionKey;
+    readonly generation: number;
+};
+export type ProviderEventPublishOptions = {
+    /** Required ownership proof forwarded to the durable platform write boundary. */
+    readonly ownerFence: ProviderEventOwnerFence;
+    /** Overrides the transport idempotency key; defaults to the event id. */
+    readonly idempotencyKey?: string;
+};
+export type PublishAck = {
+    /** Whether this event was accepted into the pod-local retry buffer. */
+    readonly accepted: boolean;
+    /** Number of events currently held in the pod-local retry buffer. */
+    readonly queued: number;
+};
+/** Fire-and-forget publication from a provider pod into the platform ingest boundary. */
+export interface ProviderEventPublisher {
+    publish(event: ProviderEvent, options: ProviderEventPublishOptions): PublishAck;
+}
+export type AppendProviderEventAndEnqueueWebhooksResult = {
+    readonly appended: boolean;
+    readonly appendedCount: number;
+    readonly matchedSubscriptionCount: number;
+    readonly enqueuedCount: number;
+    readonly recoveredFanoutCount?: number;
+    readonly fenced?: boolean;
+};
+export type ProviderEventPipelineAppendOptions = {
+    readonly now?: string;
+    readonly idFactory?: () => string;
+    readonly metricEmitter?: ProviderEventMetricEmitter;
+    readonly beforeAppend?: () => Promise<boolean> | boolean;
+    readonly ownerFence?: ProviderEventOwnerFence;
+};
+/**
+ * Durable append-and-fanout contract implemented on the platform side.
+ *
+ * Provider-pod code must depend on ProviderEventPublisher, never ProviderEventPipeline: a pod-local
+ * publisher cannot truthfully report a durable append or downstream webhook fanout.
+ */
+export interface ProviderEventPipeline {
+    appendAndFanout(event: ProviderEvent, options?: ProviderEventPipelineAppendOptions): Promise<AppendProviderEventAndEnqueueWebhooksResult>;
+}

package/dist/stateful/provider-event-pipeline.js

@@ -0,0 +1 @@
+export {};

package/dist/stateful/provider-events.d.ts

@@ -0,0 +1,101 @@
+export type ProviderEventSubject = {
+    /** Provider-defined resource category, for example `message`, `mailbox`, or `browser-context`. */
+    kind: string;
+    id: string;
+};
+export type ProviderEventSession = {
+    /** Canonical logical session identity shared by every stateful provider. */
+    sessionKey: string;
+    /** Ownership generation shared by every stateful provider for stale-event fencing. */
+    generation: number;
+};
+export interface ProviderEvent<TPayload = Record<string, unknown>> {
+    /** Universal stable identity used for transport retries and deduplication. */
+    eventId: string;
+    /** Universal provider namespace needed to route and interpret the event. */
+    providerId: string;
+    /** Optional because mailbox/browser protocols may not expose an API connection identity. */
+    connectionId?: string;
+    /** Optional because not every provider session maps to a platform service account. */
+    serviceAccountId?: string;
+    /** Universal provider-defined event classification. */
+    eventType: string;
+    /** Optional for protocol-level events without a single resource subject. */
+    subject?: ProviderEventSubject;
+    /** Optional when the upstream protocol does not provide an occurrence timestamp. */
+    occurredAt?: string;
+    /** Universal SDK observation time used for ordering and lag measurement. */
+    observedAt: string;
+    /** Universal JSON data envelope; protocols without data use an empty object. */
+    payload: TPayload;
+    /** Universal stateful ownership fence for rejecting events from stale sessions. */
+    session: ProviderEventSession;
+    providerCursor?: string;
+    dedupeKey?: string;
+    rawRef?: string;
+}
+export type ProviderEventIdFactory = () => string;
+export type ProviderEventClock = () => Date;
+export type BuildProviderEventInput<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<ProviderEvent<TPayload>, "eventId" | "observedAt"> & {
+    eventId?: string;
+    observedAt?: string;
+    clock?: ProviderEventClock;
+    idFactory?: ProviderEventIdFactory;
+    maxPayloadBytes?: number;
+    shouldRedactPayload?: boolean;
+    /** Provider-specific credential key patterns added to the conservative SDK defaults. */
+    redactionPatterns?: readonly RegExp[];
+};
+export type ProviderEventListOptions = {
+    providerId?: string;
+    connectionId?: string;
+    eventType?: string;
+    subjectKind?: string;
+    subjectId?: string;
+    afterObservedAt?: string;
+    limit?: number;
+};
+export type ProviderEventAppendResult = {
+    event: ProviderEvent;
+    appended: boolean;
+};
+export interface ProviderEventLog {
+    append(event: ProviderEvent): Promise<ProviderEventAppendResult>;
+    get(eventId: string): Promise<ProviderEvent | null>;
+    list(options?: ProviderEventListOptions): Promise<ProviderEvent[]>;
+}
+export type ProviderEventEmitterDefaults = {
+    providerId: string;
+    connectionId?: string;
+    serviceAccountId?: string;
+    session: ProviderEventSession;
+    clock?: ProviderEventClock;
+    idFactory?: ProviderEventIdFactory;
+    maxPayloadBytes?: number;
+    shouldRedactPayload?: boolean;
+    redactionPatterns?: readonly RegExp[];
+};
+export type ProviderEventEmitterInput<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<BuildProviderEventInput<TPayload>, "providerId" | "connectionId" | "serviceAccountId" | "session"> & {
+    providerId?: string;
+    connectionId?: string;
+    serviceAccountId?: string;
+    session?: ProviderEventSession;
+};
+export declare class ProviderEventValidationError extends Error {
+    constructor(message: string);
+}
+export declare function buildProviderEvent<TPayload extends Record<string, unknown> = Record<string, unknown>>(input: BuildProviderEventInput<TPayload>): ProviderEvent<TPayload>;
+export declare function redactProviderEventPayload<TPayload>(payload: TPayload, extraPatterns?: readonly RegExp[]): TPayload;
+export declare function isStaleProviderEvent(event: ProviderEvent, currentGeneration: number): boolean;
+export declare class InMemoryProviderEventLog implements ProviderEventLog {
+    #private;
+    append(event: ProviderEvent): Promise<ProviderEventAppendResult>;
+    get(eventId: string): Promise<ProviderEvent | null>;
+    list(options?: ProviderEventListOptions): Promise<ProviderEvent[]>;
+}
+export declare class ProviderEventEmitter {
+    #private;
+    constructor(log: ProviderEventLog, defaults: ProviderEventEmitterDefaults);
+    emit<TPayload extends Record<string, unknown> = Record<string, unknown>>(input: ProviderEventEmitterInput<TPayload>): Promise<ProviderEventAppendResult>;
+}
+export declare function randomProviderEventId(): string;

package/dist/stateful/provider-events.js

@@ -0,0 +1,289 @@
+import { createHash, randomUUID } from "node:crypto";
+const DEFAULT_MAX_PAYLOAD_BYTES = 256 * 1024;
+const REDACTED_VALUE = "[REDACTED]";
+const CREDENTIAL_KEY_PATTERN = /(?:token|password|secret|credential|cookie|authorization)/i;
+export class ProviderEventValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProviderEventValidationError";
+    }
+}
+export function buildProviderEvent(input) {
+    validatePayload(input.payload, input.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES);
+    const observedAt = input.observedAt ?? input.clock?.().toISOString() ?? new Date().toISOString();
+    const payload = input.shouldRedactPayload === false
+        ? input.payload
+        : redactProviderEventPayload(input.payload, input.redactionPatterns);
+    const event = {
+        eventId: input.eventId ?? buildEventId({ ...input, observedAt }),
+        providerId: input.providerId,
+        eventType: input.eventType,
+        observedAt,
+        payload,
+        session: input.session,
+        ...(input.connectionId ? { connectionId: input.connectionId } : {}),
+        ...(input.serviceAccountId ? { serviceAccountId: input.serviceAccountId } : {}),
+        ...(input.subject ? { subject: input.subject } : {}),
+        ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+        ...(input.providerCursor ? { providerCursor: input.providerCursor } : {}),
+        ...(input.dedupeKey ? { dedupeKey: input.dedupeKey } : {}),
+        ...(input.rawRef ? { rawRef: input.rawRef } : {}),
+    };
+    validateProviderEvent(event, input.maxPayloadBytes);
+    return event;
+}
+export function redactProviderEventPayload(payload, extraPatterns = []) {
+    const cloned = structuredClone(payload);
+    redactValueInPlace(cloned, [CREDENTIAL_KEY_PATTERN, ...extraPatterns]);
+    return cloned;
+}
+export function isStaleProviderEvent(event, currentGeneration) {
+    return event.session.generation < currentGeneration;
+}
+export class InMemoryProviderEventLog {
+    #events = [];
+    #eventIds = new Set();
+    #dedupeKeys = new Set();
+    async append(event) {
+        validateProviderEvent(event);
+        if (this.#eventIds.has(event.eventId)) {
+            return { event, appended: false };
+        }
+        const dedupeTuple = event.dedupeKey ? buildDedupeTuple(event) : undefined;
+        if (dedupeTuple && this.#dedupeKeys.has(dedupeTuple)) {
+            return { event, appended: false };
+        }
+        this.#events.push(event);
+        this.#eventIds.add(event.eventId);
+        if (dedupeTuple)
+            this.#dedupeKeys.add(dedupeTuple);
+        return { event, appended: true };
+    }
+    async get(eventId) {
+        validateRequiredString("eventId", eventId);
+        return this.#events.find((event) => event.eventId === eventId) ?? null;
+    }
+    async list(options = {}) {
+        validateListOptions(options);
+        let events = this.#events;
+        if (options.providerId) {
+            events = events.filter((event) => event.providerId === options.providerId);
+        }
+        if (options.connectionId) {
+            events = events.filter((event) => event.connectionId === options.connectionId);
+        }
+        if (options.eventType) {
+            events = events.filter((event) => event.eventType === options.eventType);
+        }
+        if (options.subjectKind) {
+            events = events.filter((event) => event.subject?.kind === options.subjectKind);
+        }
+        if (options.subjectId) {
+            events = events.filter((event) => event.subject?.id === options.subjectId);
+        }
+        if (options.afterObservedAt) {
+            const afterMs = Date.parse(options.afterObservedAt);
+            events = events.filter((event) => Date.parse(event.observedAt) > afterMs);
+        }
+        return typeof options.limit === "number" ? events.slice(0, options.limit) : [...events];
+    }
+}
+export class ProviderEventEmitter {
+    #log;
+    #defaults;
+    constructor(log, defaults) {
+        validateRequiredString("providerId", defaults.providerId);
+        if (defaults.connectionId !== undefined) {
+            validateRequiredString("connectionId", defaults.connectionId);
+        }
+        if (defaults.serviceAccountId !== undefined) {
+            validateRequiredString("serviceAccountId", defaults.serviceAccountId);
+        }
+        validateSession(defaults.session);
+        this.#log = log;
+        this.#defaults = defaults;
+    }
+    emit(input) {
+        const event = buildProviderEvent({
+            ...input,
+            providerId: input.providerId ?? this.#defaults.providerId,
+            connectionId: input.connectionId ?? this.#defaults.connectionId,
+            serviceAccountId: input.serviceAccountId ?? this.#defaults.serviceAccountId,
+            session: input.session ?? this.#defaults.session,
+            clock: input.clock ?? this.#defaults.clock,
+            idFactory: input.idFactory ?? this.#defaults.idFactory,
+            maxPayloadBytes: input.maxPayloadBytes ?? this.#defaults.maxPayloadBytes,
+            shouldRedactPayload: input.shouldRedactPayload ?? this.#defaults.shouldRedactPayload,
+            redactionPatterns: input.redactionPatterns ?? this.#defaults.redactionPatterns,
+        });
+        return this.#log.append(event);
+    }
+}
+function buildEventId(input) {
+    if (input.dedupeKey) {
+        return deterministicProviderEventId([
+            input.providerId,
+            input.connectionId ?? "",
+            input.eventType,
+            input.dedupeKey,
+        ]);
+    }
+    return (input.idFactory?.() ??
+        deterministicProviderEventId([
+            input.providerId,
+            input.connectionId ?? "",
+            input.eventType,
+            input.subject?.kind ?? "",
+            input.subject?.id ?? "",
+            input.observedAt,
+        ]));
+}
+function deterministicProviderEventId(parts) {
+    return `pevt_${createHash("sha256").update(parts.join("\u001f")).digest("hex")}`;
+}
+function validateProviderEvent(event, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES) {
+    validateRequiredString("eventId", event.eventId);
+    validateRequiredString("providerId", event.providerId);
+    if (event.connectionId !== undefined)
+        validateRequiredString("connectionId", event.connectionId);
+    if (event.serviceAccountId !== undefined) {
+        validateRequiredString("serviceAccountId", event.serviceAccountId);
+    }
+    validateRequiredString("eventType", event.eventType);
+    if (event.subject) {
+        validateRequiredString("subject.kind", event.subject.kind);
+        validateRequiredString("subject.id", event.subject.id);
+    }
+    if (event.occurredAt !== undefined) {
+        validateRequiredString("occurredAt", event.occurredAt);
+        validateTimestamp("occurredAt", event.occurredAt);
+    }
+    validateRequiredString("observedAt", event.observedAt);
+    validateTimestamp("observedAt", event.observedAt);
+    validateSession(event.session);
+    if (event.providerCursor !== undefined) {
+        validateRequiredString("providerCursor", event.providerCursor);
+    }
+    if (event.dedupeKey !== undefined) {
+        validateRequiredString("dedupeKey", event.dedupeKey);
+    }
+    if (event.rawRef !== undefined) {
+        validateRequiredString("rawRef", event.rawRef);
+    }
+    validatePayload(event.payload, maxPayloadBytes);
+}
+function validateSession(session) {
+    validateRequiredString("session.sessionKey", session?.sessionKey);
+    if (!Number.isInteger(session?.generation) || session.generation < 0) {
+        throw new ProviderEventValidationError("ProviderEvent session.generation must be a non-negative integer.");
+    }
+}
+function validateRequiredString(name, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new ProviderEventValidationError(`ProviderEvent ${name} must be a non-empty string.`);
+    }
+}
+function validateTimestamp(name, value) {
+    if (!Number.isFinite(Date.parse(value))) {
+        throw new ProviderEventValidationError(`ProviderEvent ${name} must be a parseable ISO timestamp string.`);
+    }
+}
+function validatePayload(payload, maxPayloadBytes) {
+    if (typeof maxPayloadBytes !== "number" ||
+        !Number.isFinite(maxPayloadBytes) ||
+        maxPayloadBytes <= 0) {
+        throw new ProviderEventValidationError("ProviderEvent maxPayloadBytes must be a positive finite number.");
+    }
+    if (!isPlainRecord(payload)) {
+        throw new ProviderEventValidationError("ProviderEvent payload must be a JSON-serializable object.");
+    }
+    assertJsonValue(payload, "payload");
+    const encoded = JSON.stringify(payload);
+    if (encoded === undefined) {
+        throw new ProviderEventValidationError("ProviderEvent payload must be JSON-serializable.");
+    }
+    const payloadBytes = Buffer.byteLength(encoded, "utf8");
+    if (payloadBytes > maxPayloadBytes) {
+        throw new ProviderEventValidationError(`ProviderEvent payload exceeds max size of ${maxPayloadBytes} bytes.`);
+    }
+}
+function assertJsonValue(value, path, seen = new WeakSet()) {
+    if (value === null)
+        return;
+    if (typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new ProviderEventValidationError(`ProviderEvent ${path} must not contain non-finite numbers.`);
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            throw new ProviderEventValidationError(`ProviderEvent ${path} must not contain circular references.`);
+        }
+        seen.add(value);
+        for (const [index, entry] of value.entries()) {
+            assertJsonValue(entry, `${path}[${index}]`, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    if (isPlainRecord(value)) {
+        if (seen.has(value)) {
+            throw new ProviderEventValidationError(`ProviderEvent ${path} must not contain circular references.`);
+        }
+        seen.add(value);
+        for (const [key, entry] of Object.entries(value)) {
+            assertJsonValue(entry, `${path}.${key}`, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    throw new ProviderEventValidationError(`ProviderEvent ${path} must be JSON-serializable.`);
+}
+function redactValueInPlace(value, patterns) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            redactValueInPlace(entry, patterns);
+        return;
+    }
+    if (!isPlainRecord(value))
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        if (patterns.some((pattern) => matchesPattern(pattern, key)))
+            value[key] = REDACTED_VALUE;
+        else
+            redactValueInPlace(entry, patterns);
+    }
+}
+function isPlainRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function buildDedupeTuple(event) {
+    return [
+        event.serviceAccountId ?? "",
+        event.providerId,
+        event.connectionId ?? "",
+        event.dedupeKey,
+    ].join("\u001f");
+}
+function matchesPattern(pattern, value) {
+    pattern.lastIndex = 0;
+    const matched = pattern.test(value);
+    pattern.lastIndex = 0;
+    return matched;
+}
+function validateListOptions(options) {
+    if (options.afterObservedAt) {
+        validateTimestamp("afterObservedAt", options.afterObservedAt);
+    }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        throw new ProviderEventValidationError("ProviderEvent list limit must be a positive integer.");
+    }
+}
+export function randomProviderEventId() {
+    return `pevt_${randomUUID().replaceAll("-", "")}`;
+}

package/dist/stateful/session-key.d.ts

@@ -0,0 +1,15 @@
+declare const SESSION_KEY_BRAND: unique symbol;
+/** Canonical, opaque identity for a stateful provider session. */
+export type SessionKey = string & {
+    readonly [SESSION_KEY_BRAND]: "SessionKey";
+};
+export interface SessionKeyParts {
+    readonly providerId: string;
+    readonly serviceAccountId: string;
+    readonly connectionId: string;
+    /** Optional extra session axes (e.g. device, mailbox, persona). Defaults to none. */
+    readonly dimensions?: Readonly<Record<string, string>>;
+}
+export declare function buildSessionKey(parts: SessionKeyParts): SessionKey;
+export declare function parseSessionKey(key: string): SessionKeyParts;
+export {};