@vxil/sdk 0.5.2 → 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). */
@@ -713,6 +724,62 @@ export interface AiJobHandle {
     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;
@@ -1152,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. */
@@ -1540,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: {
@@ -2148,7 +2248,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             /** `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). */
+             *  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<{
@@ -2156,6 +2262,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 session: AuthSession;
                 verified: boolean;
                 merged?: boolean;
+                rekeyed?: boolean;
             }>;
         };
         /** Email OTP sign-in: a 6-digit single-use code (distinct from magic-link).
@@ -2204,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;
@@ -2214,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;
@@ -2391,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[];
             }>;

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) {
@@ -650,7 +658,13 @@ export class Vxil {
             /** `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). */
+             *  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).
@@ -674,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,
             },
         },
@@ -782,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,
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.5.2",
+  "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).",