@vxil/sdk 0.22.0 → 0.24.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.
package/dist/index.d.ts CHANGED
@@ -393,6 +393,10 @@ export interface UsageCurrent {
393
393
  functions: {
394
394
  invocations_today: number | null;
395
395
  limit_per_day: number;
396
+ /** CPU-ms charged to the daily budget today; null without a fresh snapshot */
397
+ cpu_ms_today: number | null;
398
+ /** the enforced daily CPU-ms budget (Free staging/development projects); null = none */
399
+ cpu_ms_limit_per_day: number | null;
396
400
  as_of: string | null;
397
401
  } | null;
398
402
  }
@@ -423,6 +427,10 @@ export interface JobRun {
423
427
  * list (`vx.jobs.runs`) and the single-run read. */
424
428
  generation_status?: string | null;
425
429
  generation_json?: Record<string, unknown> | null;
430
+ /** generation runs only: the provider's job id, read from its accepted
431
+ * START answer at `completion.ref_path` (e.g. fal's `request_id`); null
432
+ * without the option or before the provider answered. List + single read. */
433
+ provider_ref?: string | null;
426
434
  /** the single-run read (`vx.jobs.run` / `waitForRun`) only: your enqueue
427
435
  * payload — `{ redacted: true }` for a platform-internal run; never on lists */
428
436
  payload_json?: unknown;
@@ -531,6 +539,23 @@ export interface JobRunsQuery {
531
539
  until?: string;
532
540
  limit?: number;
533
541
  }
542
+ /** A row of `vx.orgs.list` / `listPage` (GET /v1/orgs). */
543
+ export interface OrgListRow {
544
+ org_id: string;
545
+ slug: string;
546
+ name: string;
547
+ created_at?: string;
548
+ /** members of the org, every role */
549
+ member_count: number;
550
+ /** the user's role, present when listed with `user_id` */
551
+ role?: string;
552
+ }
553
+ /** One page of `vx.orgs.listPage`. */
554
+ export interface OrgsListPage {
555
+ orgs: OrgListRow[];
556
+ /** pass back as `cursor` for the next older page; null on the last page */
557
+ next_cursor: string | null;
558
+ }
534
559
  /** One page of `vx.jobs.runsPage`. */
535
560
  export interface JobRunsPage {
536
561
  runs: JobRun[];
@@ -943,7 +968,14 @@ export interface PaymentsLedgerEntry {
943
968
  /** the Idempotency-Key the consume / grant was sent with */
944
969
  idempotency_key: string | null;
945
970
  created_at: string;
946
- }
971
+ /** (2026-10-11) non-null on a job hold's rows (its consume and its release
972
+ * reversal): they moved `held`, not the balance — `held` while the job
973
+ * runs, `settled` once it settled (the charge is the `settle` row),
974
+ * `released` once given back. null on every row that moved the balance. */
975
+ hold: PaymentsLedgerHold | null;
976
+ }
977
+ /** Where a job hold's ledger row stands (`PaymentsLedgerEntry.hold`). */
978
+ export type PaymentsLedgerHold = 'held' | 'settled' | 'released';
947
979
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
948
980
  export interface PaymentsRefund {
949
981
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -1386,6 +1418,10 @@ export interface JobGenerationSettledEventPayload {
1386
1418
  /** the provider hint alone (`Upstream said: gemini 400: …`); null on
1387
1419
  * `completed` and whenever the failure carried none */
1388
1420
  error_hint: string | null;
1421
+ /** the provider's job id (`completion.ref_path` of the START answer);
1422
+ * null without the option or when the provider never accepted the run;
1423
+ * absent on events written before 2026-10-11 */
1424
+ provider_ref?: string | null;
1389
1425
  /** the failure-event vocabulary every `*.failed` carries (guide 12):
1390
1426
  * `completed` → info; `failed` → error, except a refusal at admission
1391
1427
  * (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
@@ -1435,7 +1471,8 @@ export interface JobBatchCompletedEventPayload {
1435
1471
  export type PaymentsEventEnvironment = 'production' | 'sandbox';
1436
1472
  /** Which credits a debit spends: ONE `credit_type`, or an ORDERED
1437
1473
  * `credit_types` (1–8 distinct) — the whole amount from the FIRST type whose
1438
- * available balance covers it, never split across types (2026-10-01 W9). */
1474
+ * available balance covers it, never split across types by default (unless
1475
+ * `allow_split: true` — 2026-10-11) (2026-10-01 W9). */
1439
1476
  export type PaymentsCreditTypeChoice = {
1440
1477
  credit_type: string;
1441
1478
  credit_types?: never;
@@ -1448,8 +1485,35 @@ export interface PaymentsConsumeResult {
1448
1485
  balance_after: number;
1449
1486
  ledger_entry_id: string | null;
1450
1487
  reversed: boolean;
1451
- /** the credit type the debit came from (the chosen one for an ordered consume) */
1488
+ /** the credit type the debit came from (the chosen one for an ordered
1489
+ * consume; the first part's for a split) */
1452
1490
  credit_type: string;
1491
+ /** (2026-10-11) only on a SPLIT (`allow_split: true` and no single type
1492
+ * covered the amount): one entry per type drawn, in list order — the first
1493
+ * is the row `ledger_entry_id` / `balance_after` / `credit_type` describe */
1494
+ parts?: Array<{
1495
+ credit_type: string;
1496
+ amount: number;
1497
+ ledger_entry_id: string;
1498
+ balance_after: number;
1499
+ }>;
1500
+ }
1501
+ /** `POST /v1/payments/credits/reverse` → `data` (2026-10-11). */
1502
+ export interface PaymentsReverseResult {
1503
+ user_id: string;
1504
+ /** the credits put back, summed over `entries` */
1505
+ amount: number;
1506
+ /** true when every consume was already reversed (a repeat): nothing moved */
1507
+ already_reversed: boolean;
1508
+ entries: Array<{
1509
+ /** the consume reversed */
1510
+ ledger_entry_id: string;
1511
+ /** the `reversal` ledger row */
1512
+ reversal_entry_id: string;
1513
+ credit_type: string;
1514
+ amount: number;
1515
+ balance_after: number | null;
1516
+ }>;
1453
1517
  }
1454
1518
  /** `payments.charge.succeeded` (a new charge row) / `payments.charge.completed`
1455
1519
  * (a recorded charge reached the provider's completed state — Paddle's
@@ -1622,6 +1686,22 @@ export interface PaymentsGrantFailedEventPayload {
1622
1686
  level: 'error';
1623
1687
  state: 'broken';
1624
1688
  }
1689
+ /** `payments.credits.reversed` (2026-10-11) — one committed consume was
1690
+ * reversed through `POST /v1/payments/credits/reverse` (one event per
1691
+ * consume; a repeated call emits nothing). */
1692
+ export interface PaymentsCreditsReversedEventPayload {
1693
+ end_user_id: string;
1694
+ credit_type: string;
1695
+ /** the credits put back (what the consume charged) */
1696
+ amount: number;
1697
+ /** the consume that was reversed */
1698
+ ledger_entry_id: string;
1699
+ /** the `reversal` ledger row */
1700
+ reversal_entry_id: string;
1701
+ /** the job the consume was held for, else null */
1702
+ job_id: string | null;
1703
+ reason: string | null;
1704
+ }
1625
1705
  /** `payments.webhook.rejected` — a signature / parse failure was persisted. */
1626
1706
  export interface PaymentsWebhookRejectedEventPayload {
1627
1707
  event_id: string;
@@ -1722,6 +1802,7 @@ export interface VxilEventPayloads {
1722
1802
  'payments.entitlement.changed': PaymentsEntitlementChangedEventPayload;
1723
1803
  'payments.entitlement.revoke.failed': PaymentsEntitlementRevokeFailedEventPayload;
1724
1804
  'payments.grant.failed': PaymentsGrantFailedEventPayload;
1805
+ 'payments.credits.reversed': PaymentsCreditsReversedEventPayload;
1725
1806
  'payments.webhook.rejected': PaymentsWebhookRejectedEventPayload;
1726
1807
  'payments.webhook_event.failed': PaymentsWebhookEventFailedEventPayload;
1727
1808
  'payments.webhook_event.reprocessed': PaymentsWebhookEventReprocessedEventPayload;
@@ -1767,8 +1848,14 @@ export interface FunctionEnvelopeBase {
1767
1848
  vxil_base: string;
1768
1849
  scoped_jwts: FunctionScopedJwts;
1769
1850
  /** Your declared per-function secrets (`secrets: ['<name>']`), keyed by
1770
- * bare name and resolved at invoke time. */
1851
+ * bare name and resolved at invoke time. An optional one (`'<name>?'`)
1852
+ * that has no stored value is absent. */
1771
1853
  secrets: Record<string, string>;
1854
+ /** Your function's declared plain settings (`vars: { NAME: 'value' }`),
1855
+ * `{}` when it declares none. Plain text, never secret. Always present on
1856
+ * an envelope from the platform; optional in the type only so envelope
1857
+ * fixtures written against SDK 0.23 still compile. */
1858
+ vars?: Record<string, string>;
1772
1859
  }
1773
1860
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
1774
1861
  * the item by `item_id`. */
@@ -1839,12 +1926,35 @@ export interface InboundWebhookTriggerData {
1839
1926
  /** true on a `POST /v1/webhooks/events/:id/replay` */
1840
1927
  replayed?: true;
1841
1928
  }
1929
+ /** Who called an `http` function (2026-10-11). Absent when there is nothing
1930
+ * to carry, and always on an async invoke. */
1931
+ export interface FunctionClient {
1932
+ /** The caller's IP address, set by vxil from the network connection — never
1933
+ * from anything the caller sent. Present when the call came straight to
1934
+ * the API with a project key; absent when another function or a platform
1935
+ * hop made it. Key per-address limits on an IPv6 address's /64, and expect
1936
+ * many users behind one IPv4 address on mobile networks. */
1937
+ ip?: string;
1938
+ /** ISO 3166-1 alpha-2 country of `ip`, when known */
1939
+ country?: string;
1940
+ /** The request headers named in the http trigger's `forwardHeaders` that the
1941
+ * call carried (lower-case names, values ≤ 256 bytes). The caller wrote
1942
+ * them: never trust one for authorization. */
1943
+ headers?: Record<string, string>;
1944
+ }
1842
1945
  /** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
1843
1946
  * parameters on a GET). */
1844
1947
  export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
1845
1948
  trigger: 'http';
1846
1949
  /** present only when the caller presented a verified end-user session */
1847
1950
  end_user?: FunctionEndUser;
1951
+ /** the caller's address and forwarded headers (see FunctionClient) */
1952
+ client?: FunctionClient;
1953
+ /** Tenant-only tokens for the http trigger's `serverScopes` (each one of the
1954
+ * function's own scopes), present only when the trigger declares them. Not
1955
+ * bound to the end user: use them for rows the user must not write, and
1956
+ * take the owner from `end_user.id`, never from the payload. */
1957
+ server_jwts?: FunctionScopedJwts;
1848
1958
  payload: P;
1849
1959
  }
1850
1960
  export interface CmsHookFunctionEnvelope extends FunctionEnvelopeBase {
@@ -2405,8 +2515,12 @@ export interface DeployedFunction {
2405
2515
  endpoint: string;
2406
2516
  scopes: string[];
2407
2517
  egressAllow: string[];
2408
- /** secret REFS only (`secret:<name>`) — never values */
2518
+ /** secret REFS only (`secret:<name>`, `secret:<name>?` = optional) — never values */
2409
2519
  secrets: string[];
2520
+ /** the plain settings delivered on the envelope as `vars` ({} when none).
2521
+ * Present only for a server key holding `features:read` or `features:write`; absent for other
2522
+ * keys and end-user (thin-client) requests */
2523
+ vars?: Record<string, string>;
2410
2524
  enabled: boolean;
2411
2525
  trigger: string;
2412
2526
  bindings: Array<{
@@ -2747,9 +2861,18 @@ export type CmsBatchOp = {
2747
2861
  id: string;
2748
2862
  if_version?: number;
2749
2863
  ref?: string;
2750
- };
2864
+ } | ({
2865
+ op: 'aggregate';
2866
+ collection: string;
2867
+ ref?: string;
2868
+ } & CmsAggregateBody) | ({
2869
+ op: 'rank';
2870
+ collection: string;
2871
+ ref?: string;
2872
+ } & CmsRankBody);
2751
2873
  /** What a 2xx batch result's `data` is, per op: the item record (get / create /
2752
- * patch), a page or `{ count }` (query), the delete tally (delete). */
2874
+ * patch), a page or `{ count }` (query), the delete tally (delete), the
2875
+ * aggregate / rank route's answer. */
2753
2876
  export type CmsBatchData<O extends CmsBatchOp> = O extends {
2754
2877
  op: 'query';
2755
2878
  } ? (O extends {
@@ -2766,6 +2889,25 @@ export type CmsBatchData<O extends CmsBatchOp> = O extends {
2766
2889
  deleted: boolean;
2767
2890
  cascaded: number;
2768
2891
  set_null: number;
2892
+ } : O extends {
2893
+ op: 'aggregate';
2894
+ } ? {
2895
+ groups: Array<Record<string, unknown> & {
2896
+ key?: Record<string, unknown>;
2897
+ }>;
2898
+ scanned: number;
2899
+ truncated: boolean;
2900
+ limit: number;
2901
+ } : O extends {
2902
+ op: 'rank';
2903
+ } ? {
2904
+ entries: Array<{
2905
+ key: Record<string, unknown>;
2906
+ partition?: Record<string, unknown>;
2907
+ metric: unknown;
2908
+ rank: number;
2909
+ }>;
2910
+ scanned: number;
2769
2911
  } : Record<string, unknown>;
2770
2912
  /** One batch result: the single route's `status` and its `data` (2xx) or
2771
2913
  * `error`. In an aborted atomic batch the undone ops carry `424 rolled_back`
@@ -2774,7 +2916,7 @@ export type CmsBatchData<O extends CmsBatchOp> = O extends {
2774
2916
  * `424 not_run`); non-atomic, an op that failed unexpectedly is
2775
2917
  * `500 internal_error` in-line — the ops before it committed and keep their
2776
2918
  * results, so never retry the whole batch on one 500. At most 5 ops may be
2777
- * `query` (a whole-batch 422 otherwise). */
2919
+ * `query` / `aggregate` / `rank` (a whole-batch 422 otherwise). */
2778
2920
  export type CmsBatchResult<O extends CmsBatchOp = CmsBatchOp> = {
2779
2921
  op: O['op'];
2780
2922
  ref?: string;
@@ -3594,6 +3736,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3594
3736
  * provider words to completed | failed | processing (`{ OK: 'completed',
3595
3737
  * ERROR: 'failed' }`); `completion.result_path` names the value the run
3596
3738
  * settles with — the status mirror receives it as `result`.
3739
+ * `completion.ref_path` keeps the provider's job id from its START answer
3740
+ * (`provider_ref` on run reads and on job.generation.completed|failed);
3741
+ * with `provider.cancel` that job is cancelled at the provider when the
3742
+ * run is cancelled or expires. `completion.error_path` keeps a failed
3743
+ * answer's detail (`error_detail`). The 202 answers `expires_at`.
3597
3744
  *
3598
3745
  * A mirror write the record refuses never fails the run: a body refusal
3599
3746
  * (e.g. a callback key the collection does not declare) is retried with
@@ -3614,6 +3761,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3614
3761
  method?: string;
3615
3762
  headers?: Record<string, string>;
3616
3763
  body?: Record<string, unknown>;
3764
+ /** the provider's own cancel call, made ONCE (best-effort, no retry)
3765
+ * when the run is cancelled or expires after the provider accepted
3766
+ * it; `{provider_ref}` in the url is replaced by the job id
3767
+ * `completion.ref_path` read (required with it). Method default POST. */
3768
+ cancel?: {
3769
+ url: string;
3770
+ method?: string;
3771
+ headers?: Record<string, string>;
3772
+ };
3617
3773
  };
3618
3774
  completion: {
3619
3775
  mode: "poll" | "webhook";
@@ -3632,6 +3788,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3632
3788
  status_map?: Record<string, "completed" | "failed" | "processing">;
3633
3789
  /** dotted path of the value a completed run settles with (mirrored as `result`) */
3634
3790
  result_path?: string;
3791
+ /** dotted path of the provider's job id in its START answer (e.g.
3792
+ * `request_id`) — kept as the run's `provider_ref` */
3793
+ ref_path?: string;
3794
+ /** dotted path of the failure detail in a failed answer (e.g.
3795
+ * `payload.detail`) — kept on the run (≤ 1000 chars of JSON text)
3796
+ * and mirrored as `error_detail` (declare that field) */
3797
+ error_path?: string;
3635
3798
  };
3636
3799
  /** `progress_fields`: the progress keys (`progress` / `stage` /
3637
3800
  * `message`) a webhook-mode `processing` callback also writes onto the
@@ -3673,6 +3836,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3673
3836
  amount: number;
3674
3837
  user_id: string;
3675
3838
  reason?: string;
3839
+ /** with `credit_types` only (2026-10-11): hold across the types in
3840
+ * order when no single one covers `amount` (default: 402) */
3841
+ allow_split?: boolean;
3676
3842
  /** payments unreachable when the hold is placed (a 5xx other than
3677
3843
  * 501, a 429, no answer within 5 s; payments switched off is NOT
3678
3844
  * unreachable — that run starts without a hold): `'fail'` (default)
@@ -3697,6 +3863,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3697
3863
  generation_status: string;
3698
3864
  state?: string;
3699
3865
  deduplicated?: boolean;
3866
+ expires_at: string | null;
3700
3867
  }>;
3701
3868
  /** The newest runs (≤ `limit`, default 50, max 100). Filters: job_name,
3702
3869
  * state, batch_id, ids, since/until (creation time, ISO). For more than
@@ -4264,6 +4431,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4264
4431
  /** sessions taken over by auth config session.maxConcurrent (present once opted in) */
4265
4432
  took_over?: string[];
4266
4433
  }>;
4434
+ /** Attach another sign-in method to the SIGNED-IN user: verifies the
4435
+ * provider token like `native`, then links its stable (provider, sub)
4436
+ * to the user behind `session_token` — no new user, no new session
4437
+ * (keep the one you hold). Use it when an address would not match, e.g.
4438
+ * an Apple "Hide My Email" relay address on an OTP account. Idempotent
4439
+ * for an identity this user already holds; 409 `oauth_identity_linked`
4440
+ * when another user holds it; 401 `invalid_session` / 409
4441
+ * `anonymous_user` for an unknown or guest session. */
4442
+ link: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4443
+ session_token: string;
4444
+ id_token?: string;
4445
+ access_token?: string;
4446
+ nonce?: string;
4447
+ }) => Promise<{
4448
+ user_id: string;
4449
+ linked: "linked";
4450
+ }>;
4267
4451
  };
4268
4452
  };
4269
4453
  readonly rateLimits: {
@@ -4701,7 +4885,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4701
4885
  * action's deployed function with `{ collection, item_id, action, actor,
4702
4886
  * item }` and returns its result. 404 when the key is not declared;
4703
4887
  * 502 `action_failed` (with `upstream.code` = the function's error
4704
- * class) when the function fails. Requires cms:write. */
4888
+ * class) when the function fails. Requires cms:write, or — server keys
4889
+ * only (no end user) — cms:read + functions:invoke (a read-only staff
4890
+ * key; the function writes under its own scopes). End-user callers
4891
+ * still need cms:write. */
4705
4892
  runAction: (collection: string, itemId: string, key: string) => Promise<{
4706
4893
  collection: string;
4707
4894
  item_id: string;
@@ -4778,7 +4965,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4778
4965
  * earlier writes and the first non-2xx op rolls every write back (the
4779
4966
  * undone ops answer `424 rolled_back`, the rest `424 not_run`). Default:
4780
4967
  * sequential, per-op status, no cross-op rollback. `ref` tags an op so
4781
- * its result is easy to find. */
4968
+ * its result is easy to find. In an atomic batch a later op's `id`, or a
4969
+ * top-level `data` value, may be `'$ref:<tag>.item_id'` — the item id an
4970
+ * earlier op tagged `<tag>` created or read (a 422 `ref_unresolved` in
4971
+ * that op's result, rolling the batch back, when that result has none). */
4782
4972
  batch: <T extends readonly CmsBatchOp[]>(ops: readonly [...T], opts?: {
4783
4973
  atomic?: boolean;
4784
4974
  }) => Promise<CmsBatchResponse<T>>;
@@ -5459,14 +5649,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5459
5649
  slug: string;
5460
5650
  name: string;
5461
5651
  }>;
5652
+ /** One page of orgs, newest first, each with `member_count` (and the
5653
+ * user's `role` when `user_id` is given), plus `next_cursor` (null on the
5654
+ * last page): pass it back as `cursor`. `limit` 1..500; omitted with no
5655
+ * `cursor` it is the tenant's org cap (one answer), with a cursor 100. */
5656
+ listPage: (q?: {
5657
+ user_id?: string | undefined;
5658
+ limit?: number | undefined;
5659
+ cursor?: string | null | undefined;
5660
+ }) => Promise<OrgsListPage>;
5661
+ /** Every org (walks `listPage` at 500 a page), each with `member_count`. */
5462
5662
  list: (q?: {
5463
5663
  user_id?: string;
5464
- }) => Promise<Array<{
5465
- org_id: string;
5466
- slug: string;
5467
- name: string;
5468
- role?: string;
5469
- }>>;
5664
+ }) => Promise<OrgListRow[]>;
5470
5665
  delete: (orgId: string) => Promise<void>;
5471
5666
  /** RBAC: org:read (viewer+), org:write (member+), members:manage (admin+),
5472
5667
  * org:admin (owner) — plus any custom-role permission-set. Pass
@@ -5735,7 +5930,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5735
5930
  usage: () => Promise<FilesUsage>;
5736
5931
  /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
5737
5932
  * object to vxil's public asset host: a stable, content-addressed URL
5738
- * (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
5933
+ * (`https://cdn.vxilcdn.com/<tenant>/<sha256>.<ext>`) served from a global
5739
5934
  * edge cache with `Cache-Control: public, max-age=31536000, immutable`,
5740
5935
  * playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
5741
5936
  * `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
@@ -6121,6 +6316,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6121
6316
  * the row, echoed on the answer and the replay read, and (job mode)
6122
6317
  * carried on the `job.generation.*` events with `generation_id`. */
6123
6318
  correlation_id?: string;
6319
+ /** SERVER mode only (an end-user caller gets 422
6320
+ * `status_mirror_server_only`); the key also needs `jobs:write` +
6321
+ * `cms:write` (or `admin`), else 403 `insufficient_scope`. The run mirrors its status word
6322
+ * (`pending` → `processing` → `completed` | `failed`) into `column`
6323
+ * (default `generation_status`) of a tenant record, and on completion
6324
+ * writes the answer to its `result` field — the parsed object for a
6325
+ * `response_schema` run (null if it failed the schema or is over 64 KiB),
6326
+ * the text otherwise (cut at 16,384 characters). Same rules as the jobs
6327
+ * `status_mirror` (`fence_field` is cms only); a refused mirror is 422
6328
+ * `status_mirror_invalid` and nothing starts. The collection must
6329
+ * declare `column` (string) and a nullable `result` field (JSON for a
6330
+ * `response_schema` run, text otherwise), or the completed write fails
6331
+ * and the record stays at `processing`. */
6332
+ status_mirror?: {
6333
+ feature: "cms";
6334
+ collection: string;
6335
+ record_id: string;
6336
+ column?: string;
6337
+ fence_field?: string;
6338
+ };
6124
6339
  }, opts?: {
6125
6340
  idempotencyKey?: string;
6126
6341
  }) => Promise<AiJobHandle>;
@@ -6431,8 +6646,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6431
6646
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
6432
6647
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
6433
6648
  * amount comes from the FIRST type whose available balance covers it (one
6434
- * ledger row, never split across types) and the answer's `credit_type` names
6649
+ * ledger row, never split across types by default — unless `allow_split: true`,
6650
+ * below) and the answer's `credit_type` names
6435
6651
  * it. A retry with the same key answers the same type.
6652
+ *
6653
+ * Split (2026-10-11): with `credit_types`, `allow_split: true` lets an
6654
+ * amount no single type covers draw across the types in list order (58
6655
+ * `expiring` + 2 `permanent` for 60) — one ledger row per type drawn,
6656
+ * listed in the answer's `parts`; a job hold of a split settles and
6657
+ * releases every part.
6436
6658
  */
6437
6659
  consume: (input: PaymentsCreditTypeChoice & {
6438
6660
  user_id: string;
@@ -6440,9 +6662,32 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6440
6662
  /** link this debit to a jobs run_id → provisional hold + auto-reverse. */
6441
6663
  job_id?: string;
6442
6664
  reason?: string;
6665
+ /** with `credit_types` only: draw across the types when no single
6666
+ * one covers the amount (default false: 402 instead) */
6667
+ allow_split?: boolean;
6443
6668
  }, opts: {
6444
6669
  idempotencyKey: string;
6445
6670
  }) => Promise<PaymentsConsumeResult>;
6671
+ /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
6672
+ * charge whose result you could not deliver. Name the consume's
6673
+ * `ledger_entry_id` (any part of a split consume reverses every part),
6674
+ * or the `job_id` (run_id) of a job hold that settled (every part of a
6675
+ * split). Puts back what was CHARGED (a pro-rated
6676
+ * settle's actual) as one `reversal` ledger row per consume — at most
6677
+ * once: a repeat answers `already_reversed: true` and moves nothing.
6678
+ * Throws VxilError 409 `not_committed` while the hold is still held (its
6679
+ * job settles or releases it), 409 `nothing_charged` for a released hold
6680
+ * or a recorded 402, 404 for no such consume. Needs payments:write;
6681
+ * SERVER-SIDE KEYS ONLY (403 `server_only` on a thin-client key). */
6682
+ reverse: (input: {
6683
+ ledger_entry_id: string;
6684
+ job_id?: never;
6685
+ reason?: string;
6686
+ } | {
6687
+ job_id: string;
6688
+ ledger_entry_id?: never;
6689
+ reason?: string;
6690
+ }) => Promise<PaymentsReverseResult>;
6446
6691
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
6447
6692
  * only ADDS; `amount` must be ≥ 1. */
6448
6693
  grant: (input: {
@@ -6486,7 +6731,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6486
6731
  balance_after: number | null;
6487
6732
  source: string | null;
6488
6733
  job_id: string | null;
6734
+ /** On a settle / reversal: the consume it corrects. */
6735
+ reverses_entry_id: string | null;
6489
6736
  created_at: string;
6737
+ /** (2026-10-11) a job hold's row (moved `held`, not the balance):
6738
+ * held / settled / released; null when the row moved the balance. */
6739
+ hold: PaymentsLedgerHold | null;
6490
6740
  }>;
6491
6741
  }>;
6492
6742
  /** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
package/dist/index.js CHANGED
@@ -823,6 +823,11 @@ export class Vxil {
823
823
  * provider words to completed | failed | processing (`{ OK: 'completed',
824
824
  * ERROR: 'failed' }`); `completion.result_path` names the value the run
825
825
  * settles with — the status mirror receives it as `result`.
826
+ * `completion.ref_path` keeps the provider's job id from its START answer
827
+ * (`provider_ref` on run reads and on job.generation.completed|failed);
828
+ * with `provider.cancel` that job is cancelled at the provider when the
829
+ * run is cancelled or expires. `completion.error_path` keeps a failed
830
+ * answer's detail (`error_detail`). The 202 answers `expires_at`.
826
831
  *
827
832
  * A mirror write the record refuses never fails the run: a body refusal
828
833
  * (e.g. a callback key the collection does not declare) is retried with
@@ -1268,6 +1273,15 @@ export class Vxil {
1268
1273
  * When sent, the id_token's `nonce` claim must equal it (401
1269
1274
  * `oauth_token_invalid` otherwise); omitted, it is not checked. */
1270
1275
  input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
1276
+ /** Attach another sign-in method to the SIGNED-IN user: verifies the
1277
+ * provider token like `native`, then links its stable (provider, sub)
1278
+ * to the user behind `session_token` — no new user, no new session
1279
+ * (keep the one you hold). Use it when an address would not match, e.g.
1280
+ * an Apple "Hide My Email" relay address on an OTP account. Idempotent
1281
+ * for an identity this user already holds; 409 `oauth_identity_linked`
1282
+ * when another user holds it; 401 `invalid_session` / 409
1283
+ * `anonymous_user` for an unknown or guest session. */
1284
+ link: async (provider, input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, { ...input, link: true })).data,
1271
1285
  },
1272
1286
  };
1273
1287
  rateLimits = {
@@ -1562,7 +1576,10 @@ export class Vxil {
1562
1576
  * action's deployed function with `{ collection, item_id, action, actor,
1563
1577
  * item }` and returns its result. 404 when the key is not declared;
1564
1578
  * 502 `action_failed` (with `upstream.code` = the function's error
1565
- * class) when the function fails. Requires cms:write. */
1579
+ * class) when the function fails. Requires cms:write, or — server keys
1580
+ * only (no end user) — cms:read + functions:invoke (a read-only staff
1581
+ * key; the function writes under its own scopes). End-user callers
1582
+ * still need cms:write. */
1566
1583
  runAction: async (collection, itemId, key) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/actions/${encodeURIComponent(key)}`)).data,
1567
1584
  /** Bounded group-by aggregate. fns count|sum|
1568
1585
  * min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
@@ -1600,7 +1617,10 @@ export class Vxil {
1600
1617
  * earlier writes and the first non-2xx op rolls every write back (the
1601
1618
  * undone ops answer `424 rolled_back`, the rest `424 not_run`). Default:
1602
1619
  * sequential, per-op status, no cross-op rollback. `ref` tags an op so
1603
- * its result is easy to find. */
1620
+ * its result is easy to find. In an atomic batch a later op's `id`, or a
1621
+ * top-level `data` value, may be `'$ref:<tag>.item_id'` — the item id an
1622
+ * earlier op tagged `<tag>` created or read (a 422 `ref_unresolved` in
1623
+ * that op's result, rolling the batch back, when that result has none). */
1604
1624
  batch: async (ops, opts) => (await this.call('POST', '/v1/cms/batch', {
1605
1625
  ops: ops.map((o) => ('expand' in o && o.expand !== undefined ? { ...o, expand: expandParam(o.expand) } : o)),
1606
1626
  ...(opts?.atomic !== undefined ? { atomic: opts.atomic } : {}),
@@ -1919,9 +1939,25 @@ export class Vxil {
1919
1939
  };
1920
1940
  orgs = {
1921
1941
  create: async (input) => (await this.call('POST', '/v1/orgs', input)).data,
1942
+ /** One page of orgs, newest first, each with `member_count` (and the
1943
+ * user's `role` when `user_id` is given), plus `next_cursor` (null on the
1944
+ * last page): pass it back as `cursor`. `limit` 1..500; omitted with no
1945
+ * `cursor` it is the tenant's org cap (one answer), with a cursor 100. */
1946
+ listPage: async (q) => {
1947
+ const s = qs({ user_id: q?.user_id || undefined, limit: q?.limit, cursor: q?.cursor || undefined });
1948
+ const d = (await this.call('GET', `/v1/orgs${s}`)).data;
1949
+ return { orgs: d.orgs, next_cursor: d.next_cursor ?? null };
1950
+ },
1951
+ /** Every org (walks `listPage` at 500 a page), each with `member_count`. */
1922
1952
  list: async (q) => {
1923
- const s = q?.user_id ? `?user_id=${encodeURIComponent(q.user_id)}` : '';
1924
- return (await this.call('GET', `/v1/orgs${s}`)).data.orgs;
1953
+ const out = [];
1954
+ let cursor = null;
1955
+ do {
1956
+ const page = await this.orgs.listPage({ user_id: q?.user_id, limit: 500, cursor });
1957
+ out.push(...page.orgs);
1958
+ cursor = page.next_cursor;
1959
+ } while (cursor);
1960
+ return out;
1925
1961
  },
1926
1962
  delete: async (orgId) => {
1927
1963
  await this.call('DELETE', `/v1/orgs/${encodeURIComponent(orgId)}`);
@@ -2079,7 +2115,7 @@ export class Vxil {
2079
2115
  usage: async () => (await this.call('GET', '/v1/files/usage')).data,
2080
2116
  /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
2081
2117
  * object to vxil's public asset host: a stable, content-addressed URL
2082
- * (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
2118
+ * (`https://cdn.vxilcdn.com/<tenant>/<sha256>.<ext>`) served from a global
2083
2119
  * edge cache with `Cache-Control: public, max-age=31536000, immutable`,
2084
2120
  * playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
2085
2121
  * `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
@@ -2452,10 +2488,29 @@ export class Vxil {
2452
2488
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
2453
2489
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
2454
2490
  * amount comes from the FIRST type whose available balance covers it (one
2455
- * ledger row, never split across types) and the answer's `credit_type` names
2491
+ * ledger row, never split across types by default — unless `allow_split: true`,
2492
+ * below) and the answer's `credit_type` names
2456
2493
  * it. A retry with the same key answers the same type.
2494
+ *
2495
+ * Split (2026-10-11): with `credit_types`, `allow_split: true` lets an
2496
+ * amount no single type covers draw across the types in list order (58
2497
+ * `expiring` + 2 `permanent` for 60) — one ledger row per type drawn,
2498
+ * listed in the answer's `parts`; a job hold of a split settles and
2499
+ * releases every part.
2457
2500
  */
2458
2501
  consume: async (input, opts) => (await this.call('POST', '/v1/payments/credits/consume', input, { 'idempotency-key': opts.idempotencyKey })).data,
2502
+ /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
2503
+ * charge whose result you could not deliver. Name the consume's
2504
+ * `ledger_entry_id` (any part of a split consume reverses every part),
2505
+ * or the `job_id` (run_id) of a job hold that settled (every part of a
2506
+ * split). Puts back what was CHARGED (a pro-rated
2507
+ * settle's actual) as one `reversal` ledger row per consume — at most
2508
+ * once: a repeat answers `already_reversed: true` and moves nothing.
2509
+ * Throws VxilError 409 `not_committed` while the hold is still held (its
2510
+ * job settles or releases it), 409 `nothing_charged` for a released hold
2511
+ * or a recorded 402, 404 for no such consume. Needs payments:write;
2512
+ * SERVER-SIDE KEYS ONLY (403 `server_only` on a thin-client key). */
2513
+ reverse: async (input) => (await this.call('POST', '/v1/payments/credits/reverse', input)).data,
2459
2514
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
2460
2515
  * only ADDS; `amount` must be ≥ 1. */
2461
2516
  grant: async (input, opts) => (await this.call('POST', '/v1/payments/credits/grant', input, { 'idempotency-key': opts.idempotencyKey })).data,
@@ -57,6 +57,14 @@ export declare const reportServerErrors: (status: number) => boolean;
57
57
  * else — the platform still sees exactly what your handler produced, and never
58
58
  * later than REPORT_TIMEOUT_MS after it produced it (not later at all when the
59
59
  * runtime passes an ExecutionContext: the report rides `ctx.waitUntil`).
60
+ *
61
+ * Wrap per request: the DSN usually comes from `secrets` in the invocation
62
+ * envelope, which does not exist at module load. A 5xx your handler builds
63
+ * from a CAUGHT error is reported as a bare "function returned 5xx" message;
64
+ * for the error's class and stack, call `report(opts, exceptionEvent(e))` in
65
+ * your catch (and pass `reportNon2xx: false` so the 5xx is not reported twice).
66
+ * The report goes to `opts.dsn` only, and its host must be in the function's
67
+ * `egressAllow`.
60
68
  */
61
69
  export declare function withReporting<H extends FetchHandler>(handler: H, opts: ReportingOptions): H;
62
70
  export declare function withReporting<F extends (request: Request, ...rest: never[]) => Promise<Response> | Response>(handler: F, opts: ReportingOptions): F;
package/dist/reporting.js CHANGED
@@ -35,12 +35,22 @@
35
35
  // • no body of the request or response is ever sent — only the error's
36
36
  // class/message/stack, the status, and the tags you pass.
37
37
  //
38
- // Usage inside a function (the DSN in a per-function secret, never the bundle):
38
+ // Usage inside a function. The DSN is a per-function secret, and secrets ride
39
+ // the invocation envelope (`secrets.<name>`), not module scope — so wrap PER
40
+ // REQUEST (guide ch. 8 "Or let the SDK write the envelope"):
39
41
  //
40
42
  // import { withReporting } from '@vxil/sdk';
41
- // export default withReporting({
42
- // async fetch(req, env, ctx) { … },
43
- // }, { dsn: SENTRY_DSN, tags: { fn: 'generation-sweeper' }, environment: 'production' });
43
+ // export default {
44
+ // async fetch(req, ...runtime) {
45
+ // const { secrets } = await req.clone().json();
46
+ // return withReporting(handle, { dsn: secrets.reporter_dsn, tags: { fn: 'sweeper' } })(req, ...runtime);
47
+ // },
48
+ // };
49
+ //
50
+ // A handler that CATCHES its own error and answers 5xx is reported only as
51
+ // "function returned 500" (no class/stack). To keep the stack, report the
52
+ // caught value yourself — `report(opts, exceptionEvent(e))` — and return the
53
+ // 5xx with `reportNon2xx: false` so it is not reported twice.
44
54
  /** The report POST is bounded to this many milliseconds. */
45
55
  export const REPORT_TIMEOUT_MS = 3_000;
46
56
  /** Parsed DSN parts, or null when the DSN is not usable. PURE. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.22.0",
3
+ "version": "0.24.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).",