@vxil/sdk 0.5.3 → 0.7.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;
@@ -768,6 +802,11 @@ export interface JobRunEventPayload {
     attempt: number;
     level?: 'error';
     state?: 'broken';
+    /** `job.dead_lettered` only, and only when something other than the
+     *  executor killed the run: `reaped` (the stuck-run reaper) or
+     *  `queue_backstop` (the queue's own retries ran out). Absent when the run
+     *  exhausted its attempts normally. */
+    reason?: 'reaped' | 'queue_backstop';
 }
 /** Event name → typed `data`, for the events that settle work you started.
  *  `VxilEventPayload<'job.generation.failed'>` names one; everything else on
@@ -780,6 +819,121 @@ export interface VxilEventPayloads {
     'job.dead_lettered': JobRunEventPayload;
 }
 export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
+/** The `trigger` label on the envelope. The config spells two of them in
+ *  camelCase (`cmsHook`, `authHook`); on the wire they are kebab-case. */
+export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
+/** The audiences a function's scoped callback tokens are minted for — one per
+ *  feature its declared scopes reach. `control-plane` carries `users:*` /
+ *  `usage:read` only. There is deliberately no `functions` audience: a function
+ *  cannot call another function. */
+export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane';
+/** One short-lived scoped token per audience your scopes imply
+ *  (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
+ *  scopes do not reach is absent. Send it as `Authorization: Bearer …` to
+ *  `vxil_base`. */
+export type FunctionScopedJwts = {
+    [A in FunctionCallbackAudience]?: string;
+};
+/** The verified end-user an `http` invocation carries when the caller presented
+ *  a vxil-auth session. */
+export interface FunctionEndUser {
+    id: string;
+    sid: string;
+    /** the step-up epoch, when the session has one */
+    elv?: number;
+}
+/** The fields every invocation carries, whatever fired it. */
+export interface FunctionEnvelopeBase {
+    tenant_id: string;
+    request_id: string;
+    /** Stable across redeliveries of the same event: delivery is at-least-once,
+     *  so dedupe your writes on it. */
+    idempotency_key: string;
+    /** The edge to call vxil back through. */
+    vxil_base: string;
+    scoped_jwts: FunctionScopedJwts;
+    /** Your declared per-function secrets (`secrets: ['secret:<name>']`), keyed by
+     *  bare name and resolved at invoke time. */
+    secrets: Record<string, string>;
+}
+/** `payload` of a `cms-hook` invocation. It carries no field values: re-read
+ *  the item by `item_id`. */
+export interface CmsHookTriggerPayload {
+    /** `cms.item.created` or `cms.item.updated` for a binding that names a
+     *  collection; a binding without one also sees the other `cms.item.*` events */
+    event: string;
+    collection: string;
+    item_id: string;
+}
+/** `payload` of an `auth-hook` invocation: the event's own fields plus
+ *  `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
+ *  `auth.session.created` → `{ user_id, session_id }`; `auth.session.revoked`
+ *  adds `reason`; `auth.signin.failure` → `{ email_hash | user_id, reason }`. */
+export interface AuthHookTriggerPayload {
+    event: string;
+    user_id?: string;
+    [field: string]: unknown;
+}
+/** `payload` of a `webhook` invocation: one platform event under the binding's
+ *  `source` prefix. `D` is the event's own payload (see `VxilEventPayload`). */
+export interface WebhookTriggerPayload<D = Record<string, unknown>> {
+    event: string;
+    audit_id: number | null;
+    occurred_at: string | null;
+    actor: string | null;
+    surface: string | null;
+    /** the event's payload; `{ truncated: true }` when it was larger than the
+     *  function's webhook payload bound, null when the event carried none */
+    data: D | {
+        truncated: true;
+    } | null;
+}
+/** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
+ *  parameters on a GET). */
+export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
+    trigger: 'http';
+    /** present only when the caller presented a verified end-user session */
+    end_user?: FunctionEndUser;
+    payload: P;
+}
+export interface CmsHookFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'cms-hook';
+    payload: CmsHookTriggerPayload;
+}
+export interface AuthHookFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'auth-hook';
+    payload: AuthHookTriggerPayload;
+}
+/** `payload` is exactly what the job was enqueued with. */
+export interface QueueFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
+    trigger: 'queue';
+    payload: P;
+}
+/** A schedule tick carries no data: `payload` is `{}`. */
+export interface CronFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'cron';
+    payload: Record<string, unknown>;
+}
+export interface WebhookFunctionEnvelope<D = Record<string, unknown>> extends FunctionEnvelopeBase {
+    trigger: 'webhook';
+    payload: WebhookTriggerPayload<D>;
+}
+/** The invocation envelope, discriminated on `trigger`. `P` types the `http`
+ *  body and the `queue` payload. A function bound to one trigger can name its
+ *  member directly (`CmsHookFunctionEnvelope`, `WebhookFunctionEnvelope<D>`). */
+export type FunctionEnvelope<P = unknown> = HttpFunctionEnvelope<P> | CmsHookFunctionEnvelope | AuthHookFunctionEnvelope | QueueFunctionEnvelope<P> | CronFunctionEnvelope | WebhookFunctionEnvelope;
+/** The body the jobs engine POSTs to a run's `target_url` (signed with
+ *  `X-Vxil-Jobs-Signature`; verify it with the secret from
+ *  `jobs.signingSecret()`). Redelivered attempts carry the same `run_id` and a
+ *  higher `attempt`. */
+export interface JobDelivery<P = unknown> {
+    run_id: string;
+    job_name: string;
+    /** 1-based */
+    attempt: number;
+    /** exactly what the run was enqueued with */
+    payload: P;
+}
 /** A re-minted mid-stream connect token (GET /v1/ai/generations/{id}/token). */
 export interface AiStreamToken {
     generation_id: string;
@@ -1231,6 +1385,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 +1402,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 +1620,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 +1922,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 +2410,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;
@@ -2433,6 +2736,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 user_id: string;
                 session: AuthSession;
             }>;
+            /** Keep a session pair usable: when it expires within `skewSeconds`
+             *  (default 300) — or `expires_at` is missing/unparseable, or already past
+             *  — rotate it through `refresh` and return the NEW pair with
+             *  `refreshed: true`; otherwise return it unchanged, with no request.
+             *  Store the pair again whenever `refreshed` is true (the old refresh
+             *  token is revoked by the rotation).
+             *
+             *  The window is capped at half the token's own lifetime (iat→exp, read
+             *  from the session JWT; 60 s for an opaque token), so a short session
+             *  TTL never makes every call rotate. Concurrent calls for the same
+             *  refresh token in one process share ONE rotation, and for 30 s after it
+             *  settles a call still carrying the OLD pair gets the new pair (no second
+             *  request) while a call with the just-minted pair gets it back unchanged.
+             *  A refresh that fails (revoked, expired, or already rotated by another
+             *  process) throws the `VxilError` — treat it as "sign in again".
+             *
+             *  Call it on a client whose key carries `auth:signin` — normally the
+             *  sign-in key, in server mode. An end-user-mode client sends its
+             *  X-Vxil-End-User token with the rotation only while that token is the
+             *  pair's own and still has 10 s left; otherwise the rotation goes out
+             *  without it, which a thin-client (`end_user_required`) key cannot do.
+             *  See https://vxil.com/docs/guide/09-security-and-multitenancy. */
+            ensureFresh: (pair: AuthSession, opts?: {
+                skewSeconds?: number;
+            }) => Promise<{
+                session: AuthSession;
+                refreshed: boolean;
+            }>;
             revoke: (token: string) => Promise<void>;
             /** "Sign out everywhere": revoke EVERY live session of a user in one call
              *  (one statement, one batched edge-cache write; each session's
@@ -2888,6 +3219,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 +4197,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 +4945,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,72 @@ 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']);
+/** `vx.auth.sessions.ensureFresh` rotates a pair this many seconds before it
+ *  expires unless the call names its own `skewSeconds`. */
+const ENSURE_FRESH_SKEW_SECONDS = 300;
+/** The window never exceeds this fraction of the token's own lifetime (iat→exp
+ *  from the session JWT), so a short session TTL cannot make every call rotate. */
+const ENSURE_FRESH_MAX_WINDOW_FRACTION = 0.5;
+/** Cap for a token whose lifetime cannot be read (an opaque, non-JWT token). */
+const ENSURE_FRESH_OPAQUE_MAX_SKEW_SECONDS = 60;
+/** An end-user-mode client keeps its X-Vxil-End-User token on the rotation
+ *  while that token has at least this long left (a thin-client key has no
+ *  server-mode fallback at the edge); closer to expiry it rotates in server mode. */
+const ENSURE_FRESH_HEADER_MARGIN_MS = 10_000;
+/** A settled rotation stays readable this long: a request that arrives just
+ *  after the winner still carrying the OLD pair adopts the winner's pair
+ *  instead of re-sending a revoked refresh token, and a pair this process just
+ *  minted is never rotated again inside the window (bounds rotations to one
+ *  per window per session per process whatever the clocks say). */
+const ENSURE_FRESH_GRACE_MS = 30_000;
+/** Rotations keyed by (edge base, OLD refresh token), shared by every client in
+ *  the process. `until` is Infinity while in flight and settle-time + grace
+ *  after a success; a failure is dropped at once. */
+const refreshRotations = new Map();
+/** (edge base, NEW refresh token) → the time until which that just-minted pair
+ *  is returned unchanged even if it already looks due. */
+const refreshJustMinted = new Map();
+function sweepRefreshCaches(now) {
+    for (const [k, r] of refreshRotations)
+        if (r.until <= now)
+            refreshRotations.delete(k);
+    for (const [k, until] of refreshJustMinted)
+        if (until <= now)
+            refreshJustMinted.delete(k);
+}
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** iat→exp of a session JWT in seconds, read WITHOUT verification (it only
+ *  schedules the refresh); undefined for an opaque or malformed token. No
+ *  atob: the SDK also runs on React Native builds that lack it. */
+function sessionLifetimeSeconds(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1] || parts[1].length > 8192)
+        return undefined;
+    let acc = 0;
+    let bits = 0;
+    let json = '';
+    for (const ch of parts[1].replace(/=+$/, '')) {
+        const v = B64URL.indexOf(ch);
+        if (v < 0)
+            return undefined;
+        acc = ((acc << 6) | v) & 0xffff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            json += String.fromCharCode((acc >> bits) & 0xff);
+        }
+    }
+    try {
+        const p = JSON.parse(json);
+        if (typeof p.iat === 'number' && typeof p.exp === 'number' && p.exp > p.iat)
+            return p.exp - p.iat;
+    }
+    catch { /* not a JWT payload */ }
+    return undefined;
+}
 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 +298,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 +313,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 +326,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 +665,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,
@@ -749,6 +851,69 @@ export class Vxil {
             verify: async (token) => (await this.call('POST', '/v1/auth/sessions/verify', { token })).data,
             /** Rotates the refresh token: store the returned pair, discard the old one. */
             refresh: async (refreshToken) => (await this.call('POST', '/v1/auth/sessions/refresh', { refresh_token: refreshToken })).data,
+            /** Keep a session pair usable: when it expires within `skewSeconds`
+             *  (default 300) — or `expires_at` is missing/unparseable, or already past
+             *  — rotate it through `refresh` and return the NEW pair with
+             *  `refreshed: true`; otherwise return it unchanged, with no request.
+             *  Store the pair again whenever `refreshed` is true (the old refresh
+             *  token is revoked by the rotation).
+             *
+             *  The window is capped at half the token's own lifetime (iat→exp, read
+             *  from the session JWT; 60 s for an opaque token), so a short session
+             *  TTL never makes every call rotate. Concurrent calls for the same
+             *  refresh token in one process share ONE rotation, and for 30 s after it
+             *  settles a call still carrying the OLD pair gets the new pair (no second
+             *  request) while a call with the just-minted pair gets it back unchanged.
+             *  A refresh that fails (revoked, expired, or already rotated by another
+             *  process) throws the `VxilError` — treat it as "sign in again".
+             *
+             *  Call it on a client whose key carries `auth:signin` — normally the
+             *  sign-in key, in server mode. An end-user-mode client sends its
+             *  X-Vxil-End-User token with the rotation only while that token is the
+             *  pair's own and still has 10 s left; otherwise the rotation goes out
+             *  without it, which a thin-client (`end_user_required`) key cannot do.
+             *  See https://vxil.com/docs/guide/09-security-and-multitenancy. */
+            ensureFresh: async (pair, opts = {}) => {
+                const skew = opts.skewSeconds ?? ENSURE_FRESH_SKEW_SECONDS;
+                if (typeof skew !== 'number' || !Number.isFinite(skew) || skew < 0) {
+                    throw new VxilError(0, 'invalid_argument', 'ensureFresh: skewSeconds must be a finite number ≥ 0.');
+                }
+                const now = Date.now();
+                const key = `${this.base}\n${pair.refresh_token}`;
+                // A pair this process already rotated (or is rotating): its tokens are
+                // revoked, so the answer is the winner's pair whatever expires_at says.
+                const prior = pair.refresh_token ? refreshRotations.get(key) : undefined;
+                if (prior && prior.until > now)
+                    return { session: await prior.session, refreshed: true };
+                const lifetime = sessionLifetimeSeconds(pair.token);
+                const window = lifetime !== undefined
+                    ? Math.min(skew, lifetime * ENSURE_FRESH_MAX_WINDOW_FRACTION)
+                    : Math.min(skew, ENSURE_FRESH_OPAQUE_MAX_SKEW_SECONDS);
+                const expMs = Date.parse(pair.expires_at);
+                if (Number.isFinite(expMs) && expMs - now > window * 1000)
+                    return { session: pair, refreshed: false };
+                if (pair.refresh_token && (refreshJustMinted.get(key) ?? 0) > now)
+                    return { session: pair, refreshed: false };
+                if (!pair.refresh_token) {
+                    throw new VxilError(0, 'refresh_token_missing', 'ensureFresh: the session is due for refresh but the pair carries no refresh_token.', 'Store both halves of the pair a sign-in returns (token + refresh_token), or sign in again.');
+                }
+                const keepEndUser = this.endUserToken !== undefined && this.endUserToken === pair.token
+                    && Number.isFinite(expMs) && expMs - now >= ENSURE_FRESH_HEADER_MARGIN_MS;
+                const client = this.endUserToken && !keepEndUser ? this.asEndUser(undefined) : this;
+                sweepRefreshCaches(now);
+                const entry = {
+                    session: client.call('POST', '/v1/auth/sessions/refresh', { refresh_token: pair.refresh_token }).then((r) => r.data.session),
+                    until: Number.POSITIVE_INFINITY,
+                };
+                entry.session.then((fresh) => {
+                    entry.until = Date.now() + ENSURE_FRESH_GRACE_MS;
+                    if (fresh.refresh_token)
+                        refreshJustMinted.set(`${this.base}\n${fresh.refresh_token}`, entry.until);
+                }, () => { if (refreshRotations.get(key) === entry)
+                    refreshRotations.delete(key); });
+                refreshRotations.set(key, entry);
+                return { session: await entry.session, refreshed: true };
+            },
             revoke: async (token) => {
                 await this.call('POST', '/v1/auth/sessions/revoke', { token });
             },
@@ -1058,6 +1223,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 +1701,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 +2065,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.7.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",