@vxil/sdk 0.5.1 → 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).
@@ -3757,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
@@ -3786,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
@@ -3834,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>`. */
@@ -4399,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,
@@ -1821,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.1",
+  "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).",