@vxil/sdk 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -393,6 +393,10 @@ export interface UsageCurrent {
393
393
  functions: {
394
394
  invocations_today: number | null;
395
395
  limit_per_day: number;
396
+ /** CPU-ms charged to the daily budget today; null without a fresh snapshot */
397
+ cpu_ms_today: number | null;
398
+ /** the enforced daily CPU-ms budget (Free staging/development projects); null = none */
399
+ cpu_ms_limit_per_day: number | null;
396
400
  as_of: string | null;
397
401
  } | null;
398
402
  }
@@ -535,6 +539,23 @@ export interface JobRunsQuery {
535
539
  until?: string;
536
540
  limit?: number;
537
541
  }
542
+ /** A row of `vx.orgs.list` / `listPage` (GET /v1/orgs). */
543
+ export interface OrgListRow {
544
+ org_id: string;
545
+ slug: string;
546
+ name: string;
547
+ created_at?: string;
548
+ /** members of the org, every role */
549
+ member_count: number;
550
+ /** the user's role, present when listed with `user_id` */
551
+ role?: string;
552
+ }
553
+ /** One page of `vx.orgs.listPage`. */
554
+ export interface OrgsListPage {
555
+ orgs: OrgListRow[];
556
+ /** pass back as `cursor` for the next older page; null on the last page */
557
+ next_cursor: string | null;
558
+ }
538
559
  /** One page of `vx.jobs.runsPage`. */
539
560
  export interface JobRunsPage {
540
561
  runs: JobRun[];
@@ -947,7 +968,14 @@ export interface PaymentsLedgerEntry {
947
968
  /** the Idempotency-Key the consume / grant was sent with */
948
969
  idempotency_key: string | null;
949
970
  created_at: string;
950
- }
971
+ /** (2026-10-11) non-null on a job hold's rows (its consume and its release
972
+ * reversal): they moved `held`, not the balance — `held` while the job
973
+ * runs, `settled` once it settled (the charge is the `settle` row),
974
+ * `released` once given back. null on every row that moved the balance. */
975
+ hold: PaymentsLedgerHold | null;
976
+ }
977
+ /** Where a job hold's ledger row stands (`PaymentsLedgerEntry.hold`). */
978
+ export type PaymentsLedgerHold = 'held' | 'settled' | 'released';
951
979
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
952
980
  export interface PaymentsRefund {
953
981
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -1820,8 +1848,14 @@ export interface FunctionEnvelopeBase {
1820
1848
  vxil_base: string;
1821
1849
  scoped_jwts: FunctionScopedJwts;
1822
1850
  /** Your declared per-function secrets (`secrets: ['<name>']`), keyed by
1823
- * bare name and resolved at invoke time. */
1851
+ * bare name and resolved at invoke time. An optional one (`'<name>?'`)
1852
+ * that has no stored value is absent. */
1824
1853
  secrets: Record<string, string>;
1854
+ /** Your function's declared plain settings (`vars: { NAME: 'value' }`),
1855
+ * `{}` when it declares none. Plain text, never secret. Always present on
1856
+ * an envelope from the platform; optional in the type only so envelope
1857
+ * fixtures written against SDK 0.23 still compile. */
1858
+ vars?: Record<string, string>;
1825
1859
  }
1826
1860
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
1827
1861
  * the item by `item_id`. */
@@ -2481,8 +2515,12 @@ export interface DeployedFunction {
2481
2515
  endpoint: string;
2482
2516
  scopes: string[];
2483
2517
  egressAllow: string[];
2484
- /** secret REFS only (`secret:<name>`) — never values */
2518
+ /** secret REFS only (`secret:<name>`, `secret:<name>?` = optional) — never values */
2485
2519
  secrets: string[];
2520
+ /** the plain settings delivered on the envelope as `vars` ({} when none).
2521
+ * Present only for a server key holding `features:read` or `features:write`; absent for other
2522
+ * keys and end-user (thin-client) requests */
2523
+ vars?: Record<string, string>;
2486
2524
  enabled: boolean;
2487
2525
  trigger: string;
2488
2526
  bindings: Array<{
@@ -2823,9 +2861,18 @@ export type CmsBatchOp = {
2823
2861
  id: string;
2824
2862
  if_version?: number;
2825
2863
  ref?: string;
2826
- };
2864
+ } | ({
2865
+ op: 'aggregate';
2866
+ collection: string;
2867
+ ref?: string;
2868
+ } & CmsAggregateBody) | ({
2869
+ op: 'rank';
2870
+ collection: string;
2871
+ ref?: string;
2872
+ } & CmsRankBody);
2827
2873
  /** What a 2xx batch result's `data` is, per op: the item record (get / create /
2828
- * patch), a page or `{ count }` (query), the delete tally (delete). */
2874
+ * patch), a page or `{ count }` (query), the delete tally (delete), the
2875
+ * aggregate / rank route's answer. */
2829
2876
  export type CmsBatchData<O extends CmsBatchOp> = O extends {
2830
2877
  op: 'query';
2831
2878
  } ? (O extends {
@@ -2842,6 +2889,25 @@ export type CmsBatchData<O extends CmsBatchOp> = O extends {
2842
2889
  deleted: boolean;
2843
2890
  cascaded: number;
2844
2891
  set_null: number;
2892
+ } : O extends {
2893
+ op: 'aggregate';
2894
+ } ? {
2895
+ groups: Array<Record<string, unknown> & {
2896
+ key?: Record<string, unknown>;
2897
+ }>;
2898
+ scanned: number;
2899
+ truncated: boolean;
2900
+ limit: number;
2901
+ } : O extends {
2902
+ op: 'rank';
2903
+ } ? {
2904
+ entries: Array<{
2905
+ key: Record<string, unknown>;
2906
+ partition?: Record<string, unknown>;
2907
+ metric: unknown;
2908
+ rank: number;
2909
+ }>;
2910
+ scanned: number;
2845
2911
  } : Record<string, unknown>;
2846
2912
  /** One batch result: the single route's `status` and its `data` (2xx) or
2847
2913
  * `error`. In an aborted atomic batch the undone ops carry `424 rolled_back`
@@ -2850,7 +2916,7 @@ export type CmsBatchData<O extends CmsBatchOp> = O extends {
2850
2916
  * `424 not_run`); non-atomic, an op that failed unexpectedly is
2851
2917
  * `500 internal_error` in-line — the ops before it committed and keep their
2852
2918
  * results, so never retry the whole batch on one 500. At most 5 ops may be
2853
- * `query` (a whole-batch 422 otherwise). */
2919
+ * `query` / `aggregate` / `rank` (a whole-batch 422 otherwise). */
2854
2920
  export type CmsBatchResult<O extends CmsBatchOp = CmsBatchOp> = {
2855
2921
  op: O['op'];
2856
2922
  ref?: string;
@@ -4819,7 +4885,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4819
4885
  * action's deployed function with `{ collection, item_id, action, actor,
4820
4886
  * item }` and returns its result. 404 when the key is not declared;
4821
4887
  * 502 `action_failed` (with `upstream.code` = the function's error
4822
- * class) when the function fails. Requires cms:write. */
4888
+ * class) when the function fails. Requires cms:write, or — server keys
4889
+ * only (no end user) — cms:read + functions:invoke (a read-only staff
4890
+ * key; the function writes under its own scopes). End-user callers
4891
+ * still need cms:write. */
4823
4892
  runAction: (collection: string, itemId: string, key: string) => Promise<{
4824
4893
  collection: string;
4825
4894
  item_id: string;
@@ -4896,7 +4965,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4896
4965
  * earlier writes and the first non-2xx op rolls every write back (the
4897
4966
  * undone ops answer `424 rolled_back`, the rest `424 not_run`). Default:
4898
4967
  * sequential, per-op status, no cross-op rollback. `ref` tags an op so
4899
- * its result is easy to find. */
4968
+ * its result is easy to find. In an atomic batch a later op's `id`, or a
4969
+ * top-level `data` value, may be `'$ref:<tag>.item_id'` — the item id an
4970
+ * earlier op tagged `<tag>` created or read (a 422 `ref_unresolved` in
4971
+ * that op's result, rolling the batch back, when that result has none). */
4900
4972
  batch: <T extends readonly CmsBatchOp[]>(ops: readonly [...T], opts?: {
4901
4973
  atomic?: boolean;
4902
4974
  }) => Promise<CmsBatchResponse<T>>;
@@ -5577,14 +5649,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5577
5649
  slug: string;
5578
5650
  name: string;
5579
5651
  }>;
5652
+ /** One page of orgs, newest first, each with `member_count` (and the
5653
+ * user's `role` when `user_id` is given), plus `next_cursor` (null on the
5654
+ * last page): pass it back as `cursor`. `limit` 1..500; omitted with no
5655
+ * `cursor` it is the tenant's org cap (one answer), with a cursor 100. */
5656
+ listPage: (q?: {
5657
+ user_id?: string | undefined;
5658
+ limit?: number | undefined;
5659
+ cursor?: string | null | undefined;
5660
+ }) => Promise<OrgsListPage>;
5661
+ /** Every org (walks `listPage` at 500 a page), each with `member_count`. */
5580
5662
  list: (q?: {
5581
5663
  user_id?: string;
5582
- }) => Promise<Array<{
5583
- org_id: string;
5584
- slug: string;
5585
- name: string;
5586
- role?: string;
5587
- }>>;
5664
+ }) => Promise<OrgListRow[]>;
5588
5665
  delete: (orgId: string) => Promise<void>;
5589
5666
  /** RBAC: org:read (viewer+), org:write (member+), members:manage (admin+),
5590
5667
  * org:admin (owner) — plus any custom-role permission-set. Pass
@@ -6239,6 +6316,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6239
6316
  * the row, echoed on the answer and the replay read, and (job mode)
6240
6317
  * carried on the `job.generation.*` events with `generation_id`. */
6241
6318
  correlation_id?: string;
6319
+ /** SERVER mode only (an end-user caller gets 422
6320
+ * `status_mirror_server_only`); the key also needs `jobs:write` +
6321
+ * `cms:write` (or `admin`), else 403 `insufficient_scope`. The run mirrors its status word
6322
+ * (`pending` → `processing` → `completed` | `failed`) into `column`
6323
+ * (default `generation_status`) of a tenant record, and on completion
6324
+ * writes the answer to its `result` field — the parsed object for a
6325
+ * `response_schema` run (null if it failed the schema or is over 64 KiB),
6326
+ * the text otherwise (cut at 16,384 characters). Same rules as the jobs
6327
+ * `status_mirror` (`fence_field` is cms only); a refused mirror is 422
6328
+ * `status_mirror_invalid` and nothing starts. The collection must
6329
+ * declare `column` (string) and a nullable `result` field (JSON for a
6330
+ * `response_schema` run, text otherwise), or the completed write fails
6331
+ * and the record stays at `processing`. */
6332
+ status_mirror?: {
6333
+ feature: "cms";
6334
+ collection: string;
6335
+ record_id: string;
6336
+ column?: string;
6337
+ fence_field?: string;
6338
+ };
6242
6339
  }, opts?: {
6243
6340
  idempotencyKey?: string;
6244
6341
  }) => Promise<AiJobHandle>;
@@ -6573,8 +6670,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6573
6670
  }) => Promise<PaymentsConsumeResult>;
6574
6671
  /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
6575
6672
  * 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
6673
+ * `ledger_entry_id` (any part of a split consume reverses every part),
6674
+ * or the `job_id` (run_id) of a job hold that settled (every part of a
6675
+ * split). Puts back what was CHARGED (a pro-rated
6578
6676
  * settle's actual) as one `reversal` ledger row per consume — at most
6579
6677
  * once: a repeat answers `already_reversed: true` and moves nothing.
6580
6678
  * Throws VxilError 409 `not_committed` while the hold is still held (its
@@ -6636,6 +6734,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6636
6734
  /** On a settle / reversal: the consume it corrects. */
6637
6735
  reverses_entry_id: string | null;
6638
6736
  created_at: string;
6737
+ /** (2026-10-11) a job hold's row (moved `held`, not the balance):
6738
+ * held / settled / released; null when the row moved the balance. */
6739
+ hold: PaymentsLedgerHold | null;
6639
6740
  }>;
6640
6741
  }>;
6641
6742
  /** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
package/dist/index.js CHANGED
@@ -1576,7 +1576,10 @@ export class Vxil {
1576
1576
  * action's deployed function with `{ collection, item_id, action, actor,
1577
1577
  * item }` and returns its result. 404 when the key is not declared;
1578
1578
  * 502 `action_failed` (with `upstream.code` = the function's error
1579
- * class) when the function fails. Requires cms:write. */
1579
+ * class) when the function fails. Requires cms:write, or — server keys
1580
+ * only (no end user) — cms:read + functions:invoke (a read-only staff
1581
+ * key; the function writes under its own scopes). End-user callers
1582
+ * still need cms:write. */
1580
1583
  runAction: async (collection, itemId, key) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/actions/${encodeURIComponent(key)}`)).data,
1581
1584
  /** Bounded group-by aggregate. fns count|sum|
1582
1585
  * min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
@@ -1614,7 +1617,10 @@ export class Vxil {
1614
1617
  * earlier writes and the first non-2xx op rolls every write back (the
1615
1618
  * undone ops answer `424 rolled_back`, the rest `424 not_run`). Default:
1616
1619
  * sequential, per-op status, no cross-op rollback. `ref` tags an op so
1617
- * its result is easy to find. */
1620
+ * its result is easy to find. In an atomic batch a later op's `id`, or a
1621
+ * top-level `data` value, may be `'$ref:<tag>.item_id'` — the item id an
1622
+ * earlier op tagged `<tag>` created or read (a 422 `ref_unresolved` in
1623
+ * that op's result, rolling the batch back, when that result has none). */
1618
1624
  batch: async (ops, opts) => (await this.call('POST', '/v1/cms/batch', {
1619
1625
  ops: ops.map((o) => ('expand' in o && o.expand !== undefined ? { ...o, expand: expandParam(o.expand) } : o)),
1620
1626
  ...(opts?.atomic !== undefined ? { atomic: opts.atomic } : {}),
@@ -1933,9 +1939,25 @@ export class Vxil {
1933
1939
  };
1934
1940
  orgs = {
1935
1941
  create: async (input) => (await this.call('POST', '/v1/orgs', input)).data,
1942
+ /** One page of orgs, newest first, each with `member_count` (and the
1943
+ * user's `role` when `user_id` is given), plus `next_cursor` (null on the
1944
+ * last page): pass it back as `cursor`. `limit` 1..500; omitted with no
1945
+ * `cursor` it is the tenant's org cap (one answer), with a cursor 100. */
1946
+ listPage: async (q) => {
1947
+ const s = qs({ user_id: q?.user_id || undefined, limit: q?.limit, cursor: q?.cursor || undefined });
1948
+ const d = (await this.call('GET', `/v1/orgs${s}`)).data;
1949
+ return { orgs: d.orgs, next_cursor: d.next_cursor ?? null };
1950
+ },
1951
+ /** Every org (walks `listPage` at 500 a page), each with `member_count`. */
1936
1952
  list: async (q) => {
1937
- const s = q?.user_id ? `?user_id=${encodeURIComponent(q.user_id)}` : '';
1938
- return (await this.call('GET', `/v1/orgs${s}`)).data.orgs;
1953
+ const out = [];
1954
+ let cursor = null;
1955
+ do {
1956
+ const page = await this.orgs.listPage({ user_id: q?.user_id, limit: 500, cursor });
1957
+ out.push(...page.orgs);
1958
+ cursor = page.next_cursor;
1959
+ } while (cursor);
1960
+ return out;
1939
1961
  },
1940
1962
  delete: async (orgId) => {
1941
1963
  await this.call('DELETE', `/v1/orgs/${encodeURIComponent(orgId)}`);
@@ -2479,8 +2501,9 @@ export class Vxil {
2479
2501
  consume: async (input, opts) => (await this.call('POST', '/v1/payments/credits/consume', input, { 'idempotency-key': opts.idempotencyKey })).data,
2480
2502
  /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
2481
2503
  * 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
2504
+ * `ledger_entry_id` (any part of a split consume reverses every part),
2505
+ * or the `job_id` (run_id) of a job hold that settled (every part of a
2506
+ * split). Puts back what was CHARGED (a pro-rated
2484
2507
  * settle's actual) as one `reversal` ledger row per consume — at most
2485
2508
  * once: a repeat answers `already_reversed: true` and moves nothing.
2486
2509
  * Throws VxilError 409 `not_committed` while the hold is still held (its
@@ -57,6 +57,14 @@ export declare const reportServerErrors: (status: number) => boolean;
57
57
  * else — the platform still sees exactly what your handler produced, and never
58
58
  * later than REPORT_TIMEOUT_MS after it produced it (not later at all when the
59
59
  * runtime passes an ExecutionContext: the report rides `ctx.waitUntil`).
60
+ *
61
+ * Wrap per request: the DSN usually comes from `secrets` in the invocation
62
+ * envelope, which does not exist at module load. A 5xx your handler builds
63
+ * from a CAUGHT error is reported as a bare "function returned 5xx" message;
64
+ * for the error's class and stack, call `report(opts, exceptionEvent(e))` in
65
+ * your catch (and pass `reportNon2xx: false` so the 5xx is not reported twice).
66
+ * The report goes to `opts.dsn` only, and its host must be in the function's
67
+ * `egressAllow`.
60
68
  */
61
69
  export declare function withReporting<H extends FetchHandler>(handler: H, opts: ReportingOptions): H;
62
70
  export declare function withReporting<F extends (request: Request, ...rest: never[]) => Promise<Response> | Response>(handler: F, opts: ReportingOptions): F;
package/dist/reporting.js CHANGED
@@ -35,12 +35,22 @@
35
35
  // • no body of the request or response is ever sent — only the error's
36
36
  // class/message/stack, the status, and the tags you pass.
37
37
  //
38
- // Usage inside a function (the DSN in a per-function secret, never the bundle):
38
+ // Usage inside a function. The DSN is a per-function secret, and secrets ride
39
+ // the invocation envelope (`secrets.<name>`), not module scope — so wrap PER
40
+ // REQUEST (guide ch. 8 "Or let the SDK write the envelope"):
39
41
  //
40
42
  // import { withReporting } from '@vxil/sdk';
41
- // export default withReporting({
42
- // async fetch(req, env, ctx) { … },
43
- // }, { dsn: SENTRY_DSN, tags: { fn: 'generation-sweeper' }, environment: 'production' });
43
+ // export default {
44
+ // async fetch(req, ...runtime) {
45
+ // const { secrets } = await req.clone().json();
46
+ // return withReporting(handle, { dsn: secrets.reporter_dsn, tags: { fn: 'sweeper' } })(req, ...runtime);
47
+ // },
48
+ // };
49
+ //
50
+ // A handler that CATCHES its own error and answers 5xx is reported only as
51
+ // "function returned 500" (no class/stack). To keep the stack, report the
52
+ // caught value yourself — `report(opts, exceptionEvent(e))` — and return the
53
+ // 5xx with `reportNon2xx: false` so it is not reported twice.
44
54
  /** The report POST is bounded to this many milliseconds. */
45
55
  export const REPORT_TIMEOUT_MS = 3_000;
46
56
  /** Parsed DSN parts, or null when the DSN is not usable. PURE. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.23.0",
3
+ "version": "0.24.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",