@vxil/sdk 0.19.0 → 0.20.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 CHANGED
@@ -885,6 +885,33 @@ export interface PaymentsCharge {
885
885
  environment: PaymentsEventEnvironment;
886
886
  created_at: string;
887
887
  }
888
+ /** A credit ledger row as listed by GET /v1/payments/credits/ledger (2026-10-05). */
889
+ export interface PaymentsLedgerEntry {
890
+ /** `led_…` */
891
+ ledger_entry_id: string;
892
+ user_id: string;
893
+ credit_type: string;
894
+ /** grant / grant_once add credits; consume and expire remove them; settle and
895
+ * reversal correct a job-linked consume (`reverses_entry_id` names it) */
896
+ kind: 'grant' | 'grant_once' | 'consume' | 'settle' | 'reversal' | 'expire';
897
+ /** `provisional` = a job-linked hold not settled yet */
898
+ state: 'provisional' | 'committed' | 'reversed';
899
+ /** `insufficient` = a recorded 402 consume (no balance moved) */
900
+ outcome: 'applied' | 'insufficient';
901
+ /** the signed amount: positive adds credits, negative removes them */
902
+ delta: number;
903
+ balance_after: number | null;
904
+ source: string | null;
905
+ /** the jobs run this row is linked to */
906
+ job_id: string | null;
907
+ /** on a settle / reversal: the consume entry it corrects */
908
+ reverses_entry_id: string | null;
909
+ /** the grant-once dedup key */
910
+ grant_key: string | null;
911
+ /** the Idempotency-Key the consume / grant was sent with */
912
+ idempotency_key: string | null;
913
+ created_at: string;
914
+ }
888
915
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
889
916
  export interface PaymentsRefund {
890
917
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -3402,11 +3429,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3402
3429
  * status NOW (`processing`, `completed` or `failed` too). The key is bound
3403
3430
  * to the request BODY: re-sending it with a different body (another
3404
3431
  * payload — a rebuilt `deadline_at` included —, provider, completion,
3405
- * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
3406
- * original run (the ai-v1 rule). That check is being rolled out: today a
3407
- * mismatch is only logged, on every project, and the send is still
3408
- * deduplicated to the first run; a changelog entry will announce
3409
- * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
3432
+ * timeout, reserve…) answers 422 `idempotency_key_reused` naming the
3433
+ * original run (the ai-v1 rule), on every project — so keep the body
3434
+ * deterministic (provider header VALUES are not compared, so a rotated
3435
+ * key is fine). A 409 `generation_in_progress`
3410
3436
  * (Retry-After 5) means the run that key names is still placing its
3411
3437
  * credit hold.
3412
3438
  *
@@ -6311,6 +6337,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6311
6337
  created_at: string;
6312
6338
  }>;
6313
6339
  }>;
6340
+ /** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
6341
+ * reconciliation or a warehouse sync. Keyset-paged: pass the prior page's
6342
+ * `next_cursor` as `cursor` until it is null; start at `since` (inclusive
6343
+ * ISO-8601). To tail later, start a new walk with `since` = the last
6344
+ * `created_at` you stored MINUS an overlap (a minute) and dedupe on
6345
+ * `ledger_entry_id` — `created_at` is the writing transaction's start, so
6346
+ * a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
6347
+ * Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
6348
+ * (`end_user_required`) key gets 403 `server_only` (use `usage` for one
6349
+ * user's own rows). */
6350
+ ledger: (q?: {
6351
+ since?: string;
6352
+ cursor?: string;
6353
+ user_id?: string;
6354
+ credit_type?: string;
6355
+ limit?: number;
6356
+ }) => Promise<{
6357
+ entries: PaymentsLedgerEntry[];
6358
+ next_cursor: string | null;
6359
+ }>;
6314
6360
  /** Start a subscription (mock = instant checkout; real providers redirect via
6315
6361
  * their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
6316
6362
  * ref. Returns the vxil subscription_id + provider sub id + status. */
package/dist/index.js CHANGED
@@ -787,11 +787,10 @@ export class Vxil {
787
787
  * status NOW (`processing`, `completed` or `failed` too). The key is bound
788
788
  * to the request BODY: re-sending it with a different body (another
789
789
  * payload — a rebuilt `deadline_at` included —, provider, completion,
790
- * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
791
- * original run (the ai-v1 rule). That check is being rolled out: today a
792
- * mismatch is only logged, on every project, and the send is still
793
- * deduplicated to the first run; a changelog entry will announce
794
- * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
790
+ * timeout, reserve…) answers 422 `idempotency_key_reused` naming the
791
+ * original run (the ai-v1 rule), on every project — so keep the body
792
+ * deterministic (provider header VALUES are not compared, so a rotated
793
+ * key is fine). A 409 `generation_in_progress`
795
794
  * (Retry-After 5) means the run that key names is still placing its
796
795
  * credit hold.
797
796
  *
@@ -2460,6 +2459,26 @@ export class Vxil {
2460
2459
  });
2461
2460
  return (await this.call('GET', `/v1/payments/usage${s}`)).data;
2462
2461
  },
2462
+ /** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
2463
+ * reconciliation or a warehouse sync. Keyset-paged: pass the prior page's
2464
+ * `next_cursor` as `cursor` until it is null; start at `since` (inclusive
2465
+ * ISO-8601). To tail later, start a new walk with `since` = the last
2466
+ * `created_at` you stored MINUS an overlap (a minute) and dedupe on
2467
+ * `ledger_entry_id` — `created_at` is the writing transaction's start, so
2468
+ * a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
2469
+ * Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
2470
+ * (`end_user_required`) key gets 403 `server_only` (use `usage` for one
2471
+ * user's own rows). */
2472
+ ledger: async (q) => {
2473
+ const suffix = qs({
2474
+ since: q?.since || undefined,
2475
+ cursor: q?.cursor || undefined,
2476
+ user_id: q?.user_id || undefined,
2477
+ credit_type: q?.credit_type || undefined,
2478
+ limit: q?.limit || undefined,
2479
+ });
2480
+ return (await this.call('GET', `/v1/payments/credits/ledger${suffix}`)).data;
2481
+ },
2463
2482
  /** Start a subscription (mock = instant checkout; real providers redirect via
2464
2483
  * their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
2465
2484
  * ref. Returns the vxil subscription_id + provider sub id + status. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.19.0",
3
+ "version": "0.20.1",
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).",