@pylonsync/functions 0.19.1 → 0.21.0

package/dist/define.d.ts

@@ -44,7 +44,8 @@ interface CommonDef<TSchema extends ValidatorSchema | undefined = ValidatorSchem
      * IDLE-timeout SECONDS for this function: how long it may go without
      * producing any activity (a stream chunk, a `ctx.db` op, an LLM
      * event) before the host cancels the call. Defaults to
-     * `PYLON_FN_CALL_TIMEOUT` (30s). Activity restarts the budget, so a
+     * `PYLON_FN_CALL_TIMEOUT` (30s; Stack0 Cloud sets 300s). Activity
+     * restarts the budget, so a
      * streaming agent run stays alive as long as it keeps producing; a
      * silent hang is cancelled at the budget. Total lifetime is capped at
      * 10× this value however chatty the call is.

package/dist/index.d.ts

@@ -20,10 +20,11 @@
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
 export { workflow } from "./workflows";
+export type { RawResponse, RawResponseInit } from "./response";
 export { agent, isAgentDefinition, validatorToJsonSchema, validatorSchemaToJsonSchema, } from "./agent";
 export type { AgentDefinition, AgentTool, AgentCallArgs, AgentResult, } from "./agent";
 export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunnerResponse, WorkflowStepResult, } from "./workflows";
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";

package/dist/response.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Raw HTTP responses from webhook actions.
+ *
+ * An action called through `/api/webhooks/<name>` normally answers with its
+ * return value as JSON and status 200. Returning `ctx.response(...)` sends
+ * the given status, content type, headers, and body instead. Every other
+ * route (`/api/fn/<name>`, `ctx.runAction`) returns the value as ordinary
+ * JSON data.
+ *
+ * The host enforces the same rules (crates/router/src/raw_response.rs), so
+ * a hand-built object cannot bypass them. The two header lists must stay in
+ * sync.
+ */
+/** What `ctx.response` accepts. */
+export interface RawResponseInit {
+    /** HTTP status, 200-599. Default 200. */
+    status?: number;
+    /** Shorthand for the `Content-Type` header. Default `text/plain; charset=utf-8`. */
+    contentType?: string;
+    /** Extra response headers. Values must be visible ASCII. */
+    headers?: Record<string, string>;
+    /** Response body. Default empty. Must be empty for 204, 205, and 304. */
+    body?: string;
+}
+/** The marked value an action returns. Build it with `ctx.response`. */
+export interface RawResponse {
+    readonly __pylonResponse: 1;
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/**
+ * Build a raw HTTP response for a webhook action to return.
+ *
+ * ```ts
+ * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+ * ```
+ */
+export declare function response(init?: RawResponseInit): RawResponse;

package/dist/runtime.d.ts

@@ -14,7 +14,7 @@
  *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
  *   needs to queue multiple RPCs per call_id.
  */
-import type { DbReader, DbWriter, Llm, Rooms, Workflows } from "./types";
+import type { DbReader, DbWriter, Llm, Rooms, Workflows, Audit } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
@@ -46,4 +46,6 @@ export declare function buildRooms(callId: string): Rooms;
  * takes it from there, so `start` returns the instance id immediately.
  * Uses the queued call_id-keyed `rpc` (the reply carries no op_id).
  */
+/** Build `ctx.audit` — round-trips `audit_op` frames to the host. */
+export declare function buildAudit(callId: string): Audit;
 export declare function buildWorkflows(callId: string): Workflows;

package/dist/ssr-runtime.d.ts

@@ -337,6 +337,13 @@ export declare function moduleExistsIn(fs: any, path: any, cwd: string, dir: str
  * in the process.
  */
 export declare function findBoundaryIn(fs: any, path: any, cwd: string, componentPath: string, fileName: string): string | null;
+/** Loopback host? `host` is a lowercase authority (`host[:port]`,
+ *  `[ipv6]:port`). True for exactly `localhost`, dotted 127.0.0.0/8
+ *  without leading zeros, `::1`, or `0.0.0.0`, with an optional numeric
+ *  port. The match is exact, so
+ *  `localhost.example.com` is not loopback. Mirrors `is_loopback_host` in
+ *  crates/router/src/public_url.rs. Exported for tests. */
+export declare function isLoopbackHost(host: string): boolean;
 /** Pure origin resolution (exported for tests).
  *
  *  SECURITY: the request `Host` (and `X-Forwarded-Proto`) is attacker-

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Type definitions for the function system.
  */
+import type { RawResponse, RawResponseInit } from "./response";
 /**
  * Declarative auth requirement for a function. The framework
  * enforces this BEFORE the handler runs — if the caller doesn't
@@ -296,8 +297,23 @@ export interface Scheduler {
     runAfter(delayMs: number, fnName: string, args: Record<string, unknown>): Promise<string>;
     /** Schedule a function to run at a specific time (Unix ms). */
     runAt(timestamp: number, fnName: string, args: Record<string, unknown>): Promise<string>;
-    /** Cancel a previously scheduled function. */
-    cancel(scheduleId: string): Promise<void>;
+    /**
+     * Cancel a scheduled function that has not started. Pass the id
+     * `runAfter` or `runAt` returned.
+     *
+     * Resolves `{ cancelled: true }` when the job will not run, and
+     * `{ cancelled: false }` when the id is unknown or the job already
+     * started or finished (a running job is not interrupted). Rejects with
+     * `SCHEDULE_CANCEL_FAILED` when the cancel could not be saved; the job
+     * then still runs.
+     *
+     * Inside a mutation, the cancel commits or rolls back with the
+     * mutation: if the mutation throws, the job stays scheduled. From an
+     * action, it takes effect at once.
+     */
+    cancel(scheduleId: string): Promise<{
+        cancelled: boolean;
+    }>;
 }
 /**
  * Transactional email transport.
@@ -523,19 +539,154 @@ export interface Workflows {
     /**
      * Start a workflow instance by name. Returns immediately with the
      * instance id — the engine's background driver executes the steps.
+     *
+     * With `key` (for example a lead id), at most one non-terminal run
+     * exists per workflow name and key. If one exists, no new run starts
+     * and its id is returned with `created: false`. A finished run frees
+     * the key.
      */
-    start(name: string, input?: unknown): Promise<{
+    start(name: string, input?: unknown, opts?: {
+        key?: string;
+    }): Promise<{
         id: string;
+        created: boolean;
     }>;
     /**
-     * Deliver an event to an instance paused on
-     * `wf.waitForEvent(event)`. Rejects when the instance isn't waiting
-     * for that event.
+     * Send an event to a run. If the run is waiting for it
+     * (`wf.waitForEvent(event)`), the run resumes and `delivered` is true.
+     * Otherwise the event is buffered (`buffered: true`) and the run's next
+     * `waitForEvent(event)` consumes it. Rejects when the run has finished
+     * or already holds 100 buffered events. Events sent without data
+     * arrive as `{}`.
      */
     sendEvent(workflowId: string, event: string, data?: unknown): Promise<{
         delivered: boolean;
+        buffered: boolean;
+    }>;
+    /**
+     * Cancel a run. No further step runs. A step already in progress may
+     * finish, but its result is discarded. Resolves `cancelled: false` when
+     * the run had already finished. Rejects for an unknown id.
+     */
+    cancel(workflowId: string, opts?: {
+        reason?: string;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Read one run, or null if the id is unknown. */
+    get(workflowId: string): Promise<WorkflowRunSummary | null>;
+    /**
+     * List runs, newest first. `status: "active"` matches every
+     * non-terminal status. `limit` defaults to 100 (max 1000).
+     *
+     * ```ts
+     * // Seller texted STOP: end every cadence for the lead.
+     * const runs = await ctx.workflows.list({ key: leadId, status: "active" });
+     * for (const run of runs) {
+     *   await ctx.workflows.cancel(run.id, { reason: "STOP" });
+     * }
+     * ```
+     */
+    list(filter?: {
+        name?: string;
+        key?: string;
+        status?: WorkflowRunStatus | "active";
+        limit?: number;
+    }): Promise<WorkflowRunSummary[]>;
+}
+/**
+ * The application audit log (`ctx.audit` on mutations and actions).
+ * Append-only, stored with the auth audit events.
+ */
+export interface AuditLog {
+    /**
+     * Record an event. The actor and tenant come from the caller's session.
+     * `action` is a short dotted name (`lead.export`, `script.update`) and
+     * is stored as `app.<action>`. `meta` values are stored as strings
+     * (non-strings as JSON text); keep secrets out of it.
+     *
+     * Inside a mutation the event is written after the mutation commits and
+     * dropped if it rolls back. Rejects with `AUDIT_WRITE_FAILED` when an
+     * action's event could not be stored.
+     */
+    log(event: {
+        action: string;
+        entity?: string;
+        entityId?: string;
+        /** The user the event is about, when not the actor. */
+        subject?: string;
+        meta?: Record<string, unknown>;
+    }): Promise<{
+        id: string;
     }>;
 }
+/**
+ * `ctx.audit` on actions: {@link AuditLog.log} plus reads. Mutations get
+ * only `log`: in a Postgres mutation the transaction holds a connection,
+ * and a read would need a second.
+ */
+export interface Audit extends AuditLog {
+    /**
+     * Read events, newest first. A caller with a tenant reads that tenant's
+     * events; a caller without one reads only events it performed. Admin
+     * callers may pass `tenant` or read all tenants. `action` matches
+     * `lead.export` as `app.lead.export`; framework actions
+     * (`entity.update`, `retention.delete`) and auth action names match as
+     * given. `limit` defaults to 100 (max 1000). To page,
+     * pass `beforeId` set to the last event's `id`. `before` (unix seconds)
+     * limits by time.
+     */
+    list(filter?: {
+        entity?: string;
+        entityId?: string;
+        actor?: string;
+        action?: string;
+        tenant?: string;
+        before?: number;
+        beforeId?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
+}
+export interface AuditEntry {
+    id: string;
+    /** Unix seconds. */
+    createdAt: number;
+    /** `app.<action>`, `entity.insert|update|delete`, `retention.delete`, or an auth action. */
+    action: string;
+    actor: string | null;
+    subject: string | null;
+    tenant: string | null;
+    entity: string | null;
+    entityId: string | null;
+    ip: string | null;
+    success: boolean;
+    reason: string | null;
+    /** For `entity.*` events, `fields` lists the changed field names. */
+    meta: Record<string, string>;
+}
+export type WorkflowRunStatus = "pending" | "running" | "sleeping" | "waiting" | "completed" | "failed" | "cancelled";
+/** A workflow run without its step history. Times are unix seconds. */
+export interface WorkflowRunSummary {
+    id: string;
+    name: string;
+    key: string | null;
+    status: WorkflowRunStatus;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+    cancelReason: string | null;
+    /** Event name the run is waiting for, when `status` is "waiting". */
+    waitingFor: string | null;
+    /** When the current wait times out, if it has a timeout. */
+    waitDeadline: number | null;
+    /** When the current sleep ends. */
+    wakeAt: number | null;
+    /** Events sent but not yet consumed by a `waitForEvent`. */
+    bufferedEvents: number;
+    createdAt: number | null;
+    startedAt: number | null;
+    completedAt: number | null;
+}
 export interface LlmMessage {
     role: "user" | "assistant" | "system" | "tool";
     content: string | LlmContentBlock[];
@@ -915,6 +1066,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Durable workflows: start / deliver events — see {@link Workflows}. */
     workflows: Workflows;
+    /** Application audit log (write only in mutations) — see {@link AuditLog}. */
+    audit: AuditLog;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
     /** Shard tickets, reads, and inputs after the commit — see {@link Shards}. */
@@ -947,8 +1100,18 @@ export interface TenantDomainResult {
     status: string;
     /** Whether the hostname + TLS certificate are both active. */
     active?: boolean;
-    /** The single CNAME the customer points their hostname at. */
-    cnameTarget: string;
+    /**
+     * True for an apex domain (`acme.com`). An apex cannot be a CNAME, so the
+     * customer adds A/AAAA records pointing at the app instead.
+     */
+    apex?: boolean;
+    /**
+     * Every DNS record the customer adds, for both kinds of domain: a CNAME
+     * (subdomain) or A/AAAA (apex), plus ownership and certificate records.
+     */
+    records?: TenantDomainRecord[];
+    /** The CNAME the customer points a subdomain at; null for an apex. */
+    cnameTarget: string | null;
     /** TXT record proving domain ownership before DNS cutover (or null). */
     ownership: TenantDomainDns | null;
     /** TXT records that issue the DV certificate. */
@@ -956,6 +1119,13 @@ export interface TenantDomainResult {
     /** Human-readable provisioning errors, empty when healthy. */
     errors: string[];
 }
+export interface TenantDomainRecord {
+    type: "A" | "AAAA" | "CNAME" | "TXT";
+    name: string;
+    value: string;
+    /** What the record is for, to show the customer. */
+    purpose: string;
+}
 /**
  * Platform domains: attach / register / detach custom domains for your app's
  * OWN end-customers, so each tenant can reach your app on their own hostname.
@@ -1081,6 +1251,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Durable workflows: start / deliver events — see {@link Workflows}. */
     workflows: Workflows;
+    /** Application audit log — see {@link Audit}. */
+    audit: Audit;
     /** Attach / register custom domains for your app's OWN end-customers
      *  (platform domains) — see {@link Domains}. Cloud-only. */
     domains: Domains;
@@ -1125,12 +1297,34 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
      * ```
      */
     request?: RequestInfo;
+    /**
+     * Build a raw HTTP response. When an action called through
+     * `/api/webhooks/<name>` returns it, the route sends this status,
+     * content type, headers, and body instead of JSON. Other routes return
+     * it as ordinary JSON data. Throws on an invalid status or header.
+     *
+     * ```ts
+     * // Twilio expects TwiML, not JSON.
+     * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+     * ```
+     */
+    response(init?: RawResponseInit): RawResponse;
 }
 /** HTTP request metadata available on an action's ctx when invoked via an
  *  HTTP route binding. Header names are lowercased. */
 export interface RequestInfo {
     method: string;
+    /** Request path with the query string, as received. */
     path: string;
+    /**
+     * The full URL the client requested: scheme, host, path, and query.
+     * Behind a proxy, the host comes from `X-Forwarded-Host` or `Host`
+     * only when it is trusted (loopback, the `PYLON_PUBLIC_URL` host,
+     * `PYLON_CANONICAL_HOST`, a `PYLON_TRUSTED_HOSTS` entry, or one of the
+     * app's domains); otherwise the `PYLON_PUBLIC_URL` origin is used. Use
+     * it to verify providers that sign the whole URL, such as Twilio.
+     */
+    url: string;
     headers: Record<string, string>;
     rawBody: string;
 }

package/dist/workflows.d.ts

@@ -57,6 +57,7 @@ export type WorkflowRunnerResponse = {
 } | {
     action: "wait_event";
     event: string;
+    timeout?: string;
 } | {
     action: "complete";
     output: unknown;
@@ -80,10 +81,26 @@ export interface WorkflowRun<TInput = unknown> {
     /** Pause the workflow for a duration ("30s", "5m", "24h", "7d"). */
     sleep(duration: string): Promise<void>;
     /**
-     * Pause until `POST /api/workflows/<id>/event` delivers this event.
-     * Resolves with the event's data payload.
+     * Pause until the event arrives through `ctx.workflows.sendEvent` or
+     * `POST /api/workflows/<id>/event`. Resolves with the event's data
+     * (`{}` when it was sent without data).
+     *
+     * Events sent while the run is not waiting for them are buffered. The
+     * next `waitForEvent` with that name consumes the oldest buffered
+     * event, so an event that arrives during a step is not lost.
+     *
+     * The same event name can be awaited more than once in a run; each
+     * call consumes one event.
      */
     waitForEvent<T = unknown>(eventName: string): Promise<T>;
+    /**
+     * Same as above, but resolves with `null` if no event arrives within
+     * `timeout` ("60s", "5m", "24h", "7d"). The timeout is durable: it
+     * survives restarts, like `sleep`.
+     */
+    waitForEvent<T = unknown>(eventName: string, opts: {
+        timeout: string;
+    }): Promise<T | null>;
 }
 export interface WorkflowDefinition<TInput = unknown> {
     readonly __pylonWorkflow: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/define.ts

@@ -59,7 +59,8 @@ interface CommonDef<
    * IDLE-timeout SECONDS for this function: how long it may go without
    * producing any activity (a stream chunk, a `ctx.db` op, an LLM
    * event) before the host cancels the call. Defaults to
-   * `PYLON_FN_CALL_TIMEOUT` (30s). Activity restarts the budget, so a
+   * `PYLON_FN_CALL_TIMEOUT` (30s; Stack0 Cloud sets 300s). Activity
+   * restarts the budget, so a
    * streaming agent run stays alive as long as it keeps producing; a
    * silent hang is cancelled at the budget. Total lifetime is capped at
    * 10× this value however chatty the call is.

package/src/index.ts

@@ -21,6 +21,7 @@
 export { query, mutation, action } from "./define";
 export { v } from "./validators";
 export { workflow } from "./workflows";
+export type { RawResponse, RawResponseInit } from "./response";
 export {
   agent,
   isAgentDefinition,
@@ -80,6 +81,11 @@ export type {
   ShardTransfer,
   MemberRow,
   Workflows,
+  WorkflowRunSummary,
+  WorkflowRunStatus,
+  Audit,
+  AuditLog,
+  AuditEntry,
   VectorSearchQuery,
   VectorSearchResult,
   SearchResult,
@@ -99,6 +105,7 @@ export type {
   // results (the DNS the end-customer must set).
   Domains,
   TenantDomainResult,
+  TenantDomainRecord,
   TenantDomainDns,
   DomainAvailability,
   DomainContact,

package/src/response.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { response } from "./response";
+
+describe("ctx.response", () => {
+  test("defaults to an empty 200", () => {
+    expect(response()).toEqual({ __pylonResponse: 1, status: 200, headers: {}, body: "" });
+  });
+
+  test("contentType sets the content-type header and replaces one in headers", () => {
+    const r = response({
+      contentType: "text/xml",
+      headers: { "Content-Type": "text/plain", "X-Id": "1" },
+      body: "<Response/>",
+    });
+    expect(r.headers).toEqual({ "X-Id": "1", "content-type": "text/xml" });
+    expect(r.body).toBe("<Response/>");
+  });
+
+  test("rejects out-of-range and non-integer status", () => {
+    for (const status of [99, 101, 600, 200.5, Number.NaN]) {
+      expect(() => response({ status })).toThrow("status");
+    }
+  });
+
+  test("rejects a body on 204", () => {
+    expect(() => response({ status: 204, body: "x" })).toThrow("cannot carry a body");
+    expect(response({ status: 204 }).status).toBe(204);
+  });
+
+  test("rejects header injection and invalid names", () => {
+    expect(() => response({ headers: { "X-A": "a\r\nSet-Cookie: x=1" } })).toThrow("control");
+    expect(() => response({ headers: { "X-A": "café" } })).toThrow("control");
+    expect(() => response({ headers: { "X A": "v" } })).toThrow("token");
+    expect(() => response({ contentType: "text/xml\r\nX: y" })).toThrow("control");
+  });
+
+  test("rejects headers the server owns, in any case", () => {
+    for (const name of ["Content-Length", "set-cookie", "Access-Control-Allow-Origin", "Connection"]) {
+      expect(() => response({ headers: { [name]: "v" } })).toThrow("set by the server");
+    }
+  });
+});

package/src/response.ts

@@ -0,0 +1,109 @@
+/**
+ * Raw HTTP responses from webhook actions.
+ *
+ * An action called through `/api/webhooks/<name>` normally answers with its
+ * return value as JSON and status 200. Returning `ctx.response(...)` sends
+ * the given status, content type, headers, and body instead. Every other
+ * route (`/api/fn/<name>`, `ctx.runAction`) returns the value as ordinary
+ * JSON data.
+ *
+ * The host enforces the same rules (crates/router/src/raw_response.rs), so
+ * a hand-built object cannot bypass them. The two header lists must stay in
+ * sync.
+ */
+
+/** What `ctx.response` accepts. */
+export interface RawResponseInit {
+  /** HTTP status, 200-599. Default 200. */
+  status?: number;
+  /** Shorthand for the `Content-Type` header. Default `text/plain; charset=utf-8`. */
+  contentType?: string;
+  /** Extra response headers. Values must be visible ASCII. */
+  headers?: Record<string, string>;
+  /** Response body. Default empty. Must be empty for 204, 205, and 304. */
+  body?: string;
+}
+
+/** The marked value an action returns. Build it with `ctx.response`. */
+export interface RawResponse {
+  readonly __pylonResponse: 1;
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+
+/** Header names the server sets itself. Compared lowercase. */
+const RESERVED_HEADERS = new Set([
+  "connection",
+  "content-length",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "set-cookie",
+  "permissions-policy",
+  "referrer-policy",
+  "x-content-type-options",
+  "x-frame-options",
+  "x-xss-protection",
+]);
+const RESERVED_HEADER_PREFIXES = ["access-control-"];
+
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const VALUE_RE = /^[\t\x20-\x7e]*$/;
+
+function checkHeader(name: string, value: unknown): void {
+  if (!TOKEN_RE.test(name)) {
+    throw new Error(`ctx.response: header name ${JSON.stringify(name)} is not a valid HTTP token`);
+  }
+  if (typeof value !== "string") {
+    throw new Error(`ctx.response: header "${name}" must have a string value`);
+  }
+  if (!VALUE_RE.test(value)) {
+    throw new Error(
+      `ctx.response: header "${name}" has a value with control or non-ASCII characters`,
+    );
+  }
+  const lower = name.toLowerCase();
+  if (RESERVED_HEADERS.has(lower) || RESERVED_HEADER_PREFIXES.some((p) => lower.startsWith(p))) {
+    throw new Error(`ctx.response: header "${name}" is set by the server`);
+  }
+}
+
+/**
+ * Build a raw HTTP response for a webhook action to return.
+ *
+ * ```ts
+ * return ctx.response({ contentType: "text/xml", body: "<Response/>" });
+ * ```
+ */
+export function response(init: RawResponseInit = {}): RawResponse {
+  const status = init.status ?? 200;
+  if (!Number.isInteger(status) || status < 200 || status > 599) {
+    throw new Error(`ctx.response: status must be an integer from 200 to 599, got ${status}`);
+  }
+  const body = init.body ?? "";
+  if (typeof body !== "string") {
+    throw new Error("ctx.response: body must be a string");
+  }
+  if (body !== "" && (status === 204 || status === 205 || status === 304)) {
+    throw new Error(`ctx.response: status ${status} cannot carry a body`);
+  }
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(init.headers ?? {})) {
+    checkHeader(name, value);
+    headers[name] = value;
+  }
+  if (init.contentType !== undefined) {
+    checkHeader("Content-Type", init.contentType);
+    for (const name of Object.keys(headers)) {
+      if (name.toLowerCase() === "content-type") delete headers[name];
+    }
+    headers["content-type"] = init.contentType;
+  }
+  return { __pylonResponse: 1, status, headers, body };
+}