@vxil/sdk 0.5.3 → 0.6.0

package/dist/index.d.ts

@@ -359,7 +359,41 @@ export interface JobRun {
     /** earliest next pickup time; for a 'delayed' run this is deliver_after */
     next_attempt_at?: string | null;
     queued_at: string;
+    started_at?: string | null;
     completed_at: string | null;
+    /** generation runs (POST /v1/jobs/generation) only: the provider-side status */
+    generation_status?: string | null;
+    generation_json?: Record<string, unknown> | null;
+    /** the single-run read (`vx.jobs.run` / `waitForRun`) only: your enqueue
+     *  payload — `{ redacted: true }` for a platform-internal run; never on lists */
+    payload_json?: unknown;
+}
+/** The run states no later write can move — what `waitForRun` and an
+ *  async+wait invoke resolve `done: true` on. */
+export declare const JOB_TERMINAL_STATES: ReadonlySet<JobRun['state']>;
+/** `GET /v1/jobs/queue` — the live queue, one aggregate over your project's
+ *  runs. `oldest_queued_age_s` is the number to alarm on: the age of the
+ *  oldest run still waiting for an executor (null when nothing waits). */
+export interface JobsQueue {
+    depth: {
+        /** waiting for an executor right now: queued + retrying whose next attempt is due */
+        queued: number;
+        /** held until a time: a deliver_after, or a retry still in its backoff */
+        delayed: number;
+        /** an executor currently holds them */
+        running: number;
+    };
+    oldest_queued_age_s: number | null;
+    in_flight_by_lane: {
+        /** your own jobs (enqueue / enqueue-batch / generation / async fn invokes) */
+        runs: number;
+        /** the platform's outbound webhook delivery runs */
+        deliveries: number;
+        /** schedule-fired runs, incl. `fn-cron:*` function ticks */
+        cron: number;
+    };
+    /** runs that reached `dead` in the last 24 hours, on every path */
+    dead_last_24h: number;
 }
 export interface JobFlowRule {
     rule_id: string;
@@ -1231,6 +1265,15 @@ export interface FnInvokeOptions {
      *  function dedupes on it); on the async lane it is also the run's dedupe key,
      *  so a repeat with the same key returns the SAME `run_id`. */
     idempotencyKey?: string;
+    /** With `async: true` — "kick and know it finished": hold the call up to
+     *  `wait` seconds (integer 1..25, sent as `X-Vxil-Wait`) for the run to reach
+     *  a terminal state. Resolves to a `FnAsyncOutcome`: `done: true` + the
+     *  terminal `run` when it settled inside the bound, else `done: false` with
+     *  the run's current `status` (the run IS queued — `vx.jobs.waitForRun` /
+     *  `vx.jobs.run` continue from there). The function's OWN response never
+     *  rides this shape; the sync lane returns it. A client `timeoutMs` shorter
+     *  than `wait` × 1000 aborts the call first. Ignored without `async`. */
+    wait?: number;
 }
 /** The async lane's 202 ack. */
 export interface FnAsyncAck {
@@ -1239,13 +1282,34 @@ export interface FnAsyncAck {
     /** present (true) when the Idempotency-Key matched an earlier run */
     deduplicated?: boolean;
 }
-/** `vx.fn.<name>`: the function's Output by default, the 202 ack with `{ async: true }`. */
+/** What `vx.fn.<name>(input, { async: true, wait })` resolves to. */
+export interface FnAsyncOutcome {
+    run_id: string;
+    /** the run's state: terminal when `done`, else its live state at the deadline */
+    status: JobRun['state'];
+    /** true ⇔ the run reached a terminal state inside the wait bound */
+    done: boolean;
+    /** the terminal run (the `GET /v1/jobs/runs/{run_id}` row); absent on a timeout */
+    run?: JobRun;
+    /** present (true) when the Idempotency-Key matched an earlier run */
+    deduplicated?: boolean;
+    /** `timeout` — the bound passed before the run was terminal; `unavailable` —
+     *  the run was queued but the platform could not hold the wait (poll it) */
+    wait?: 'timeout' | 'unavailable';
+}
+/** `vx.fn.<name>`: the function's Output by default; the 202 ack with
+ *  `{ async: true }`; the run outcome with `{ async: true, wait }`. */
 export interface FnInvoker<I, O> {
     (input: I, opts?: FnInvokeOptions & {
         async?: false;
     }): Promise<O>;
     (input: I, opts: FnInvokeOptions & {
         async: true;
+        wait: number;
+    }): Promise<FnAsyncOutcome>;
+    (input: I, opts: FnInvokeOptions & {
+        async: true;
+        wait?: undefined;
     }): Promise<FnAsyncAck>;
 }
 /** feature client property → the feature key (in S['features']) that enables it.
@@ -1436,6 +1500,104 @@ export type CmsTxStep = {
     item_id: string;
     $where?: Record<string, unknown>;
 };
+/** One op of `vx.cms.batch` (cms.md §21) — the single route's own body keys,
+ *  typed by op. `ref` is an opaque tag echoed on the matching result. */
+export type CmsBatchOp = {
+    op: 'get';
+    collection: string;
+    id: string;
+    expand?: readonly string[] | string;
+    ref?: string;
+} | {
+    op: 'query';
+    collection: string;
+    filter?: Record<string, unknown>;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+    expand?: readonly string[] | string;
+    count?: boolean;
+    ref?: string;
+} | {
+    op: 'create';
+    collection: string;
+    data: Record<string, unknown>;
+    status?: 'draft' | 'published';
+    lock?: string;
+    guard?: CmsGuard;
+    guards?: CmsGuardTerm[];
+    ref?: string;
+} | {
+    op: 'patch';
+    collection: string;
+    id: string;
+    data?: Record<string, unknown>;
+    $inc?: Record<string, number>;
+    if?: Record<string, unknown>;
+    if_version?: number;
+    lock?: string;
+    guard?: CmsGuard;
+    guards?: CmsGuardTerm[];
+    ref?: string;
+} | {
+    op: 'delete';
+    collection: string;
+    id: string;
+    if_version?: number;
+    ref?: string;
+};
+/** What a 2xx batch result's `data` is, per op: the item record (get / create /
+ *  patch), a page or `{ count }` (query), the delete tally (delete). */
+export type CmsBatchData<O extends CmsBatchOp> = O extends {
+    op: 'query';
+} ? (O extends {
+    count: true;
+} ? {
+    count: number;
+} : {
+    items: Array<Record<string, unknown>>;
+    next_cursor: string | null;
+}) : O extends {
+    op: 'delete';
+} ? {
+    item_id: string;
+    deleted: boolean;
+    cascaded: number;
+    set_null: number;
+} : Record<string, unknown>;
+/** One batch result: the single route's `status` and its `data` (2xx) or
+ *  `error`. In an aborted atomic batch the undone ops carry `424 rolled_back`
+ *  and the ops after the failure `424 not_run`. The op whose result crossed
+ *  the 8 MiB per-batch budget is `413 batch_result_too_large` (the rest
+ *  `424 not_run`); non-atomic, an op that failed unexpectedly is
+ *  `500 internal_error` in-line — the ops before it committed and keep their
+ *  results, so never retry the whole batch on one 500. At most 5 ops may be
+ *  `query` (a whole-batch 422 otherwise). */
+export type CmsBatchResult<O extends CmsBatchOp = CmsBatchOp> = {
+    op: O['op'];
+    ref?: string;
+    status: number;
+    data: CmsBatchData<O>;
+    error?: undefined;
+} | {
+    op: O['op'];
+    ref?: string;
+    status: number;
+    data?: undefined;
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+    };
+};
+export interface CmsBatchResponse<T extends readonly CmsBatchOp[]> {
+    /** true iff every op is 2xx — for an atomic batch, iff the transaction committed. */
+    ok: boolean;
+    atomic: boolean;
+    results: {
+        [K in keyof T]: T[K] extends CmsBatchOp ? CmsBatchResult<T[K]> : never;
+    };
+}
 /** One CMS item as the API returns it — the envelope `$expand` inlines in place
  *  of a stored relation id (cms.md §6.2). `R` is the target collection's Row. */
 export interface CmsItemEnvelope<R> {
@@ -1640,7 +1802,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      *  `vx.fn.<name>(payload, { async: true })` takes the ASYNC lane
      *  (`x-vxil-async: 1`): it resolves to the `202 { run_id, status:'queued' }`
      *  ack at once and the run is delivered through the jobs lane — poll
-     *  `vx.jobs.run(run_id)` or subscribe to `job.*` events. */
+     *  `vx.jobs.run(run_id)` or subscribe to `job.*` events. With `wait` (1..25 s)
+     *  the call holds for the run to settle and resolves to a `FnAsyncOutcome`. */
     readonly fn: { [K in keyof S["functions"] & string]: FnInvoker<S["functions"][K]["Input"], S["functions"][K]["Output"]>; };
     private call;
     readonly users: {
@@ -2127,6 +2290,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             limit?: number;
         }) => Promise<JobRun[]>;
         run: (runId: string) => Promise<JobRun>;
+        /** "Wait for this run": `GET /v1/jobs/runs/{run_id}?wait=<seconds>` holds
+         *  the request platform-side (re-reading the run on one bounded connection,
+         *  500 ms at first then backing off to 2 s) until the run is terminal —
+         *  succeeded / failed / dead / cancelled — or `seconds` (integer 1..25)
+         *  pass; then the CURRENT run comes back with `done: false` (also when the
+         *  per-tenant budget of 60 held reads a minute declined to hold the wait —
+         *  the response header `x-vxil-wait` says `timeout` or `unavailable`). `run` is the plain `run(runId)` row either
+         *  way (same `jobs:read` scope; 404 at once for an unknown id). Loop it for a
+         *  longer wait. A client `timeoutMs` shorter than `seconds` × 1000 aborts the
+         *  call first. NOT `wait(runId, …)` — that is the durable in-handler
+         *  wait-for-event. */
+        waitForRun: (runId: string, opts: {
+            seconds: number;
+        }) => Promise<{
+            run: JobRun;
+            done: boolean;
+        }>;
+        /** The live queue: depth by state, the oldest waiting run's age (the
+         *  number to alarm on), in-flight runs per lane, dead letters in 24 h. */
+        queue: () => Promise<JobsQueue>;
         cancel: (runId: string) => Promise<{
             run_id: string;
             state: string;
@@ -2888,6 +3071,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             committed: boolean;
             tx_id: string;
         }>;
+        /** P1-1 (cms.md §21): several get / query / create / patch / delete ops in
+         *  ONE round trip — the function-chain shape ("read 3 rows → patch 2 →
+         *  create 1" is one call, not six). ≤25 ops, each run through the SAME path
+         *  its single route uses (scopes, owner-scoping, hooks, guards, `if`,
+         *  `if_version`, `$inc`), each reporting its own status in `results` — a
+         *  batch never throws for a per-op failure; check `ok` / each `status`.
+         *  `atomic: true` runs everything in ONE tenant transaction: reads see
+         *  earlier writes and the first non-2xx op rolls every write back (the
+         *  undone ops answer `424 rolled_back`, the rest `424 not_run`). Default:
+         *  sequential, per-op status, no cross-op rollback. `ref` tags an op so
+         *  its result is easy to find. */
+        batch: <T extends readonly CmsBatchOp[]>(ops: readonly [...T], opts?: {
+            atomic?: boolean;
+        }) => Promise<CmsBatchResponse<T>>;
         /** cms-rel B5 (cms.md §12.4): declared read-models (config `readModels`
          *  bag) — list with last-run status, and "run now" materialization into
          *  the rollup collection. */
@@ -3852,11 +4049,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 template: string;
                 version: number;
             }>;
-            /** List stored templates (each name + its latest version). */
+            /** List stored templates (each name + its latest version). `content_sha256`
+             *  is the canonical hash of the latest version's {system, user, schema},
+             *  stored when the version was written — what `vxil push` compares a
+             *  declared `ai.templates[]` entry against; absent on a version stored
+             *  before 2026-09-23 (the next push re-puts that template once). */
             list: () => Promise<Array<{
                 name: string;
                 latest_version: number;
                 created_at: string;
+                content_sha256?: string;
             }>>;
         };
         /** Provider × capability matrix + the tenant's default provider (the set an
@@ -4595,4 +4797,4 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         };
     };
 }
-export {};
+export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, type ReportingOptions, type ReportEvent, type FetchHandler, } from './reporting.js';

package/dist/index.js

@@ -47,6 +47,9 @@ export class VxilError extends Error {
         this.name = 'VxilError';
     }
 }
+/** The run states no later write can move — what `waitForRun` and an
+ *  async+wait invoke resolve `done: true` on. */
+export const JOB_TERMINAL_STATES = new Set(['succeeded', 'failed', 'dead', 'cancelled']);
 const DEFAULT_BASE = 'https://api.vxil.com';
 /** Normalize the `expand` option to the `$expand` query value: a comma-joined
  *  list (the server's spelling), or `undefined` when nothing is expanded so the
@@ -232,7 +235,8 @@ export class Vxil {
      *  `vx.fn.<name>(payload, { async: true })` takes the ASYNC lane
      *  (`x-vxil-async: 1`): it resolves to the `202 { run_id, status:'queued' }`
      *  ack at once and the run is delivered through the jobs lane — poll
-     *  `vx.jobs.run(run_id)` or subscribe to `job.*` events. */
+     *  `vx.jobs.run(run_id)` or subscribe to `job.*` events. With `wait` (1..25 s)
+     *  the call holds for the run to settle and resolves to a `FnAsyncOutcome`. */
     fn = new Proxy({}, {
         get: (_t, prop) => {
             if (typeof prop !== 'string')
@@ -246,6 +250,7 @@ export class Vxil {
                     headers: {
                         authorization: `Bearer ${this.key}`, ...this.authHeaders(), 'content-type': 'application/json',
                         ...(opts?.async ? { 'x-vxil-async': '1' } : {}),
+                        ...(opts?.async && opts.wait !== undefined ? { 'x-vxil-wait': String(opts.wait) } : {}),
                         ...(opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {}),
                     },
                     body: JSON.stringify(payload ?? {}),
@@ -258,6 +263,22 @@ export class Vxil {
                     catch { /* non-JSON error body */ }
                     throw new VxilError(res.status, e.code ?? `http_${res.status}`, e.message ?? text.slice(0, 200), undefined, undefined, undefined, parseRetryAfter(res.headers.get('retry-after')));
                 }
+                if (opts?.async && opts.wait !== undefined) {
+                    // kick-and-wait: 200 = the terminal run's { data, meta } envelope
+                    // (the jobs read shape); 202 = the ack with the run's current state
+                    // (+ x-vxil-wait: timeout | unavailable). Normalised to ONE shape.
+                    const parsed = (text.length ? JSON.parse(text) : {});
+                    if (res.status === 200 && parsed.data) {
+                        const run = parsed.data;
+                        return { run_id: run.run_id, status: run.state, done: JOB_TERMINAL_STATES.has(run.state), run };
+                    }
+                    const w = res.headers.get('x-vxil-wait');
+                    return {
+                        run_id: parsed.run_id ?? '', status: parsed.status ?? 'queued', done: false,
+                        ...(parsed.deduplicated ? { deduplicated: true } : {}),
+                        ...(w === 'timeout' || w === 'unavailable' ? { wait: w } : {}),
+                    };
+                }
                 return text.length ? JSON.parse(text) : undefined;
             };
         },
@@ -581,6 +602,24 @@ export class Vxil {
             return (await this.call('GET', `/v1/jobs/runs${s}`)).data.runs;
         },
         run: async (runId) => (await this.call('GET', `/v1/jobs/runs/${encodeURIComponent(runId)}`)).data,
+        /** "Wait for this run": `GET /v1/jobs/runs/{run_id}?wait=<seconds>` holds
+         *  the request platform-side (re-reading the run on one bounded connection,
+         *  500 ms at first then backing off to 2 s) until the run is terminal —
+         *  succeeded / failed / dead / cancelled — or `seconds` (integer 1..25)
+         *  pass; then the CURRENT run comes back with `done: false` (also when the
+         *  per-tenant budget of 60 held reads a minute declined to hold the wait —
+         *  the response header `x-vxil-wait` says `timeout` or `unavailable`). `run` is the plain `run(runId)` row either
+         *  way (same `jobs:read` scope; 404 at once for an unknown id). Loop it for a
+         *  longer wait. A client `timeoutMs` shorter than `seconds` × 1000 aborts the
+         *  call first. NOT `wait(runId, …)` — that is the durable in-handler
+         *  wait-for-event. */
+        waitForRun: async (runId, opts) => {
+            const { data } = await this.call('GET', `/v1/jobs/runs/${encodeURIComponent(runId)}?wait=${encodeURIComponent(String(opts.seconds))}`);
+            return { run: data, done: JOB_TERMINAL_STATES.has(data.state) };
+        },
+        /** The live queue: depth by state, the oldest waiting run's age (the
+         *  number to alarm on), in-flight runs per lane, dead letters in 24 h. */
+        queue: async () => (await this.call('GET', '/v1/jobs/queue')).data,
         cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
         /** Clone a terminal run into a fresh queued run. */
         replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
@@ -1058,6 +1097,21 @@ export class Vxil {
          *  rolls the WHOLE transaction back (409 precondition_failed names the
          *  step). cms-internal only — no cross-feature effects inside the tx. */
         transaction: async (steps) => (await this.call('POST', '/v1/cms/transactions', { steps })).data,
+        /** P1-1 (cms.md §21): several get / query / create / patch / delete ops in
+         *  ONE round trip — the function-chain shape ("read 3 rows → patch 2 →
+         *  create 1" is one call, not six). ≤25 ops, each run through the SAME path
+         *  its single route uses (scopes, owner-scoping, hooks, guards, `if`,
+         *  `if_version`, `$inc`), each reporting its own status in `results` — a
+         *  batch never throws for a per-op failure; check `ok` / each `status`.
+         *  `atomic: true` runs everything in ONE tenant transaction: reads see
+         *  earlier writes and the first non-2xx op rolls every write back (the
+         *  undone ops answer `424 rolled_back`, the rest `424 not_run`). Default:
+         *  sequential, per-op status, no cross-op rollback. `ref` tags an op so
+         *  its result is easy to find. */
+        batch: async (ops, opts) => (await this.call('POST', '/v1/cms/batch', {
+            ops: ops.map((o) => ('expand' in o && o.expand !== undefined ? { ...o, expand: expandParam(o.expand) } : o)),
+            ...(opts?.atomic !== undefined ? { atomic: opts.atomic } : {}),
+        })).data,
         /** cms-rel B5 (cms.md §12.4): declared read-models (config `readModels`
          *  bag) — list with last-run status, and "run now" materialization into
          *  the rollup collection. */
@@ -1521,7 +1575,11 @@ export class Vxil {
              *  requests — the output is validated (with one repair pass) against it;
              *  a per-request `response_schema` overrides it. Ignored on streams. */
             put: async (input) => (await this.call('POST', '/v1/ai/templates', input)).data,
-            /** List stored templates (each name + its latest version). */
+            /** List stored templates (each name + its latest version). `content_sha256`
+             *  is the canonical hash of the latest version's {system, user, schema},
+             *  stored when the version was written — what `vxil push` compares a
+             *  declared `ai.templates[]` entry against; absent on a version stored
+             *  before 2026-09-23 (the next push re-puts that template once). */
             list: async () => (await this.call('GET', '/v1/ai/templates')).data.templates,
         },
         /** Provider × capability matrix + the tenant's default provider (the set an
@@ -1881,3 +1939,6 @@ export class Vxil {
         },
     };
 }
+// Failure reporting for tenant functions — the Sentry-envelope forwarder
+// (roadmap §4.11 P0-4e). Zero dependencies; see reporting.ts.
+export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, } from './reporting.js';

package/dist/reporting.d.ts

@@ -0,0 +1,62 @@
+/** The report POST is bounded to this many milliseconds. */
+export declare const REPORT_TIMEOUT_MS = 3000;
+export interface ReportingOptions {
+    /** The reporter's DSN: `https://<key>@<host>/<projectId>`. */
+    dsn: string;
+    /** Free-form tags stamped on every event (string values only). */
+    tags?: Record<string, string>;
+    /** `environment` / `release` as your reporter shows them. */
+    environment?: string;
+    release?: string;
+    /** Override the fetch used to post the envelope (tests; a custom egress). */
+    fetch?: typeof fetch;
+    /** `false` never reports a Response, whatever its status (throws are always
+     *  reported). */
+    reportNon2xx?: boolean;
+    /** Which Response statuses are reported. Default: 5xx only — a 4xx is your
+     *  caller's problem, and reporting it would let an unauthenticated caller of
+     *  an HTTP-triggered function post one envelope per bad request. Opt 4xx in
+     *  deliberately: `reportStatuses: (s) => s >= 400`. */
+    reportStatuses?: (status: number) => boolean;
+    /** Bound on the report POST, in milliseconds (default REPORT_TIMEOUT_MS). */
+    timeoutMs?: number;
+}
+export interface FetchHandler {
+    fetch(request: Request, ...rest: unknown[]): Promise<Response> | Response;
+}
+/** Parsed DSN parts, or null when the DSN is not usable. PURE. */
+export declare function parseDsn(dsn: string): {
+    endpoint: string;
+    key: string;
+} | null;
+export interface ReportEvent {
+    /** `exception` for a throw; `message` for a non-2xx response. */
+    kind: 'exception' | 'message';
+    type?: string;
+    value: string;
+    stack?: string;
+    status?: number;
+    tags?: Record<string, string>;
+    environment?: string;
+    release?: string;
+}
+/** The envelope body for one event (three NDJSON lines). PURE. */
+export declare function buildEnvelope(dsn: string, ev: ReportEvent, now?: Date): string;
+/** POST one event to the DSN. Never throws, never takes longer than
+ *  `timeoutMs` (REPORT_TIMEOUT_MS by default); resolves true when the reporter
+ *  accepted it. Exported so a handler can report on its own terms too. */
+export declare function report(opts: ReportingOptions, ev: ReportEvent): Promise<boolean>;
+/** The event for a thrown value. PURE. */
+export declare function exceptionEvent(e: unknown): ReportEvent;
+/** The default status filter: 5xx only. */
+export declare const reportServerErrors: (status: number) => boolean;
+/**
+ * Wrap a function's `{ fetch }` handler (or a bare `(request) => Response`).
+ * A throw is reported and re-thrown; a 5xx Response (or whatever
+ * `reportStatuses` selects) is reported and returned. The wrapper adds nothing
+ * else — the platform still sees exactly what your handler produced, and never
+ * later than REPORT_TIMEOUT_MS after it produced it (not later at all when the
+ * runtime passes an ExecutionContext: the report rides `ctx.waitUntil`).
+ */
+export declare function withReporting<H extends FetchHandler>(handler: H, opts: ReportingOptions): H;
+export declare function withReporting<F extends (request: Request, ...rest: never[]) => Promise<Response> | Response>(handler: F, opts: ReportingOptions): F;

package/dist/reporting.js

@@ -0,0 +1,218 @@
+// withReporting — forward a tenant function's failure to the tenant's OWN
+// error reporter over the Sentry envelope HTTP format (roadmap §4.11 P0-4e,
+// techmaker evaluation P0-5's "SDK half", 2026-09-23).
+//
+// NOT a Sentry SDK and NOT a dependency on one: the function sandbox is
+// Web-standard fetch/crypto only, so this is the plain ingestion envelope
+// (https://develop.sentry.dev/sdk/data-model/envelopes/) posted to
+// `<scheme>://<host>/api/<project>/envelope/` with the `X-Sentry-Auth` header
+// derived from the DSN. Any reporter that speaks that endpoint — Sentry,
+// GlitchTip, Bugsink, a self-hosted relay — receives it.
+//
+// CONTRACT
+//   • a handler that THROWS is reported, then the throw is re-thrown unchanged —
+//     the platform's own retry / dead-letter / functions.run.failed semantics
+//     are never altered by observing them;
+//   • a handler that returns a 5xx Response is reported as a message event
+//     and the Response is returned unchanged. A 4xx is the CALLER's problem
+//     and is NOT reported by default: an HTTP-triggered function answering
+//     401/404 to bad requests must not let any internet caller drive one
+//     envelope per request out of the tenant's egress and reporter quota
+//     (`reportStatuses` widens it deliberately);
+//   • the report NEVER extends the handler's wall time beyond REPORT_TIMEOUT_MS:
+//     the POST is bounded (`AbortSignal.timeout` on the fetch AND a race, for
+//     a fetch that ignores its signal), and when the runtime hands the handler
+//     an ExecutionContext (`fetch(request, env, ctx)`) the report rides
+//     `ctx.waitUntil` and delays the result by nothing at all. Without the
+//     bound, a reporter host that accepted the TCP connection and never
+//     answered turned a 200 ms failure into the function's own deadline
+//     expiry, the run was recorded as a timeout instead of the real error, and
+//     each retry burned the whole budget on the reporter;
+//   • the report itself can NEVER surface into the handler's result: a
+//     malformed DSN, a blocked egress (403 egress_blocked — put the DSN host in
+//     the function's `egressAllow`), a network fault, a timeout or a 5xx from
+//     the reporter are swallowed (and printed with `console.warn` so `vxil
+//     functions logs` shows them);
+//   • no body of the request or response is ever sent — only the error's
+//     class/message/stack, the status, and the tags you pass.
+//
+// Usage inside a function (the DSN in a per-function secret, never the bundle):
+//
+//   import { withReporting } from '@vxil/sdk';
+//   export default withReporting({
+//     async fetch(req, env, ctx) { … },
+//   }, { dsn: SENTRY_DSN, tags: { fn: 'generation-sweeper' }, environment: 'production' });
+/** The report POST is bounded to this many milliseconds. */
+export const REPORT_TIMEOUT_MS = 3_000;
+/** Parsed DSN parts, or null when the DSN is not usable. PURE. */
+export function parseDsn(dsn) {
+    try {
+        const u = new URL(dsn);
+        const key = u.username;
+        const project = u.pathname.replace(/\/+$/, '').split('/').pop() ?? '';
+        if (!key || !project || !/^https?:$/.test(u.protocol))
+            return null;
+        const base = u.pathname.slice(0, u.pathname.lastIndexOf(`/${project}`));
+        return { endpoint: `${u.protocol}//${u.host}${base}/api/${project}/envelope/`, key };
+    }
+    catch {
+        return null;
+    }
+}
+/** A 32-hex event id (the envelope requires one). */
+function eventId() {
+    const b = new Uint8Array(16);
+    crypto.getRandomValues(b);
+    return [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}
+/** The envelope body for one event (three NDJSON lines). PURE. */
+export function buildEnvelope(dsn, ev, now = new Date()) {
+    const id = eventId();
+    const header = { event_id: id, sent_at: now.toISOString(), dsn };
+    const item = { type: 'event', content_type: 'application/json' };
+    const event = {
+        event_id: id,
+        timestamp: now.toISOString(),
+        platform: 'javascript',
+        level: 'error',
+        sdk: { name: 'vxil.withReporting', version: '1' },
+        tags: { ...(ev.tags ?? {}), ...(ev.status !== undefined ? { http_status: String(ev.status) } : {}) },
+        ...(ev.environment ? { environment: ev.environment } : {}),
+        ...(ev.release ? { release: ev.release } : {}),
+    };
+    if (ev.kind === 'exception') {
+        event.exception = {
+            values: [{
+                    type: ev.type ?? 'Error',
+                    value: ev.value,
+                    ...(ev.stack ? { stacktrace: { frames: framesOf(ev.stack) } } : {}),
+                }],
+        };
+    }
+    else {
+        event.message = { formatted: ev.value };
+        event.logger = 'vxil.function';
+    }
+    return `${JSON.stringify(header)}\n${JSON.stringify(item)}\n${JSON.stringify(event)}\n`;
+}
+/** Best-effort V8 stack → Sentry frames (innermost last, as Sentry expects). */
+function framesOf(stack) {
+    const out = [];
+    for (const line of stack.split('\n')) {
+        const m = /^\s*at\s+(?:(.*?)\s+\()?(.*?):(\d+):(\d+)\)?\s*$/.exec(line);
+        if (!m)
+            continue;
+        out.push({ function: m[1] ?? '<anonymous>', filename: m[2], lineno: Number(m[3]), colno: Number(m[4]) });
+    }
+    return out.reverse().slice(-50);
+}
+/** POST one event to the DSN. Never throws, never takes longer than
+ *  `timeoutMs` (REPORT_TIMEOUT_MS by default); resolves true when the reporter
+ *  accepted it. Exported so a handler can report on its own terms too. */
+export async function report(opts, ev) {
+    const parsed = parseDsn(opts.dsn);
+    if (!parsed) {
+        console.warn('vxil.withReporting: unusable DSN (expected https://<key>@<host>/<project>)');
+        return false;
+    }
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const timeoutMs = Math.max(1, opts.timeoutMs ?? REPORT_TIMEOUT_MS);
+    // Two bounds on purpose: the signal ends the real request early (and frees
+    // the connection); the race ends the WAIT even when a fetch ignores its
+    // signal, so the handler's wall time is bounded regardless.
+    const signal = typeof AbortSignal?.timeout === 'function' ? AbortSignal.timeout(timeoutMs) : undefined;
+    let timer;
+    const deadline = new Promise((resolve) => { timer = setTimeout(() => resolve('timeout'), timeoutMs); });
+    try {
+        const res = await Promise.race([
+            doFetch(parsed.endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/x-sentry-envelope',
+                    'x-sentry-auth': `Sentry sentry_version=7, sentry_client=vxil.withReporting/1, sentry_key=${parsed.key}`,
+                },
+                body: buildEnvelope(opts.dsn, {
+                    ...ev,
+                    tags: { ...(opts.tags ?? {}), ...(ev.tags ?? {}) },
+                    ...(opts.environment ? { environment: opts.environment } : {}),
+                    ...(opts.release ? { release: opts.release } : {}),
+                }),
+                ...(signal ? { signal } : {}),
+            }),
+            deadline,
+        ]);
+        if (res === 'timeout') {
+            console.warn(`vxil.withReporting: reporter did not answer within ${timeoutMs} ms`);
+            return false;
+        }
+        if (!res.ok) {
+            console.warn(`vxil.withReporting: reporter answered ${res.status}` + (res.status === 403 ? ' (is the DSN host in egressAllow?)' : ''));
+            return false;
+        }
+        return true;
+    }
+    catch (e) {
+        console.warn(`vxil.withReporting: report failed: ${String(e?.message ?? e).slice(0, 200)}`);
+        return false;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** The event for a thrown value. PURE. */
+export function exceptionEvent(e) {
+    if (e instanceof Error) {
+        return { kind: 'exception', type: e.name || 'Error', value: e.message || String(e), ...(e.stack ? { stack: e.stack } : {}) };
+    }
+    return { kind: 'exception', type: 'Error', value: typeof e === 'string' ? e : JSON.stringify(e)?.slice(0, 500) ?? String(e) };
+}
+/** The first `ExecutionContext`-shaped argument after the request (Workers
+ *  hand `fetch(request, env, ctx)`), or null. */
+function waitUntilOf(rest) {
+    for (const x of rest) {
+        if (x && typeof x === 'object' && typeof x.waitUntil === 'function')
+            return x;
+    }
+    return null;
+}
+/** The default status filter: 5xx only. */
+export const reportServerErrors = (status) => status >= 500;
+export function withReporting(handler, opts) {
+    const inner = typeof handler === 'function'
+        ? (req, ...rest) => handler(req, ...rest)
+        : (req, ...rest) => handler.fetch(req, ...rest);
+    const shouldReport = opts.reportStatuses ?? reportServerErrors;
+    const wrapped = async (req, ...rest) => {
+        const ctx = waitUntilOf(rest);
+        // With a ctx the report is handed off and the result is not delayed at
+        // all; without one it is awaited, but report() is itself bounded.
+        const dispatch = (ev) => {
+            const p = report(opts, ev);
+            if (ctx) {
+                ctx.waitUntil(p);
+                return Promise.resolve();
+            }
+            return p;
+        };
+        let res;
+        try {
+            res = await inner(req, ...rest);
+        }
+        catch (e) {
+            await dispatch(exceptionEvent(e));
+            throw e;
+        }
+        if (opts.reportNon2xx !== false && shouldReport(res.status)) {
+            await dispatch({
+                kind: 'message',
+                value: `function returned ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`,
+                status: res.status,
+            });
+        }
+        return res;
+    };
+    if (typeof handler === 'function')
+        return wrapped;
+    return { ...handler, fetch: wrapped };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",