@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 +153 -4
- package/dist/index.js +34 -2
- package/package.json +1 -1
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
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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