@renoxium/sdk 0.0.0-stage → 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,261 @@
+import type { JobState } from "./ctx.ts";
+/** Codes an op rejects with inside tenant code ("thrown" and "both" in ops.md section 13). */
+export declare const RENOX_ERROR_CODES: readonly ["RENOX_DB_AUTH", "RENOX_DB_BUSY", "RENOX_DB_TIMEOUT", "RENOX_DB_QUOTA", "RENOX_DB_CONSTRAINT", "RENOX_DB_SQL", "RENOX_DB_PARAM", "RENOX_DB_COLUMN_NAME", "RENOX_DB_MULTI_STATEMENT", "RENOX_DB_RESULT_LIMIT", "RENOX_DB_TX_STATE", "RENOX_DB_SCOPE", "RENOX_FETCH_BLOCKED", "RENOX_FETCH_FAILED", "RENOX_FETCH_EGRESS_LIMIT", "RENOX_DEADLINE", "RENOX_NO_REQUEST", "RENOX_SECRETS_CONSUMED", "RENOX_MODULE_UNDECLARED", "RENOX_MODULE_SERVICE", "RENOX_EVENT_PAYLOAD", "RENOX_FORBIDDEN", "RENOX_REALTIME_LIMIT", "RENOX_REALTIME_BACKPRESSURE", "RENOX_JOB_NOT_FOUND", "RENOX_JOB_STATE", "RENOX_STORAGE_QUOTA", "RENOX_STORAGE_TYPE", "RENOX_STORAGE_TOO_LARGE", "RENOX_STORAGE_KEY", "RENOX_STORAGE_NOT_FOUND", "RENOX_AI_QUOTA", "RENOX_AI_UNAVAILABLE", "RENOX_PDF_LIMIT"];
+/** Codes the platform answers with when a request ends ("response" and "both"). */
+export declare const RESPONSE_ERROR_CODES: readonly ["RENOX_DEADLINE", "RENOX_CPU_LIMIT", "RENOX_OOM", "RENOX_BUSY", "RENOX_INTERNAL", "RENOX_BODY_TOO_LARGE", "RENOX_CSRF", "RENOX_RENDER_LIMIT", "RENOX_MODULE_EVAL", "RENOX_FORBIDDEN", "RENOX_REALTIME_LIMIT", "RENOX_REALTIME_BACKPRESSURE", "RENOX_TOOL_INPUT", "RENOX_TOOL_SCOPE", "RENOX_TOOL_CONFIRM", "RENOX_IMAGE_RATE", "RENOX_WEBHOOK_SIGNATURE"];
+export type DbErrorCode = "RENOX_DB_AUTH" | "RENOX_DB_BUSY" | "RENOX_DB_TIMEOUT" | "RENOX_DB_QUOTA" | "RENOX_DB_CONSTRAINT" | "RENOX_DB_SQL" | "RENOX_DB_PARAM" | "RENOX_DB_COLUMN_NAME" | "RENOX_DB_MULTI_STATEMENT" | "RENOX_DB_RESULT_LIMIT" | "RENOX_DB_TX_STATE" | "RENOX_DB_SCOPE";
+export type FetchErrorCode = "RENOX_FETCH_BLOCKED" | "RENOX_FETCH_FAILED" | "RENOX_FETCH_EGRESS_LIMIT";
+/** Codes of the module broker (ops.md section 15). */
+export type ModuleErrorCode = "RENOX_MODULE_UNDECLARED" | "RENOX_MODULE_SERVICE" | "RENOX_EVENT_PAYLOAD";
+/** A policy denied (ops.md section 17): thrown by `authz.require` and `realtime.subscribe`, answered by a `guard`. */
+export type AuthzErrorCode = "RENOX_FORBIDDEN";
+/** The realtime limits (ops.md section 18): thrown by the realtime ops, and the reason of a platform close. */
+export type RealtimeErrorCode = "RENOX_REALTIME_LIMIT" | "RENOX_REALTIME_BACKPRESSURE";
+/** `/mcp` refusals before a tool runs (ops.md section 19), as JSON-RPC errors. */
+export type ToolErrorCode = "RENOX_TOOL_INPUT" | "RENOX_TOOL_SCOPE" | "RENOX_TOOL_CONFIRM";
+export type RenoxErrorCode = (typeof RENOX_ERROR_CODES)[number];
+/** Never reaches tenant code as an exception; clients see it in the error body. */
+export type ResponseErrorCode = (typeof RESPONSE_ERROR_CODES)[number];
+/** Body of a platform error response on an API route (errors.md, "Response body"). */
+export interface ErrorResponseBody {
+    error: {
+        code: ResponseErrorCode;
+        request_id: string;
+        message: string;
+    };
+}
+export declare class RenoxError extends Error {
+    readonly code: RenoxErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: RenoxErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * True for any error carrying a known `RenoxErrorCode`. Prefer it over
+ * `instanceof`: an error raised by the platform's runtime glue and the class a
+ * tenant bundled are not guaranteed to be the same object.
+ */
+export declare function isRenoxError(error: unknown): error is RenoxError;
+export declare class DbPermissionError extends RenoxError {
+    readonly code: "RENOX_DB_AUTH";
+    readonly details: {
+        readonly table: string;
+        readonly action: string;
+    };
+    constructor(message: string, details: {
+        table: string;
+        action: string;
+    });
+}
+export declare class DbBusyError extends RenoxError {
+    readonly code: "RENOX_DB_BUSY";
+    constructor(message: string);
+}
+export declare class DbTimeoutError extends RenoxError {
+    readonly code: "RENOX_DB_TIMEOUT";
+    constructor(message: string);
+}
+export declare class DbQuotaError extends RenoxError {
+    readonly code: "RENOX_DB_QUOTA";
+    constructor(message: string);
+}
+export declare class DbConstraintError extends RenoxError {
+    readonly code: "RENOX_DB_CONSTRAINT";
+    readonly details: {
+        readonly kind: "unique" | "foreign_key" | "not_null" | "check" | "primary_key";
+    };
+    constructor(message: string, details: {
+        kind: "unique" | "foreign_key" | "not_null" | "check" | "primary_key";
+    });
+}
+export declare class DbSqlError extends RenoxError {
+    readonly code: "RENOX_DB_SQL";
+    constructor(message: string);
+}
+export type DbUsageErrorCode = "RENOX_DB_PARAM" | "RENOX_DB_COLUMN_NAME" | "RENOX_DB_MULTI_STATEMENT" | "RENOX_DB_RESULT_LIMIT" | "RENOX_DB_TX_STATE";
+export declare class DbUsageError extends RenoxError {
+    readonly code: DbUsageErrorCode;
+    constructor(code: DbUsageErrorCode, message: string);
+}
+export type DbScopeReason = "unscoped" | "scope_missing" | "owner_mismatch" | "unprovable";
+/** Module code reached an owned table without a scope, or the rewriter refused the statement (ops.md section 17). */
+export declare class DbScopeError extends RenoxError {
+    readonly code: "RENOX_DB_SCOPE";
+    readonly details: {
+        readonly table: string;
+        readonly module: string;
+        readonly reason: DbScopeReason;
+    };
+    constructor(message: string, details: {
+        table: string;
+        module: string;
+        reason: DbScopeReason;
+    });
+}
+export type FetchBlockedReason = "not_allowlisted" | "scheme" | "port" | "blocked_address" | "redirect_limit" | "method";
+export type FetchFailedReason = "dns" | "connect" | "tls" | "reset" | "redirect" | "concurrency" | "headers";
+export declare class FetchBlockedError extends RenoxError {
+    readonly code: "RENOX_FETCH_BLOCKED";
+    readonly details: {
+        readonly host: string;
+        readonly reason: FetchBlockedReason;
+    };
+    constructor(message: string, details: {
+        host: string;
+        reason: FetchBlockedReason;
+    });
+}
+export declare class FetchError extends RenoxError {
+    readonly code: "RENOX_FETCH_FAILED";
+    readonly details: {
+        readonly host: string;
+        readonly reason: FetchFailedReason;
+    };
+    constructor(message: string, details: {
+        host: string;
+        reason: FetchFailedReason;
+    });
+}
+export declare class FetchEgressLimitError extends RenoxError {
+    readonly code: "RENOX_FETCH_EGRESS_LIMIT";
+    readonly details: {
+        readonly host: string;
+        readonly limitBytes: number;
+    };
+    constructor(message: string, details: {
+        host: string;
+        limitBytes: number;
+    });
+}
+export declare class DeadlineError extends RenoxError {
+    readonly code: "RENOX_DEADLINE";
+    constructor(message: string);
+}
+/** A service call, hook run, or event emit the caller's manifest does not allow. */
+export declare class ModuleUndeclaredError extends RenoxError {
+    readonly code: "RENOX_MODULE_UNDECLARED";
+    readonly details: {
+        readonly module: string;
+        readonly target: string;
+    };
+    constructor(message: string, details: {
+        module: string;
+        target: string;
+    });
+}
+export type ModuleServiceErrorDetails = {
+    readonly module: string;
+    readonly service?: string;
+    readonly hook?: string;
+    readonly event?: string;
+    readonly cause_code: string | null;
+};
+/**
+ * A service, hook filler, or in-memory event handler of another module threw.
+ * `module` names the callee, `service` the service (null for a hook filler or
+ * an event handler). The enclosing transaction has been rolled back.
+ */
+export declare class ModuleServiceError extends RenoxError {
+    readonly code: "RENOX_MODULE_SERVICE";
+    readonly details: ModuleServiceErrorDetails;
+    readonly module: string;
+    readonly service: string | null;
+    constructor(message: string, details: ModuleServiceErrorDetails);
+}
+export type EventPayloadReason = "schema" | "not_json" | "too_large";
+/** The payload does not match the event's exported schema; never carries the payload. */
+export declare class EventPayloadError extends RenoxError {
+    readonly code: "RENOX_EVENT_PAYLOAD";
+    readonly details: {
+        readonly event: string;
+        readonly reason: EventPayloadReason;
+    };
+    constructor(message: string, details: {
+        event: string;
+        reason: EventPayloadReason;
+    });
+}
+export type JobErrorCode = "RENOX_JOB_NOT_FOUND" | "RENOX_JOB_STATE";
+export type JobOp = "retry" | "cancel";
+/** `op_jobs_retry` / `op_jobs_cancel` for an id that is not a job row of this tenant. */
+export declare class JobNotFoundError extends RenoxError {
+    readonly code: "RENOX_JOB_NOT_FOUND";
+    readonly details: {
+        readonly id: string;
+    };
+    constructor(message: string, details: {
+        id: string;
+    });
+}
+/** Retry on a row that is not dead, or cancel on a running row. */
+export declare class JobStateError extends RenoxError {
+    readonly code: "RENOX_JOB_STATE";
+    readonly details: {
+        readonly id: string;
+        readonly state: JobState;
+        readonly op: JobOp;
+    };
+    constructor(message: string, details: {
+        id: string;
+        state: JobState;
+        op: JobOp;
+    });
+}
+export type StorageErrorCode = "RENOX_STORAGE_QUOTA" | "RENOX_STORAGE_TYPE" | "RENOX_STORAGE_TOO_LARGE" | "RENOX_STORAGE_KEY" | "RENOX_STORAGE_NOT_FOUND";
+export type AiErrorCode = "RENOX_AI_QUOTA" | "RENOX_AI_UNAVAILABLE";
+/** One of the storage refusals (section 21). */
+export declare class StorageError extends RenoxError {
+    readonly code: StorageErrorCode;
+    constructor(code: StorageErrorCode, message: string, details?: Record<string, unknown>);
+}
+/** The tenant's monthly AI tokens are spent (section 23). */
+export declare class AiQuotaError extends RenoxError {
+    readonly code: "RENOX_AI_QUOTA";
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** The model provider or the platform gateway failed (section 23). */
+export declare class AiUnavailableError extends RenoxError {
+    readonly code: "RENOX_AI_UNAVAILABLE";
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** A PDF over 200 pages or 20 MB (section 24). */
+export declare class PdfLimitError extends RenoxError {
+    readonly code: "RENOX_PDF_LIMIT";
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export type ForbiddenReason = "deny" | "unknown_action" | "missing_attribute" | "evaluation_error" | "eval_limit" | "dev_only";
+export type ForbiddenErrorDetails = {
+    readonly action: string;
+    readonly resource: {
+        readonly type: string;
+        readonly id: string;
+    } | null;
+    readonly reason: ForbiddenReason;
+    /** The deciding policy id in dev mode only. */
+    readonly policy: string | null;
+};
+/** A policy denied the action. Uncaught, it ends the request with 403 `RENOX_FORBIDDEN`, not 500. */
+export declare class ForbiddenError extends RenoxError {
+    readonly code: "RENOX_FORBIDDEN";
+    readonly details: ForbiddenErrorDetails;
+    constructor(message: string, details: ForbiddenErrorDetails);
+}
+export type RealtimeLimitReason = "tenant" | "user" | "topics" | "message_size" | "flood";
+export declare class RealtimeLimitError extends RenoxError {
+    readonly code: "RENOX_REALTIME_LIMIT";
+    readonly details: {
+        readonly reason: RealtimeLimitReason;
+    };
+    constructor(message: string, details: {
+        reason: RealtimeLimitReason;
+    });
+}
+/** The connection's outbound queue was full: it has been closed with 1008. */
+export declare class RealtimeBackpressureError extends RenoxError {
+    readonly code: "RENOX_REALTIME_BACKPRESSURE";
+    readonly details: {
+        readonly conn: string;
+    };
+    constructor(message: string, details: {
+        conn: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,232 @@
+// Error codes and classes of docs/contracts/ops.md section 13 (contract
+// version 1.6.0). tests/errors.test.ts checks the lists below against the
+// table in ops.md; tests/contract.test-d.ts checks the types against ctx.d.ts.
+/** Codes an op rejects with inside tenant code ("thrown" and "both" in ops.md section 13). */
+export const RENOX_ERROR_CODES = [
+    "RENOX_DB_AUTH",
+    "RENOX_DB_BUSY",
+    "RENOX_DB_TIMEOUT",
+    "RENOX_DB_QUOTA",
+    "RENOX_DB_CONSTRAINT",
+    "RENOX_DB_SQL",
+    "RENOX_DB_PARAM",
+    "RENOX_DB_COLUMN_NAME",
+    "RENOX_DB_MULTI_STATEMENT",
+    "RENOX_DB_RESULT_LIMIT",
+    "RENOX_DB_TX_STATE",
+    // ops 1.5.0: an owned table without a scope (section 17).
+    "RENOX_DB_SCOPE",
+    "RENOX_FETCH_BLOCKED",
+    "RENOX_FETCH_FAILED",
+    "RENOX_FETCH_EGRESS_LIMIT",
+    "RENOX_DEADLINE",
+    "RENOX_NO_REQUEST",
+    "RENOX_SECRETS_CONSUMED",
+    "RENOX_MODULE_UNDECLARED",
+    "RENOX_MODULE_SERVICE",
+    "RENOX_EVENT_PAYLOAD",
+    // ops 1.5.0: a policy denied (section 17); the realtime limits (section 18).
+    "RENOX_FORBIDDEN",
+    "RENOX_REALTIME_LIMIT",
+    "RENOX_REALTIME_BACKPRESSURE",
+    // ops 1.6.0: the jobs module's ops (section 20).
+    "RENOX_JOB_NOT_FOUND",
+    "RENOX_JOB_STATE",
+    // ops 1.7.0: storage (section 21), AI (section 23), PDF (section 24).
+    "RENOX_STORAGE_QUOTA",
+    "RENOX_STORAGE_TYPE",
+    "RENOX_STORAGE_TOO_LARGE",
+    "RENOX_STORAGE_KEY",
+    "RENOX_STORAGE_NOT_FOUND",
+    "RENOX_AI_QUOTA",
+    "RENOX_AI_UNAVAILABLE",
+    "RENOX_PDF_LIMIT",
+];
+/** Codes the platform answers with when a request ends ("response" and "both"). */
+export const RESPONSE_ERROR_CODES = [
+    "RENOX_DEADLINE",
+    "RENOX_CPU_LIMIT",
+    "RENOX_OOM",
+    "RENOX_BUSY",
+    "RENOX_INTERNAL",
+    "RENOX_BODY_TOO_LARGE",
+    "RENOX_CSRF",
+    "RENOX_RENDER_LIMIT",
+    // ops 1.4.0: a lazy route module failed its first evaluation.
+    "RENOX_MODULE_EVAL",
+    // ops 1.5.0: a guard or the tool check denied; the realtime caps; /mcp refusals (sections 17-19).
+    "RENOX_FORBIDDEN",
+    "RENOX_REALTIME_LIMIT",
+    "RENOX_REALTIME_BACKPRESSURE",
+    "RENOX_TOOL_INPUT",
+    "RENOX_TOOL_SCOPE",
+    "RENOX_TOOL_CONFIRM",
+    // ops 1.7.0: the image transform rate (section 21), a refused webhook delivery (section 22).
+    "RENOX_IMAGE_RATE",
+    "RENOX_WEBHOOK_SIGNATURE",
+];
+export class RenoxError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        if (details !== undefined)
+            this.details = Object.freeze({ ...details });
+    }
+}
+/**
+ * True for any error carrying a known `RenoxErrorCode`. Prefer it over
+ * `instanceof`: an error raised by the platform's runtime glue and the class a
+ * tenant bundled are not guaranteed to be the same object.
+ */
+export function isRenoxError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return typeof code === "string" && RENOX_ERROR_CODES.includes(code);
+}
+// Database (ops.md section 1)
+export class DbPermissionError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_DB_AUTH", message, details);
+    }
+}
+export class DbBusyError extends RenoxError {
+    constructor(message) {
+        super("RENOX_DB_BUSY", message);
+    }
+}
+export class DbTimeoutError extends RenoxError {
+    constructor(message) {
+        super("RENOX_DB_TIMEOUT", message);
+    }
+}
+export class DbQuotaError extends RenoxError {
+    constructor(message) {
+        super("RENOX_DB_QUOTA", message);
+    }
+}
+export class DbConstraintError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_DB_CONSTRAINT", message, details);
+    }
+}
+export class DbSqlError extends RenoxError {
+    constructor(message) {
+        super("RENOX_DB_SQL", message);
+    }
+}
+export class DbUsageError extends RenoxError {
+    constructor(code, message) {
+        super(code, message);
+    }
+}
+/** Module code reached an owned table without a scope, or the rewriter refused the statement (ops.md section 17). */
+export class DbScopeError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_DB_SCOPE", message, details);
+    }
+}
+export class FetchBlockedError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_FETCH_BLOCKED", message, details);
+    }
+}
+export class FetchError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_FETCH_FAILED", message, details);
+    }
+}
+export class FetchEgressLimitError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_FETCH_EGRESS_LIMIT", message, details);
+    }
+}
+// Deadline (ops.md section 5)
+export class DeadlineError extends RenoxError {
+    constructor(message) {
+        super("RENOX_DEADLINE", message);
+    }
+}
+// Modules (ops.md section 15)
+/** A service call, hook run, or event emit the caller's manifest does not allow. */
+export class ModuleUndeclaredError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_MODULE_UNDECLARED", message, details);
+    }
+}
+/**
+ * A service, hook filler, or in-memory event handler of another module threw.
+ * `module` names the callee, `service` the service (null for a hook filler or
+ * an event handler). The enclosing transaction has been rolled back.
+ */
+export class ModuleServiceError extends RenoxError {
+    module;
+    service;
+    constructor(message, details) {
+        super("RENOX_MODULE_SERVICE", message, { ...details });
+        this.module = details.module;
+        this.service = details.service ?? null;
+    }
+}
+/** The payload does not match the event's exported schema; never carries the payload. */
+export class EventPayloadError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_EVENT_PAYLOAD", message, details);
+    }
+}
+/** `op_jobs_retry` / `op_jobs_cancel` for an id that is not a job row of this tenant. */
+export class JobNotFoundError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_JOB_NOT_FOUND", message, details);
+    }
+}
+/** Retry on a row that is not dead, or cancel on a running row. */
+export class JobStateError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_JOB_STATE", message, details);
+    }
+}
+/** One of the storage refusals (section 21). */
+export class StorageError extends RenoxError {
+    constructor(code, message, details) {
+        super(code, message, details);
+    }
+}
+/** The tenant's monthly AI tokens are spent (section 23). */
+export class AiQuotaError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_AI_QUOTA", message, details);
+    }
+}
+/** The model provider or the platform gateway failed (section 23). */
+export class AiUnavailableError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_AI_UNAVAILABLE", message, details);
+    }
+}
+/** A PDF over 200 pages or 20 MB (section 24). */
+export class PdfLimitError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_PDF_LIMIT", message, details);
+    }
+}
+/** A policy denied the action. Uncaught, it ends the request with 403 `RENOX_FORBIDDEN`, not 500. */
+export class ForbiddenError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_FORBIDDEN", message, { ...details });
+    }
+}
+export class RealtimeLimitError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_REALTIME_LIMIT", message, details);
+    }
+}
+/** The connection's outbound queue was full: it has been closed with 1008. */
+export class RealtimeBackpressureError extends RenoxError {
+    constructor(message, details) {
+        super("RENOX_REALTIME_BACKPRESSURE", message, details);
+    }
+}

package/dist/fakes.d.ts

@@ -0,0 +1,35 @@
+import type { Ai, AiRequest, Storage, StoredFile, WebhookProvider } from "./ctx.ts";
+/** An in-memory `ctx.storage` for `module` (keys under `<module>/`). */
+export declare function fakeStorage(module?: string, options?: {
+    maxFileBytes?: number;
+    now?: () => number;
+}): Storage & {
+    files: Map<string, {
+        file: StoredFile;
+        bytes: Uint8Array;
+    }>;
+};
+/** One recorded answer: text, or a tool call the code under test must answer. */
+export type RecordedTurn = {
+    text: string;
+} | {
+    tool: string;
+    input?: unknown;
+};
+/**
+ * A `ctx.ai` that replays recorded answers in order, running local tools
+ * like the platform does; `requests` keeps what the code asked.
+ */
+export declare function fakeAi(turns: RecordedTurn[]): Ai & {
+    requests: AiRequest[];
+};
+/**
+ * A webhook delivery signed the way `provider` signs it (ops.md section 22),
+ * for a test of a `functions/webhooks/*.ts` handler against `renox test`.
+ * `generic` signs into `header` (default `x-webhook-signature`).
+ */
+export declare function signWebhook(provider: Exclude<WebhookProvider, "apple" | "google">, secret: string, payload: unknown, options?: {
+    url?: string;
+    header?: string;
+    now?: number;
+}): Promise<Request>;

package/dist/fakes.js

@@ -0,0 +1,144 @@
+// `@renoxium/sdk/fakes` (#323; docs/contracts/ops.md 1.7.0 sections 21-23): stand-ins
+// for `ctx.storage`, `ctx.ai` and webhook deliveries in a tenant's unit
+// tests, so a handler can be called without a worker.
+//
+//   import { fakeStorage, fakeAi, signWebhook } from "@renoxium/sdk/fakes";
+//   const ctx = { ...base, storage: fakeStorage(), ai: fakeAi([{ text: "AED 5" }]) };
+//   const req = await signWebhook("stripe", "whsec_test", { id: "evt_1" });
+//
+// The fakes follow the contract's rules (key prefix, ttl range, the
+// `StorageError` codes), never the network.
+import { StorageError } from "./errors.js";
+const KEY = /^[a-z0-9][a-z0-9/_.-]{0,255}$/u;
+async function sha256Hex(bytes) {
+    const d = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return [...d].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** An in-memory `ctx.storage` for `module` (keys under `<module>/`). */
+export function fakeStorage(module = "app", options = {}) {
+    const files = new Map();
+    const now = options.now ?? Date.now;
+    const check = (key) => {
+        if (!KEY.test(key) || key.split("/").some((s) => s === "" || s === "." || s === "..") || !key.startsWith(`${module}/`)) {
+            throw new StorageError("RENOX_STORAGE_KEY", "The storage key is not allowed.", { key });
+        }
+    };
+    const found = (key) => {
+        const f = files.get(key);
+        if (f === undefined)
+            throw new StorageError("RENOX_STORAGE_NOT_FOUND", "No stored file has this key.", { key });
+        return f;
+    };
+    return {
+        files,
+        async put(key, bytes, opts) {
+            check(key);
+            if (bytes.length > (options.maxFileBytes ?? 10 * 1024 * 1024))
+                throw new StorageError("RENOX_STORAGE_TOO_LARGE", "The file is over the per-file limit.", { key });
+            if (opts.contentType === "image/svg+xml" && opts.sanitised !== true)
+                throw new StorageError("RENOX_STORAGE_TYPE", "The content type is not allowed for this file.", { key, reason: "svg_unsanitised" });
+            const file = { key, bytes: bytes.length, content_type: opts.contentType, sha256: await sha256Hex(bytes), width: null, height: null, public: opts.public === true, created_at: now() };
+            files.set(key, { file, bytes: bytes.slice() });
+            return file;
+        },
+        async get(key) {
+            check(key);
+            return found(key).file;
+        },
+        async read(key) {
+            check(key);
+            return found(key).bytes.slice();
+        },
+        async delete(key) {
+            check(key);
+            return files.delete(key);
+        },
+        async sign(key, ttlSeconds) {
+            check(key);
+            if (!Number.isInteger(ttlSeconds) || ttlSeconds < 60 || ttlSeconds > 604800)
+                throw new RangeError("storage.sign: ttl is 60 to 604800 seconds");
+            found(key);
+            const exp = Math.floor(now() / 1000) + ttlSeconds;
+            return { url: `/_files/${key}?exp=${exp}&sig=fake`, expires_at: exp * 1000 };
+        },
+        async list(prefix, opts = {}) {
+            const p = prefix === "" ? `${module}/` : prefix;
+            if (!p.startsWith(`${module}/`))
+                throw new StorageError("RENOX_STORAGE_KEY", "The storage key is not allowed.", { key: p });
+            const keys = [...files.keys()].filter((k) => k.startsWith(p) && k > (opts.cursor ?? "")).sort();
+            const limit = opts.limit ?? 100;
+            const page = keys.slice(0, limit);
+            return { items: page.map((k) => files.get(k).file), next_cursor: keys.length > limit ? (page[page.length - 1] ?? null) : null };
+        },
+    };
+}
+/**
+ * A `ctx.ai` that replays recorded answers in order, running local tools
+ * like the platform does; `requests` keeps what the code asked.
+ */
+export function fakeAi(turns) {
+    const requests = [];
+    let i = 0;
+    const next = () => {
+        const t = turns[i++];
+        if (t === undefined)
+            throw new Error("fakeAi: no recorded answer left");
+        return t;
+    };
+    return {
+        requests,
+        async chat(request) {
+            requests.push(request);
+            let input = 0;
+            let output = 0;
+            for (let round = 0; round < 8; round++) {
+                const t = next();
+                input += 10;
+                output += 5;
+                if ("text" in t) {
+                    return { id: `fake_${i}`, model: request.model ?? "default", content: [{ type: "text", text: t.text }], stop_reason: "end_turn", usage: { input_tokens: input, output_tokens: output } };
+                }
+                const tool = request.tools?.find((x) => x.name === t.tool);
+                if (typeof tool?.run !== "function") {
+                    const content = [{ type: "tool_use", id: `tu_${i}`, name: t.tool, input: (t.input ?? {}) }];
+                    return { id: `fake_${i}`, model: request.model ?? "default", content, stop_reason: "tool_use", usage: { input_tokens: input, output_tokens: output } };
+                }
+                await tool.run((t.input ?? {}));
+            }
+            throw new Error("fakeAi: more than 8 tool rounds");
+        },
+    };
+}
+const HEADERS = {
+    checkout: "cko-signature",
+    telr: "x-telr-signature",
+    paytabs: "signature",
+    ngenius: "x-ngenius-signature",
+    tabby: "x-tabby-signature",
+    tamara: "tamara-signature",
+};
+async function hmacHex(secret, data) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return [...new Uint8Array(await crypto.subtle.sign("HMAC", key, data))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * A webhook delivery signed the way `provider` signs it (ops.md section 22),
+ * for a test of a `functions/webhooks/*.ts` handler against `renox test`.
+ * `generic` signs into `header` (default `x-webhook-signature`).
+ */
+export async function signWebhook(provider, secret, payload, options = {}) {
+    const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const bytes = new TextEncoder().encode(body);
+    const headers = { "content-type": "application/json" };
+    if (provider === "stripe") {
+        const t = Math.floor((options.now ?? Date.now()) / 1000);
+        headers["stripe-signature"] = `t=${t},v1=${await hmacHex(secret, new TextEncoder().encode(`${t}.${body}`))}`;
+    }
+    else if (provider === "generic") {
+        headers[(options.header ?? "x-webhook-signature").toLowerCase()] = await hmacHex(secret, bytes);
+    }
+    else {
+        headers[HEADERS[provider]] = await hmacHex(secret, bytes);
+    }
+    return new Request(options.url ?? `https://app.renox.test/webhooks/${provider}`, { method: "POST", headers, body });
+}