@vxil/sdk 0.22.0 → 0.23.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
@@ -423,6 +423,10 @@ export interface JobRun {
423
423
  * list (`vx.jobs.runs`) and the single-run read. */
424
424
  generation_status?: string | null;
425
425
  generation_json?: Record<string, unknown> | null;
426
+ /** generation runs only: the provider's job id, read from its accepted
427
+ * START answer at `completion.ref_path` (e.g. fal's `request_id`); null
428
+ * without the option or before the provider answered. List + single read. */
429
+ provider_ref?: string | null;
426
430
  /** the single-run read (`vx.jobs.run` / `waitForRun`) only: your enqueue
427
431
  * payload — `{ redacted: true }` for a platform-internal run; never on lists */
428
432
  payload_json?: unknown;
@@ -1386,6 +1390,10 @@ export interface JobGenerationSettledEventPayload {
1386
1390
  /** the provider hint alone (`Upstream said: gemini 400: …`); null on
1387
1391
  * `completed` and whenever the failure carried none */
1388
1392
  error_hint: string | null;
1393
+ /** the provider's job id (`completion.ref_path` of the START answer);
1394
+ * null without the option or when the provider never accepted the run;
1395
+ * absent on events written before 2026-10-11 */
1396
+ provider_ref?: string | null;
1389
1397
  /** the failure-event vocabulary every `*.failed` carries (guide 12):
1390
1398
  * `completed` → info; `failed` → error, except a refusal at admission
1391
1399
  * (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
@@ -1435,7 +1443,8 @@ export interface JobBatchCompletedEventPayload {
1435
1443
  export type PaymentsEventEnvironment = 'production' | 'sandbox';
1436
1444
  /** Which credits a debit spends: ONE `credit_type`, or an ORDERED
1437
1445
  * `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). */
1446
+ * available balance covers it, never split across types by default (unless
1447
+ * `allow_split: true` — 2026-10-11) (2026-10-01 W9). */
1439
1448
  export type PaymentsCreditTypeChoice = {
1440
1449
  credit_type: string;
1441
1450
  credit_types?: never;
@@ -1448,8 +1457,35 @@ export interface PaymentsConsumeResult {
1448
1457
  balance_after: number;
1449
1458
  ledger_entry_id: string | null;
1450
1459
  reversed: boolean;
1451
- /** the credit type the debit came from (the chosen one for an ordered consume) */
1460
+ /** the credit type the debit came from (the chosen one for an ordered
1461
+ * consume; the first part's for a split) */
1452
1462
  credit_type: string;
1463
+ /** (2026-10-11) only on a SPLIT (`allow_split: true` and no single type
1464
+ * covered the amount): one entry per type drawn, in list order — the first
1465
+ * is the row `ledger_entry_id` / `balance_after` / `credit_type` describe */
1466
+ parts?: Array<{
1467
+ credit_type: string;
1468
+ amount: number;
1469
+ ledger_entry_id: string;
1470
+ balance_after: number;
1471
+ }>;
1472
+ }
1473
+ /** `POST /v1/payments/credits/reverse` → `data` (2026-10-11). */
1474
+ export interface PaymentsReverseResult {
1475
+ user_id: string;
1476
+ /** the credits put back, summed over `entries` */
1477
+ amount: number;
1478
+ /** true when every consume was already reversed (a repeat): nothing moved */
1479
+ already_reversed: boolean;
1480
+ entries: Array<{
1481
+ /** the consume reversed */
1482
+ ledger_entry_id: string;
1483
+ /** the `reversal` ledger row */
1484
+ reversal_entry_id: string;
1485
+ credit_type: string;
1486
+ amount: number;
1487
+ balance_after: number | null;
1488
+ }>;
1453
1489
  }
1454
1490
  /** `payments.charge.succeeded` (a new charge row) / `payments.charge.completed`
1455
1491
  * (a recorded charge reached the provider's completed state — Paddle's
@@ -1622,6 +1658,22 @@ export interface PaymentsGrantFailedEventPayload {
1622
1658
  level: 'error';
1623
1659
  state: 'broken';
1624
1660
  }
1661
+ /** `payments.credits.reversed` (2026-10-11) — one committed consume was
1662
+ * reversed through `POST /v1/payments/credits/reverse` (one event per
1663
+ * consume; a repeated call emits nothing). */
1664
+ export interface PaymentsCreditsReversedEventPayload {
1665
+ end_user_id: string;
1666
+ credit_type: string;
1667
+ /** the credits put back (what the consume charged) */
1668
+ amount: number;
1669
+ /** the consume that was reversed */
1670
+ ledger_entry_id: string;
1671
+ /** the `reversal` ledger row */
1672
+ reversal_entry_id: string;
1673
+ /** the job the consume was held for, else null */
1674
+ job_id: string | null;
1675
+ reason: string | null;
1676
+ }
1625
1677
  /** `payments.webhook.rejected` — a signature / parse failure was persisted. */
1626
1678
  export interface PaymentsWebhookRejectedEventPayload {
1627
1679
  event_id: string;
@@ -1722,6 +1774,7 @@ export interface VxilEventPayloads {
1722
1774
  'payments.entitlement.changed': PaymentsEntitlementChangedEventPayload;
1723
1775
  'payments.entitlement.revoke.failed': PaymentsEntitlementRevokeFailedEventPayload;
1724
1776
  'payments.grant.failed': PaymentsGrantFailedEventPayload;
1777
+ 'payments.credits.reversed': PaymentsCreditsReversedEventPayload;
1725
1778
  'payments.webhook.rejected': PaymentsWebhookRejectedEventPayload;
1726
1779
  'payments.webhook_event.failed': PaymentsWebhookEventFailedEventPayload;
1727
1780
  'payments.webhook_event.reprocessed': PaymentsWebhookEventReprocessedEventPayload;
@@ -1839,12 +1892,35 @@ export interface InboundWebhookTriggerData {
1839
1892
  /** true on a `POST /v1/webhooks/events/:id/replay` */
1840
1893
  replayed?: true;
1841
1894
  }
1895
+ /** Who called an `http` function (2026-10-11). Absent when there is nothing
1896
+ * to carry, and always on an async invoke. */
1897
+ export interface FunctionClient {
1898
+ /** The caller's IP address, set by vxil from the network connection — never
1899
+ * from anything the caller sent. Present when the call came straight to
1900
+ * the API with a project key; absent when another function or a platform
1901
+ * hop made it. Key per-address limits on an IPv6 address's /64, and expect
1902
+ * many users behind one IPv4 address on mobile networks. */
1903
+ ip?: string;
1904
+ /** ISO 3166-1 alpha-2 country of `ip`, when known */
1905
+ country?: string;
1906
+ /** The request headers named in the http trigger's `forwardHeaders` that the
1907
+ * call carried (lower-case names, values ≤ 256 bytes). The caller wrote
1908
+ * them: never trust one for authorization. */
1909
+ headers?: Record<string, string>;
1910
+ }
1842
1911
  /** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
1843
1912
  * parameters on a GET). */
1844
1913
  export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
1845
1914
  trigger: 'http';
1846
1915
  /** present only when the caller presented a verified end-user session */
1847
1916
  end_user?: FunctionEndUser;
1917
+ /** the caller's address and forwarded headers (see FunctionClient) */
1918
+ client?: FunctionClient;
1919
+ /** Tenant-only tokens for the http trigger's `serverScopes` (each one of the
1920
+ * function's own scopes), present only when the trigger declares them. Not
1921
+ * bound to the end user: use them for rows the user must not write, and
1922
+ * take the owner from `end_user.id`, never from the payload. */
1923
+ server_jwts?: FunctionScopedJwts;
1848
1924
  payload: P;
1849
1925
  }
1850
1926
  export interface CmsHookFunctionEnvelope extends FunctionEnvelopeBase {
@@ -3594,6 +3670,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3594
3670
  * provider words to completed | failed | processing (`{ OK: 'completed',
3595
3671
  * ERROR: 'failed' }`); `completion.result_path` names the value the run
3596
3672
  * settles with — the status mirror receives it as `result`.
3673
+ * `completion.ref_path` keeps the provider's job id from its START answer
3674
+ * (`provider_ref` on run reads and on job.generation.completed|failed);
3675
+ * with `provider.cancel` that job is cancelled at the provider when the
3676
+ * run is cancelled or expires. `completion.error_path` keeps a failed
3677
+ * answer's detail (`error_detail`). The 202 answers `expires_at`.
3597
3678
  *
3598
3679
  * A mirror write the record refuses never fails the run: a body refusal
3599
3680
  * (e.g. a callback key the collection does not declare) is retried with
@@ -3614,6 +3695,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3614
3695
  method?: string;
3615
3696
  headers?: Record<string, string>;
3616
3697
  body?: Record<string, unknown>;
3698
+ /** the provider's own cancel call, made ONCE (best-effort, no retry)
3699
+ * when the run is cancelled or expires after the provider accepted
3700
+ * it; `{provider_ref}` in the url is replaced by the job id
3701
+ * `completion.ref_path` read (required with it). Method default POST. */
3702
+ cancel?: {
3703
+ url: string;
3704
+ method?: string;
3705
+ headers?: Record<string, string>;
3706
+ };
3617
3707
  };
3618
3708
  completion: {
3619
3709
  mode: "poll" | "webhook";
@@ -3632,6 +3722,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3632
3722
  status_map?: Record<string, "completed" | "failed" | "processing">;
3633
3723
  /** dotted path of the value a completed run settles with (mirrored as `result`) */
3634
3724
  result_path?: string;
3725
+ /** dotted path of the provider's job id in its START answer (e.g.
3726
+ * `request_id`) — kept as the run's `provider_ref` */
3727
+ ref_path?: string;
3728
+ /** dotted path of the failure detail in a failed answer (e.g.
3729
+ * `payload.detail`) — kept on the run (≤ 1000 chars of JSON text)
3730
+ * and mirrored as `error_detail` (declare that field) */
3731
+ error_path?: string;
3635
3732
  };
3636
3733
  /** `progress_fields`: the progress keys (`progress` / `stage` /
3637
3734
  * `message`) a webhook-mode `processing` callback also writes onto the
@@ -3673,6 +3770,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3673
3770
  amount: number;
3674
3771
  user_id: string;
3675
3772
  reason?: string;
3773
+ /** with `credit_types` only (2026-10-11): hold across the types in
3774
+ * order when no single one covers `amount` (default: 402) */
3775
+ allow_split?: boolean;
3676
3776
  /** payments unreachable when the hold is placed (a 5xx other than
3677
3777
  * 501, a 429, no answer within 5 s; payments switched off is NOT
3678
3778
  * unreachable — that run starts without a hold): `'fail'` (default)
@@ -3697,6 +3797,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3697
3797
  generation_status: string;
3698
3798
  state?: string;
3699
3799
  deduplicated?: boolean;
3800
+ expires_at: string | null;
3700
3801
  }>;
3701
3802
  /** The newest runs (≤ `limit`, default 50, max 100). Filters: job_name,
3702
3803
  * state, batch_id, ids, since/until (creation time, ISO). For more than
@@ -4264,6 +4365,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4264
4365
  /** sessions taken over by auth config session.maxConcurrent (present once opted in) */
4265
4366
  took_over?: string[];
4266
4367
  }>;
4368
+ /** Attach another sign-in method to the SIGNED-IN user: verifies the
4369
+ * provider token like `native`, then links its stable (provider, sub)
4370
+ * to the user behind `session_token` — no new user, no new session
4371
+ * (keep the one you hold). Use it when an address would not match, e.g.
4372
+ * an Apple "Hide My Email" relay address on an OTP account. Idempotent
4373
+ * for an identity this user already holds; 409 `oauth_identity_linked`
4374
+ * when another user holds it; 401 `invalid_session` / 409
4375
+ * `anonymous_user` for an unknown or guest session. */
4376
+ link: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4377
+ session_token: string;
4378
+ id_token?: string;
4379
+ access_token?: string;
4380
+ nonce?: string;
4381
+ }) => Promise<{
4382
+ user_id: string;
4383
+ linked: "linked";
4384
+ }>;
4267
4385
  };
4268
4386
  };
4269
4387
  readonly rateLimits: {
@@ -5735,7 +5853,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5735
5853
  usage: () => Promise<FilesUsage>;
5736
5854
  /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
5737
5855
  * object to vxil's public asset host: a stable, content-addressed URL
5738
- * (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
5856
+ * (`https://cdn.vxilcdn.com/<tenant>/<sha256>.<ext>`) served from a global
5739
5857
  * edge cache with `Cache-Control: public, max-age=31536000, immutable`,
5740
5858
  * playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
5741
5859
  * `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
@@ -6431,8 +6549,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6431
6549
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
6432
6550
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
6433
6551
  * 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
6552
+ * ledger row, never split across types by default — unless `allow_split: true`,
6553
+ * below) and the answer's `credit_type` names
6435
6554
  * it. A retry with the same key answers the same type.
6555
+ *
6556
+ * Split (2026-10-11): with `credit_types`, `allow_split: true` lets an
6557
+ * amount no single type covers draw across the types in list order (58
6558
+ * `expiring` + 2 `permanent` for 60) — one ledger row per type drawn,
6559
+ * listed in the answer's `parts`; a job hold of a split settles and
6560
+ * releases every part.
6436
6561
  */
6437
6562
  consume: (input: PaymentsCreditTypeChoice & {
6438
6563
  user_id: string;
@@ -6440,9 +6565,31 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6440
6565
  /** link this debit to a jobs run_id → provisional hold + auto-reverse. */
6441
6566
  job_id?: string;
6442
6567
  reason?: string;
6568
+ /** with `credit_types` only: draw across the types when no single
6569
+ * one covers the amount (default false: 402 instead) */
6570
+ allow_split?: boolean;
6443
6571
  }, opts: {
6444
6572
  idempotencyKey: string;
6445
6573
  }) => Promise<PaymentsConsumeResult>;
6574
+ /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
6575
+ * charge whose result you could not deliver. Name the consume's
6576
+ * `ledger_entry_id`, or the `job_id` (run_id) of a job hold that settled
6577
+ * (every part of a split). Puts back what was CHARGED (a pro-rated
6578
+ * settle's actual) as one `reversal` ledger row per consume — at most
6579
+ * once: a repeat answers `already_reversed: true` and moves nothing.
6580
+ * Throws VxilError 409 `not_committed` while the hold is still held (its
6581
+ * job settles or releases it), 409 `nothing_charged` for a released hold
6582
+ * or a recorded 402, 404 for no such consume. Needs payments:write;
6583
+ * SERVER-SIDE KEYS ONLY (403 `server_only` on a thin-client key). */
6584
+ reverse: (input: {
6585
+ ledger_entry_id: string;
6586
+ job_id?: never;
6587
+ reason?: string;
6588
+ } | {
6589
+ job_id: string;
6590
+ ledger_entry_id?: never;
6591
+ reason?: string;
6592
+ }) => Promise<PaymentsReverseResult>;
6446
6593
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
6447
6594
  * only ADDS; `amount` must be ≥ 1. */
6448
6595
  grant: (input: {
@@ -6486,6 +6633,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6486
6633
  balance_after: number | null;
6487
6634
  source: string | null;
6488
6635
  job_id: string | null;
6636
+ /** On a settle / reversal: the consume it corrects. */
6637
+ reverses_entry_id: string | null;
6489
6638
  created_at: string;
6490
6639
  }>;
6491
6640
  }>;
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 = {
@@ -2079,7 +2093,7 @@ export class Vxil {
2079
2093
  usage: async () => (await this.call('GET', '/v1/files/usage')).data,
2080
2094
  /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
2081
2095
  * object to vxil's public asset host: a stable, content-addressed URL
2082
- * (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
2096
+ * (`https://cdn.vxilcdn.com/<tenant>/<sha256>.<ext>`) served from a global
2083
2097
  * edge cache with `Cache-Control: public, max-age=31536000, immutable`,
2084
2098
  * playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
2085
2099
  * `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
@@ -2452,10 +2466,28 @@ export class Vxil {
2452
2466
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
2453
2467
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
2454
2468
  * 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
2469
+ * ledger row, never split across types by default — unless `allow_split: true`,
2470
+ * below) and the answer's `credit_type` names
2456
2471
  * it. A retry with the same key answers the same type.
2472
+ *
2473
+ * Split (2026-10-11): with `credit_types`, `allow_split: true` lets an
2474
+ * amount no single type covers draw across the types in list order (58
2475
+ * `expiring` + 2 `permanent` for 60) — one ledger row per type drawn,
2476
+ * listed in the answer's `parts`; a job hold of a split settles and
2477
+ * releases every part.
2457
2478
  */
2458
2479
  consume: async (input, opts) => (await this.call('POST', '/v1/payments/credits/consume', input, { 'idempotency-key': opts.idempotencyKey })).data,
2480
+ /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
2481
+ * charge whose result you could not deliver. Name the consume's
2482
+ * `ledger_entry_id`, or the `job_id` (run_id) of a job hold that settled
2483
+ * (every part of a split). Puts back what was CHARGED (a pro-rated
2484
+ * settle's actual) as one `reversal` ledger row per consume — at most
2485
+ * once: a repeat answers `already_reversed: true` and moves nothing.
2486
+ * Throws VxilError 409 `not_committed` while the hold is still held (its
2487
+ * job settles or releases it), 409 `nothing_charged` for a released hold
2488
+ * or a recorded 402, 404 for no such consume. Needs payments:write;
2489
+ * SERVER-SIDE KEYS ONLY (403 `server_only` on a thin-client key). */
2490
+ reverse: async (input) => (await this.call('POST', '/v1/payments/credits/reverse', input)).data,
2459
2491
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
2460
2492
  * only ADDS; `amount` must be ≥ 1. */
2461
2493
  grant: async (input, opts) => (await this.call('POST', '/v1/payments/credits/grant', input, { 'idempotency-key': opts.idempotencyKey })).data,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.22.0",
3
+ "version": "0.23.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).",