@vxil/sdk 0.16.1 → 0.18.0

package/dist/index.d.ts

@@ -160,7 +160,11 @@ export interface Delivery {
     template_id: string;
     locale: string;
     to_email: string;
-    status: 'queued' | 'sent' | 'failed' | 'suppressed';
+    /** `test_sink` (2026-10-04): the recipient matched the project's
+     *  `notifications.suppression.testRecipients` — rendered in full and recorded,
+     *  but no provider was called and the send is not billed. Read what would
+     *  have gone out with `notifications.delivery(id)` (`rendered`). */
+    status: 'queued' | 'sent' | 'failed' | 'suppressed' | 'test_sink';
     attempts: number;
     provider: string;
     provider_message_id: string | null;
@@ -185,6 +189,27 @@ export interface Delivery {
      *  `delivery_id` on the 202.) */
     deliver_after?: string | null;
 }
+/** One delivery by id (`notifications.delivery(id)`): the row plus a render.
+ *  For a `test_sink` row `rendered` is the FULL render the send produced (its
+ *  data, its locale — an `ar` template carries `dir="rtl"`) and `rendered_from`
+ *  is `'send'` — EXCEPT auth mail (the `magic-link` / `otp-code` templates and
+ *  the auth feature's password-reset / e-mail-verification mail) and a row
+ *  sunk at delivery time (an address added to `testRecipients` after the send
+ *  was queued): those are rendered WITHOUT the send's data (`rendered_from:
+ *  'send_redacted'`), so a sign-in link, code or reset link is never stored or
+ *  readable. For every other row the template variables were never stored, so
+ *  `rendered` is the template re-rendered with no data (`rendered_from:
+ *  'template'`), or null when it cannot be rendered. */
+export interface DeliveryDetail extends Delivery {
+    last_error_msg?: string | null;
+    rendered: {
+        subject: string;
+        html: string;
+        text: string;
+        locale: string;
+    } | null;
+    rendered_from?: 'send' | 'send_redacted' | 'template';
+}
 /** An ADDITIVE, non-fatal note on a 202 send — today only `mock_provider`
  *  (the send is recorded but no email leaves vxil). */
 export interface NotificationWarning {
@@ -403,9 +428,20 @@ export interface JobRun {
      *  problem (400 / 413 / 422 — e.g. a callback key the collection does not
      *  declare) is retried with only the status column (a progress update tries
      *  the declared `progress_fields` first), so an undeclared key no longer
-     *  strands the row; this says what was dropped. Never flips the run; not cleared by a later
-     *  successful mirror (compare `generation_status` / `at`). */
+     *  strands the row; this says what was dropped (`status_written`: whether
+     *  the record holds the status word). Never flips the run. A later TERMINAL
+     *  mirror that lands cleanly moves it to `last_mirror_error` (null here
+     *  again); a non-terminal success leaves it. A write the record refuses
+     *  because it already holds a terminal word, or because its
+     *  `status_mirror.fence_field` names another run, is skipped quietly —
+     *  never a mirror_error. */
     mirror_error?: JobRunMirrorError | null;
+    /** the single-run read, generation runs only: the `mirror_error` a later
+     *  clean terminal mirror healed; null otherwise */
+    last_mirror_error?: JobRunMirrorError | null;
+    /** the single-run read, generation runs only: when that healing terminal
+     *  mirror landed (ISO); null otherwise */
+    mirror_ok_at?: string | null;
     /** the single-run read only: the enqueue `concurrency_key` this run holds
      *  while running or waiting; null for an unkeyed run */
     concurrency_key?: string | null;
@@ -458,6 +494,7 @@ export interface JobEnqueueResult {
 export interface JobRunsQuery {
     job_name?: string;
     state?: JobRun['state'] | string;
+    /** exact run_ids, at most 50 distinct (more answers 422 — page in chunks of 50) */
     ids?: string[];
     batch_id?: string;
     /** ISO: runs created at or after */
@@ -501,13 +538,25 @@ export interface JobRunMirrorError {
     code: string | null;
     /** the target's message (≤ 200 chars), e.g. "unknown field 'video_url'" */
     message: string | null;
+    /** the target's hint (≤ 200 chars) when it sent one — e.g. the engine
+     *  detail of a cms validate hook that could not evaluate */
+    hint?: string;
     /** when it was refused (ISO) */
     at: string;
+    /** whether the record holds `generation_status` after this write: true
+     *  when a narrower retry carrying the status word landed (or the write left
+     *  the word out because the record already held it); false when no write
+     *  carrying it landed — the full write was already the status column alone,
+     *  the refusal was not a body problem (401 / 403 / 404 / 409 / 429 / 5xx,
+     *  a timeout), or every narrower retry was refused. Absent on errors
+     *  recorded before it existed. */
+    status_written?: boolean;
     /** present when a narrower retry LANDED: the keys that were not written */
     fields_dropped?: string[];
-    /** present when every narrower retry was refused too (the last one's HTTP
-     *  status, 0 = no answer): the status word itself was refused and the
-     *  record still holds the previous status */
+    /** present when narrower retries ran and none landed: the LAST one's HTTP
+     *  status (0 = no answer). The ladder stops at the first refusal that is not
+     *  a body problem, so read `status_written`, not this, for "did the status
+     *  word land" */
     retry_status?: number;
 }
 /** A run's latest progress report (`JobRun.progress`): only these keys pass. */
@@ -748,6 +797,28 @@ export interface PaymentsSimulationResult {
         pass: boolean;
     };
 }
+/** `payments.moveSubscriptionUntil` (the test clock) — the moved row and the
+ *  user's entitlement snapshot after the refold. */
+export interface PaymentsTestClockResult {
+    subscription_id: string;
+    user_id: string;
+    tier: string | null;
+    /** 'lapsed' after a move into the past, 'active' after one into the future */
+    status: string;
+    since: string | null;
+    until: string;
+    previous_until: string | null;
+    /** true when THIS move ended access (payments.subscription.lapsed emitted) */
+    lapsed: boolean;
+    /** why the project may use the test clock */
+    lane: 'mock' | 'sandbox' | 'dev';
+    entitlement: {
+        tier: string;
+        entitlements: string[];
+        quotas: Record<string, number>;
+        source_sub_id: string | null;
+    };
+}
 /** The ONE complete entitlement read (GET /v1/payments/entitlements; guide ch. 6,
  *  payments). `until` is the winning subscription's current_period_end (+ the
  *  configured grace window when it is past_due); null on the free baseline. */
@@ -880,6 +951,10 @@ export interface FileUploadUrl {
     expires_in: number;
     /** When the OBJECT expires (null = never). */
     expires_at: string | null;
+    /** The headers the PUT to `upload_url` must send, exactly — each one is
+     *  signed into the URL: `content-type`, plus `x-amz-checksum-sha256` when
+     *  the request declared `checksum_sha256`. */
+    upload_headers?: Record<string, string>;
 }
 /** `files.usage` answer. */
 export interface FilesUsage {
@@ -893,7 +968,15 @@ export interface FilesUsage {
         maxObjectBytes?: number;
         maxTotalBytes?: number;
     };
-    available: Record<string, number | null>;
+    /** Headroom left under the quotas. Never negative: when usage sits ABOVE a
+     *  lowered quota (or a plan downgrade) both read 0 and `over_quota` is true
+     *  — new uploads answer 422 quota_exceeded until usage drops back under. */
+    available: {
+        object_slots: number;
+        bytes_remaining: number;
+        over_quota?: boolean;
+        [key: string]: number | boolean | null | undefined;
+    };
     /** Your plan's storage ceiling, and whether `quotas.maxTotalBytes` is that
      *  ceiling (`plan`) or your own lower value (`config`). */
     storage_plan?: {
@@ -1361,7 +1444,8 @@ export interface PaymentsSubscriptionStatusEventPayload {
     current_period_end: string | null;
     environment: PaymentsEventEnvironment;
     /** what wrote it: the provider event type, `subscription.synced` /
-     *  `subscription.restored`, or `period_end_enforced` */
+     *  `subscription.restored`, `period_end_enforced`, or `test_clock` (a
+     *  `moveSubscriptionUntil` on a non-production project ended the row) */
     event_type: string;
     slack_hours: number | null;
     level: 'info';
@@ -1502,6 +1586,24 @@ export interface PaymentsConformanceEventPayload {
     level: 'info' | 'error';
     state: 'ok' | 'broken';
 }
+/** `payments.test_clock.moved` — the test clock moved a manual grant's or a
+ *  purchase pass's end (`moveSubscriptionUntil`; non-production projects only).
+ *  `lapsed` is true when this move ended access (a `payments.subscription.lapsed`
+ *  with `event_type: 'test_clock'` follows); `lane` names why the project was
+ *  allowed: `mock` provider, a `sandbox` provider environment, or a `dev`
+ *  (preview / `vxil dev up`) project. */
+export interface PaymentsTestClockMovedEventPayload {
+    end_user_id: string;
+    subscription_id: string;
+    provider_sub_id: string;
+    tier: string | null;
+    previous_until: string | null;
+    until: string;
+    lapsed: boolean;
+    lane: 'mock' | 'sandbox' | 'dev';
+    level: 'info';
+    state: 'ok';
+}
 /** Event name → typed `data`, for the events that settle work you started and
  *  (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
  *  names one; everything else on the catalog is `Record<string, unknown>` until
@@ -1536,6 +1638,7 @@ export interface VxilEventPayloads {
     'payments.reconcile.discrepancy': PaymentsReconcileDiscrepancyEventPayload;
     'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
     'payments.conformance': PaymentsConformanceEventPayload;
+    'payments.test_clock.moved': PaymentsTestClockMovedEventPayload;
 }
 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
@@ -2266,6 +2369,11 @@ type DisabledFeatures<S extends VxilSchemaShape> = {
 export type EnabledVxil<S extends VxilSchemaShape> = Omit<Vxil<S>, DisabledFeatures<S>> & {
     [P in DisabledFeatures<S>]: DisabledFeature<FeatureMap[P] & string>;
 };
+/** A cms collection's END-USER ACCESS mode (guide ch. 9): what a verified end
+ *  user (thin-client key + session) may do on it — `'readwrite'` (default),
+ *  `'read'` (writes are `403 server_only`) or `'none'` (reads and writes are
+ *  `403 server_only`). Server keys are never affected. */
+export type CmsEndUserAccess = 'readwrite' | 'read' | 'none';
 /** One config-declared per-record ACTION (guide ch. 4): a button on a record row
  *  that invokes the deployed tenant function `fn` ONCE with `{ collection,
  *  item_id, action, actor, item }`. Exactly one human-initiated step — no
@@ -2753,6 +2861,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         get: (id: string, opts?: {
             includeDeleted?: boolean;
         }) => Promise<VxilUser>;
+        /**
+         * Update a user. `email` / `display_name` / `avatar_url` are replaced
+         * (null clears them). `attributes` is DEEP-MERGED into the stored
+         * attributes (RFC 7396 merge patch): objects merge key by key, arrays and
+         * scalars replace, and `null` deletes a key AT ANY DEPTH — including inside
+         * a subtree the row does not have yet, where the null is simply dropped
+         * (`{ attributes: { prefs: { phone: null } } }` never stores a null).
+         * Scope users:write.
+         */
         patch: (id: string, patch: {
             email?: string | null;
             display_name?: string | null;
@@ -2775,7 +2892,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * Merge a REGISTRY-ONLY user (a row you created with upsert that never
          * signed in) INTO another user of the tenant: its attributes fill the
          * survivor's gaps (the survivor wins on conflicts), the merged id is
-         * soft-deleted, its owner-scoped cms / files / payments rows move to the
+         * soft-deleted, its owner-scoped cms / files / payments / jobs rows move to the
          * survivor, and `auth.user.merged { from, into, method: 'registry_merge' }`
          * is audited. `rekeyed: false` means a re-key could not finish inside the
          * request — the event is the backstop (call the feature's re-key route
@@ -2994,8 +3111,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             /** Reset the row and re-enqueue the original message. */
             replay: (deliveryId: string) => Promise<void>;
         };
-        /** A single delivery by id (the list is `deliveries()`). */
-        delivery: (deliveryId: string) => Promise<Delivery>;
+        /** A single delivery by id (the list is `deliveries()`), with its render —
+         *  the full one for a `test_sink` row (see `DeliveryDetail`). */
+        delivery: (deliveryId: string) => Promise<DeliveryDetail>;
         /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
          *  send (status `scheduled`); omit it for a `draft`. */
@@ -3048,6 +3166,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 skipped_freq_cap: number;
                 skipped_no_email: number;
                 already_sent: number;
+                /** recipients in `suppression.testRecipients` on this page: recorded
+                 *  `test_sink`, never sent, never billed */
+                test_sink?: number;
             }>;
         };
     };
@@ -3220,7 +3341,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *
          * The answer's `generation_status` is `pending` on a fresh enqueue; a replay
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
-         * status NOW (`processing`, `completed` or `failed` too).
+         * status NOW (`processing`, `completed` or `failed` too). The key is bound
+         * to the request BODY: re-sending it with a different body (another
+         * payload — a rebuilt `deadline_at` included —, provider, completion,
+         * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
+         * original run (the ai-v1 rule). That check is being rolled out: today a
+         * mismatch is only logged, on every project, and the send is still
+         * deduplicated to the first run; a changelog entry will announce
+         * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
+         * (Retry-After 5) means the run that key names is still placing its
+         * credit hold.
          *
          * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
@@ -3228,7 +3358,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
          * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
          * the enqueue (insufficient balance; the run ends with job.generation.failed
-         * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
+         * `ReserveInsufficient` and the 402 names its `run_id`; the key is released,
+         * so the same request after a top-up starts a new run); a runaway over the
          * per-tenant outstanding-holds ceiling → 429 (Retry-After 5). Payments
          * unreachable at the hold → 503 `payments_unavailable` (Retry-After 15;
          * nothing started, nothing held — re-send the same request), unless
@@ -3249,8 +3380,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *
          * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
          * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
-         * `queue_full`) and a 503 `payments_unavailable`, honouring Retry-After
-         * with jitter, with the SAME
+         * `queue_full`), a 503 `payments_unavailable` / `enqueue_interrupted` and a
+         * 409 `generation_in_progress` (the key's run is still placing its credit
+         * hold), honouring Retry-After with jitter, with the SAME
          * idempotency_key (one is generated when the input has none), until
          * maxWaitMs has passed — then the last 429 is thrown. */
         generation: (input: {
@@ -3281,13 +3413,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             };
             /** `progress_fields`: the progress keys (`progress` / `stage` /
              *  `message`) a webhook-mode `processing` callback also writes onto the
-             *  mirrored record — realtime clients of that record see them live */
+             *  mirrored record — realtime clients of that record see them live.
+             *  In END-USER mode (`asEndUser`, or a function invoked for a signed-in
+             *  user) the target must be a cms record that user can read: another
+             *  user's row, a server-only collection or a non-cms feature answers
+             *  403 `mirror_target_forbidden` and nothing starts (503
+             *  `mirror_check_unavailable` if the check could not run — retry).
+             *  Mirror onto a server-only row from server-mode code instead. */
             status_mirror?: {
                 feature: string;
                 collection: string;
                 record_id: string;
                 column?: string;
                 progress_fields?: Array<"progress" | "stage" | "message">;
+                /** cms only: a declared string field the mirror stamps with this
+                 *  run's `run_id` on its first write; every later write of the run
+                 *  requires it (a cms `if` precondition), so an older run's late
+                 *  writes never land on a row a newer run has claimed. A write the
+                 *  record refuses that way — or because it already holds
+                 *  `completed` / `failed` — is skipped, not a `mirror_error`. */
+                fence_field?: string;
             };
             timeout?: {
                 after_ms: number;
@@ -3365,9 +3510,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Cancel a run that has not started its current attempt (`queued`,
          *  `delayed`, `retrying`) or a plain run handed off to its signed callback
          *  (`waiting` after its handler answered 202 — the callback URL is
-         *  consumed). A `running` run (a delivery in flight, or a generation
-         *  waiting on its provider), a run waiting on an event, or a terminal run
-         *  answers `409 not_cancellable`. A generation's credit hold is released. */
+         *  consumed). A generation's credit hold is released — a STARTED
+         *  generation's too (its provider accepted it): it ends `failed`
+         *  (`Cancelled`) and a late provider callback is a no-op, but the provider
+         *  is NOT told, so its work and its charge may still complete. A plain
+         *  `running` run (a delivery in flight), a run waiting on an event, or a
+         *  terminal run answers `409 not_cancellable`. */
         cancel: (runId: string) => Promise<{
             run_id: string;
             state: string;
@@ -3378,6 +3526,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             run_id: string;
             replayed_from: string;
         }>;
+        /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move the
+         *  credit-hold owner (`reserve_credits.user_id`) of every run of
+         *  `from_user_id`, in any state, onto `into_user_id`, so the surviving
+         *  account reads, cancels and replays the generation runs it started as a
+         *  guest. ONE bounded page (≤500 runs) per call — call again until `done`
+         *  (idempotent: a second call moves 0). The jobs consumer of
+         *  `auth.user.merged { from, into }`; auth and `users.merge` call it after
+         *  a merge, the event is the backstop. Emits one `jobs.runs.rekeyed` when
+         *  a call moved at least one run (none on a zero-move call). Unlike the
+         *  files re-key it does not check that `into_user_id` exists.
+         *  Scope jobs:write. */
+        reKey: (input: {
+            from_user_id: string;
+            into_user_id: string;
+        }) => Promise<{
+            moved: number;
+            done: boolean;
+        }>;
         /**
          * Suspend the RUNNING run until an event (call from the executing
          * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -3502,9 +3668,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 sent: true;
                 test_link?: string;
             }>;
-            /** `opts.anonymous_token` is REQUIRED for a link that was requested with
-             *  one (the guest claim above): the same guest session must present it,
-             *  else `401 invalid_session`. `merged` is true only when the guest was
+            /** An unknown, expired or already-used link answers `401 invalid_token`
+             *  (request a new one with `request`). `opts.anonymous_token` is REQUIRED
+             *  for a link that was requested with one (the guest claim above): the
+             *  same guest session must present it, else `401 invalid_session`. `merged` is true only when the guest was
              *  folded into an existing account (then `user_id` is that account), and
              *  `rekeyed` rides beside it: true ⇒ the guest's payments / cms / files
              *  rows were already moved onto `user_id` when this returned; false ⇒
@@ -3689,7 +3856,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }) => Promise<AuthImportResult>;
             /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
              *  deep-merges a bounded `attributes` object into its OWN shared identity
-             *  row (null deletes a key; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
+             *  row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
              *  fields are not patchable here. In server mode the call throws 422
              *  `end_user_mode_required` — use `users.patch(id, …)` instead. */
             patchMe: (attributes: Record<string, unknown>) => Promise<{
@@ -3933,7 +4100,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     };
     readonly cms: {
         collections: {
-            /** Define a content type. The model is data — not config. */
+            /** Define a content type. The model is data — not config.
+             *  Model management (`create`, `addField` and every fields-route meta-op
+             *  in this namespace) is SERVER-ONLY: a client acting as a signed-in end
+             *  user (`asEndUser`, a thin-client key) gets `403 server_only`. Call
+             *  these with a server key — your backend, `vxil push`, or the dashboard. */
             create: (input: {
                 collection: string;
                 singular?: string;
@@ -3949,6 +4120,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  and the owner_field are never exposed. Optional; defaults false. Use the
                  *  top-level `cmsPublicUrl` / `listCmsPublic` helpers for the reader side. */
                 public?: boolean;
+                /** What a VERIFIED end user may do here (guide ch. 9, "Read-only and
+                 *  server-only collections"): `'readwrite'` (default), `'read'` (every
+                 *  end-user write is `403 server_only`; reads unchanged) or `'none'`
+                 *  (end-user reads and writes are `403 server_only`, even with an
+                 *  owner_field). Server keys are never affected. */
+                end_user_access?: CmsEndUserAccess;
                 fields?: Array<{
                     field: string;
                     type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -3996,12 +4173,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 owner_field?: string;
                 public?: boolean;
                 actions?: CmsActionDef[];
+                /** present when not the default 'readwrite' */
+                end_user_access?: CmsEndUserAccess;
             }>;
             list: () => Promise<Array<{
                 collection: string;
                 singular: string;
                 fields: unknown[];
                 owner_field?: string | null;
+                /** the collection's end-user access mode (absent from an older server = 'readwrite') */
+                end_user_access?: CmsEndUserAccess;
             }>>;
             addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
             /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
@@ -4033,6 +4214,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  the owner_field are never exposed. `false` closes the lane (and purges the
              *  edge cache). Read the public side with `cmsPublicUrl` / `listCmsPublic`. */
             setPublic: (collection: string, isPublic: boolean) => Promise<void>;
+            /** Set the collection's END-USER ACCESS mode (guide ch. 9, "Read-only and
+             *  server-only collections"). `'read'`: a verified end user (thin-client
+             *  key + session) may still read — owner-scoped when the collection has an
+             *  owner_field — but every end-user write answers `403 server_only`;
+             *  `'none'`: end-user reads and writes are both refused; `'readwrite'`
+             *  (default) restores today's behaviour. Server keys are never affected.
+             *  Audited; takes effect on the next request. */
+            setEndUserAccess: (collection: string, access: CmsEndUserAccess) => Promise<{
+                collection: string;
+                end_user_access: CmsEndUserAccess;
+            }>;
             /** Re-project the collection's index slots after an `index_slot` move
              *  (guide ch. 4). Slots are projected on WRITE only, so until this runs,
              *  stored rows keep their OLD projection: the new slot is NULL and the
@@ -5071,16 +5263,27 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  long after the mint, whether or not `files.ttl` is enabled; `null` =
          *  never. The answer's `expires_in` is the UPLOAD URL's life in seconds;
          *  `expires_at` is when the object expires (null = never). `user_id` is
-         *  required with a server key and omitted in end-user mode. */
+         *  required with a server key and omitted in end-user mode.
+         *  `checksum_sha256` (the SHA-256 of the bytes, 64 hex or 44 base64
+         *  characters) is signed into the URL (send the answer's `upload_headers`
+         *  on the PUT) and kept with the upload: `complete` compares it with the
+         *  SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
+         *  they differ, 409 `checksum_unverified` when the store reports none —
+         *  and on success answers the verified `checksum_sha256`. */
         createUploadUrl: (input: {
             user_id?: string;
             filename: string;
             content_type: string;
             size_bytes: number;
             expiresInSeconds?: number | null;
+            checksum_sha256?: string;
         }) => Promise<FileUploadUrl>;
         /** Confirm the PUT (bytes verified, object → available). Answers the
-         *  object's `expires_at` (null = never). */
+         *  object's `expires_at` (null = never) and `checksum_sha256` (hex; null
+         *  when the store reported none) — a repeated complete answers the same.
+         *  When the upload declared `checksum_sha256`: 409 `checksum_mismatch` if
+         *  the bytes hash differently, 409 `checksum_unverified` if the store
+         *  reports no checksum (the object stays pending either way). */
         complete: (objectId: string) => Promise<{
             object_id: string;
             status: string;
@@ -6047,6 +6250,30 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id: string;
             tier?: string;
         }) => Promise<PaymentsSimulationResult>;
+        /** SERVER-ONLY TEST CLOCK — move the end (`until`, past or future, within
+         *  5 years of now) of a MANUAL grant or a purchase pass, to test expired /
+         *  export-window / renew-soon states on demand. Allowed only where no live
+         *  money can be involved: a `mock`-provider project, a project whose
+         *  provider runs in its sandbox (`paddle.sandbox`, `paypal.sandbox`, a
+         *  Stripe `sk_test_` key), or a dev/preview project — elsewhere 403
+         *  `test_clock_forbidden` (also for a pass linked to a non-sandbox charge).
+         *  409 `provider_managed` for a provider subscription (use the provider's
+         *  own test clock); 409 `subscription_ended` for a revoked/refunded row.
+         *  The effect is a natural lapse's: the entitlements refold
+         *  (`payments.entitlement.changed`), a move into the past turns an active
+         *  row `lapsed` and emits `payments.subscription.lapsed` (`event_type:
+         *  'test_clock'`, `environment: 'sandbox'`) once; a move back into the
+         *  future revives it (as `active` — a `trialing` row does not return to
+         *  `trialing`; a `past_due` row's status is left as it is). Only the end
+         *  moves: `since` (the period start) is never rewritten, so after a move
+         *  before it `since` > `until`. Every move emits
+         *  `payments.test_clock.moved`. Both events are emitted after the move
+         *  commits, best-effort (as the period-end sweep's are): if one fails to
+         *  record, the move still stands and is not re-announced on a retry, so
+         *  assert on the returned `status` / `lapsed` rather than only on the
+         *  event. Same-tier passes stacked behind the moved one are not
+         *  re-chained. No credits are granted or reversed. */
+        moveSubscriptionUntil: (subscriptionId: string, until: string | Date) => Promise<PaymentsTestClockResult>;
         /** The last report-only reconciliation sweep result for this project
          *  (`run: null` before the first daily tick). Finding kinds:
          *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,

package/dist/index.js

@@ -432,6 +432,15 @@ export class Vxil {
         upsert: async (user) => (await this.call('POST', '/v1/users', user)).data,
         bulk: async (users) => (await this.call('POST', '/v1/users/bulk', { users })).data.upserted,
         get: async (id, opts) => (await this.call('GET', `/v1/users/${encodeURIComponent(id)}${opts?.includeDeleted ? '?include_deleted=true' : ''}`)).data,
+        /**
+         * Update a user. `email` / `display_name` / `avatar_url` are replaced
+         * (null clears them). `attributes` is DEEP-MERGED into the stored
+         * attributes (RFC 7396 merge patch): objects merge key by key, arrays and
+         * scalars replace, and `null` deletes a key AT ANY DEPTH — including inside
+         * a subtree the row does not have yet, where the null is simply dropped
+         * (`{ attributes: { prefs: { phone: null } } }` never stores a null).
+         * Scope users:write.
+         */
         patch: async (id, patch) => (await this.call('PATCH', `/v1/users/${encodeURIComponent(id)}`, patch)).data,
         /**
          * Delete a user. By default this is a SOFT delete (sets deleted_at; the PII
@@ -449,7 +458,7 @@ export class Vxil {
          * Merge a REGISTRY-ONLY user (a row you created with upsert that never
          * signed in) INTO another user of the tenant: its attributes fill the
          * survivor's gaps (the survivor wins on conflicts), the merged id is
-         * soft-deleted, its owner-scoped cms / files / payments rows move to the
+         * soft-deleted, its owner-scoped cms / files / payments / jobs rows move to the
          * survivor, and `auth.user.merged { from, into, method: 'registry_merge' }`
          * is audited. `rekeyed: false` means a re-key could not finish inside the
          * request — the event is the backstop (call the feature's re-key route
@@ -567,7 +576,8 @@ export class Vxil {
                 await this.call('POST', `/v1/notifications/dead-letters/${encodeURIComponent(deliveryId)}/replay`);
             },
         },
-        /** A single delivery by id (the list is `deliveries()`). */
+        /** A single delivery by id (the list is `deliveries()`), with its render —
+         *  the full one for a `test_sink` row (see `DeliveryDetail`). */
         delivery: async (deliveryId) => (await this.call('GET', `/v1/notifications/deliveries/${encodeURIComponent(deliveryId)}`)).data,
         /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
@@ -756,7 +766,16 @@ export class Vxil {
          *
          * The answer's `generation_status` is `pending` on a fresh enqueue; a replay
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
-         * status NOW (`processing`, `completed` or `failed` too).
+         * status NOW (`processing`, `completed` or `failed` too). The key is bound
+         * to the request BODY: re-sending it with a different body (another
+         * payload — a rebuilt `deadline_at` included —, provider, completion,
+         * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
+         * original run (the ai-v1 rule). That check is being rolled out: today a
+         * mismatch is only logged, on every project, and the send is still
+         * deduplicated to the first run; a changelog entry will announce
+         * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
+         * (Retry-After 5) means the run that key names is still placing its
+         * credit hold.
          *
          * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
@@ -764,7 +783,8 @@ export class Vxil {
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
          * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
          * the enqueue (insufficient balance; the run ends with job.generation.failed
-         * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
+         * `ReserveInsufficient` and the 402 names its `run_id`; the key is released,
+         * so the same request after a top-up starts a new run); a runaway over the
          * per-tenant outstanding-holds ceiling → 429 (Retry-After 5). Payments
          * unreachable at the hold → 503 `payments_unavailable` (Retry-After 15;
          * nothing started, nothing held — re-send the same request), unless
@@ -785,8 +805,9 @@ export class Vxil {
          *
          * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
          * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
-         * `queue_full`) and a 503 `payments_unavailable`, honouring Retry-After
-         * with jitter, with the SAME
+         * `queue_full`), a 503 `payments_unavailable` / `enqueue_interrupted` and a
+         * 409 `generation_in_progress` (the key's run is still placing its credit
+         * hold), honouring Retry-After with jitter, with the SAME
          * idempotency_key (one is generated when the input has none), until
          * maxWaitMs has passed — then the last 429 is thrown. */
         generation: async (input, opts) => {
@@ -835,13 +856,28 @@ export class Vxil {
         /** Cancel a run that has not started its current attempt (`queued`,
          *  `delayed`, `retrying`) or a plain run handed off to its signed callback
          *  (`waiting` after its handler answered 202 — the callback URL is
-         *  consumed). A `running` run (a delivery in flight, or a generation
-         *  waiting on its provider), a run waiting on an event, or a terminal run
-         *  answers `409 not_cancellable`. A generation's credit hold is released. */
+         *  consumed). A generation's credit hold is released — a STARTED
+         *  generation's too (its provider accepted it): it ends `failed`
+         *  (`Cancelled`) and a late provider callback is a no-op, but the provider
+         *  is NOT told, so its work and its charge may still complete. A plain
+         *  `running` run (a delivery in flight), a run waiting on an event, or a
+         *  terminal run answers `409 not_cancellable`. */
         cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
         /** Clone a terminal run into a fresh queued run. A generation run answers
          *  `409 not_replayable` — submit the generation again instead. */
         replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
+        /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move the
+         *  credit-hold owner (`reserve_credits.user_id`) of every run of
+         *  `from_user_id`, in any state, onto `into_user_id`, so the surviving
+         *  account reads, cancels and replays the generation runs it started as a
+         *  guest. ONE bounded page (≤500 runs) per call — call again until `done`
+         *  (idempotent: a second call moves 0). The jobs consumer of
+         *  `auth.user.merged { from, into }`; auth and `users.merge` call it after
+         *  a merge, the event is the backstop. Emits one `jobs.runs.rekeyed` when
+         *  a call moved at least one run (none on a zero-move call). Unlike the
+         *  files re-key it does not check that `into_user_id` exists.
+         *  Scope jobs:write. */
+        reKey: async (input) => (await this.call('POST', '/v1/jobs/runs/re-key', input)).data,
         /**
          * Suspend the RUNNING run until an event (call from the executing
          * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -926,9 +962,10 @@ export class Vxil {
              *  existing account; swap tokens). Needs `anonymous.enabled`; a non-guest
              *  bearer is `409 not_anonymous`. */
             request: async (input) => (await this.call('POST', '/v1/auth/magic-link/request', input)).data,
-            /** `opts.anonymous_token` is REQUIRED for a link that was requested with
-             *  one (the guest claim above): the same guest session must present it,
-             *  else `401 invalid_session`. `merged` is true only when the guest was
+            /** An unknown, expired or already-used link answers `401 invalid_token`
+             *  (request a new one with `request`). `opts.anonymous_token` is REQUIRED
+             *  for a link that was requested with one (the guest claim above): the
+             *  same guest session must present it, else `401 invalid_session`. `merged` is true only when the guest was
              *  folded into an existing account (then `user_id` is that account), and
              *  `rekeyed` rides beside it: true ⇒ the guest's payments / cms / files
              *  rows were already moved onto `user_id` when this returned; false ⇒
@@ -1026,7 +1063,7 @@ export class Vxil {
             import: async (input) => (await this.call('POST', '/v1/auth/users/import', input)).data,
             /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
              *  deep-merges a bounded `attributes` object into its OWN shared identity
-             *  row (null deletes a key; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
+             *  row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
              *  fields are not patchable here. In server mode the call throws 422
              *  `end_user_mode_required` — use `users.patch(id, …)` instead. */
             patchMe: async (attributes) => (await this.call('PATCH', '/v1/auth/users/me', { attributes })).data,
@@ -1210,7 +1247,11 @@ export class Vxil {
     };
     cms = {
         collections: {
-            /** Define a content type. The model is data — not config. */
+            /** Define a content type. The model is data — not config.
+             *  Model management (`create`, `addField` and every fields-route meta-op
+             *  in this namespace) is SERVER-ONLY: a client acting as a signed-in end
+             *  user (`asEndUser`, a thin-client key) gets `403 server_only`. Call
+             *  these with a server key — your backend, `vxil push`, or the dashboard. */
             create: async (input) => (await this.call('POST', '/v1/cms/collections', input)).data,
             list: async () => (await this.call('GET', '/v1/cms/collections')).data.collections,
             addField: async (collection, field) => {
@@ -1262,6 +1303,14 @@ export class Vxil {
             setPublic: async (collection, isPublic) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { public: isPublic });
             },
+            /** Set the collection's END-USER ACCESS mode (guide ch. 9, "Read-only and
+             *  server-only collections"). `'read'`: a verified end user (thin-client
+             *  key + session) may still read — owner-scoped when the collection has an
+             *  owner_field — but every end-user write answers `403 server_only`;
+             *  `'none'`: end-user reads and writes are both refused; `'readwrite'`
+             *  (default) restores today's behaviour. Server keys are never affected.
+             *  Audited; takes effect on the next request. */
+            setEndUserAccess: async (collection, access) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { end_user_access: access })).data,
             /** Re-project the collection's index slots after an `index_slot` move
              *  (guide ch. 4). Slots are projected on WRITE only, so until this runs,
              *  stored rows keep their OLD projection: the new slot is NULL and the
@@ -1852,10 +1901,20 @@ export class Vxil {
          *  long after the mint, whether or not `files.ttl` is enabled; `null` =
          *  never. The answer's `expires_in` is the UPLOAD URL's life in seconds;
          *  `expires_at` is when the object expires (null = never). `user_id` is
-         *  required with a server key and omitted in end-user mode. */
+         *  required with a server key and omitted in end-user mode.
+         *  `checksum_sha256` (the SHA-256 of the bytes, 64 hex or 44 base64
+         *  characters) is signed into the URL (send the answer's `upload_headers`
+         *  on the PUT) and kept with the upload: `complete` compares it with the
+         *  SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
+         *  they differ, 409 `checksum_unverified` when the store reports none —
+         *  and on success answers the verified `checksum_sha256`. */
         createUploadUrl: async (input) => (await this.call('POST', '/v1/files/upload-url', input)).data,
         /** Confirm the PUT (bytes verified, object → available). Answers the
-         *  object's `expires_at` (null = never). */
+         *  object's `expires_at` (null = never) and `checksum_sha256` (hex; null
+         *  when the store reported none) — a repeated complete answers the same.
+         *  When the upload declared `checksum_sha256`: 409 `checksum_mismatch` if
+         *  the bytes hash differently, 409 `checksum_unverified` if the store
+         *  reports no checksum (the object stays pending either way). */
         complete: async (objectId) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/complete`)).data,
         downloadUrl: async (objectId) => (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url`)).data.download_url,
         /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
@@ -2371,6 +2430,30 @@ export class Vxil {
          *  past-due-grace, cross-platform-unlock, transfer) through the mock
          *  webhook path and judge it with the conformance oracle. */
         simulate: async (input) => (await this.call('POST', '/v1/payments/simulate', input)).data,
+        /** SERVER-ONLY TEST CLOCK — move the end (`until`, past or future, within
+         *  5 years of now) of a MANUAL grant or a purchase pass, to test expired /
+         *  export-window / renew-soon states on demand. Allowed only where no live
+         *  money can be involved: a `mock`-provider project, a project whose
+         *  provider runs in its sandbox (`paddle.sandbox`, `paypal.sandbox`, a
+         *  Stripe `sk_test_` key), or a dev/preview project — elsewhere 403
+         *  `test_clock_forbidden` (also for a pass linked to a non-sandbox charge).
+         *  409 `provider_managed` for a provider subscription (use the provider's
+         *  own test clock); 409 `subscription_ended` for a revoked/refunded row.
+         *  The effect is a natural lapse's: the entitlements refold
+         *  (`payments.entitlement.changed`), a move into the past turns an active
+         *  row `lapsed` and emits `payments.subscription.lapsed` (`event_type:
+         *  'test_clock'`, `environment: 'sandbox'`) once; a move back into the
+         *  future revives it (as `active` — a `trialing` row does not return to
+         *  `trialing`; a `past_due` row's status is left as it is). Only the end
+         *  moves: `since` (the period start) is never rewritten, so after a move
+         *  before it `since` > `until`. Every move emits
+         *  `payments.test_clock.moved`. Both events are emitted after the move
+         *  commits, best-effort (as the period-end sweep's are): if one fails to
+         *  record, the move still stands and is not re-announced on a retry, so
+         *  assert on the returned `status` / `lapsed` rather than only on the
+         *  event. Same-tier passes stacked behind the moved one are not
+         *  re-chained. No credits are granted or reversed. */
+        moveSubscriptionUntil: async (subscriptionId, until) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/until`, { until: typeof until === 'string' ? until : until.toISOString() })).data,
         /** The last report-only reconciliation sweep result for this project
          *  (`run: null` before the first daily tick). Finding kinds:
          *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,

package/dist/retry.d.ts

@@ -55,6 +55,11 @@ export declare const CAPACITY_ERROR_CODES: ReadonlySet<string>;
  *  started and nothing held, and the SAME request re-sent after Retry-After
  *  starts the run (the refused run released its idempotency key). */
 export declare const UNAVAILABLE_ERROR_CODES: ReadonlySet<string>;
+/** The 409 answers retried the same way: the run this idempotency_key names
+ *  is still placing its credit hold (`generation_in_progress`, Retry-After 5)
+ *  — the SAME request re-sent then answers with that run (or, when the
+ *  earlier enqueue was cut off, starts a fresh one). */
+export declare const IN_PROGRESS_ERROR_CODES: ReadonlySet<string>;
 /** Is this thrown error one `retryOnCapacity` waits out? Duck-typed on
  *  `{ status, code }` (VxilError's fields). */
 export declare function isCapacityRetryable(e: unknown): boolean;
@@ -68,8 +73,9 @@ export interface RetryOnCapacityOptions {
     now?: () => number;
 }
 /**
- * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`) or
- * a 503 `payments_unavailable` (`UNAVAILABLE_ERROR_CODES`):
+ * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`),
+ * a 503 `payments_unavailable` / `enqueue_interrupted` (`UNAVAILABLE_ERROR_CODES`)
+ * or a 409 `generation_in_progress` (`IN_PROGRESS_ERROR_CODES`):
  * wait the server's `Retry-After` (else 5 s) plus up to 20 % jitter (≤ 1 s,
  * so many clients told the same second do not all return on it), and never
  * past `maxWaitMs` since the first attempt — then the last 429 is rethrown.

package/dist/retry.js

@@ -166,7 +166,12 @@ export const CAPACITY_ERROR_CODES = new Set([
  *  lane could not reach payments to place its credit hold — nothing was
  *  started and nothing held, and the SAME request re-sent after Retry-After
  *  starts the run (the refused run released its idempotency key). */
-export const UNAVAILABLE_ERROR_CODES = new Set(['payments_unavailable']);
+export const UNAVAILABLE_ERROR_CODES = new Set(['payments_unavailable', 'enqueue_interrupted']);
+/** The 409 answers retried the same way: the run this idempotency_key names
+ *  is still placing its credit hold (`generation_in_progress`, Retry-After 5)
+ *  — the SAME request re-sent then answers with that run (or, when the
+ *  earlier enqueue was cut off, starts a fresh one). */
+export const IN_PROGRESS_ERROR_CODES = new Set(['generation_in_progress']);
 /** Is this thrown error one `retryOnCapacity` waits out? Duck-typed on
  *  `{ status, code }` (VxilError's fields). */
 export function isCapacityRetryable(e) {
@@ -174,13 +179,15 @@ export function isCapacityRetryable(e) {
     if (!err || typeof err.code !== 'string')
         return false;
     return (err.status === 429 && CAPACITY_ERROR_CODES.has(err.code))
-        || (err.status === 503 && UNAVAILABLE_ERROR_CODES.has(err.code));
+        || (err.status === 503 && UNAVAILABLE_ERROR_CODES.has(err.code))
+        || (err.status === 409 && IN_PROGRESS_ERROR_CODES.has(err.code));
 }
 /** Fallback wait (ms) when a capacity 429 carries no Retry-After. */
 const CAPACITY_DEFAULT_WAIT_MS = 5_000;
 /**
- * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`) or
- * a 503 `payments_unavailable` (`UNAVAILABLE_ERROR_CODES`):
+ * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`),
+ * a 503 `payments_unavailable` / `enqueue_interrupted` (`UNAVAILABLE_ERROR_CODES`)
+ * or a 409 `generation_in_progress` (`IN_PROGRESS_ERROR_CODES`):
  * wait the server's `Retry-After` (else 5 s) plus up to 20 % jitter (≤ 1 s,
  * so many clients told the same second do not all return on it), and never
  * past `maxWaitMs` since the first attempt — then the last 429 is rethrown.

package/package.json

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