@vxil/sdk 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +314 -18
  2. package/dist/index.js +160 -14
  3. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -885,6 +885,33 @@ export interface PaymentsCharge {
885
885
  environment: PaymentsEventEnvironment;
886
886
  created_at: string;
887
887
  }
888
+ /** A credit ledger row as listed by GET /v1/payments/credits/ledger (2026-10-05). */
889
+ export interface PaymentsLedgerEntry {
890
+ /** `led_…` */
891
+ ledger_entry_id: string;
892
+ user_id: string;
893
+ credit_type: string;
894
+ /** grant / grant_once add credits; consume and expire remove them; settle and
895
+ * reversal correct a job-linked consume (`reverses_entry_id` names it) */
896
+ kind: 'grant' | 'grant_once' | 'consume' | 'settle' | 'reversal' | 'expire';
897
+ /** `provisional` = a job-linked hold not settled yet */
898
+ state: 'provisional' | 'committed' | 'reversed';
899
+ /** `insufficient` = a recorded 402 consume (no balance moved) */
900
+ outcome: 'applied' | 'insufficient';
901
+ /** the signed amount: positive adds credits, negative removes them */
902
+ delta: number;
903
+ balance_after: number | null;
904
+ source: string | null;
905
+ /** the jobs run this row is linked to */
906
+ job_id: string | null;
907
+ /** on a settle / reversal: the consume entry it corrects */
908
+ reverses_entry_id: string | null;
909
+ /** the grant-once dedup key */
910
+ grant_key: string | null;
911
+ /** the Idempotency-Key the consume / grant was sent with */
912
+ idempotency_key: string | null;
913
+ created_at: string;
914
+ }
888
915
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
889
916
  export interface PaymentsRefund {
890
917
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -1646,9 +1673,11 @@ export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloa
1646
1673
  export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
1647
1674
  /** The audiences a function's scoped callback tokens are minted for — one per
1648
1675
  * feature its declared scopes reach. `control-plane` carries `users:*` /
1649
- * `usage:read` only. There is deliberately no `functions` audience: a function
1650
- * cannot call another function. */
1651
- export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane';
1676
+ * `usage:read` / `audit:read` only; `webhooks` carries `webhooks:read` only (read the inbound
1677
+ * sources and received events — e.g. `GET /v1/webhooks/events?after=`). There
1678
+ * is deliberately no `functions` audience: a function cannot call another
1679
+ * function. */
1680
+ export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane' | 'webhooks';
1652
1681
  /** One short-lived scoped token per audience your scopes imply
1653
1682
  * (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
1654
1683
  * scopes do not reach is absent. Send it as `Authorization: Bearer …` to
@@ -1710,6 +1739,43 @@ export interface WebhookTriggerPayload<D = Record<string, unknown>> {
1710
1739
  truncated: true;
1711
1740
  } | null;
1712
1741
  }
1742
+ /** The verification parameters of an inbound `hmac` source (`webhooks.sources.create`). */
1743
+ export interface WebhookHmacVerify {
1744
+ /** the header carrying the signature (case-insensitive) */
1745
+ header: string;
1746
+ algorithm?: 'sha256' | 'sha1';
1747
+ encoding?: 'hex' | 'base64';
1748
+ /** stripped before comparing (e.g. `sha256=`); required on the request when set */
1749
+ prefix?: string;
1750
+ /** a header carrying the signing timestamp (unix seconds or ISO 8601): the
1751
+ * signed message becomes `<timestamp><timestamp_separator><body>` */
1752
+ timestamp_header?: string;
1753
+ /** default '.'; '' to concatenate */
1754
+ timestamp_separator?: string;
1755
+ /** default 300, 1..3600 */
1756
+ tolerance_seconds?: number;
1757
+ event_id_header?: string;
1758
+ event_type_header?: string;
1759
+ }
1760
+ /** `payload.data` of a `webhook` invocation fired by an inbound source whose
1761
+ * `target_function` is this function (`payload.event === 'inbound_webhook.received'`). */
1762
+ export interface InboundWebhookTriggerData {
1763
+ vxil_event_id: string;
1764
+ source_id: string;
1765
+ provider: string;
1766
+ provider_event_id: string | null;
1767
+ event_type: string | null;
1768
+ sig_verified: boolean;
1769
+ /** the provider's JSON body; null when it was larger than 48 000 bytes
1770
+ * (`payload_omitted: true`) — read it with
1771
+ * `GET /v1/webhooks/events?event_id=<vxil_event_id>` (scope webhooks:read) */
1772
+ payload: Record<string, unknown> | unknown[] | null;
1773
+ payload_omitted?: true;
1774
+ /** true on a `POST /v1/webhooks/sources/:id/test` probe */
1775
+ test?: true;
1776
+ /** true on a `POST /v1/webhooks/events/:id/replay` */
1777
+ replayed?: true;
1778
+ }
1713
1779
  /** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
1714
1780
  * parameters on a GET). */
1715
1781
  export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
@@ -2847,6 +2913,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
2847
2913
  readonly fn: { [K in keyof S["functions"] & string]: FnInvoker<S["functions"][K]["Input"], S["functions"][K]["Output"]>; };
2848
2914
  private call;
2849
2915
  readonly users: {
2916
+ /** Create or replace a tenant user by id. Upserting a deleted id brings it
2917
+ * back; upserting an ERASED id re-creates it as a new, empty user
2918
+ * (`erased_at` cleared — the erase already removed the old data). While
2919
+ * the erased user's files are still being erased the call fails with 409
2920
+ * `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
2850
2921
  upsert: (user: {
2851
2922
  id: string;
2852
2923
  email?: string;
@@ -3215,11 +3286,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3215
3286
  brief?: boolean;
3216
3287
  }) => Promise<VxilPlan>;
3217
3288
  };
3289
+ /** The project audit log. Needs `audit:read` (the narrow read-only scope —
3290
+ * declare it on a function to read the log from its callback token) or
3291
+ * `features:read`. Server-only: a public / thin-client key cannot read it. */
3218
3292
  readonly audit: {
3293
+ /**
3294
+ * The audit trail, newest first. `subject` narrows to the events about ONE
3295
+ * thing: a user id (`payload.user_id` / `payload.id`), a cms record
3296
+ * (`payload.item_id` — the record's history), a verified end user
3297
+ * (`payload.end_user_id` — what that person changed through a thin-client
3298
+ * key or a function acting for them, and their payments events), or a
3299
+ * principal (`actor`). Server keys only.
3300
+ */
3219
3301
  list: (q?: {
3220
3302
  since?: string;
3221
3303
  cursor?: string;
3222
3304
  limit?: number;
3305
+ subject?: string;
3223
3306
  }) => Promise<Array<{
3224
3307
  id: string;
3225
3308
  event: string;
@@ -3237,6 +3320,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3237
3320
  until?: string;
3238
3321
  after_id?: string;
3239
3322
  limit?: number;
3323
+ /** the same subject filter as `list` */
3324
+ subject?: string;
3240
3325
  }) => Promise<{
3241
3326
  events: Array<{
3242
3327
  id: string;
@@ -3521,7 +3606,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3521
3606
  state: string;
3522
3607
  }>;
3523
3608
  /** Clone a terminal run into a fresh queued run. A generation run answers
3524
- * `409 not_replayable` — submit the generation again instead. */
3609
+ * `409 not_replayable` — submit the generation again instead; a redacted
3610
+ * or erased run answers `409 run_redacted` (its payload is gone). */
3525
3611
  replay: (runId: string) => Promise<{
3526
3612
  run_id: string;
3527
3613
  replayed_from: string;
@@ -3544,6 +3630,30 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3544
3630
  moved: number;
3545
3631
  done: boolean;
3546
3632
  }>;
3633
+ /** SERVER-ONLY (403 server_only in end-user mode). Redact FINISHED runs
3634
+ * that hold personal data: the payload becomes `{ erased: true }`, the
3635
+ * result, progress, callback body and error text are cleared, a
3636
+ * generation's provider request body/headers are dropped and its credit
3637
+ * hold's user id is pseudonymized (unless its settle is still owed). The
3638
+ * row itself stays (state, timings, job_name). The same fields a GDPR
3639
+ * erase clears on the runs it can link to a user — use this for runs
3640
+ * nothing links to one (a plain queue run, an async function call).
3641
+ * `{ run_ids }` (≤500, one call; open runs are left alone and counted in
3642
+ * `skipped_open`) or `{ user_id }` (the generation runs whose credit hold
3643
+ * names that user — ONE page of ≤500 per call, call again until `done`).
3644
+ * Idempotent. Audited as `jobs.runs.redacted` (counts only; none when a
3645
+ * call redacted nothing). NOT cleared: concurrency_key, debounce_key,
3646
+ * idempotency_key and target_url — keep user ids out of those (hash them).
3647
+ * A redacted run does not replay. Scope jobs:write. */
3648
+ redact: (input: {
3649
+ run_ids: string[];
3650
+ } | {
3651
+ user_id: string;
3652
+ }) => Promise<{
3653
+ redacted: number;
3654
+ skipped_open: number;
3655
+ done: boolean;
3656
+ }>;
3547
3657
  /**
3548
3658
  * Suspend the RUNNING run until an event (call from the executing
3549
3659
  * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -3734,8 +3844,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3734
3844
  /** On success the guest keeps its user id (`user_id` unchanged).
3735
3845
  * If the claimed email ALREADY has an account, the guest is MERGED
3736
3846
  * into it: `user_id` is the existing account, `merged: true`, and a
3737
- * fresh `session.token` (same session, re-signed for the merged
3738
- * identity — swap it client-side; other guest sessions are revoked).
3847
+ * fresh `session.token` (the same session carried over to the merged
3848
+ * identity under a new session id — swap it client-side: the old
3849
+ * guest token is revoked, the refresh token keeps working; other
3850
+ * guest sessions are revoked).
3739
3851
  * `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
3740
3852
  * files rows were already moved onto `user_id` when this returned, so
3741
3853
  * the merged user's next request finds them; false ⇒ the move ran
@@ -3967,15 +4079,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3967
4079
  verified: true;
3968
4080
  }>;
3969
4081
  };
3970
- /** Social sign-in. The web `start`/`callback` flows are browser redirects
3971
- * (not JSON calls): send the browser to
3972
- * `GET /v1/auth/oauth/{provider}/start?redirect_uri=…` (server-side, with
3973
- * your key) and hand the returned `code`+`state` to `…/callback`; `native`
4082
+ /** Social sign-in. The web flow: `startUrl` fetches the provider authorize
4083
+ * URL with your key (a browser cannot follow the header-carrying 302 of
4084
+ * `GET /v1/auth/oauth/{provider}/start` itself), you navigate the browser
4085
+ * there, and hand the returned `code`+`state` to `…/callback`; `native`
3974
4086
  * is the mobile / broker token-exchange the SDK wraps. `oidc` is the
3975
4087
  * tenant's generic OIDC / SSO issuer (auth config `providers.oidc` —
3976
4088
  * Okta / Entra / Auth0 / any OpenID Connect IdP, or a SAML broker that
3977
4089
  * speaks OIDC); it rides the same three routes. */
3978
4090
  oauth: {
4091
+ /** Start the web sign-in from a browser SPA: answers the provider
4092
+ * `authorize_url` (PKCE challenge, one-shot `state`, and for `oidc` a
4093
+ * nonce bound to the flow — all held server-side) for you to navigate
4094
+ * to: `location.assign((await vx.auth.oauth.startUrl('oidc',
4095
+ * { redirect_uri })).authorize_url)`. The provider returns to
4096
+ * `redirect_uri` with `?code&state`, which your page sends to
4097
+ * `GET /v1/auth/oauth/{provider}/callback` for the session. The same
4098
+ * rules as the redirect form apply: `redirect_uri` must match the auth
4099
+ * config `security.allowedRedirectOrigins` when set (else
4100
+ * `422 redirect_not_allowed`), and the state expires after
4101
+ * `expires_in` seconds (600). `anonymous_token` (a guest bearer)
4102
+ * promotes or merges that guest at the callback. */
4103
+ startUrl: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4104
+ redirect_uri: string;
4105
+ anonymous_token?: string;
4106
+ }) => Promise<{
4107
+ authorize_url: string;
4108
+ expires_in: number;
4109
+ }>;
3979
4110
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
3980
4111
  * for a vxil session (`linked` marks whether the user was created or
3981
4112
  * matched to an existing identity). */
@@ -4126,6 +4257,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4126
4257
  * (end-user reads and writes are `403 server_only`, even with an
4127
4258
  * owner_field). Server keys are never affected. */
4128
4259
  end_user_access?: CmsEndUserAccess;
4260
+ /** Role slugs one of which a VERIFIED end user must hold to WRITE this
4261
+ * collection (create / update / $inc / delete / publish / transaction
4262
+ * step / batch / filtered delete, and an end-user delete's cascade into
4263
+ * it) — otherwise `403 role_required`. Reads are unaffected; server keys
4264
+ * are never affected. Omitted/`[]` = ungated. ≤16 entries, each
4265
+ * `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
4266
+ write_roles?: string[];
4267
+ /** Retention (guide ch. 4): live items created more than this many days
4268
+ * ago (1..3650) are soft-deleted by the nightly platform sweep — like a
4269
+ * normal delete (no restore; purged at least 30 days later, unique values freed), with ONE
4270
+ * `cms.collection.retention_swept` audit event per collection per night
4271
+ * instead of per-item delete events. A collection another collection
4272
+ * references with an `on_delete` rule is skipped. Omit/null = keep. */
4273
+ retain_days?: number | null;
4129
4274
  fields?: Array<{
4130
4275
  field: string;
4131
4276
  type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -4175,6 +4320,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4175
4320
  actions?: CmsActionDef[];
4176
4321
  /** present when not the default 'readwrite' */
4177
4322
  end_user_access?: CmsEndUserAccess;
4323
+ /** present when the collection is role-gated for end-user writes */
4324
+ write_roles?: string[];
4325
+ /** present when retention is set */
4326
+ retain_days?: number;
4178
4327
  }>;
4179
4328
  list: () => Promise<Array<{
4180
4329
  collection: string;
@@ -4183,6 +4332,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4183
4332
  owner_field?: string | null;
4184
4333
  /** the collection's end-user access mode (absent from an older server = 'readwrite') */
4185
4334
  end_user_access?: CmsEndUserAccess;
4335
+ /** the roles an end user needs to write it (null / absent = ungated) */
4336
+ write_roles?: string[] | null;
4337
+ /** retention in days (null = keep until deleted; absent from an older server) */
4338
+ retain_days?: number | null;
4186
4339
  }>>;
4187
4340
  addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
4188
4341
  /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
@@ -4225,6 +4378,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4225
4378
  collection: string;
4226
4379
  end_user_access: CmsEndUserAccess;
4227
4380
  }>;
4381
+ /** Set (or clear, with `[]` / `null`) the collection's END-USER WRITE
4382
+ * ROLES (guide ch. 9): a verified end user must hold one of `roles` (the
4383
+ * session's verified role claims — orgs roles) to write the collection,
4384
+ * otherwise every write door answers `403 role_required`. Reads are
4385
+ * unaffected; server keys are never affected. Audited; takes effect on
4386
+ * the next write. */
4387
+ setWriteRoles: (collection: string, roles: string[] | null) => Promise<{
4388
+ collection: string;
4389
+ write_roles: string[];
4390
+ }>;
4391
+ /** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
4392
+ * ch. 4): the nightly platform sweep soft-deletes live items created more
4393
+ * than `days` ago — bounded per project per night, no restore, purged at
4394
+ * least 30 days later like any delete, one `cms.collection.retention_swept` audit event
4395
+ * per collection per sweep. Audited (`cms.collection.retain_days.set`). */
4396
+ setRetention: (collection: string, days: number | null) => Promise<{
4397
+ collection: string;
4398
+ retain_days: number | null;
4399
+ }>;
4228
4400
  /** Re-project the collection's index slots after an `index_slot` move
4229
4401
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
4230
4402
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -4276,6 +4448,29 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4276
4448
  version: number;
4277
4449
  data: Record<string, unknown>;
4278
4450
  }>;
4451
+ /** Upsert by a declared `unique` field (guide ch. 4): creates the item, or
4452
+ * — when a live item already holds `data[field]` — merges `patch` into
4453
+ * THAT item instead (one transaction; update hooks, guards, version bump
4454
+ * and a `cms.item.updated` audit, exactly like `patch`; null clears a
4455
+ * field). `created` tells which happened (201 vs 200). Concurrent upserts
4456
+ * of one key serialize, so they never create a duplicate. */
4457
+ upsert: (collection: string, input: {
4458
+ data: Record<string, unknown>;
4459
+ onConflict: {
4460
+ field: string;
4461
+ patch: Record<string, unknown>;
4462
+ };
4463
+ status?: "draft" | "published";
4464
+ lock?: string;
4465
+ guard?: CmsGuard;
4466
+ guards?: CmsGuardTerm[];
4467
+ }) => Promise<{
4468
+ item_id: string;
4469
+ status: string;
4470
+ version: number;
4471
+ data: Record<string, unknown>;
4472
+ created: boolean;
4473
+ }>;
4279
4474
  /** `expand` inlines relation/file fields into `data` (guide ch. 4): the
4280
4475
  * full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
4281
4476
  * the bare id on a cycle/depth cut, `null` for an invisible target. */
@@ -4284,7 +4479,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4284
4479
  }) => Promise<Record<string, unknown>>;
4285
4480
  /**
4286
4481
  * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
4287
- * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
4482
+ * ($ne is NULL-safe: a row whose field is absent or null counts as not
4483
+ * equal; on a dotted join term the row still needs a readable target,
4484
+ * so a null or dangling relation is excluded) $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
4288
4485
  * fields) $arrayContains/$anyOf (json/relation array containment, indexed);
4289
4486
  * range/sort needs slot-indexed fields. This is the
4290
4487
  * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
@@ -4674,6 +4871,32 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4674
4871
  };
4675
4872
  warnings?: string[];
4676
4873
  }>;
4874
+ /**
4875
+ * Log records of ONE function, one per invocation (outcome, wall/cpu ms,
4876
+ * console lines, exceptions), oldest first. Pass the returned `next_since`
4877
+ * back as `since` to read only newer records (a tail); without it, the most
4878
+ * recent records of the last 24 hours. Kept 14 days. Needs
4879
+ * `functions:read`. (GET /v1/functions/:name/logs)
4880
+ */
4881
+ logs: (name: string, opts?: {
4882
+ since?: string;
4883
+ }) => Promise<{
4884
+ lines: Array<{
4885
+ ts: string;
4886
+ outcome: string;
4887
+ wall_ms: number | null;
4888
+ cpu_ms: number | null;
4889
+ logs: Array<{
4890
+ level: string;
4891
+ message: string;
4892
+ }>;
4893
+ exceptions: Array<{
4894
+ name: string;
4895
+ message: string;
4896
+ }>;
4897
+ }>;
4898
+ next_since: string | null;
4899
+ }>;
4677
4900
  };
4678
4901
  /** The MCP aggregation surface (the `mcp` feature). */
4679
4902
  readonly mcp: {
@@ -4969,20 +5192,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4969
5192
  last_error_msg?: string | null;
4970
5193
  }>;
4971
5194
  sources: {
4972
- /** Register an inbound source; the receiver URL is returned ONCE. */
5195
+ /** Register an inbound source; the receiver URL is returned ONCE.
5196
+ *
5197
+ * Destination: `forward_url` (your endpoint) OR `target_function` (a
5198
+ * deployed function that declares a bare `trigger: { kind: 'webhook' }`
5199
+ * binding — it receives `payload.event === 'inbound_webhook.received'`
5200
+ * with the inbound envelope as `payload.data`), never both; neither =
5201
+ * store only (read with `events.list`).
5202
+ *
5203
+ * `provider: 'hmac'` is the parameterized preset for any provider that
5204
+ * signs an HMAC of the raw body (Shopify, Intercom, Linear, Zendesk, …):
5205
+ * `verify` says which header, sha256|sha1, hex|base64, an optional prefix
5206
+ * and an optional timestamp header + tolerance. Like stripe/paddle/slack it
5207
+ * fails closed (401) until the source's signing secret is set. */
4973
5208
  create: (input: {
4974
- provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic";
5209
+ provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic" | "hmac";
4975
5210
  name: string;
4976
5211
  forward_url?: string;
5212
+ target_function?: string;
5213
+ verify?: WebhookHmacVerify;
4977
5214
  }) => Promise<{
4978
5215
  source_id: string;
4979
5216
  receiver_url_path: string;
4980
5217
  provider: string;
5218
+ target_function?: string | null;
4981
5219
  }>;
4982
5220
  list: () => Promise<Array<{
4983
5221
  source_id: string;
4984
5222
  provider: string;
4985
5223
  name: string;
5224
+ forward_url?: string | null;
5225
+ target_function?: string | null;
5226
+ verify?: WebhookHmacVerify | null;
4986
5227
  }>>;
4987
5228
  delete: (sourceId: string) => Promise<void>;
4988
5229
  /** Send a sample envelope to the source's forward_url through the real
@@ -4997,20 +5238,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4997
5238
  }>;
4998
5239
  };
4999
5240
  events: {
5241
+ /** Received events. Newest first, paged with `cursor`; or — with `after`
5242
+ * (your watermark, an event id) — OLDEST first from just after it, the
5243
+ * drain shape: store `next_after` and pass it back, `has_more` says
5244
+ * another page waits. The `after` drain answers only events received
5245
+ * at least 10 s ago (ids are not strictly arrival-ordered, so a fresher
5246
+ * event could otherwise commit below a stored watermark and be
5247
+ * skipped); `cursor` and `event_id` reads are not lagged. `event_id`
5248
+ * reads exactly one event. `cursor` and `after` are exclusive. */
5000
5249
  list: (q?: {
5001
5250
  source_id?: string;
5002
5251
  status?: string;
5003
5252
  cursor?: string;
5004
5253
  limit?: number;
5254
+ after?: string;
5255
+ event_id?: string;
5005
5256
  }) => Promise<{
5006
5257
  events: Array<{
5007
5258
  event_id: string;
5259
+ source_id: string;
5260
+ provider: string;
5261
+ provider_event_id: string | null;
5008
5262
  event_type: string | null;
5009
5263
  payload: Record<string, unknown>;
5010
5264
  sig_verified: boolean;
5011
5265
  status: string;
5266
+ received_at: string;
5012
5267
  }>;
5013
5268
  next_cursor: string | null;
5269
+ /** `after` pages only */
5270
+ next_after?: string | null;
5271
+ /** `after` pages only */
5272
+ has_more?: boolean;
5014
5273
  }>;
5015
5274
  replay: (eventId: string) => Promise<void>;
5016
5275
  /** The Svix message-attempt view: delivery state/attempts/DLQ flag for
@@ -5231,8 +5490,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5231
5490
  * matching its TokenProvider type *structurally* (no import — a static
5232
5491
  * import would break the single-file served sdk.mjs) that re-mints via
5233
5492
  * POST /v1/realtime/tokens with `defaults` merged over the channel the
5234
- * client asks for. Server-side (Node) use only — it needs the API key;
5235
- * browsers must fetch tokens from YOUR backend instead. */
5493
+ * client asks for. Two safe ways to use it:
5494
+ * - on a server, with a server key (`user_id` names the subject); or
5495
+ * - in a browser / mobile app, with a PUBLIC `end_user_required` key and
5496
+ * the signed-in user's session (`endUserToken` on the client): the mint
5497
+ * runs in end-user mode and the token's subject is FORCED to the
5498
+ * verified user (any `user_id` you pass is overridden), so no
5499
+ * backend of your own is needed.
5500
+ * Never ship a server key to a browser. */
5236
5501
  tokenProvider: (defaults: {
5237
5502
  user_id: string;
5238
5503
  ttl_seconds?: number;
@@ -5808,6 +6073,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5808
6073
  model?: string;
5809
6074
  user_id?: string;
5810
6075
  input?: Record<string, unknown>;
6076
+ /** Drop chunks whose cosine `similarity` to the query is below this
6077
+ * (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
6078
+ min_similarity?: number;
5811
6079
  }) => Promise<RagAnswer>;
5812
6080
  /** Streamed grounded answer: citations + the channel handle up front, tokens
5813
6081
  * over the realtime channel. */
@@ -5822,13 +6090,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5822
6090
  model?: string;
5823
6091
  user_id?: string;
5824
6092
  input?: Record<string, unknown>;
6093
+ /** Drop chunks whose cosine `similarity` to the query is below this
6094
+ * (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
6095
+ min_similarity?: number;
5825
6096
  }) => Promise<RagStreamHandle>;
5826
6097
  /** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
5827
6098
  * would ground on, with rerank + metadata boosts applied — no generation,
5828
6099
  * no token spend. `boosts`/`rerank`/`min_score` override the rag config.
5829
6100
  * `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
5830
- * 0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
5831
- * relevance by each hit's `similarity` (cosine, -1..1) instead. */
6101
+ * 0.016–0.033 at the top): a floor above ~0.033 drops every hit. For a
6102
+ * relevance threshold use `min_similarity`, which floors each hit's cosine
6103
+ * `similarity` (-1..1; overrides config `retrieval.minSimilarity`; a hit
6104
+ * with no measured similarity, e.g. keyword mode, is kept). */
5832
6105
  search: (input: {
5833
6106
  query: string;
5834
6107
  collection?: string;
@@ -5838,6 +6111,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5838
6111
  rerank?: boolean;
5839
6112
  boosts?: Record<string, unknown>;
5840
6113
  min_score?: number;
6114
+ min_similarity?: number;
5841
6115
  }) => Promise<RagSearchResult>;
5842
6116
  /** Ingest into the backing vector-search collection (chunk → embed → index). */
5843
6117
  ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -5999,7 +6273,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5999
6273
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
6000
6274
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
6001
6275
  * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
6002
- * available balance can't cover `amount`.
6276
+ * available balance can't cover `amount`. Throws VxilError(409,
6277
+ * 'job_released') when `job_id` names a generation run that already ended
6278
+ * (cancelled or failed) before this hold landed: nothing is held.
6003
6279
  *
6004
6280
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
6005
6281
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
@@ -6062,6 +6338,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6062
6338
  created_at: string;
6063
6339
  }>;
6064
6340
  }>;
6341
+ /** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
6342
+ * reconciliation or a warehouse sync. Keyset-paged: pass the prior page's
6343
+ * `next_cursor` as `cursor` until it is null; start at `since` (inclusive
6344
+ * ISO-8601). To tail later, start a new walk with `since` = the last
6345
+ * `created_at` you stored MINUS an overlap (a minute) and dedupe on
6346
+ * `ledger_entry_id` — `created_at` is the writing transaction's start, so
6347
+ * a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
6348
+ * Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
6349
+ * (`end_user_required`) key gets 403 `server_only` (use `usage` for one
6350
+ * user's own rows). */
6351
+ ledger: (q?: {
6352
+ since?: string;
6353
+ cursor?: string;
6354
+ user_id?: string;
6355
+ credit_type?: string;
6356
+ limit?: number;
6357
+ }) => Promise<{
6358
+ entries: PaymentsLedgerEntry[];
6359
+ next_cursor: string | null;
6360
+ }>;
6065
6361
  /** Start a subscription (mock = instant checkout; real providers redirect via
6066
6362
  * their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
6067
6363
  * ref. Returns the vxil subscription_id + provider sub id + status. */
package/dist/index.js CHANGED
@@ -429,6 +429,11 @@ export class Vxil {
429
429
  return { data: parsed.data, meta: parsed.meta ?? { request_id: '' }, response: res };
430
430
  }
431
431
  users = {
432
+ /** Create or replace a tenant user by id. Upserting a deleted id brings it
433
+ * back; upserting an ERASED id re-creates it as a new, empty user
434
+ * (`erased_at` cleared — the erase already removed the old data). While
435
+ * the erased user's files are still being erased the call fails with 409
436
+ * `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
432
437
  upsert: async (user) => (await this.call('POST', '/v1/users', user)).data,
433
438
  bulk: async (users) => (await this.call('POST', '/v1/users/bulk', { users })).data.upserted,
434
439
  get: async (id, opts) => (await this.call('GET', `/v1/users/${encodeURIComponent(id)}${opts?.includeDeleted ? '?include_deleted=true' : ''}`)).data,
@@ -638,12 +643,24 @@ export class Vxil {
638
643
  ...(opts?.brief === false ? { brief: false } : {}),
639
644
  })).data,
640
645
  };
646
+ /** The project audit log. Needs `audit:read` (the narrow read-only scope —
647
+ * declare it on a function to read the log from its callback token) or
648
+ * `features:read`. Server-only: a public / thin-client key cannot read it. */
641
649
  audit = {
650
+ /**
651
+ * The audit trail, newest first. `subject` narrows to the events about ONE
652
+ * thing: a user id (`payload.user_id` / `payload.id`), a cms record
653
+ * (`payload.item_id` — the record's history), a verified end user
654
+ * (`payload.end_user_id` — what that person changed through a thin-client
655
+ * key or a function acting for them, and their payments events), or a
656
+ * principal (`actor`). Server keys only.
657
+ */
642
658
  list: async (q) => {
643
659
  const s = qs({
644
660
  since: q?.since || undefined,
645
661
  cursor: q?.cursor || undefined,
646
662
  limit: q?.limit || undefined,
663
+ subject: q?.subject || undefined,
647
664
  });
648
665
  return (await this.call('GET', `/v1/audit${s}`)).data.events;
649
666
  },
@@ -657,6 +674,7 @@ export class Vxil {
657
674
  until: q?.until || undefined,
658
675
  after_id: q?.after_id || undefined,
659
676
  limit: q?.limit || undefined,
677
+ subject: q?.subject || undefined,
660
678
  });
661
679
  const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/audit/export${s}`)}`, {
662
680
  method: 'GET',
@@ -864,7 +882,8 @@ export class Vxil {
864
882
  * terminal run answers `409 not_cancellable`. */
865
883
  cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
866
884
  /** Clone a terminal run into a fresh queued run. A generation run answers
867
- * `409 not_replayable` — submit the generation again instead. */
885
+ * `409 not_replayable` — submit the generation again instead; a redacted
886
+ * or erased run answers `409 run_redacted` (its payload is gone). */
868
887
  replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
869
888
  /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move the
870
889
  * credit-hold owner (`reserve_credits.user_id`) of every run of
@@ -878,6 +897,22 @@ export class Vxil {
878
897
  * files re-key it does not check that `into_user_id` exists.
879
898
  * Scope jobs:write. */
880
899
  reKey: async (input) => (await this.call('POST', '/v1/jobs/runs/re-key', input)).data,
900
+ /** SERVER-ONLY (403 server_only in end-user mode). Redact FINISHED runs
901
+ * that hold personal data: the payload becomes `{ erased: true }`, the
902
+ * result, progress, callback body and error text are cleared, a
903
+ * generation's provider request body/headers are dropped and its credit
904
+ * hold's user id is pseudonymized (unless its settle is still owed). The
905
+ * row itself stays (state, timings, job_name). The same fields a GDPR
906
+ * erase clears on the runs it can link to a user — use this for runs
907
+ * nothing links to one (a plain queue run, an async function call).
908
+ * `{ run_ids }` (≤500, one call; open runs are left alone and counted in
909
+ * `skipped_open`) or `{ user_id }` (the generation runs whose credit hold
910
+ * names that user — ONE page of ≤500 per call, call again until `done`).
911
+ * Idempotent. Audited as `jobs.runs.redacted` (counts only; none when a
912
+ * call redacted nothing). NOT cleared: concurrency_key, debounce_key,
913
+ * idempotency_key and target_url — keep user ids out of those (hash them).
914
+ * A redacted run does not replay. Scope jobs:write. */
915
+ redact: async (input) => (await this.call('POST', '/v1/jobs/runs/redact', input)).data,
881
916
  /**
882
917
  * Suspend the RUNNING run until an event (call from the executing
883
918
  * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -995,8 +1030,10 @@ export class Vxil {
995
1030
  /** On success the guest keeps its user id (`user_id` unchanged).
996
1031
  * If the claimed email ALREADY has an account, the guest is MERGED
997
1032
  * into it: `user_id` is the existing account, `merged: true`, and a
998
- * fresh `session.token` (same session, re-signed for the merged
999
- * identity — swap it client-side; other guest sessions are revoked).
1033
+ * fresh `session.token` (the same session carried over to the merged
1034
+ * identity under a new session id — swap it client-side: the old
1035
+ * guest token is revoked, the refresh token keeps working; other
1036
+ * guest sessions are revoked).
1000
1037
  * `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
1001
1038
  * files rows were already moved onto `user_id` when this returned, so
1002
1039
  * the merged user's next request finds them; false ⇒ the move ran
@@ -1182,15 +1219,33 @@ export class Vxil {
1182
1219
  },
1183
1220
  confirm: async (token) => (await this.call('POST', '/v1/auth/email/verify/confirm', { token })).data,
1184
1221
  },
1185
- /** Social sign-in. The web `start`/`callback` flows are browser redirects
1186
- * (not JSON calls): send the browser to
1187
- * `GET /v1/auth/oauth/{provider}/start?redirect_uri=…` (server-side, with
1188
- * your key) and hand the returned `code`+`state` to `…/callback`; `native`
1222
+ /** Social sign-in. The web flow: `startUrl` fetches the provider authorize
1223
+ * URL with your key (a browser cannot follow the header-carrying 302 of
1224
+ * `GET /v1/auth/oauth/{provider}/start` itself), you navigate the browser
1225
+ * there, and hand the returned `code`+`state` to `…/callback`; `native`
1189
1226
  * is the mobile / broker token-exchange the SDK wraps. `oidc` is the
1190
1227
  * tenant's generic OIDC / SSO issuer (auth config `providers.oidc` —
1191
1228
  * Okta / Entra / Auth0 / any OpenID Connect IdP, or a SAML broker that
1192
1229
  * speaks OIDC); it rides the same three routes. */
1193
1230
  oauth: {
1231
+ /** Start the web sign-in from a browser SPA: answers the provider
1232
+ * `authorize_url` (PKCE challenge, one-shot `state`, and for `oidc` a
1233
+ * nonce bound to the flow — all held server-side) for you to navigate
1234
+ * to: `location.assign((await vx.auth.oauth.startUrl('oidc',
1235
+ * { redirect_uri })).authorize_url)`. The provider returns to
1236
+ * `redirect_uri` with `?code&state`, which your page sends to
1237
+ * `GET /v1/auth/oauth/{provider}/callback` for the session. The same
1238
+ * rules as the redirect form apply: `redirect_uri` must match the auth
1239
+ * config `security.allowedRedirectOrigins` when set (else
1240
+ * `422 redirect_not_allowed`), and the state expires after
1241
+ * `expires_in` seconds (600). `anonymous_token` (a guest bearer)
1242
+ * promotes or merges that guest at the callback. */
1243
+ startUrl: async (provider, input) => {
1244
+ // plain encodeURIComponent (no URLSearchParams — React Native ≤ 0.79)
1245
+ const q = `redirect_uri=${encodeURIComponent(input.redirect_uri)}`
1246
+ + (input.anonymous_token ? `&anonymous_token=${encodeURIComponent(input.anonymous_token)}` : '');
1247
+ return (await this.call('GET', `/v1/auth/oauth/${encodeURIComponent(provider)}/start?${q}`, undefined, { accept: 'application/json' })).data;
1248
+ },
1194
1249
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
1195
1250
  * for a vxil session (`linked` marks whether the user was created or
1196
1251
  * matched to an existing identity). */
@@ -1201,6 +1256,9 @@ export class Vxil {
1201
1256
  * (`linked: 'merged'`, `user_id` = that account, `rekeyed` says whether
1202
1257
  * the guest's owner-scoped rows already moved — see
1203
1258
  * `anonymous.link.verify`). */
1259
+ /** `nonce`: the value your app put on the IdP authorize request. For
1260
+ * When sent, the id_token's `nonce` claim must equal it (401
1261
+ * `oauth_token_invalid` otherwise); omitted, it is not checked. */
1204
1262
  input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
1205
1263
  },
1206
1264
  };
@@ -1311,6 +1369,19 @@ export class Vxil {
1311
1369
  * (default) restores today's behaviour. Server keys are never affected.
1312
1370
  * Audited; takes effect on the next request. */
1313
1371
  setEndUserAccess: async (collection, access) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { end_user_access: access })).data,
1372
+ /** Set (or clear, with `[]` / `null`) the collection's END-USER WRITE
1373
+ * ROLES (guide ch. 9): a verified end user must hold one of `roles` (the
1374
+ * session's verified role claims — orgs roles) to write the collection,
1375
+ * otherwise every write door answers `403 role_required`. Reads are
1376
+ * unaffected; server keys are never affected. Audited; takes effect on
1377
+ * the next write. */
1378
+ setWriteRoles: async (collection, roles) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { write_roles: roles ?? [] })).data,
1379
+ /** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
1380
+ * ch. 4): the nightly platform sweep soft-deletes live items created more
1381
+ * than `days` ago — bounded per project per night, no restore, purged at
1382
+ * least 30 days later like any delete, one `cms.collection.retention_swept` audit event
1383
+ * per collection per sweep. Audited (`cms.collection.retain_days.set`). */
1384
+ setRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { retain_days: days })).data,
1314
1385
  /** Re-project the collection's index slots after an `index_slot` move
1315
1386
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
1316
1387
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -1379,6 +1450,16 @@ export class Vxil {
1379
1450
  /** `lock` serializes same-key writers (a per-key lock); `guard`
1380
1451
  * is the declarative capacity/overlap invariant (requires lock) — guide ch. 4. */
1381
1452
  create: async (collection, input) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input)).data,
1453
+ /** Upsert by a declared `unique` field (guide ch. 4): creates the item, or
1454
+ * — when a live item already holds `data[field]` — merges `patch` into
1455
+ * THAT item instead (one transaction; update hooks, guards, version bump
1456
+ * and a `cms.item.updated` audit, exactly like `patch`; null clears a
1457
+ * field). `created` tells which happened (201 vs 200). Concurrent upserts
1458
+ * of one key serialize, so they never create a duplicate. */
1459
+ upsert: async (collection, input) => {
1460
+ const r = await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input);
1461
+ return { ...r.data, created: r.response.status === 201 };
1462
+ },
1382
1463
  /** `expand` inlines relation/file fields into `data` (guide ch. 4): the
1383
1464
  * full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
1384
1465
  * the bare id on a cycle/depth cut, `null` for an invisible target. */
@@ -1388,7 +1469,9 @@ export class Vxil {
1388
1469
  },
1389
1470
  /**
1390
1471
  * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
1391
- * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
1472
+ * ($ne is NULL-safe: a row whose field is absent or null counts as not
1473
+ * equal; on a dotted join term the row still needs a readable target,
1474
+ * so a null or dangling relation is excluded) $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
1392
1475
  * fields) $arrayContains/$anyOf (json/relation array containment, indexed);
1393
1476
  * range/sort needs slot-indexed fields. This is the
1394
1477
  * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
@@ -1619,6 +1702,17 @@ export class Vxil {
1619
1702
  * `features:write`. (DELETE /v1/functions/:name)
1620
1703
  */
1621
1704
  delete: async (name, opts) => (await this.call('DELETE', `/v1/functions/${encodeURIComponent(name)}`, undefined, opts?.ifMatch !== undefined ? { 'if-match': String(opts.ifMatch) } : {})).data,
1705
+ /**
1706
+ * Log records of ONE function, one per invocation (outcome, wall/cpu ms,
1707
+ * console lines, exceptions), oldest first. Pass the returned `next_since`
1708
+ * back as `since` to read only newer records (a tail); without it, the most
1709
+ * recent records of the last 24 hours. Kept 14 days. Needs
1710
+ * `functions:read`. (GET /v1/functions/:name/logs)
1711
+ */
1712
+ logs: async (name, opts) => {
1713
+ const s = qs({ since: opts?.since || undefined });
1714
+ return (await this.call('GET', `/v1/functions/${encodeURIComponent(name)}/logs${s}`)).data;
1715
+ },
1622
1716
  };
1623
1717
  /** The MCP aggregation surface (the `mcp` feature). */
1624
1718
  mcp = {
@@ -1757,7 +1851,19 @@ export class Vxil {
1757
1851
  */
1758
1852
  test: async (subId) => (await this.call('POST', `/v1/webhooks/subscriptions/${encodeURIComponent(subId)}/test`)).data,
1759
1853
  sources: {
1760
- /** Register an inbound source; the receiver URL is returned ONCE. */
1854
+ /** Register an inbound source; the receiver URL is returned ONCE.
1855
+ *
1856
+ * Destination: `forward_url` (your endpoint) OR `target_function` (a
1857
+ * deployed function that declares a bare `trigger: { kind: 'webhook' }`
1858
+ * binding — it receives `payload.event === 'inbound_webhook.received'`
1859
+ * with the inbound envelope as `payload.data`), never both; neither =
1860
+ * store only (read with `events.list`).
1861
+ *
1862
+ * `provider: 'hmac'` is the parameterized preset for any provider that
1863
+ * signs an HMAC of the raw body (Shopify, Intercom, Linear, Zendesk, …):
1864
+ * `verify` says which header, sha256|sha1, hex|base64, an optional prefix
1865
+ * and an optional timestamp header + tolerance. Like stripe/paddle/slack it
1866
+ * fails closed (401) until the source's signing secret is set. */
1761
1867
  create: async (input) => (await this.call('POST', '/v1/webhooks/sources', input)).data,
1762
1868
  list: async () => (await this.call('GET', '/v1/webhooks/sources')).data.sources,
1763
1869
  delete: async (sourceId) => {
@@ -1768,11 +1874,21 @@ export class Vxil {
1768
1874
  test: async (sourceId) => (await this.call('POST', `/v1/webhooks/sources/${encodeURIComponent(sourceId)}/test`)).data,
1769
1875
  },
1770
1876
  events: {
1877
+ /** Received events. Newest first, paged with `cursor`; or — with `after`
1878
+ * (your watermark, an event id) — OLDEST first from just after it, the
1879
+ * drain shape: store `next_after` and pass it back, `has_more` says
1880
+ * another page waits. The `after` drain answers only events received
1881
+ * at least 10 s ago (ids are not strictly arrival-ordered, so a fresher
1882
+ * event could otherwise commit below a stored watermark and be
1883
+ * skipped); `cursor` and `event_id` reads are not lagged. `event_id`
1884
+ * reads exactly one event. `cursor` and `after` are exclusive. */
1771
1885
  list: async (q) => {
1772
1886
  const s = qs({
1773
1887
  source_id: q?.source_id || undefined,
1774
1888
  status: q?.status || undefined,
1775
1889
  cursor: q?.cursor || undefined,
1890
+ after: q?.after || undefined,
1891
+ event_id: q?.event_id || undefined,
1776
1892
  limit: q?.limit || undefined,
1777
1893
  });
1778
1894
  return (await this.call('GET', `/v1/webhooks/events${s}`)).data;
@@ -1875,8 +1991,14 @@ export class Vxil {
1875
1991
  * matching its TokenProvider type *structurally* (no import — a static
1876
1992
  * import would break the single-file served sdk.mjs) that re-mints via
1877
1993
  * POST /v1/realtime/tokens with `defaults` merged over the channel the
1878
- * client asks for. Server-side (Node) use only — it needs the API key;
1879
- * browsers must fetch tokens from YOUR backend instead. */
1994
+ * client asks for. Two safe ways to use it:
1995
+ * - on a server, with a server key (`user_id` names the subject); or
1996
+ * - in a browser / mobile app, with a PUBLIC `end_user_required` key and
1997
+ * the signed-in user's session (`endUserToken` on the client): the mint
1998
+ * runs in end-user mode and the token's subject is FORCED to the
1999
+ * verified user (any `user_id` you pass is overridden), so no
2000
+ * backend of your own is needed.
2001
+ * Never ship a server key to a browser. */
1880
2002
  tokenProvider: (defaults) => (ctx) => this.realtime.mintToken({ channel: ctx.channel, ...defaults }),
1881
2003
  /** One-shot: mint a token AND open the WebSocket. Uses the global
1882
2004
  * `WebSocket` (browser / Node ≥22). On older Node, pass a constructor —
@@ -2170,8 +2292,10 @@ export class Vxil {
2170
2292
  * would ground on, with rerank + metadata boosts applied — no generation,
2171
2293
  * no token spend. `boosts`/`rerank`/`min_score` override the rag config.
2172
2294
  * `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
2173
- * 0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
2174
- * relevance by each hit's `similarity` (cosine, -1..1) instead. */
2295
+ * 0.016–0.033 at the top): a floor above ~0.033 drops every hit. For a
2296
+ * relevance threshold use `min_similarity`, which floors each hit's cosine
2297
+ * `similarity` (-1..1; overrides config `retrieval.minSimilarity`; a hit
2298
+ * with no measured similarity, e.g. keyword mode, is kept). */
2175
2299
  search: async (input) => (await this.call('POST', '/v1/rag/search', input)).data,
2176
2300
  /** Ingest into the backing vector-search collection (chunk → embed → index). */
2177
2301
  ingest: async (collection, input) => (await this.call('POST', `/v1/rag/ingest/${encodeURIComponent(collection)}`, input)).data,
@@ -2309,7 +2433,9 @@ export class Vxil {
2309
2433
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
2310
2434
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
2311
2435
  * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
2312
- * available balance can't cover `amount`.
2436
+ * available balance can't cover `amount`. Throws VxilError(409,
2437
+ * 'job_released') when `job_id` names a generation run that already ended
2438
+ * (cancelled or failed) before this hold landed: nothing is held.
2313
2439
  *
2314
2440
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
2315
2441
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
@@ -2334,6 +2460,26 @@ export class Vxil {
2334
2460
  });
2335
2461
  return (await this.call('GET', `/v1/payments/usage${s}`)).data;
2336
2462
  },
2463
+ /** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
2464
+ * reconciliation or a warehouse sync. Keyset-paged: pass the prior page's
2465
+ * `next_cursor` as `cursor` until it is null; start at `since` (inclusive
2466
+ * ISO-8601). To tail later, start a new walk with `since` = the last
2467
+ * `created_at` you stored MINUS an overlap (a minute) and dedupe on
2468
+ * `ledger_entry_id` — `created_at` is the writing transaction's start, so
2469
+ * a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
2470
+ * Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
2471
+ * (`end_user_required`) key gets 403 `server_only` (use `usage` for one
2472
+ * user's own rows). */
2473
+ ledger: async (q) => {
2474
+ const suffix = qs({
2475
+ since: q?.since || undefined,
2476
+ cursor: q?.cursor || undefined,
2477
+ user_id: q?.user_id || undefined,
2478
+ credit_type: q?.credit_type || undefined,
2479
+ limit: q?.limit || undefined,
2480
+ });
2481
+ return (await this.call('GET', `/v1/payments/credits/ledger${suffix}`)).data;
2482
+ },
2337
2483
  /** Start a subscription (mock = instant checkout; real providers redirect via
2338
2484
  * their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
2339
2485
  * ref. Returns the vxil subscription_id + provider sub id + status. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.18.0",
3
+ "version": "0.20.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",