@vxil/sdk 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -399,6 +399,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 +646,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 +663,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,6 +706,10 @@ 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;
 }
@@ -2110,20 +2124,38 @@ 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). */
+            verify: (token: string, opts?: {
+                anonymous_token?: string;
+            }) => Promise<{
                 user_id: string;
                 session: AuthSession;
                 verified: boolean;
+                merged?: boolean;
             }>;
         };
         /** Email OTP sign-in: a 6-digit single-use code (distinct from magic-link).
@@ -2189,6 +2221,37 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 }>;
             };
         };
+        /** E-mail CHANGE for a signed-in (non-anonymous) user: a 6-digit code is
+         *  mailed to the NEW address; verify swaps the account's address (both the
+         *  auth row and the shared identity row, in one transaction), marks it
+         *  verified, and revokes every OTHER session of the user (reason
+         *  `email_changed`) — the presenting `token` keeps working. `request` is
+         *  always 202 whether or not the address is taken (no enumeration);
+         *  a taken address surfaces at `verify` as 409 `email_in_use`. A guest
+         *  session is 409 `anonymous_user` — guests use `anonymous.link`. Shares
+         *  the OTP knobs (cooldown → 429 `otp_rate_limited`, attempts, TTL,
+         *  `test_code` for `otp.testRecipients`) but does NOT need `otp.enabled`. */
+        email: {
+            change: {
+                request: (input: {
+                    token: string;
+                    new_email: string;
+                    locale?: string;
+                }) => Promise<{
+                    sent: true;
+                    test_code?: string;
+                }>;
+                verify: (input: {
+                    token: string;
+                    new_email: string;
+                    code: string;
+                }) => Promise<{
+                    user_id: string;
+                    email: string;
+                    verified: true;
+                }>;
+            };
+        };
         /** Step-up re-auth: an OTP challenge on the CURRENT session. On verify the
          *  bearer token ROTATES (the returned session.token replaces the old one —
          *  swap it client-side) and the JWT gains an `elv` claim. */
@@ -2668,6 +2731,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 }>;
                 scanned: number;
             }>;
+            /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move
+             *  every row `from_user_id` owns — across every collection that declares
+             *  an `owner_field`, soft-deleted rows included, the stored owner value
+             *  AND its indexed projection — onto `into_user_id`. ONE bounded page (≤500
+             *  rows) per call: loop while `done` is false. Idempotent (a second pass
+             *  moves 0). Bumps each moved row's `version`. The cms consumer of the
+             *  `auth.user.merged { from, into }` event; auth-v1 calls it after a
+             *  merge, the event is the backstop. Emits one `cms.items.rekeyed`. */
+            reKey: (input: {
+                from_user_id: string;
+                into_user_id: string;
+            }) => Promise<{
+                moved: number;
+                done: boolean;
+            }>;
         };
         /** cms-rel B4 (cms.md §13): atomic multi-collection transaction — 1–5
          *  steps over ≤3 collections, per-step `$where` CAS preconditions (the
@@ -3505,6 +3583,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             object_id: string;
             expires_at: string | null;
         }>;
+        /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move
+         *  every object `from_user_id` owns (every status, tombstones included) and
+         *  the shared links minted on them onto `into_user_id`, which must be a
+         *  live tenant user (404 user_not_found otherwise). ONE bounded page (≤500
+         *  objects) per call: loop while `done` is false. Idempotent. An erased
+         *  `from` user's objects are held back for the GDPR byte sweep (moved 0).
+         *  The files consumer of the `auth.user.merged { from, into }` event;
+         *  auth-v1 calls it after a merge, the event is the backstop. Emits one
+         *  `files.objects.rekeyed`. */
+        reKey: (input: {
+            from_user_id: string;
+            into_user_id: string;
+        }) => Promise<{
+            moved: number;
+            done: boolean;
+        }>;
         sharedLinks: {
             /** Public (unauthenticated) URL for the object; revocable. Optional
              *  `max_downloads` (1 = one-time link) and an absolute `expires_at`; the
@@ -3614,7 +3708,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      * openrouter) route via BYO keys in tenant_secrets. `images` on the generate
      * inputs takes up to 8 vision refs: a public https:// URL, a
      * data:image/...;base64 URL, or file:<object_id> (a files-feature object) —
-     * fetched images are capped at 4 MiB each / 16 MiB total.
+     * fetched images are capped at 4 MiB each; `documents` (pdf/text, ≤10 MiB
+     * each) share one 20 MiB inline ceiling per request with them.
      */
     readonly ai: {
         templates: {
@@ -3694,6 +3789,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
@@ -3723,6 +3822,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
@@ -3771,6 +3874,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>`. */
@@ -4336,6 +4443,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

@@ -635,9 +635,23 @@ 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). */
+            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,
@@ -664,6 +678,22 @@ export class Vxil {
                 verify: async (input) => (await this.call('POST', '/v1/auth/anonymous/link/verify', input)).data,
             },
         },
+        /** E-mail CHANGE for a signed-in (non-anonymous) user: a 6-digit code is
+         *  mailed to the NEW address; verify swaps the account's address (both the
+         *  auth row and the shared identity row, in one transaction), marks it
+         *  verified, and revokes every OTHER session of the user (reason
+         *  `email_changed`) — the presenting `token` keeps working. `request` is
+         *  always 202 whether or not the address is taken (no enumeration);
+         *  a taken address surfaces at `verify` as 409 `email_in_use`. A guest
+         *  session is 409 `anonymous_user` — guests use `anonymous.link`. Shares
+         *  the OTP knobs (cooldown → 429 `otp_rate_limited`, attempts, TTL,
+         *  `test_code` for `otp.testRecipients`) but does NOT need `otp.enabled`. */
+        email: {
+            change: {
+                request: async (input) => (await this.call('POST', '/v1/auth/email/change/request', input)).data,
+                verify: async (input) => (await this.call('POST', '/v1/auth/email/change/verify', input)).data,
+            },
+        },
         /** Step-up re-auth: an OTP challenge on the CURRENT session. On verify the
          *  bearer token ROTATES (the returned session.token replaces the old one —
          *  swap it client-side) and the JWT gains an `elv` claim. */
@@ -983,6 +1013,15 @@ export class Vxil {
              *  row_number|rank|percent_rank, computed over ≤500 aggregated groups
              *  (never raw rows), optional partitionBy. Same scan cap as aggregate. */
             rank: async (collection, body) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/rank`, body)).data,
+            /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move
+             *  every row `from_user_id` owns — across every collection that declares
+             *  an `owner_field`, soft-deleted rows included, the stored owner value
+             *  AND its indexed projection — onto `into_user_id`. ONE bounded page (≤500
+             *  rows) per call: loop while `done` is false. Idempotent (a second pass
+             *  moves 0). Bumps each moved row's `version`. The cms consumer of the
+             *  `auth.user.merged { from, into }` event; auth-v1 calls it after a
+             *  merge, the event is the backstop. Emits one `cms.items.rekeyed`. */
+            reKey: async (input) => (await this.call('POST', '/v1/cms/items/re-key', input)).data,
         },
         /** cms-rel B4 (cms.md §13): atomic multi-collection transaction — 1–5
          *  steps over ≤3 collections, per-step `$where` CAS preconditions (the
@@ -1365,6 +1404,16 @@ export class Vxil {
         /** Set / extend / clear an object's TTL. `expiresInSeconds: null` clears it
          *  (else a future auto-delete after the given seconds; minimum 60). */
         setTtl: async (objectId, expiresInSeconds) => (await this.call('PUT', `/v1/files/${encodeURIComponent(objectId)}/ttl`, { expiresInSeconds })).data,
+        /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move
+         *  every object `from_user_id` owns (every status, tombstones included) and
+         *  the shared links minted on them onto `into_user_id`, which must be a
+         *  live tenant user (404 user_not_found otherwise). ONE bounded page (≤500
+         *  objects) per call: loop while `done` is false. Idempotent. An erased
+         *  `from` user's objects are held back for the GDPR byte sweep (moved 0).
+         *  The files consumer of the `auth.user.merged { from, into }` event;
+         *  auth-v1 calls it after a merge, the event is the backstop. Emits one
+         *  `files.objects.rekeyed`. */
+        reKey: async (input) => (await this.call('POST', '/v1/files/objects/re-key', input)).data,
         sharedLinks: {
             /** Public (unauthenticated) URL for the object; revocable. Optional
              *  `max_downloads` (1 = one-time link) and an absolute `expires_at`; the
@@ -1432,7 +1481,8 @@ export class Vxil {
      * openrouter) route via BYO keys in tenant_secrets. `images` on the generate
      * inputs takes up to 8 vision refs: a public https:// URL, a
      * data:image/...;base64 URL, or file:<object_id> (a files-feature object) —
-     * fetched images are capped at 4 MiB each / 16 MiB total.
+     * fetched images are capped at 4 MiB each; `documents` (pdf/text, ≤10 MiB
+     * each) share one 20 MiB inline ceiling per request with them.
      */
     ai = {
         templates: {
@@ -1785,6 +1835,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.0",
+  "version": "0.5.2",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",