@vxil/sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -562,6 +562,30 @@ export interface PaymentsCharge {
     status: string;
     created_at: string;
 }
+/** A subscription row as listed by GET /v1/payments/subscriptions (payments.md
+ *  §3) — provider subscriptions, manual grants and purchase passes alike.
+ *  `current_period_start` (2026-09-25) is the row's own window start: for a
+ *  purchase pass (`provider_sub_id: 'purchase:<charge_id>'`) the day its access
+ *  begins, which is in the FUTURE for a pass queued behind a live one; for a
+ *  manual grant the time the grant was written. A `type` with an index
+ *  signature (not an interface), so code that typed these rows as
+ *  `Record<string, unknown>` keeps compiling. */
+export type PaymentsSubscription = {
+    subscription_id: string;
+    end_user_id: string;
+    /** 'manual' for a support grant or a purchase pass; else the provider */
+    provider: string;
+    provider_sub_id: string;
+    tier: string | null;
+    /** trialing | active | past_due | cancelled | expired | lapsed */
+    status: string;
+    current_period_start: string | null;
+    current_period_end: string | null;
+    /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
+    charge_id: string | null;
+    created_at: string;
+    [key: string]: unknown;
+};
 export interface FileObject {
     object_id: string;
     filename: string;
@@ -2489,7 +2513,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             run_id: string;
             state: string;
         }>;
-        /** Clone a terminal run into a fresh queued run. */
+        /** Clone a terminal run into a fresh queued run. A generation run answers
+         *  `409 not_replayable` — submit the generation again instead. */
         replay: (runId: string) => Promise<{
             run_id: string;
             replayed_from: string;
@@ -2804,8 +2829,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  refresh token in one process share ONE rotation, and for 30 s after it
              *  settles a call still carrying the OLD pair gets the new pair (no second
              *  request) while a call with the just-minted pair gets it back unchanged.
-             *  A refresh that fails (revoked, expired, or already rotated by another
-             *  process) throws the `VxilError` — treat it as "sign in again".
+             *  A refresh that fails throws the `VxilError`. A `401 invalid_refresh`
+             *  can be a rotation another process (another server instance) just
+             *  made, so do not clear the session on the first one — keep the cookie
+             *  and treat only a repeat failure of the same pair after a short grace
+             *  as "sign in again"; see guide 09's refresh recipe.
              *
              *  Call it on a client whose key carries `auth:signin` — normally the
              *  sign-in key, in server mode. An end-user-mode client sends its
@@ -2965,9 +2993,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * Consume budget. With behavior 'block' an exceeded check throws
          * VxilError(429); 'shape' resolves with allowed=false instead.
          * `override_id` is present when a per-identifier override was applied.
+         * Name the policy by EXACTLY ONE of `policy_id` or `policy` (its name —
+         * unique per project, and it survives a delete-and-recreate). An unknown
+         * name is the same 404 `not_found` as an unknown id; a policy created
+         * before 2026-09-23 is found by name once it has been saved or listed again.
          */
-        check: (input: {
+        check: (input: ({
             policy_id: string;
+            policy?: never;
+        } | {
+            policy: string;
+            policy_id?: never;
+        }) & {
             key_values?: Record<string, string>;
             cost?: number;
         }) => Promise<{
@@ -4789,11 +4826,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             cancel_at: string | null;
         }>;
         /** List subscriptions (the cancel enabler — discover the subscription_id);
-         *  optionally scoped to one user / status. */
+         *  optionally scoped to one user / status. Each row carries its own
+         *  window: `current_period_start` … `current_period_end` (a queued pass
+         *  starts in the future). In end-user mode the list is always the signed-in
+         *  user's own rows, whatever `user_id` says. */
         listSubscriptions: (q?: {
             user_id?: string;
             status?: string;
-        }) => Promise<Array<Record<string, unknown>>>;
+        }) => Promise<PaymentsSubscription[]>;
         /**
          * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
          * the returned `url`; completion lands server-side via the provider webhook
@@ -4888,6 +4928,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id: string;
             tier: string;
             status: string;
+            /** (2026-09-25) the grant row's start — the time it was WRITTEN (a replay
+             *  answers the first grant's), never a window you computed */
+            since?: string | null;
             until: string | null;
             charge_id: string | null;
             replayed: boolean;

package/dist/index.js

@@ -699,7 +699,8 @@ export class Vxil {
          *  number to alarm on), in-flight runs per lane, dead letters in 24 h. */
         queue: async () => (await this.call('GET', '/v1/jobs/queue')).data,
         cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
-        /** Clone a terminal run into a fresh queued run. */
+        /** Clone a terminal run into a fresh queued run. A generation run answers
+         *  `409 not_replayable` — submit the generation again instead. */
         replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
         /**
          * Suspend the RUNNING run until an event (call from the executing
@@ -879,8 +880,11 @@ export class Vxil {
              *  refresh token in one process share ONE rotation, and for 30 s after it
              *  settles a call still carrying the OLD pair gets the new pair (no second
              *  request) while a call with the just-minted pair gets it back unchanged.
-             *  A refresh that fails (revoked, expired, or already rotated by another
-             *  process) throws the `VxilError` — treat it as "sign in again".
+             *  A refresh that fails throws the `VxilError`. A `401 invalid_refresh`
+             *  can be a rotation another process (another server instance) just
+             *  made, so do not clear the session on the first one — keep the cookie
+             *  and treat only a repeat failure of the same pair after a short grace
+             *  as "sign in again"; see guide 09's refresh recipe.
              *
              *  Call it on a client whose key carries `auth:signin` — normally the
              *  sign-in key, in server mode. An end-user-mode client sends its
@@ -1017,6 +1021,10 @@ export class Vxil {
          * Consume budget. With behavior 'block' an exceeded check throws
          * VxilError(429); 'shape' resolves with allowed=false instead.
          * `override_id` is present when a per-identifier override was applied.
+         * Name the policy by EXACTLY ONE of `policy_id` or `policy` (its name —
+         * unique per project, and it survives a delete-and-recreate). An unknown
+         * name is the same 404 `not_found` as an unknown id; a policy created
+         * before 2026-09-23 is found by name once it has been saved or listed again.
          */
         check: async (input) => (await this.call('POST', '/v1/rate-limits/check', input)).data,
         /** Per-identifier overrides layered over a policy: `pattern` matches the
@@ -1967,7 +1975,10 @@ export class Vxil {
          *  period closes; false revokes immediately and re-folds entitlements. */
         cancel: async (subscriptionId, opts) => (await this.call('DELETE', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}${opts?.atPeriodEnd ? '?at_period_end=true' : ''}`)).data,
         /** List subscriptions (the cancel enabler — discover the subscription_id);
-         *  optionally scoped to one user / status. */
+         *  optionally scoped to one user / status. Each row carries its own
+         *  window: `current_period_start` … `current_period_end` (a queued pass
+         *  starts in the future). In end-user mode the list is always the signed-in
+         *  user's own rows, whatever `user_id` says. */
         listSubscriptions: async (q) => {
             const s = qs({ user_id: q?.user_id || undefined, status: q?.status || undefined });
             return (await this.call('GET', `/v1/payments/subscriptions${s}`)).data.subscriptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",