@vxil/sdk 0.26.2 → 0.28.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 +366 -20
- package/dist/index.js +78 -10
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -412,6 +412,25 @@ export interface UsageCurrent {
|
|
|
412
412
|
cpu_ms_limit_per_day: number | null;
|
|
413
413
|
as_of: string | null;
|
|
414
414
|
} | null;
|
|
415
|
+
/** pricing v3: each capped lane of the plan (used / cap / resets_at /
|
|
416
|
+
* state) for the pool its caps count in — a Free account's projects share
|
|
417
|
+
* one. `used` null = not readable here yet; `cap` null = by contract.
|
|
418
|
+
* `db_bytes` is the project's row payload in the shared database (cms
|
|
419
|
+
* items, vector-search documents and chunks), measured nightly
|
|
420
|
+
* (`measured_at`; `resets_at` null): over it cms creates and updates
|
|
421
|
+
* answer 413 db_size_limit, reads and deletes always work.
|
|
422
|
+
* Absent from an older server; null for an end-user (thin-client) key. */
|
|
423
|
+
daily_caps?: {
|
|
424
|
+
pool: 'account' | 'project';
|
|
425
|
+
lanes: Array<{
|
|
426
|
+
lane: string;
|
|
427
|
+
used: number | null;
|
|
428
|
+
cap: number | null;
|
|
429
|
+
resets_at: string | null;
|
|
430
|
+
state: 'ok' | 'warning' | 'reached' | 'unknown';
|
|
431
|
+
measured_at?: string | null;
|
|
432
|
+
}>;
|
|
433
|
+
} | null;
|
|
415
434
|
}
|
|
416
435
|
export interface DeadLetter {
|
|
417
436
|
delivery_id: string;
|
|
@@ -491,6 +510,13 @@ export interface JobRun {
|
|
|
491
510
|
/** the single-run read, generation runs only: when that healing terminal
|
|
492
511
|
* mirror landed (ISO); null otherwise */
|
|
493
512
|
mirror_ok_at?: string | null;
|
|
513
|
+
/** the single-run read, generation runs only: each provider START call
|
|
514
|
+
* (timing, HTTP status, error class), oldest first, the last 10 kept; a
|
|
515
|
+
* START with no answer (network fault, timeout) is recorded with
|
|
516
|
+
* `http_status: null`. null before the first START returned and on every
|
|
517
|
+
* other run. A START that threw before its outcome was read records no
|
|
518
|
+
* entry, so attempt numbers can skip. */
|
|
519
|
+
attempts?: GenerationProviderAttempt[] | null;
|
|
494
520
|
/** the single-run read only: the enqueue `concurrency_key` this run holds
|
|
495
521
|
* while running or waiting; null for an unkeyed run */
|
|
496
522
|
concurrency_key?: string | null;
|
|
@@ -1013,6 +1039,24 @@ export interface PaymentsLedgerEntry {
|
|
|
1013
1039
|
}
|
|
1014
1040
|
/** Where a job hold's ledger row stands (`PaymentsLedgerEntry.hold`). */
|
|
1015
1041
|
export type PaymentsLedgerHold = 'held' | 'settled' | 'released';
|
|
1042
|
+
/** What `createRefund` answers. `cancel` is present only when the refund asked
|
|
1043
|
+
* for a cancel (`cancel: 'period_end' | 'immediately'`, or the payments config
|
|
1044
|
+
* `refunds.cancelAtProvider` default): `cancel_scheduled` (the provider
|
|
1045
|
+
* subscription now ends — at period end, or at once for `immediately`), `awaiting_refund_settlement` (the refund is still
|
|
1046
|
+
* pending — the cancel runs when the provider settles it), `no_subscription`
|
|
1047
|
+
* (the charge paid no subscription), `failed` (see `error`; call
|
|
1048
|
+
* `DELETE /v1/payments/subscriptions/{id}` yourself). */
|
|
1049
|
+
export interface PaymentsRefundResult {
|
|
1050
|
+
refund_id: string;
|
|
1051
|
+
status: 'pending' | 'succeeded' | 'failed';
|
|
1052
|
+
amount_cents: number;
|
|
1053
|
+
cancel?: {
|
|
1054
|
+
requested: 'period_end' | 'immediately';
|
|
1055
|
+
status: 'cancel_scheduled' | 'awaiting_refund_settlement' | 'no_subscription' | 'failed';
|
|
1056
|
+
subscription_id?: string;
|
|
1057
|
+
error?: string;
|
|
1058
|
+
};
|
|
1059
|
+
}
|
|
1016
1060
|
/** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
|
|
1017
1061
|
export interface PaymentsRefund {
|
|
1018
1062
|
/** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
|
|
@@ -1047,16 +1091,24 @@ export type PaymentsSubscription = {
|
|
|
1047
1091
|
provider: string;
|
|
1048
1092
|
provider_sub_id: string;
|
|
1049
1093
|
tier: string | null;
|
|
1050
|
-
/** trialing | active | past_due | cancelled | expired | lapsed */
|
|
1094
|
+
/** trialing | active | past_due | paused | cancelled | expired | lapsed */
|
|
1051
1095
|
status: string;
|
|
1052
1096
|
current_period_start: string | null;
|
|
1053
1097
|
current_period_end: string | null;
|
|
1098
|
+
/** the scheduled cancellation (2026-10-13): access ends then; null when
|
|
1099
|
+
* none. Informational — access follows `status` and `current_period_end` */
|
|
1100
|
+
cancel_at: string | null;
|
|
1054
1101
|
/** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
|
|
1055
1102
|
charge_id: string | null;
|
|
1056
1103
|
/** the tenant's own reference from the checkout's custom data (Paddle
|
|
1057
1104
|
* `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
|
|
1058
1105
|
* can set it, so match on it — never grant access because of it */
|
|
1059
1106
|
reference: string | null;
|
|
1107
|
+
/** true while a refund / chargeback ended this row in vxil but its PROVIDER
|
|
1108
|
+
* subscription keeps billing (Stripe, Paddle, PayPal) — cancel it with
|
|
1109
|
+
* `cancelSubscription`. false otherwise; a cancel or a newer provider
|
|
1110
|
+
* event clears it. */
|
|
1111
|
+
provider_subscription_active: boolean;
|
|
1060
1112
|
created_at: string;
|
|
1061
1113
|
[key: string]: unknown;
|
|
1062
1114
|
};
|
|
@@ -1143,6 +1195,19 @@ export interface PublishedFile {
|
|
|
1143
1195
|
published_at: string | null;
|
|
1144
1196
|
variants: Record<string, string>;
|
|
1145
1197
|
}
|
|
1198
|
+
/** `VxilError.code` values a social / OIDC sign-in (`auth.oauth.native`, the
|
|
1199
|
+
* `…/callback` exchange) can answer beyond the generic envelope codes:
|
|
1200
|
+
* `oauth_token_invalid` (401, the token did not verify),
|
|
1201
|
+
* `oidc_domain_not_allowed` (403, the email is outside
|
|
1202
|
+
* `providers.oidc.allowedDomains`), `oidc_link_only` (403,
|
|
1203
|
+
* `providers.oidc.linkOnly` is on and no existing account matches the
|
|
1204
|
+
* identity — nothing was created; create or import the user first),
|
|
1205
|
+
* `signup_not_allowed` (403, the sign-up gate refused a new account),
|
|
1206
|
+
* `auth_method_disabled` (403, the provider is turned off in `methods`),
|
|
1207
|
+
* `oauth_email_conflict` (409, the email belongs to an account the rule will
|
|
1208
|
+
* not link to), `oauth_provider_unconfigured` (501),
|
|
1209
|
+
* `oauth_provider_unreachable` (502). */
|
|
1210
|
+
export type OAuthSignInErrorCode = 'oauth_token_invalid' | 'oidc_domain_not_allowed' | 'oidc_link_only' | 'signup_not_allowed' | 'auth_method_disabled' | 'oauth_email_conflict' | 'oauth_provider_unconfigured' | 'oauth_provider_unreachable';
|
|
1146
1211
|
/** Why one id of a bulk publish was not published. */
|
|
1147
1212
|
export type PublishErrorCode = 'not_found' | 'upload_incomplete' | 'content_type_not_publishable' | 'object_too_large' | 'quota_exceeded' | 'batch_budget_exceeded' | 'asset_taken_down' | 'publish_failed';
|
|
1148
1213
|
/** A live shared link as listed by GET /v1/files/{id}/shared-links (guide ch. 6,
|
|
@@ -1421,6 +1486,12 @@ export interface AiJobHandle {
|
|
|
1421
1486
|
* (`generateAsync`), kept 30 days after it settles; a sync/stream generation
|
|
1422
1487
|
* returned its answer to you directly and records none. The lookup always
|
|
1423
1488
|
* carries `result: null` — read the text by id. */
|
|
1489
|
+
/** What `vx.ai.getGeneration(id, { wait })` resolves to: the record, plus
|
|
1490
|
+
* `wait` only when a held read did not see a terminal generation. */
|
|
1491
|
+
export type AiGenerationRead = AiGenerationRecord & {
|
|
1492
|
+
/** `timeout` — the bound passed first; `unavailable` — the wait was not held */
|
|
1493
|
+
wait?: 'timeout' | 'unavailable';
|
|
1494
|
+
};
|
|
1424
1495
|
export interface AiGenerationRecord {
|
|
1425
1496
|
generation_id: string;
|
|
1426
1497
|
correlation_id: string | null;
|
|
@@ -1446,6 +1517,11 @@ export interface AiGenerationRecord {
|
|
|
1446
1517
|
* user was erased) · `not_recorded` (not settled yet, or a sync/stream
|
|
1447
1518
|
* generation) */
|
|
1448
1519
|
result_state: 'stored' | 'purged' | 'not_recorded';
|
|
1520
|
+
/** a job-lane generation's model calls (timing, the upstream HTTP status,
|
|
1521
|
+
* error class), oldest first, the last 10 kept — a retried attempt shows
|
|
1522
|
+
* up here with the status the model provider answered. Empty on a
|
|
1523
|
+
* sync/stream generation and before the first call returned */
|
|
1524
|
+
attempts?: GenerationProviderAttempt[];
|
|
1449
1525
|
}
|
|
1450
1526
|
/** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
|
|
1451
1527
|
export interface JobGenerationQueuedEventPayload {
|
|
@@ -1488,6 +1564,16 @@ export interface JobGenerationSettledEventPayload {
|
|
|
1488
1564
|
* null without the option or when the provider never accepted the run;
|
|
1489
1565
|
* absent on events written before 2026-10-11 */
|
|
1490
1566
|
provider_ref?: string | null;
|
|
1567
|
+
/** the START attempt the run settled on (1-based; 0 when it never made
|
|
1568
|
+
* one — expired or refused before its first provider call). Absent on a
|
|
1569
|
+
* run refused at its credit hold and on events written before 2026-10-13 */
|
|
1570
|
+
attempt?: number;
|
|
1571
|
+
/** how long the settling provider START call took, in ms, when the run
|
|
1572
|
+
* settled from that answer (the ai lane: the START is the whole model
|
|
1573
|
+
* call); null when it settled from a poll, a callback or the expiry.
|
|
1574
|
+
* Every attempt's timing is on the run: GET /v1/jobs/runs/{id} `attempts`
|
|
1575
|
+
* (and GET /v1/ai/generations/{id} `attempts` for an ai generation) */
|
|
1576
|
+
provider_ms?: number | null;
|
|
1491
1577
|
/** the failure-event vocabulary every `*.failed` carries (guide 12):
|
|
1492
1578
|
* `completed` → info; `failed` → error, except a refusal at admission
|
|
1493
1579
|
* (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
|
|
@@ -1495,9 +1581,41 @@ export interface JobGenerationSettledEventPayload {
|
|
|
1495
1581
|
level: 'info' | 'warn' | 'error';
|
|
1496
1582
|
state: 'ok' | 'broken';
|
|
1497
1583
|
}
|
|
1584
|
+
/** One provider call of a generation, as the run keeps it (AI-ATTEMPT-TIMING,
|
|
1585
|
+
* 2026-10-13). On a jobs run (`attempts` on GET /v1/jobs/runs/{id}) it is
|
|
1586
|
+
* one START call, timed from the jobs side — on the ai lane its
|
|
1587
|
+
* `http_status` is the ai exec receiver's answer (e.g. 422, 503), not the
|
|
1588
|
+
* model provider's; on GET /v1/ai/generations/{id} it is the model call
|
|
1589
|
+
* itself, timed inside ai, with the provider's own status. The last 10 are
|
|
1590
|
+
* kept. */
|
|
1591
|
+
export interface GenerationProviderAttempt {
|
|
1592
|
+
/** 1-based attempt number */
|
|
1593
|
+
attempt: number;
|
|
1594
|
+
/** ISO time the call started */
|
|
1595
|
+
started_at: string;
|
|
1596
|
+
/** how long the call took, in ms */
|
|
1597
|
+
ms: number;
|
|
1598
|
+
/** the HTTP status the call answered (on ai: the upstream model provider's),
|
|
1599
|
+
* or null when there was none (a network fault, a timeout) */
|
|
1600
|
+
http_status: number | null;
|
|
1601
|
+
/** the attempt's error class, or null when it succeeded */
|
|
1602
|
+
error_class: string | null;
|
|
1603
|
+
}
|
|
1604
|
+
/** The `data` of `job.generation.retrying` (2026-10-13): a START attempt
|
|
1605
|
+
* failed with a retryable error (a 5xx, 429, 408 or a network fault) and the
|
|
1606
|
+
* run will call the provider again in `retry_in_s` seconds. Informational —
|
|
1607
|
+
* the run is not over; it still ends with `completed` or `failed`. */
|
|
1608
|
+
export interface JobGenerationRetryingEventPayload extends GenerationProviderAttempt {
|
|
1609
|
+
run_id: string;
|
|
1610
|
+
generation_id: string | null;
|
|
1611
|
+
correlation_id: string | null;
|
|
1612
|
+
/** seconds until the next attempt */
|
|
1613
|
+
retry_in_s: number;
|
|
1614
|
+
}
|
|
1498
1615
|
/** The union a handler subscribed to `job.generation.` receives as `data`:
|
|
1499
|
-
* narrow on `'status' in data` (queued
|
|
1500
|
-
|
|
1616
|
+
* narrow on `'status' in data` (queued and retrying carry none) and on
|
|
1617
|
+
* `'retry_in_s' in data` (retrying only). */
|
|
1618
|
+
export type JobGenerationEventPayload = JobGenerationQueuedEventPayload | JobGenerationRetryingEventPayload | JobGenerationSettledEventPayload;
|
|
1501
1619
|
/** The `data` of `job.succeeded` / `job.dead_lettered` (every run kind). The
|
|
1502
1620
|
* dead letter is the one that carries `level: 'error'` / `state: 'broken'`;
|
|
1503
1621
|
* `job.succeeded` carries neither. */
|
|
@@ -1671,7 +1789,7 @@ export interface PaymentsRefundFailedEventPayload {
|
|
|
1671
1789
|
state: 'broken';
|
|
1672
1790
|
}
|
|
1673
1791
|
/** `payments.subscription.<status>` (`trialing` | `active` | `past_due` |
|
|
1674
|
-
* `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
|
|
1792
|
+
* `paused` | `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
|
|
1675
1793
|
* (the period-end sweep's own ending). */
|
|
1676
1794
|
export interface PaymentsSubscriptionStatusEventPayload {
|
|
1677
1795
|
end_user_id: string;
|
|
@@ -1679,7 +1797,7 @@ export interface PaymentsSubscriptionStatusEventPayload {
|
|
|
1679
1797
|
provider: string;
|
|
1680
1798
|
provider_sub_id: string | null;
|
|
1681
1799
|
tier: string | null;
|
|
1682
|
-
status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
|
|
1800
|
+
status: 'trialing' | 'active' | 'past_due' | 'paused' | 'cancelled' | 'expired' | 'lapsed';
|
|
1683
1801
|
current_period_start: string | null;
|
|
1684
1802
|
current_period_end: string | null;
|
|
1685
1803
|
/** the subscription row's `reference` (a provider subscription carries the
|
|
@@ -1695,8 +1813,26 @@ export interface PaymentsSubscriptionStatusEventPayload {
|
|
|
1695
1813
|
/** the store transaction id of that purchase / renewal (RevenueCat
|
|
1696
1814
|
* `transaction_id`) — a stable dedup id for ad-platform conversions */
|
|
1697
1815
|
transaction_id: string | null;
|
|
1816
|
+
/** the store the subscription is billed through, lower-case (RevenueCat
|
|
1817
|
+
* `store`: `app_store` | `play_store` | `stripe` | `promotional` | …);
|
|
1818
|
+
* null for Stripe / Paddle / PayPal / manual rows */
|
|
1819
|
+
store: string | null;
|
|
1820
|
+
/** the purchase country, ISO 3166-1 alpha-2 upper-case, when THIS delivery
|
|
1821
|
+
* carries it (RevenueCat `country_code`; Paddle only when the payload
|
|
1822
|
+
* includes the address); null otherwise */
|
|
1823
|
+
country: string | null;
|
|
1824
|
+
/** when access ends because the subscription will not renew (auto-renew
|
|
1825
|
+
* off / a scheduled cancel): Stripe `cancel_at`, Paddle
|
|
1826
|
+
* `scheduled_change.effective_at`, RevenueCat CANCELLATION's period end —
|
|
1827
|
+
* cleared by UNCANCELLATION / a renewal. null when nothing is scheduled */
|
|
1828
|
+
cancel_at: string | null;
|
|
1829
|
+
/** the provider's OWN event type (RevenueCat `RENEWAL` vs
|
|
1830
|
+
* `INITIAL_PURCHASE`, Stripe `customer.subscription.updated`, Paddle
|
|
1831
|
+
* `subscription.updated`, PayPal `BILLING.SUBSCRIPTION.ACTIVATED`); null
|
|
1832
|
+
* when no provider delivery wrote it (sync, period-end sweep, test clock) */
|
|
1833
|
+
provider_event_type: string | null;
|
|
1698
1834
|
environment: PaymentsEventEnvironment;
|
|
1699
|
-
/** what wrote it: the
|
|
1835
|
+
/** what wrote it: the normalized event type (`subscription.updated`, …), `subscription.synced` /
|
|
1700
1836
|
* `subscription.restored`, `period_end_enforced`, or `test_clock` (a
|
|
1701
1837
|
* `moveSubscriptionUntil` on a non-production project ended the row) */
|
|
1702
1838
|
event_type: string;
|
|
@@ -1739,9 +1875,43 @@ export interface PaymentsSubscriptionRevokedEventPayload {
|
|
|
1739
1875
|
via: 'delete' | 'revoke' | 'refund' | 'chargeback';
|
|
1740
1876
|
charge_id: string | null;
|
|
1741
1877
|
provider_refund_id: string | null;
|
|
1878
|
+
/** (2026-10-22 PAY-REFUND-STILL-BILLING) `true` when this ended row is a
|
|
1879
|
+
* PROVIDER subscription (Stripe, Paddle, PayPal) that vxil did NOT cancel at
|
|
1880
|
+
* the provider — the customer is charged again at the next renewal unless the
|
|
1881
|
+
* handler calls `DELETE /v1/payments/subscriptions/{id}` (or the refund was
|
|
1882
|
+
* made with `cancel: 'period_end'`). `false` for a manual / purchase-entitlement
|
|
1883
|
+
* row and a `/revoke` or `DELETE`; `null` for a store subscription
|
|
1884
|
+
* (RevenueCat — the store, not vxil, controls renewal). */
|
|
1885
|
+
provider_subscription_active: boolean | null;
|
|
1742
1886
|
level: 'info';
|
|
1743
1887
|
state: 'ok';
|
|
1744
1888
|
}
|
|
1889
|
+
/** `payments.charge.dispute_reversed` (2026-10-22 PAY-DISPUTE-REINSTATE) — a
|
|
1890
|
+
* dispute / chargeback was WON or REVERSED (Stripe `charge.dispute.closed`
|
|
1891
|
+
* won / `funds_reinstated`, Paddle `chargeback_reverse`, PayPal
|
|
1892
|
+
* `CUSTOMER.DISPUTE.RESOLVED` in your favour, RevenueCat `REFUND_REVERSED`).
|
|
1893
|
+
* Fires only when something came back: the subscription rows the dispute
|
|
1894
|
+
* ended (`restored_subscriptions`), the `disputed` charge label, or the credits
|
|
1895
|
+
* it clawed back (`credits_restored`). */
|
|
1896
|
+
export interface PaymentsChargeDisputeReversedEventPayload {
|
|
1897
|
+
end_user_id: string | null;
|
|
1898
|
+
provider: string;
|
|
1899
|
+
charge_id: string | null;
|
|
1900
|
+
provider_charge_id: string | null;
|
|
1901
|
+
provider_refund_id: string | null;
|
|
1902
|
+
restored_subscriptions: Array<{
|
|
1903
|
+
subscription_id: string;
|
|
1904
|
+
tier: string | null;
|
|
1905
|
+
}>;
|
|
1906
|
+
credits_restored: Array<{
|
|
1907
|
+
credit_type: string;
|
|
1908
|
+
amount: number;
|
|
1909
|
+
}>;
|
|
1910
|
+
reference: string | null;
|
|
1911
|
+
source: 'webhook';
|
|
1912
|
+
environment: PaymentsEventEnvironment;
|
|
1913
|
+
level: 'info';
|
|
1914
|
+
}
|
|
1745
1915
|
/** `payments.subscription.transferred` — a RevenueCat TRANSFER (`reason:
|
|
1746
1916
|
* 'transfer'`) or the account-merge re-key (`reason: 'account_merge'`,
|
|
1747
1917
|
* `provider: null`). */
|
|
@@ -1877,12 +2047,53 @@ export interface PaymentsTestClockMovedEventPayload {
|
|
|
1877
2047
|
level: 'info';
|
|
1878
2048
|
state: 'ok';
|
|
1879
2049
|
}
|
|
2050
|
+
/** Who wrote a cms item: `'function'` a deployed function's own callback
|
|
2051
|
+
* (`end_user_id` still names the user it acted for), `'end_user'` a verified
|
|
2052
|
+
* end-user session, `'server'` a server key or a platform hop. */
|
|
2053
|
+
export type CmsWriterKind = 'server' | 'end_user' | 'function';
|
|
2054
|
+
/** `data` of `cms.item.created` / `cms.item.updated` / `cms.item.deleted` /
|
|
2055
|
+
* `cms.item.published`. No field values: re-read the item by `item_id`.
|
|
2056
|
+
* Delivery is at-least-once and may arrive out of order — keep the highest
|
|
2057
|
+
* `version` you applied per `item_id` and drop any delivery at or below it;
|
|
2058
|
+
* when `version` is absent, re-read the item instead of comparing.
|
|
2059
|
+
* `version`, `writer_kind` and `key_id` are absent on events written before
|
|
2060
|
+
* 2026-10-13 (a retry or replay can still deliver one). Retention sweeps,
|
|
2061
|
+
* cascaded children, read-model targets and account re-keys change rows
|
|
2062
|
+
* WITHOUT a per-item event (they write `cms.collection.retention_swept`,
|
|
2063
|
+
* `cms.item.cascade`, `cms.readmodel.materialized`, `cms.items.rekeyed`):
|
|
2064
|
+
* a mirror re-syncs on those. */
|
|
2065
|
+
export interface CmsItemEventPayload {
|
|
2066
|
+
collection: string;
|
|
2067
|
+
item_id: string;
|
|
2068
|
+
/** the item's version AFTER this write (the If-Match / ETag counter);
|
|
2069
|
+
* absent before 2026-10-13 */
|
|
2070
|
+
version?: number;
|
|
2071
|
+
/** absent before 2026-10-13 */
|
|
2072
|
+
writer_kind?: CmsWriterKind;
|
|
2073
|
+
/** the calling API key's id (`ak_…`), or null when the key isn't known
|
|
2074
|
+
* (a function callback, a platform write, or briefly after a key-cache
|
|
2075
|
+
* refresh) — null does NOT prove a function wrote it; read `writer_kind`.
|
|
2076
|
+
* Absent before 2026-10-13. */
|
|
2077
|
+
key_id?: string | null;
|
|
2078
|
+
/** the verified end user behind the write; absent for a server write */
|
|
2079
|
+
end_user_id?: string;
|
|
2080
|
+
/** `created` only */
|
|
2081
|
+
status?: string;
|
|
2082
|
+
/** set when the write was one step of `cms.transaction` */
|
|
2083
|
+
tx_id?: string;
|
|
2084
|
+
/** `updated` by `$inc` only: the deltas applied */
|
|
2085
|
+
inc?: Record<string, number>;
|
|
2086
|
+
/** `deleted` only: rows the declared cascade removed / nulled */
|
|
2087
|
+
cascaded?: number;
|
|
2088
|
+
set_null?: number;
|
|
2089
|
+
}
|
|
1880
2090
|
/** Event name → typed `data`, for the events that settle work you started and
|
|
1881
2091
|
* (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
|
|
1882
2092
|
* names one; everything else on the catalog is `Record<string, unknown>` until
|
|
1883
2093
|
* typed here. */
|
|
1884
2094
|
export interface VxilEventPayloads {
|
|
1885
2095
|
'job.generation.queued': JobGenerationQueuedEventPayload;
|
|
2096
|
+
'job.generation.retrying': JobGenerationRetryingEventPayload;
|
|
1886
2097
|
'job.generation.completed': JobGenerationSettledEventPayload;
|
|
1887
2098
|
'job.generation.failed': JobGenerationSettledEventPayload;
|
|
1888
2099
|
'job.succeeded': JobRunEventPayload;
|
|
@@ -1892,10 +2103,12 @@ export interface VxilEventPayloads {
|
|
|
1892
2103
|
'payments.charge.completed': PaymentsChargeEventPayload;
|
|
1893
2104
|
'payments.charge.refunded': PaymentsChargeRefundedEventPayload;
|
|
1894
2105
|
'payments.charge.disputed': PaymentsChargeRefundedEventPayload;
|
|
2106
|
+
'payments.charge.dispute_reversed': PaymentsChargeDisputeReversedEventPayload;
|
|
1895
2107
|
'payments.refund.failed': PaymentsRefundFailedEventPayload;
|
|
1896
2108
|
'payments.subscription.trialing': PaymentsSubscriptionStatusEventPayload;
|
|
1897
2109
|
'payments.subscription.active': PaymentsSubscriptionStatusEventPayload;
|
|
1898
2110
|
'payments.subscription.past_due': PaymentsSubscriptionStatusEventPayload;
|
|
2111
|
+
'payments.subscription.paused': PaymentsSubscriptionStatusEventPayload;
|
|
1899
2112
|
'payments.subscription.cancelled': PaymentsSubscriptionStatusEventPayload;
|
|
1900
2113
|
'payments.subscription.expired': PaymentsSubscriptionStatusEventPayload;
|
|
1901
2114
|
'payments.subscription.lapsed': PaymentsSubscriptionStatusEventPayload;
|
|
@@ -1913,6 +2126,10 @@ export interface VxilEventPayloads {
|
|
|
1913
2126
|
'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
|
|
1914
2127
|
'payments.conformance': PaymentsConformanceEventPayload;
|
|
1915
2128
|
'payments.test_clock.moved': PaymentsTestClockMovedEventPayload;
|
|
2129
|
+
'cms.item.created': CmsItemEventPayload;
|
|
2130
|
+
'cms.item.updated': CmsItemEventPayload;
|
|
2131
|
+
'cms.item.deleted': CmsItemEventPayload;
|
|
2132
|
+
'cms.item.published': CmsItemEventPayload;
|
|
1916
2133
|
}
|
|
1917
2134
|
export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
|
|
1918
2135
|
/** The `trigger` label on the envelope. The config spells two of them in
|
|
@@ -1971,11 +2188,16 @@ export interface FunctionEnvelopeBase {
|
|
|
1971
2188
|
/** `payload` of a `cms-hook` invocation. It carries no field values: re-read
|
|
1972
2189
|
* the item by `item_id`. */
|
|
1973
2190
|
export interface CmsHookTriggerPayload {
|
|
1974
|
-
/** `cms.item.created`, `cms.item.updated
|
|
1975
|
-
* binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
|
|
2191
|
+
/** `cms.item.created`, `cms.item.updated`, `cms.item.published` or
|
|
2192
|
+
* `cms.item.deleted` (`afterDelete`) (per the binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
|
|
1976
2193
|
event: string;
|
|
1977
2194
|
collection: string;
|
|
1978
2195
|
item_id: string;
|
|
2196
|
+
/** `cms.item.deleted` only: the deleted row's owner (null when the
|
|
2197
|
+
* collection has no owner or the row had none). Absent on other events. */
|
|
2198
|
+
owner?: string | null;
|
|
2199
|
+
/** `cms.item.deleted` only: the row's workspace org (null when none). */
|
|
2200
|
+
org?: string | null;
|
|
1979
2201
|
}
|
|
1980
2202
|
/** `payload` of an `auth-hook` invocation: the event's own fields plus
|
|
1981
2203
|
* `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
|
|
@@ -4436,20 +4658,56 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4436
4658
|
* on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
|
|
4437
4659
|
* only for identities the import creates or still holds, and a subject
|
|
4438
4660
|
* already linked stays where it is (`identities_linked` counts the new
|
|
4439
|
-
* ones). `
|
|
4440
|
-
*
|
|
4661
|
+
* ones). `dry_run: true` answers exactly what the call would do now
|
|
4662
|
+
* (same results, counts and link counts) and writes nothing.
|
|
4663
|
+
* `vxil migrate data --with-password-hashes` /
|
|
4664
|
+
* `--with-oauth-identities` drives this for you (without `--execute` it previews). */
|
|
4441
4665
|
import: (input: {
|
|
4442
4666
|
users: Array<{
|
|
4443
4667
|
id: string;
|
|
4444
4668
|
password_hash?: string | null;
|
|
4445
4669
|
email_verified?: boolean;
|
|
4670
|
+
/** source timestamps (ISO 8601 with a zone), written on create only and
|
|
4671
|
+
* clamped to now; `email_verified_at` implies `email_verified` */
|
|
4672
|
+
created_at?: string;
|
|
4673
|
+
email_verified_at?: string;
|
|
4446
4674
|
identities?: Array<{
|
|
4447
4675
|
provider: "google" | "apple" | "github" | "facebook";
|
|
4448
4676
|
subject: string;
|
|
4449
4677
|
}>;
|
|
4450
4678
|
}>;
|
|
4451
4679
|
oidc_issuer?: string;
|
|
4680
|
+
/** report what would be created / updated / kept / skipped / linked; nothing is written */
|
|
4681
|
+
dry_run?: boolean;
|
|
4452
4682
|
}) => Promise<AuthImportResult>;
|
|
4683
|
+
/** PRODUCTION CANARIES / STORE REVIEWERS (server key only, `auth:write`):
|
|
4684
|
+
* flag (`true`) or unflag (`false`) the ONE user a CI canary or an
|
|
4685
|
+
* app-store reviewer signs in as. Off until the auth config sets
|
|
4686
|
+
* `security: { canarySessions: true }` (403 `canary_sessions_disabled`;
|
|
4687
|
+
* unflagging always works). Every user starts unflagged. Unflagging
|
|
4688
|
+
* revokes the user's live canary sessions (`revoked` counts them). A
|
|
4689
|
+
* signed-in end user, a function or an app key gets 403
|
|
4690
|
+
* `server_key_required`; a guest cannot be flagged (409). */
|
|
4691
|
+
setCanary: (userId: string, enabled: boolean) => Promise<{
|
|
4692
|
+
user_id: string;
|
|
4693
|
+
canary: boolean;
|
|
4694
|
+
revoked: number;
|
|
4695
|
+
}>;
|
|
4696
|
+
/** Mint a short session for a user flagged with `setCanary` — no password,
|
|
4697
|
+
* code or mail (server key only, `auth:write`). Lasts `ttlMinutes`
|
|
4698
|
+
* (1–60, default 15, never longer than `session.ttlMinutes`) and comes
|
|
4699
|
+
* WITHOUT a refresh token: it cannot be refreshed. Its JWT carries
|
|
4700
|
+
* `cny: 1` (tell it from a real sign-in) and it does not count toward
|
|
4701
|
+
* `session.maxConcurrent`. Revoke it with `sessions.revokeById(session_id)`
|
|
4702
|
+
* or by unflagging the user. 403 `canary_sessions_disabled` unless the
|
|
4703
|
+
* auth config sets `security.canarySessions: true`; 403
|
|
4704
|
+
* `canary_not_enabled` for an unflagged user; 429
|
|
4705
|
+
* `canary_session_rate_limited` past 3 mints per user per minute
|
|
4706
|
+
* (revoked ones count) or 10 live canary sessions. Audited as `auth.session.canary_minted` with
|
|
4707
|
+
* the calling key's id. */
|
|
4708
|
+
canarySession: (userId: string, opts?: {
|
|
4709
|
+
ttlMinutes?: number;
|
|
4710
|
+
}) => Promise<AuthCanarySession>;
|
|
4453
4711
|
/** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
|
|
4454
4712
|
* deep-merges a bounded `attributes` object into its OWN shared identity
|
|
4455
4713
|
* row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
|
|
@@ -4643,7 +4901,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4643
4901
|
}>;
|
|
4644
4902
|
/** Native social sign-in: exchange a provider `id_token`/`access_token`
|
|
4645
4903
|
* for a vxil session (`linked` marks whether the user was created or
|
|
4646
|
-
* matched to an existing identity).
|
|
4904
|
+
* matched to an existing identity). Refusals throw `VxilError` with an
|
|
4905
|
+
* `OAuthSignInErrorCode` — e.g. 403 `oidc_link_only` when the auth config
|
|
4906
|
+
* sets `providers.oidc.linkOnly` and no existing account matches. */
|
|
4647
4907
|
native: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
|
|
4648
4908
|
id_token?: string;
|
|
4649
4909
|
access_token?: string;
|
|
@@ -4825,6 +5085,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4825
5085
|
* instead of per-item delete events. A collection another collection
|
|
4826
5086
|
* references with an `on_delete` rule is skipped. Omit/null = keep. */
|
|
4827
5087
|
retain_days?: number | null;
|
|
5088
|
+
/** Recovery window for DELETED items (guide ch. 4): 0..29 days a
|
|
5089
|
+
* soft-deleted item stays restorable before the nightly cleanup purges
|
|
5090
|
+
* it (0 = at the next nightly run). Omit/null = the default 30 days. */
|
|
5091
|
+
deleted_retain_days?: number | null;
|
|
5092
|
+
/** What a GDPR erase of a user does to the items they own here (guide
|
|
5093
|
+
* ch. 9; needs `owner_field`): 'delete' hard-deletes them in the erase
|
|
5094
|
+
* transaction; 'keep' (default) leaves them. */
|
|
5095
|
+
on_owner_erase?: "delete" | "keep" | null;
|
|
4828
5096
|
/** Workspace scope (guide ch. 4): the workspace field — a string field on
|
|
4829
5097
|
* index slot s1–s4 holding the orgs org id. End users then read and
|
|
4830
5098
|
* write only rows of their ACTIVE org (`vx.auth.sessions.switchOrg`);
|
|
@@ -4885,6 +5153,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4885
5153
|
write_roles?: string[];
|
|
4886
5154
|
/** present when retention is set */
|
|
4887
5155
|
retain_days?: number;
|
|
5156
|
+
/** present when a shorter deleted-item window is set */
|
|
5157
|
+
deleted_retain_days?: number;
|
|
5158
|
+
/** present when a user's erase deletes their items here */
|
|
5159
|
+
on_owner_erase?: "delete";
|
|
4888
5160
|
/** present when the collection is workspace-scoped */
|
|
4889
5161
|
org_field?: string;
|
|
4890
5162
|
org_read_roles?: string[];
|
|
@@ -4900,6 +5172,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4900
5172
|
write_roles?: string[] | null;
|
|
4901
5173
|
/** retention in days (null = keep until deleted; absent from an older server) */
|
|
4902
5174
|
retain_days?: number | null;
|
|
5175
|
+
/** deleted-item recovery window in days (null = the default 30) */
|
|
5176
|
+
deleted_retain_days?: number | null;
|
|
5177
|
+
/** 'delete' = a user's erase deletes the items they own (null = keep) */
|
|
5178
|
+
on_owner_erase?: "delete" | null;
|
|
4903
5179
|
/** the workspace field / org read gate (null = not workspace-scoped) */
|
|
4904
5180
|
org_field?: string | null;
|
|
4905
5181
|
org_read_roles?: string[] | null;
|
|
@@ -4990,6 +5266,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4990
5266
|
collection: string;
|
|
4991
5267
|
retain_days: number | null;
|
|
4992
5268
|
}>;
|
|
5269
|
+
/** Set (0..29 days) or reset (`null` = the default 30) how long a DELETED
|
|
5270
|
+
* item stays restorable (guide ch. 4) before the nightly cleanup purges
|
|
5271
|
+
* it for good; 0 = purged at the next nightly run. Audited
|
|
5272
|
+
* (`cms.collection.deleted_retain_days.set`). */
|
|
5273
|
+
setDeletedRetention: (collection: string, days: number | null) => Promise<{
|
|
5274
|
+
collection: string;
|
|
5275
|
+
deleted_retain_days: number | null;
|
|
5276
|
+
}>;
|
|
5277
|
+
/** What a GDPR erase of a user does to the items they OWN in this
|
|
5278
|
+
* collection (guide ch. 9; needs its owner_field): 'delete' hard-deletes
|
|
5279
|
+
* them (live and deleted) inside the erase transaction; 'keep' (the
|
|
5280
|
+
* default) leaves them. Audited (`cms.collection.on_owner_erase.set`). */
|
|
5281
|
+
setOnOwnerErase: (collection: string, mode: "delete" | "keep") => Promise<{
|
|
5282
|
+
collection: string;
|
|
5283
|
+
on_owner_erase: "delete" | null;
|
|
5284
|
+
}>;
|
|
4993
5285
|
/** Re-project the collection's index slots after an `index_slot` move
|
|
4994
5286
|
* (guide ch. 4). Slots are projected on WRITE only, so until this runs,
|
|
4995
5287
|
* stored rows keep their OLD projection: the new slot is NULL and the
|
|
@@ -5996,8 +6288,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5996
6288
|
/** invite_token is returned ONCE — your app builds the accept URL.
|
|
5997
6289
|
* `role`: admin | member | viewer, or a custom role_key defined with
|
|
5998
6290
|
* `roles.define` (never owner). Pass `email: null` for a LINK invite —
|
|
5999
|
-
* no email is sent and any signed-in user holding the token may accept.
|
|
6000
|
-
|
|
6291
|
+
* no email is sent and any signed-in user holding the token may accept.
|
|
6292
|
+
* `opts.notify: false` keeps vxil from e-mailing the invitee (your app
|
|
6293
|
+
* delivers the invitation itself with the returned token). */
|
|
6294
|
+
create: (orgId: string, email: string | null, role: "admin" | "member" | "viewer" | (string & {}), opts?: {
|
|
6295
|
+
notify?: boolean;
|
|
6296
|
+
}) => Promise<{
|
|
6001
6297
|
invite_id: string;
|
|
6002
6298
|
invite_token: string;
|
|
6003
6299
|
org_id: string;
|
|
@@ -6684,8 +6980,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6684
6980
|
}) => Promise<AiJobHandle>;
|
|
6685
6981
|
/** One generation: status, usage, run, and — for a settled job-lane
|
|
6686
6982
|
* generation — the settled answer (`result`, kept 30 days). In end-user
|
|
6687
|
-
* mode only the caller's own generation reads (a foreign id is a 404).
|
|
6688
|
-
|
|
6983
|
+
* mode only the caller's own generation reads (a foreign id is a 404).
|
|
6984
|
+
* With `{ wait }` (integer 1..25 seconds) the read is held platform-side
|
|
6985
|
+
* until the generation is `completed` / `failed` — ONE API call instead of
|
|
6986
|
+
* a poll loop; if it is still running at the deadline the current record
|
|
6987
|
+
* comes back with `wait: 'timeout'` (`'unavailable'` when the per-tenant
|
|
6988
|
+
* budget of 60 held reads a minute declined to hold). A client
|
|
6989
|
+
* `timeoutMs` shorter than `wait` × 1000 aborts the call first. */
|
|
6990
|
+
getGeneration: (generationId: string, opts?: {
|
|
6991
|
+
wait?: number;
|
|
6992
|
+
}) => Promise<AiGenerationRead>;
|
|
6689
6993
|
/** Find generations by YOUR `correlation_id` (newest first, at most 20) —
|
|
6690
6994
|
* the recovery read after a timed-out or lost `generateAsync` answer.
|
|
6691
6995
|
* Each carries `result: null` (`result_state` still says whether an answer
|
|
@@ -6924,6 +7228,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6924
7228
|
capabilities: string[];
|
|
6925
7229
|
ledger_capabilities: string[];
|
|
6926
7230
|
missing: string[];
|
|
7231
|
+
/** (2026-10-22) every provider the tenant can drive (primary + secondaries with their own config block) */
|
|
7232
|
+
providers: Array<{
|
|
7233
|
+
provider: string;
|
|
7234
|
+
primary: boolean;
|
|
7235
|
+
capabilities: string[];
|
|
7236
|
+
missing: string[];
|
|
7237
|
+
}>;
|
|
6927
7238
|
client: {
|
|
6928
7239
|
revenuecat: {
|
|
6929
7240
|
project_id: string;
|
|
@@ -7145,7 +7456,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7145
7456
|
listSubscriptions: (q?: {
|
|
7146
7457
|
user_id?: string;
|
|
7147
7458
|
status?: string;
|
|
7459
|
+
still_billing?: boolean;
|
|
7460
|
+
limit?: number;
|
|
7148
7461
|
}) => Promise<PaymentsSubscription[]>;
|
|
7462
|
+
/** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
|
|
7463
|
+
* — null on the last page; pass it back as `cursor`. `limit` 1..100,
|
|
7464
|
+
* default 50. A malformed cursor is a 422. */
|
|
7465
|
+
listSubscriptionsPage: (q?: {
|
|
7466
|
+
user_id?: string;
|
|
7467
|
+
status?: string;
|
|
7468
|
+
still_billing?: boolean;
|
|
7469
|
+
cursor?: string | null;
|
|
7470
|
+
limit?: number;
|
|
7471
|
+
}) => Promise<{
|
|
7472
|
+
subscriptions: PaymentsSubscription[];
|
|
7473
|
+
next_cursor: string | null;
|
|
7474
|
+
}>;
|
|
7149
7475
|
/**
|
|
7150
7476
|
* Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
|
|
7151
7477
|
* the returned `url`; completion lands server-side via the provider webhook
|
|
@@ -7203,18 +7529,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7203
7529
|
* retrying the same refund fails the same way. A provider call that actually
|
|
7204
7530
|
* fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
|
|
7205
7531
|
* (the row that went `failed`) so you can tie them to this call.
|
|
7532
|
+
*
|
|
7533
|
+
* A refund ends access in vxil but the PROVIDER subscription keeps billing
|
|
7534
|
+
* until it is cancelled. `cancel: 'period_end'` stops it at period end once
|
|
7535
|
+
* the refund has settled; `cancel: 'immediately'` ends it at once (Stripe
|
|
7536
|
+
* and the mock only — 422 `cancel_immediately_unsupported` elsewhere);
|
|
7537
|
+
* `'none'` keeps them separate. Without `cancel` the payments config
|
|
7538
|
+
* `refunds.cancelAtProvider` decides (default off). Rows still billing:
|
|
7539
|
+
* `listSubscriptions({ still_billing: true })`.
|
|
7206
7540
|
*/
|
|
7207
7541
|
createRefund: (input: {
|
|
7208
7542
|
charge_id: string;
|
|
7209
7543
|
amount_cents?: number;
|
|
7210
7544
|
reason?: string;
|
|
7545
|
+
cancel?: "none" | "period_end" | "immediately";
|
|
7211
7546
|
}, opts: {
|
|
7212
7547
|
idempotencyKey: string;
|
|
7213
|
-
}) => Promise<
|
|
7214
|
-
refund_id: string;
|
|
7215
|
-
status: "pending" | "succeeded" | "failed";
|
|
7216
|
-
amount_cents: number;
|
|
7217
|
-
}>;
|
|
7548
|
+
}) => Promise<PaymentsRefundResult>;
|
|
7218
7549
|
/** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
|
|
7219
7550
|
* (the provider of their live subscription, not the tenant's primary):
|
|
7220
7551
|
* `kind: 'portal'` = a provider-minted portal session URL (Stripe, Paddle
|
|
@@ -7445,6 +7776,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7445
7776
|
};
|
|
7446
7777
|
}
|
|
7447
7778
|
export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, type ReportingOptions, type ReportEvent, type FetchHandler, } from './reporting.js';
|
|
7779
|
+
/** `auth.users.canarySession` (POST /v1/auth/users/{id}/canary-session):
|
|
7780
|
+
* a short, non-refreshable session for a canary-flagged user. */
|
|
7781
|
+
export interface AuthCanarySession {
|
|
7782
|
+
user_id: string;
|
|
7783
|
+
session_id: string;
|
|
7784
|
+
canary: true;
|
|
7785
|
+
session: {
|
|
7786
|
+
token: string;
|
|
7787
|
+
expires_at: string;
|
|
7788
|
+
};
|
|
7789
|
+
}
|
|
7448
7790
|
/** `auth.users.import` (POST /v1/auth/users/import) — one result per id. */
|
|
7449
7791
|
export interface AuthImportResult {
|
|
7450
7792
|
results: Array<{
|
|
@@ -7458,4 +7800,8 @@ export interface AuthImportResult {
|
|
|
7458
7800
|
skipped: number;
|
|
7459
7801
|
/** social sign-in links (users[].identities) created by this call */
|
|
7460
7802
|
identities_linked?: number;
|
|
7803
|
+
/** session hand-over links (oidc_issuer) created by this call */
|
|
7804
|
+
oidc_linked?: number;
|
|
7805
|
+
/** true when the call ran with `dry_run`: every figure is what it WOULD do; nothing was written */
|
|
7806
|
+
dry_run?: boolean;
|
|
7461
7807
|
}
|
package/dist/index.js
CHANGED
|
@@ -1266,9 +1266,33 @@ export class Vxil {
|
|
|
1266
1266
|
* on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
|
|
1267
1267
|
* only for identities the import creates or still holds, and a subject
|
|
1268
1268
|
* already linked stays where it is (`identities_linked` counts the new
|
|
1269
|
-
* ones). `
|
|
1270
|
-
*
|
|
1269
|
+
* ones). `dry_run: true` answers exactly what the call would do now
|
|
1270
|
+
* (same results, counts and link counts) and writes nothing.
|
|
1271
|
+
* `vxil migrate data --with-password-hashes` /
|
|
1272
|
+
* `--with-oauth-identities` drives this for you (without `--execute` it previews). */
|
|
1271
1273
|
import: async (input) => (await this.call('POST', '/v1/auth/users/import', input)).data,
|
|
1274
|
+
/** PRODUCTION CANARIES / STORE REVIEWERS (server key only, `auth:write`):
|
|
1275
|
+
* flag (`true`) or unflag (`false`) the ONE user a CI canary or an
|
|
1276
|
+
* app-store reviewer signs in as. Off until the auth config sets
|
|
1277
|
+
* `security: { canarySessions: true }` (403 `canary_sessions_disabled`;
|
|
1278
|
+
* unflagging always works). Every user starts unflagged. Unflagging
|
|
1279
|
+
* revokes the user's live canary sessions (`revoked` counts them). A
|
|
1280
|
+
* signed-in end user, a function or an app key gets 403
|
|
1281
|
+
* `server_key_required`; a guest cannot be flagged (409). */
|
|
1282
|
+
setCanary: async (userId, enabled) => (await this.call('PUT', `/v1/auth/users/${encodeURIComponent(userId)}/canary`, { enabled })).data,
|
|
1283
|
+
/** Mint a short session for a user flagged with `setCanary` — no password,
|
|
1284
|
+
* code or mail (server key only, `auth:write`). Lasts `ttlMinutes`
|
|
1285
|
+
* (1–60, default 15, never longer than `session.ttlMinutes`) and comes
|
|
1286
|
+
* WITHOUT a refresh token: it cannot be refreshed. Its JWT carries
|
|
1287
|
+
* `cny: 1` (tell it from a real sign-in) and it does not count toward
|
|
1288
|
+
* `session.maxConcurrent`. Revoke it with `sessions.revokeById(session_id)`
|
|
1289
|
+
* or by unflagging the user. 403 `canary_sessions_disabled` unless the
|
|
1290
|
+
* auth config sets `security.canarySessions: true`; 403
|
|
1291
|
+
* `canary_not_enabled` for an unflagged user; 429
|
|
1292
|
+
* `canary_session_rate_limited` past 3 mints per user per minute
|
|
1293
|
+
* (revoked ones count) or 10 live canary sessions. Audited as `auth.session.canary_minted` with
|
|
1294
|
+
* the calling key's id. */
|
|
1295
|
+
canarySession: async (userId, opts = {}) => (await this.call('POST', `/v1/auth/users/${encodeURIComponent(userId)}/canary-session`, opts.ttlMinutes !== undefined ? { ttl_minutes: opts.ttlMinutes } : {})).data,
|
|
1272
1296
|
/** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
|
|
1273
1297
|
* deep-merges a bounded `attributes` object into its OWN shared identity
|
|
1274
1298
|
* row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
|
|
@@ -1468,7 +1492,9 @@ export class Vxil {
|
|
|
1468
1492
|
},
|
|
1469
1493
|
/** Native social sign-in: exchange a provider `id_token`/`access_token`
|
|
1470
1494
|
* for a vxil session (`linked` marks whether the user was created or
|
|
1471
|
-
* matched to an existing identity).
|
|
1495
|
+
* matched to an existing identity). Refusals throw `VxilError` with an
|
|
1496
|
+
* `OAuthSignInErrorCode` — e.g. 403 `oidc_link_only` when the auth config
|
|
1497
|
+
* sets `providers.oidc.linkOnly` and no existing account matches. */
|
|
1472
1498
|
native: async (provider,
|
|
1473
1499
|
/** `anonymous_token`: the caller's CURRENT guest session bearer — the
|
|
1474
1500
|
* guest is PROMOTED to this identity (same user id, `linked: 'promoted'`)
|
|
@@ -1628,6 +1654,16 @@ export class Vxil {
|
|
|
1628
1654
|
* least 30 days later like any delete, one `cms.collection.retention_swept` audit event
|
|
1629
1655
|
* per collection per sweep. Audited (`cms.collection.retain_days.set`). */
|
|
1630
1656
|
setRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { retain_days: days })).data,
|
|
1657
|
+
/** Set (0..29 days) or reset (`null` = the default 30) how long a DELETED
|
|
1658
|
+
* item stays restorable (guide ch. 4) before the nightly cleanup purges
|
|
1659
|
+
* it for good; 0 = purged at the next nightly run. Audited
|
|
1660
|
+
* (`cms.collection.deleted_retain_days.set`). */
|
|
1661
|
+
setDeletedRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { deleted_retain_days: days })).data,
|
|
1662
|
+
/** What a GDPR erase of a user does to the items they OWN in this
|
|
1663
|
+
* collection (guide ch. 9; needs its owner_field): 'delete' hard-deletes
|
|
1664
|
+
* them (live and deleted) inside the erase transaction; 'keep' (the
|
|
1665
|
+
* default) leaves them. Audited (`cms.collection.on_owner_erase.set`). */
|
|
1666
|
+
setOnOwnerErase: async (collection, mode) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { on_owner_erase: mode })).data,
|
|
1631
1667
|
/** Re-project the collection's index slots after an `index_slot` move
|
|
1632
1668
|
* (guide ch. 4). Slots are projected on WRITE only, so until this runs,
|
|
1633
1669
|
* stored rows keep their OLD projection: the new slot is NULL and the
|
|
@@ -2227,8 +2263,10 @@ export class Vxil {
|
|
|
2227
2263
|
/** invite_token is returned ONCE — your app builds the accept URL.
|
|
2228
2264
|
* `role`: admin | member | viewer, or a custom role_key defined with
|
|
2229
2265
|
* `roles.define` (never owner). Pass `email: null` for a LINK invite —
|
|
2230
|
-
* no email is sent and any signed-in user holding the token may accept.
|
|
2231
|
-
|
|
2266
|
+
* no email is sent and any signed-in user holding the token may accept.
|
|
2267
|
+
* `opts.notify: false` keeps vxil from e-mailing the invitee (your app
|
|
2268
|
+
* delivers the invitation itself with the returned token). */
|
|
2269
|
+
create: async (orgId, email, role, opts) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`, { ...(email === null ? { role } : { email, role }), ...(opts?.notify === false ? { notify: false } : {}) })).data,
|
|
2232
2270
|
/** Redeem a token. With an end-user session the signed-in user is seated
|
|
2233
2271
|
* (omit `userId`) and an email invite needs that user's VERIFIED email to
|
|
2234
2272
|
* match (403 `invitation_email_mismatch`); a server key passes `userId`. */
|
|
@@ -2541,8 +2579,19 @@ export class Vxil {
|
|
|
2541
2579
|
generateAsync: async (input, opts) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job' }, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
|
|
2542
2580
|
/** One generation: status, usage, run, and — for a settled job-lane
|
|
2543
2581
|
* generation — the settled answer (`result`, kept 30 days). In end-user
|
|
2544
|
-
* mode only the caller's own generation reads (a foreign id is a 404).
|
|
2545
|
-
|
|
2582
|
+
* mode only the caller's own generation reads (a foreign id is a 404).
|
|
2583
|
+
* With `{ wait }` (integer 1..25 seconds) the read is held platform-side
|
|
2584
|
+
* until the generation is `completed` / `failed` — ONE API call instead of
|
|
2585
|
+
* a poll loop; if it is still running at the deadline the current record
|
|
2586
|
+
* comes back with `wait: 'timeout'` (`'unavailable'` when the per-tenant
|
|
2587
|
+
* budget of 60 held reads a minute declined to hold). A client
|
|
2588
|
+
* `timeoutMs` shorter than `wait` × 1000 aborts the call first. */
|
|
2589
|
+
getGeneration: async (generationId, opts) => {
|
|
2590
|
+
const qs = opts?.wait !== undefined ? `?wait=${encodeURIComponent(String(opts.wait))}` : '';
|
|
2591
|
+
const { data, response } = await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}${qs}`);
|
|
2592
|
+
const w = response.headers.get('x-vxil-wait');
|
|
2593
|
+
return w === 'timeout' || w === 'unavailable' ? { ...data, wait: w } : data;
|
|
2594
|
+
},
|
|
2546
2595
|
/** Find generations by YOUR `correlation_id` (newest first, at most 20) —
|
|
2547
2596
|
* the recovery read after a timed-out or lost `generateAsync` answer.
|
|
2548
2597
|
* Each carries `result: null` (`result_state` still says whether an answer
|
|
@@ -2834,9 +2883,20 @@ export class Vxil {
|
|
|
2834
2883
|
* window: `current_period_start` … `current_period_end` (a queued pass
|
|
2835
2884
|
* starts in the future). In end-user mode the list is always the signed-in
|
|
2836
2885
|
* user's own rows, whatever `user_id` says. */
|
|
2837
|
-
listSubscriptions: async (q) =>
|
|
2838
|
-
|
|
2839
|
-
|
|
2886
|
+
listSubscriptions: async (q) => (await this.payments.listSubscriptionsPage(q)).subscriptions,
|
|
2887
|
+
/** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
|
|
2888
|
+
* — null on the last page; pass it back as `cursor`. `limit` 1..100,
|
|
2889
|
+
* default 50. A malformed cursor is a 422. */
|
|
2890
|
+
listSubscriptionsPage: async (q) => {
|
|
2891
|
+
const s = qs({
|
|
2892
|
+
user_id: q?.user_id || undefined,
|
|
2893
|
+
status: q?.status || undefined,
|
|
2894
|
+
still_billing: q?.still_billing ? 'true' : undefined,
|
|
2895
|
+
cursor: q?.cursor || undefined,
|
|
2896
|
+
limit: q?.limit || undefined,
|
|
2897
|
+
});
|
|
2898
|
+
const d = (await this.call('GET', `/v1/payments/subscriptions${s}`)).data;
|
|
2899
|
+
return { subscriptions: d.subscriptions, next_cursor: d.next_cursor ?? null };
|
|
2840
2900
|
},
|
|
2841
2901
|
/**
|
|
2842
2902
|
* Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
|
|
@@ -2869,6 +2929,14 @@ export class Vxil {
|
|
|
2869
2929
|
* retrying the same refund fails the same way. A provider call that actually
|
|
2870
2930
|
* fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
|
|
2871
2931
|
* (the row that went `failed`) so you can tie them to this call.
|
|
2932
|
+
*
|
|
2933
|
+
* A refund ends access in vxil but the PROVIDER subscription keeps billing
|
|
2934
|
+
* until it is cancelled. `cancel: 'period_end'` stops it at period end once
|
|
2935
|
+
* the refund has settled; `cancel: 'immediately'` ends it at once (Stripe
|
|
2936
|
+
* and the mock only — 422 `cancel_immediately_unsupported` elsewhere);
|
|
2937
|
+
* `'none'` keeps them separate. Without `cancel` the payments config
|
|
2938
|
+
* `refunds.cancelAtProvider` decides (default off). Rows still billing:
|
|
2939
|
+
* `listSubscriptions({ still_billing: true })`.
|
|
2872
2940
|
*/
|
|
2873
2941
|
createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
|
|
2874
2942
|
/** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
|
package/package.json
CHANGED