@vxil/sdk 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -169,6 +169,17 @@ export interface Delivery {
     delivered_at?: string | null;
     opened_at?: string | null;
     clicked_at?: string | null;
+    /** The instant the first delivery attempt may fire (a `send_at` /
+     *  `delay_seconds` schedule, a campaign quiet-hours deferral, a dead-letter
+     *  replay); null = at `queued_at`. A `queued` row with no attempt 30 min past
+     *  this is checked against its jobs run by a platform sweep and becomes
+     *  `failed` / `last_error_code: 'never_attempted'` only when that run is gone
+     *  or terminal (a run still waiting — e.g. behind the jobs concurrency cap —
+     *  moves this instant forward instead) — send it again with the same
+     *  Idempotency-Key. (The key itself is never on the row on the wire; a
+     *  replay is the `x-vxil-idempotent-replay: true` header plus the identical
+     *  `delivery_id` on the 202.) */
+    deliver_after?: string | null;
 }
 /** An ADDITIVE, non-fatal note on a 202 send — today only `mock_provider`
  *  (the send is recorded but no email leaves vxil). */
@@ -399,6 +410,12 @@ export interface PaymentsWebhookEvent {
     event_id: string;
     provider: string;
     provider_evt_id: string;
+    /** the NORMALISED charge id the receiver stamped at delivery time — the same
+     *  string `payments.charge.*` events carry as `provider_charge_id`. `null`
+     *  when the delivery carries no charge (subscription events, failures) or
+     *  was received before the column existed. Filter on it with
+     *  `webhookEvents.list({ provider_charge_id })`. */
+    provider_charge_id?: string | null;
     event_type: string;
     /** received | processed | error | sig_failed | parse_failed | reprocessed |
      *  ignored (a well-formed provider type we deliberately do not fold) |
@@ -640,6 +657,8 @@ export interface AiChatMessage {
 /** A synchronous generation result (POST /v1/ai/generate without stream). */
 export interface AiGeneration {
     generation_id: string;
+    /** your own `correlation_id` echoed back (null when you sent none). */
+    correlation_id?: string | null;
     text: string;
     usage: AiUsage;
     finish: string;
@@ -655,6 +674,8 @@ export interface AiGeneration {
 /** A streamed generation handle: open the realtime channel for token frames. */
 export interface AiStreamHandle {
     generation_id: string;
+    /** your own `correlation_id` echoed back (null when you sent none). */
+    correlation_id?: string | null;
     channel: string;
     token?: string;
     ttl_seconds?: number;
@@ -696,9 +717,69 @@ export interface AiTokenExpiringEvent {
 export interface AiJobHandle {
     generation_id: string;
     run_id: string;
+    /** your own `correlation_id` echoed back (null when you sent none). The
+     *  `job.generation.completed|failed` events carry BOTH `generation_id` and
+     *  `correlation_id` next to `run_id`, so no run→record link is needed. */
+    correlation_id?: string | null;
     status: string;
     resume_path: string;
 }
+/** The `data` of `job.generation.queued` (jobs.md §11): the run was accepted. */
+export interface JobGenerationQueuedEventPayload {
+    run_id: string;
+    job_name: string;
+    /** the `202` handle's id from `POST /v1/ai/generate` (a tenant-authored
+     *  `POST /v1/jobs/generation` run echoes its own `payload.generation_id`) */
+    generation_id: string | null;
+    /** your own `correlation_id` from that request (≤128 chars), or null */
+    correlation_id: string | null;
+    /** the completion mode the run was enqueued with (the ai lane enqueues `poll`) */
+    mode: 'poll' | 'webhook';
+    /** when the run is failed as expired if the provider never settles it */
+    expires_at: string;
+}
+/** The `data` of `job.generation.completed` / `job.generation.failed`. */
+export interface JobGenerationSettledEventPayload {
+    run_id: string;
+    generation_id: string | null;
+    correlation_id: string | null;
+    /** `completed` on the healthy terminal, `failed` on the broken one */
+    status: 'completed' | 'failed';
+    /** the run's SETTLED error class (`provider_error`, `PollExhausted`, …);
+     *  always null on `completed` */
+    error_class: string | null;
+    /** the provider hint alone (`Upstream said: gemini 400: …`); null on
+     *  `completed` and whenever the failure carried none */
+    error_hint: string | null;
+    /** the failure-event vocabulary every `*.failed` carries (guide 12) */
+    level: 'info' | 'error';
+    state: 'ok' | 'broken';
+}
+/** The union a handler subscribed to `job.generation.` receives as `data`:
+ *  narrow on `'status' in data` (queued carries none). */
+export type JobGenerationEventPayload = JobGenerationQueuedEventPayload | JobGenerationSettledEventPayload;
+/** The `data` of `job.succeeded` / `job.dead_lettered` (every run kind). The
+ *  dead letter is the one that carries `level: 'error'` / `state: 'broken'`;
+ *  `job.succeeded` carries neither. */
+export interface JobRunEventPayload {
+    run_id: string;
+    job_name: string;
+    /** the attempt that settled the run (1-based) */
+    attempt: number;
+    level?: 'error';
+    state?: 'broken';
+}
+/** Event name → typed `data`, for the events that settle work you started.
+ *  `VxilEventPayload<'job.generation.failed'>` names one; everything else on
+ *  the catalog is `Record<string, unknown>` until typed here. */
+export interface VxilEventPayloads {
+    'job.generation.queued': JobGenerationQueuedEventPayload;
+    'job.generation.completed': JobGenerationSettledEventPayload;
+    'job.generation.failed': JobGenerationSettledEventPayload;
+    'job.succeeded': JobRunEventPayload;
+    'job.dead_lettered': JobRunEventPayload;
+}
+export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
 /** A re-minted mid-stream connect token (GET /v1/ai/generations/{id}/token). */
 export interface AiStreamToken {
     generation_id: string;
@@ -1138,6 +1219,35 @@ export interface VxilSchemaShape {
         Output: unknown;
     }>;
 }
+/** Per-call options of `vx.fn.<name>(input, opts)`. */
+export interface FnInvokeOptions {
+    /** `true` ⇒ the ASYNC http lane (`x-vxil-async: 1`): the call resolves to the
+     *  `202 { run_id, status:'queued' }` ack at once; the run is delivered through
+     *  the jobs lane with exactly one attempt and records the function's real
+     *  status — poll `vx.jobs.run(run_id)` or listen for `job.*` events.
+     *  Server-mode only (an end-user client gets `403 server_only`). */
+    async?: boolean;
+    /** Sent as `Idempotency-Key`: rides the envelope as `idempotency_key` (the
+     *  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;
+}
+/** The async lane's 202 ack. */
+export interface FnAsyncAck {
+    run_id: string;
+    status: 'queued';
+    /** 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 }`. */
+export interface FnInvoker<I, O> {
+    (input: I, opts?: FnInvokeOptions & {
+        async?: false;
+    }): Promise<O>;
+    (input: I, opts: FnInvokeOptions & {
+        async: true;
+    }): Promise<FnAsyncAck>;
+}
 /** feature client property → the feature key (in S['features']) that enables it.
  *  The renamed namespaces map to their real feature ids. Used by EnabledVxil to
  *  disable namespaces a tenant hasn't enabled. */
@@ -1526,8 +1636,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
      *  /v1/fn/<name>; the generated `VxilSchema` types Input/Output (Level-0
      *  opaque until a function declares a signature). A Proxy gives the
-     *  `vx.fn.<name>` accessor shape without enumerating names at runtime. */
-    readonly fn: { [K in keyof S["functions"] & string]: (input: S["functions"][K]["Input"]) => Promise<S["functions"][K]["Output"]>; };
+     *  `vx.fn.<name>` accessor shape without enumerating names at runtime.
+     *  `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. */
+    readonly fn: { [K in keyof S["functions"] & string]: FnInvoker<S["functions"][K]["Input"], S["functions"][K]["Output"]>; };
     private call;
     readonly users: {
         upsert: (user: {
@@ -2110,20 +2224,45 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  `otp.testRecipients` (store-review / CI accounts): no mail is sent and
              *  the full sign-in link comes back instead. `captcha_token` is required
              *  when the tenant configured `security.captchaSecretRef`; `locale`
-             *  chooses the mail's language. */
+             *  chooses the mail's language. `redirect_url` is an https page in your
+             *  app — or `http://localhost[:port]` / `http://127.0.0.1[:port]` for local
+             *  development (plain http on any other host is refused).
+             *
+             *  GUEST CLAIM: pass the guest's session bearer as `anonymous_token` and
+             *  the link claims `email` FOR THAT GUEST — `verify` (which must present
+             *  the same `anonymous_token`) then keeps the guest's `user_id` (every
+             *  owner-scoped row survives) or, when the address already has an
+             *  account, merges the guest into it (`merged: true`, `user_id` = the
+             *  existing account; swap tokens). Needs `anonymous.enabled`; a non-guest
+             *  bearer is `409 not_anonymous`. */
             request: (input: {
                 email: string;
                 redirect_url: string;
                 locale?: string;
                 captcha_token?: string;
+                anonymous_token?: string;
             }) => Promise<{
                 sent: true;
                 test_link?: string;
             }>;
-            verify: (token: string) => Promise<{
+            /** `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 ⇒
+             *  the move continues in the background — wait for the
+             *  `auth.user.rekeyed` event before reading owner-scoped rows as the
+             *  merged user. The event is written when the pass finishes and is
+             *  best-effort past this response (see `anonymous.link.verify`). */
+            verify: (token: string, opts?: {
+                anonymous_token?: string;
+            }) => Promise<{
                 user_id: string;
                 session: AuthSession;
                 verified: boolean;
+                merged?: boolean;
+                rekeyed?: boolean;
             }>;
         };
         /** Email OTP sign-in: a 6-digit single-use code (distinct from magic-link).
@@ -2172,7 +2311,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  If the claimed email ALREADY has an account, the guest is MERGED
                  *  into it: `user_id` is the existing account, `merged: true`, and a
                  *  fresh `session.token` (same session, re-signed for the merged
-                 *  identity — swap it client-side; other guest sessions are revoked). */
+                 *  identity — swap it client-side; other guest sessions are revoked).
+                 *  `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
+                 *  files rows were already moved onto `user_id` when this returned, so
+                 *  the merged user's next request finds them; false ⇒ the move ran
+                 *  past its in-request budget and continues in the background — wait
+                 *  for the `auth.user.rekeyed { from_user_id, into_user_id, moved,
+                 *  done, failed }` event before reading owner-scoped rows as `user_id`.
+                 *  That event is written when the pass finishes and is BEST-EFFORT past
+                 *  this response: the continuation is not re-run if the instance
+                 *  serving it is evicted, and a failed event write is logged, not
+                 *  retried — treat `rekeyed: false` with no event within a minute or
+                 *  so as "poll your own rows", or re-run the idempotent
+                 *  `cms.items.reKey` / `files.reKey` / `payments.reKeySubscriptions`
+                 *  routes from the `auth.user.merged` backstop. */
                 verify: (input: {
                     token: string;
                     email: string;
@@ -2182,6 +2334,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     email: string;
                     verified: boolean;
                     merged?: true;
+                    rekeyed?: boolean;
                     session?: {
                         token: string;
                         expires_at: string;
@@ -2359,6 +2512,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 session: AuthSession;
                 verified: boolean;
                 linked: "created" | "existing" | "promoted" | "merged";
+                /** present exactly when `linked === 'merged'`: true ⇒ the guest's rows
+                 *  are already under `user_id`; false ⇒ wait for `auth.user.rekeyed`
+                 *  (best-effort past this response — see `anonymous.link.verify`) */
+                rekeyed?: boolean;
                 /** sessions taken over by auth config session.maxConcurrent (present once opted in) */
                 took_over?: string[];
             }>;
@@ -3757,6 +3914,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 ttl?: "5m" | "1h";
             };
             user_id?: string;
+            /** Your own opaque handle (1..128 chars) for this generation — stored on
+             *  the row, echoed on the answer and the replay read, and (job mode)
+             *  carried on the `job.generation.*` events with `generation_id`. */
+            correlation_id?: string;
         }) => Promise<AiGeneration>;
         /** Streamed generation: returns the channel + connect token immediately; open
          *  the realtime channel for AiStreamFrame frames (token/title, then a
@@ -3786,6 +3947,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  {{prompt}}); overrides the built-in instruction (stream-only). */
             title_template?: string;
             user_id?: string;
+            /** Your own opaque handle (1..128 chars) for this generation — stored on
+             *  the row, echoed on the answer and the replay read, and (job mode)
+             *  carried on the `job.generation.*` events with `generation_id`. */
+            correlation_id?: string;
         }) => Promise<AiStreamHandle>;
         /** Job-routed async generation (long/vision/batch): 202 + a jobs run drives
          *  the provider call; the settled answer lands in the replay buffer at
@@ -3834,6 +3999,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 ttl?: "5m" | "1h";
             };
             user_id?: string;
+            /** Your own opaque handle (1..128 chars) for this generation — stored on
+             *  the row, echoed on the answer and the replay read, and (job mode)
+             *  carried on the `job.generation.*` events with `generation_id`. */
+            correlation_id?: string;
         }) => Promise<AiJobHandle>;
         /** Re-mint a fresh connect token for a LIVE stream (a generation that
          *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
@@ -4399,6 +4568,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 outcome?: "received" | "processed" | "error" | "sig_failed" | "parse_failed" | "reprocessed" | "ignored" | "unowned" | "rejected_environment";
                 /** the provider-reported environment axis (not the API key's label) */
                 environment?: "production" | "sandbox";
+                /** exact match on the normalised charge id (= `payments.charge.*`'s
+                 *  `provider_charge_id`) — the delivery that recorded a charge, and any
+                 *  refund/dispute delivery against it, in ≤ a few rows; then ONE
+                 *  detail `get` reads the verified payload. */
+                provider_charge_id?: string;
+                /** exact match on the provider's own event id. */
+                provider_evt_id?: string;
                 since?: string;
                 cursor?: string;
                 limit?: number;

package/dist/index.js

@@ -228,7 +228,11 @@ export class Vxil {
     /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
      *  /v1/fn/<name>; the generated `VxilSchema` types Input/Output (Level-0
      *  opaque until a function declares a signature). A Proxy gives the
-     *  `vx.fn.<name>` accessor shape without enumerating names at runtime. */
+     *  `vx.fn.<name>` accessor shape without enumerating names at runtime.
+     *  `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. */
     fn = new Proxy({}, {
         get: (_t, prop) => {
             if (typeof prop !== 'string')
@@ -236,10 +240,14 @@ export class Vxil {
             // /v1/fn/<name> returns the function's RAW Response (not a {data,meta}
             // envelope), so bypass call()'s unwrap — read the body directly, like
             // audit.export. Errors still surface as VxilError.
-            return async (payload) => {
+            return async (payload, opts) => {
                 const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/fn/${encodeURIComponent(prop)}`)}`, {
                     method: 'POST',
-                    headers: { authorization: `Bearer ${this.key}`, ...this.authHeaders(), 'content-type': 'application/json' },
+                    headers: {
+                        authorization: `Bearer ${this.key}`, ...this.authHeaders(), 'content-type': 'application/json',
+                        ...(opts?.async ? { 'x-vxil-async': '1' } : {}),
+                        ...(opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {}),
+                    },
                     body: JSON.stringify(payload ?? {}),
                 });
                 if (!res.ok) {
@@ -635,9 +643,29 @@ export class Vxil {
              *  `otp.testRecipients` (store-review / CI accounts): no mail is sent and
              *  the full sign-in link comes back instead. `captcha_token` is required
              *  when the tenant configured `security.captchaSecretRef`; `locale`
-             *  chooses the mail's language. */
+             *  chooses the mail's language. `redirect_url` is an https page in your
+             *  app — or `http://localhost[:port]` / `http://127.0.0.1[:port]` for local
+             *  development (plain http on any other host is refused).
+             *
+             *  GUEST CLAIM: pass the guest's session bearer as `anonymous_token` and
+             *  the link claims `email` FOR THAT GUEST — `verify` (which must present
+             *  the same `anonymous_token`) then keeps the guest's `user_id` (every
+             *  owner-scoped row survives) or, when the address already has an
+             *  account, merges the guest into it (`merged: true`, `user_id` = the
+             *  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,
-            verify: async (token) => (await this.call('POST', '/v1/auth/magic-link/verify', { token })).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
+             *  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 ⇒
+             *  the move continues in the background — wait for the
+             *  `auth.user.rekeyed` event before reading owner-scoped rows as the
+             *  merged user. The event is written when the pass finishes and is
+             *  best-effort past this response (see `anonymous.link.verify`). */
+            verify: async (token, opts = {}) => (await this.call('POST', '/v1/auth/magic-link/verify', { token, ...(opts.anonymous_token !== undefined ? { anonymous_token: opts.anonymous_token } : {}) })).data,
         },
         /** Email OTP sign-in: a 6-digit single-use code (distinct from magic-link).
          *  Server-side guessing budget (config otp.maxAttempts), single active code,
@@ -660,7 +688,20 @@ export class Vxil {
                  *  If the claimed email ALREADY has an account, the guest is MERGED
                  *  into it: `user_id` is the existing account, `merged: true`, and a
                  *  fresh `session.token` (same session, re-signed for the merged
-                 *  identity — swap it client-side; other guest sessions are revoked). */
+                 *  identity — swap it client-side; other guest sessions are revoked).
+                 *  `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
+                 *  files rows were already moved onto `user_id` when this returned, so
+                 *  the merged user's next request finds them; false ⇒ the move ran
+                 *  past its in-request budget and continues in the background — wait
+                 *  for the `auth.user.rekeyed { from_user_id, into_user_id, moved,
+                 *  done, failed }` event before reading owner-scoped rows as `user_id`.
+                 *  That event is written when the pass finishes and is BEST-EFFORT past
+                 *  this response: the continuation is not re-run if the instance
+                 *  serving it is evicted, and a failed event write is logged, not
+                 *  retried — treat `rekeyed: false` with no event within a minute or
+                 *  so as "poll your own rows", or re-run the idempotent
+                 *  `cms.items.reKey` / `files.reKey` / `payments.reKeySubscriptions`
+                 *  routes from the `auth.user.merged` backstop. */
                 verify: async (input) => (await this.call('POST', '/v1/auth/anonymous/link/verify', input)).data,
             },
         },
@@ -768,7 +809,9 @@ export class Vxil {
             /** `anonymous_token`: the caller's CURRENT guest session bearer — the
              *  guest is PROMOTED to this identity (same user id, `linked: 'promoted'`)
              *  or, if the identity already has an account, MERGED into it
-             *  (`linked: 'merged'`, `user_id` = that account). */
+             *  (`linked: 'merged'`, `user_id` = that account, `rekeyed` says whether
+             *  the guest's owner-scoped rows already moved — see
+             *  `anonymous.link.verify`). */
             input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
         },
     };
@@ -1821,6 +1864,8 @@ export class Vxil {
                     event_type: q?.event_type || undefined,
                     outcome: q?.outcome || undefined,
                     environment: q?.environment || undefined,
+                    provider_charge_id: q?.provider_charge_id || undefined,
+                    provider_evt_id: q?.provider_evt_id || undefined,
                     since: q?.since || undefined,
                     cursor: q?.cursor || undefined,
                     limit: q?.limit || undefined,

package/package.json

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