@vxil/sdk 0.23.0 → 0.24.1
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 +121 -17
- package/dist/index.js +32 -7
- package/dist/reporting.d.ts +8 -0
- package/dist/reporting.js +14 -4
- package/package.json +1 -1
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
|
|
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>>;
|
|
@@ -5089,7 +5161,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5089
5161
|
/** The deployed functions (name, endpoint, bindings, scopes, limits, the
|
|
5090
5162
|
* runtime each script runs under), `runtime`, the settings a deploy uses
|
|
5091
5163
|
* now, and `cpuMsCeiling`, the per-invocation CPU limit (ms) the plan
|
|
5092
|
-
* gives a function now (its own `limits.cpuMs` can only lower it),
|
|
5164
|
+
* gives a function now (its own `limits.cpuMs` can only lower it),
|
|
5165
|
+
* `cpuMsDefault`, the CPU (ms) a function declaring no `limits.cpuMs`
|
|
5166
|
+
* gets (50 on a dev project, the ceiling elsewhere), and
|
|
5093
5167
|
* `enabled`: false while the project's functions are paused as a whole
|
|
5094
5168
|
* (a Free project on the production workload, a downgrade) — invokes then
|
|
5095
5169
|
* answer 404. Any authenticated key may read it. (GET /v1/functions) */
|
|
@@ -5101,6 +5175,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5101
5175
|
compatibilityFlags: string[];
|
|
5102
5176
|
};
|
|
5103
5177
|
cpuMsCeiling?: number;
|
|
5178
|
+
cpuMsDefault?: number;
|
|
5104
5179
|
}>;
|
|
5105
5180
|
/**
|
|
5106
5181
|
* Remove ONE function from the deployed set — a new functions config
|
|
@@ -5577,14 +5652,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5577
5652
|
slug: string;
|
|
5578
5653
|
name: string;
|
|
5579
5654
|
}>;
|
|
5655
|
+
/** One page of orgs, newest first, each with `member_count` (and the
|
|
5656
|
+
* user's `role` when `user_id` is given), plus `next_cursor` (null on the
|
|
5657
|
+
* last page): pass it back as `cursor`. `limit` 1..500; omitted with no
|
|
5658
|
+
* `cursor` it is the tenant's org cap (one answer), with a cursor 100. */
|
|
5659
|
+
listPage: (q?: {
|
|
5660
|
+
user_id?: string | undefined;
|
|
5661
|
+
limit?: number | undefined;
|
|
5662
|
+
cursor?: string | null | undefined;
|
|
5663
|
+
}) => Promise<OrgsListPage>;
|
|
5664
|
+
/** Every org (walks `listPage` at 500 a page), each with `member_count`. */
|
|
5580
5665
|
list: (q?: {
|
|
5581
5666
|
user_id?: string;
|
|
5582
|
-
}) => Promise<
|
|
5583
|
-
org_id: string;
|
|
5584
|
-
slug: string;
|
|
5585
|
-
name: string;
|
|
5586
|
-
role?: string;
|
|
5587
|
-
}>>;
|
|
5667
|
+
}) => Promise<OrgListRow[]>;
|
|
5588
5668
|
delete: (orgId: string) => Promise<void>;
|
|
5589
5669
|
/** RBAC: org:read (viewer+), org:write (member+), members:manage (admin+),
|
|
5590
5670
|
* org:admin (owner) — plus any custom-role permission-set. Pass
|
|
@@ -6239,6 +6319,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6239
6319
|
* the row, echoed on the answer and the replay read, and (job mode)
|
|
6240
6320
|
* carried on the `job.generation.*` events with `generation_id`. */
|
|
6241
6321
|
correlation_id?: string;
|
|
6322
|
+
/** SERVER mode only (an end-user caller gets 422
|
|
6323
|
+
* `status_mirror_server_only`); the key also needs `jobs:write` +
|
|
6324
|
+
* `cms:write` (or `admin`), else 403 `insufficient_scope`. The run mirrors its status word
|
|
6325
|
+
* (`pending` → `processing` → `completed` | `failed`) into `column`
|
|
6326
|
+
* (default `generation_status`) of a tenant record, and on completion
|
|
6327
|
+
* writes the answer to its `result` field — the parsed object for a
|
|
6328
|
+
* `response_schema` run (null if it failed the schema or is over 64 KiB),
|
|
6329
|
+
* the text otherwise (cut at 16,384 characters). Same rules as the jobs
|
|
6330
|
+
* `status_mirror` (`fence_field` is cms only); a refused mirror is 422
|
|
6331
|
+
* `status_mirror_invalid` and nothing starts. The collection must
|
|
6332
|
+
* declare `column` (string) and a nullable `result` field (JSON for a
|
|
6333
|
+
* `response_schema` run, text otherwise), or the completed write fails
|
|
6334
|
+
* and the record stays at `processing`. */
|
|
6335
|
+
status_mirror?: {
|
|
6336
|
+
feature: "cms";
|
|
6337
|
+
collection: string;
|
|
6338
|
+
record_id: string;
|
|
6339
|
+
column?: string;
|
|
6340
|
+
fence_field?: string;
|
|
6341
|
+
};
|
|
6242
6342
|
}, opts?: {
|
|
6243
6343
|
idempotencyKey?: string;
|
|
6244
6344
|
}) => Promise<AiJobHandle>;
|
|
@@ -6573,8 +6673,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6573
6673
|
}) => Promise<PaymentsConsumeResult>;
|
|
6574
6674
|
/** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
|
|
6575
6675
|
* charge whose result you could not deliver. Name the consume's
|
|
6576
|
-
* `ledger_entry_id
|
|
6577
|
-
* (
|
|
6676
|
+
* `ledger_entry_id` (any part of a split consume reverses every part),
|
|
6677
|
+
* or the `job_id` (run_id) of a job hold that settled (every part of a
|
|
6678
|
+
* split). Puts back what was CHARGED (a pro-rated
|
|
6578
6679
|
* settle's actual) as one `reversal` ledger row per consume — at most
|
|
6579
6680
|
* once: a repeat answers `already_reversed: true` and moves nothing.
|
|
6580
6681
|
* Throws VxilError 409 `not_committed` while the hold is still held (its
|
|
@@ -6636,6 +6737,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6636
6737
|
/** On a settle / reversal: the consume it corrects. */
|
|
6637
6738
|
reverses_entry_id: string | null;
|
|
6638
6739
|
created_at: string;
|
|
6740
|
+
/** (2026-10-11) a job hold's row (moved `held`, not the balance):
|
|
6741
|
+
* held / settled / released; null when the row moved the balance. */
|
|
6742
|
+
hold: PaymentsLedgerHold | null;
|
|
6639
6743
|
}>;
|
|
6640
6744
|
}>;
|
|
6641
6745
|
/** (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 } : {}),
|
|
@@ -1708,7 +1714,9 @@ export class Vxil {
|
|
|
1708
1714
|
/** The deployed functions (name, endpoint, bindings, scopes, limits, the
|
|
1709
1715
|
* runtime each script runs under), `runtime`, the settings a deploy uses
|
|
1710
1716
|
* now, and `cpuMsCeiling`, the per-invocation CPU limit (ms) the plan
|
|
1711
|
-
* gives a function now (its own `limits.cpuMs` can only lower it),
|
|
1717
|
+
* gives a function now (its own `limits.cpuMs` can only lower it),
|
|
1718
|
+
* `cpuMsDefault`, the CPU (ms) a function declaring no `limits.cpuMs`
|
|
1719
|
+
* gets (50 on a dev project, the ceiling elsewhere), and
|
|
1712
1720
|
* `enabled`: false while the project's functions are paused as a whole
|
|
1713
1721
|
* (a Free project on the production workload, a downgrade) — invokes then
|
|
1714
1722
|
* answer 404. Any authenticated key may read it. (GET /v1/functions) */
|
|
@@ -1933,9 +1941,25 @@ export class Vxil {
|
|
|
1933
1941
|
};
|
|
1934
1942
|
orgs = {
|
|
1935
1943
|
create: async (input) => (await this.call('POST', '/v1/orgs', input)).data,
|
|
1944
|
+
/** One page of orgs, newest first, each with `member_count` (and the
|
|
1945
|
+
* user's `role` when `user_id` is given), plus `next_cursor` (null on the
|
|
1946
|
+
* last page): pass it back as `cursor`. `limit` 1..500; omitted with no
|
|
1947
|
+
* `cursor` it is the tenant's org cap (one answer), with a cursor 100. */
|
|
1948
|
+
listPage: async (q) => {
|
|
1949
|
+
const s = qs({ user_id: q?.user_id || undefined, limit: q?.limit, cursor: q?.cursor || undefined });
|
|
1950
|
+
const d = (await this.call('GET', `/v1/orgs${s}`)).data;
|
|
1951
|
+
return { orgs: d.orgs, next_cursor: d.next_cursor ?? null };
|
|
1952
|
+
},
|
|
1953
|
+
/** Every org (walks `listPage` at 500 a page), each with `member_count`. */
|
|
1936
1954
|
list: async (q) => {
|
|
1937
|
-
const
|
|
1938
|
-
|
|
1955
|
+
const out = [];
|
|
1956
|
+
let cursor = null;
|
|
1957
|
+
do {
|
|
1958
|
+
const page = await this.orgs.listPage({ user_id: q?.user_id, limit: 500, cursor });
|
|
1959
|
+
out.push(...page.orgs);
|
|
1960
|
+
cursor = page.next_cursor;
|
|
1961
|
+
} while (cursor);
|
|
1962
|
+
return out;
|
|
1939
1963
|
},
|
|
1940
1964
|
delete: async (orgId) => {
|
|
1941
1965
|
await this.call('DELETE', `/v1/orgs/${encodeURIComponent(orgId)}`);
|
|
@@ -2479,8 +2503,9 @@ export class Vxil {
|
|
|
2479
2503
|
consume: async (input, opts) => (await this.call('POST', '/v1/payments/credits/consume', input, { 'idempotency-key': opts.idempotencyKey })).data,
|
|
2480
2504
|
/** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
|
|
2481
2505
|
* charge whose result you could not deliver. Name the consume's
|
|
2482
|
-
* `ledger_entry_id
|
|
2483
|
-
* (
|
|
2506
|
+
* `ledger_entry_id` (any part of a split consume reverses every part),
|
|
2507
|
+
* or the `job_id` (run_id) of a job hold that settled (every part of a
|
|
2508
|
+
* split). Puts back what was CHARGED (a pro-rated
|
|
2484
2509
|
* settle's actual) as one `reversal` ledger row per consume — at most
|
|
2485
2510
|
* once: a repeat answers `already_reversed: true` and moves nothing.
|
|
2486
2511
|
* Throws VxilError 409 `not_committed` while the hold is still held (its
|
package/dist/reporting.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
42
|
-
// async fetch(req,
|
|
43
|
-
//
|
|
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