@vxil/sdk 0.36.0 → 0.37.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
@@ -341,6 +341,10 @@ export interface FeatureConfig {
341
341
  /** cms writes only (PUT /v1/config/cms): what the write changed in
342
342
  * `features.cms.rules[]` (the App builder apps' rules). */
343
343
  rules_summary?: ConfigRulesSummary;
344
+ /** A config write whose body had top-level keys the feature does not declare
345
+ * (every feature but cms, which answers 422): those keys were not stored,
346
+ * and a setting sent under a misspelled key keeps its default. */
347
+ warnings?: string[];
344
348
  }
345
349
  /** One rules[] entry as a cms config write reports it. */
346
350
  export interface ConfigRuleLine {
@@ -908,6 +912,20 @@ export type JobSchedulePatch = Partial<Omit<JobScheduleInput, 'external_id' | 'm
908
912
  external_id?: string | null;
909
913
  max_attempts?: number | null;
910
914
  };
915
+ /** One listed session of `vx.auth.sessions.list` (`GET /v1/auth/sessions`). */
916
+ export interface VxilAuthSessionInfo {
917
+ session_id: string;
918
+ created_at: string;
919
+ /** when the ACCESS token expires */
920
+ expires_at: string;
921
+ user_agent: string | null;
922
+ /** `active` while the access token is valid; `idle` when only the refresh
923
+ * token is (the device has not refreshed yet). */
924
+ state: 'active' | 'idle';
925
+ /** when the refresh token stops working (created_at + session.refreshTtlDays);
926
+ * null for a canary session, which never refreshes. */
927
+ refresh_expires_at: string | null;
928
+ }
911
929
  export interface AuthSession {
912
930
  token: string;
913
931
  refresh_token: string;
@@ -1006,6 +1024,12 @@ export interface PaymentsSyncOutcome {
1006
1024
  tier: string | null;
1007
1025
  until: string | null;
1008
1026
  }>;
1027
+ /** RevenueCat only, present only when non-empty: products the sync
1028
+ * deliberately did not fold, `<id>: <why>` (`<id>: not_restored` on an
1029
+ * end-user restore) — an ended product matching no store purchase, a
1030
+ * purchase the store ended inside the same period, a product whose own
1031
+ * row belongs to another store. Not errors: nothing was written. */
1032
+ not_folded?: string[];
1009
1033
  dry_run?: boolean;
1010
1034
  }
1011
1035
  /** A lifecycle simulation run (guide ch. 6, payments; mock/dev tenants only). */
@@ -4972,13 +4996,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4972
4996
  revokeById: (sessionId: string) => Promise<void>;
4973
4997
  /** List a user's active sessions (the account "signed-in devices" surface).
4974
4998
  * Scope `auth:read`. In end-user mode the list is bound to the signed-in
4975
- * user regardless of `userId` (the verified principal wins). */
4976
- list: (userId: string) => Promise<Array<{
4977
- session_id: string;
4978
- created_at: string;
4979
- expires_at: string;
4980
- user_agent: string | null;
4981
- }>>;
4999
+ * user regardless of `userId` (the verified principal wins). Each
5000
+ * session says `state` — `active` while its access token is valid,
5001
+ * `idle` when only its refresh token is — and `refresh_expires_at`
5002
+ * (null for a canary session, which never refreshes). Today only
5003
+ * `active` sessions are listed; idle devices are listed (and counted by
5004
+ * `session.maxConcurrent`) from the release the changelog's Coming next
5005
+ * names. */
5006
+ list: (userId: string) => Promise<Array<VxilAuthSessionInfo>>;
4982
5007
  };
4983
5008
  password: {
4984
5009
  /** Always resolves (anti-enumeration). `captcha_token` is required only
@@ -6734,10 +6759,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6734
6759
  * download; omitted = raster images inline, everything else attachment.
6735
6760
  * `filename` sets the name the browser saves (sanitised server-side:
6736
6761
  * control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
6737
- * RFC 6266 `filename*`), default the upload's filename. */
6762
+ * RFC 6266 `filename*`), default the upload's filename. `user_id`
6763
+ * (narrowing only): minted only when the object is that end user's
6764
+ * personal upload, else 404 — a server acting for one user never hands
6765
+ * out someone else's file. */
6738
6766
  downloadUrl: (objectId: string, opts?: {
6739
6767
  disposition?: "inline" | "attachment";
6740
6768
  filename?: string;
6769
+ user_id?: string;
6741
6770
  }) => Promise<string>;
6742
6771
  /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
6743
6772
  * — a gallery page costs one request, not one per image. `urls[]` keeps
@@ -7875,8 +7904,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7875
7904
  * subscription — use `cancel`; a production store row ends when the store
7876
7905
  * cancels or refunds it). Never touches a provider; a revoked RevenueCat
7877
7906
  * row is never revived by a later sandbox delivery or restore (a real
7878
- * production purchase still entitles the user). Credits the row
7879
- * already granted stay. */
7907
+ * production purchase still entitles the user). Revoke the user's
7908
+ * restored (`<app user id>:<product>`) row too if they have one: it is a
7909
+ * separate row. Credits the row already granted stay. */
7880
7910
  revokeSubscription: (subscriptionId: string) => Promise<{
7881
7911
  subscription_id: string;
7882
7912
  status: string;
@@ -7884,10 +7914,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7884
7914
  revoked_at: string | null;
7885
7915
  }>;
7886
7916
  /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
7887
- * fold them through the same conditional upsert a webhook uses (never a
7888
- * second write path). `dry_run` diffs without writing. Capped 30/min per
7889
- * project (429 rate_limited). The migration backfill (`vxil migrate
7890
- * payments --from-provider …`) drives this per customer. */
7917
+ * fold them through the same conditional upsert a webhook uses (a stale
7918
+ * snapshot never moves a newer row). `dry_run` diffs without writing.
7919
+ * Capped 30/min per project (429 rate_limited). The migration backfill
7920
+ * (`vxil migrate payments --from-provider …`) drives this per customer.
7921
+ *
7922
+ * RevenueCat: the subscriber read has no original transaction id, so a
7923
+ * snapshot is matched to the webhook row of the SAME store purchase — an
7924
+ * ended product only by its exact store transaction (else it is listed in
7925
+ * `not_folded` and nothing is written); a live one also by a live row of the
7926
+ * same store, environment and current product. With no match a live
7927
+ * product gets its own row (`<app user id>:<product>`) that ends at its
7928
+ * own period end and that the purchase's first webhook takes over. Emits
7929
+ * `payments.subscription.<status>` (`event_type: 'subscription.synced'`)
7930
+ * for each row it changes and `payments.entitlement.changed` (`reason:
7931
+ * 'subscription.synced'`) when access changed. */
7891
7932
  syncSubscriptions: (input: {
7892
7933
  user_id?: string;
7893
7934
  customer_ref?: string;
@@ -7897,7 +7938,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7897
7938
  /** The server leg of "Restore Purchases": in end-user mode the verified
7898
7939
  * principal's OWN provider state is re-read (no user id needed); in server
7899
7940
  * mode pass `user_id`. 3 per hour per user (429). Returns the sync outcome
7900
- * plus the fresh entitlement view in one answer. */
7941
+ * plus the fresh entitlement view in one answer. The same matching and
7942
+ * events as `syncSubscriptions`, with `event_type` / `reason`
7943
+ * `'subscription.restored'`; in end-user mode an unmatched ended product
7944
+ * is listed in `not_folded` as `<id>: not_restored`. */
7901
7945
  restoreSubscriptions: (input?: {
7902
7946
  user_id?: string;
7903
7947
  provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
package/dist/index.js CHANGED
@@ -1520,7 +1520,13 @@ export class Vxil {
1520
1520
  },
1521
1521
  /** List a user's active sessions (the account "signed-in devices" surface).
1522
1522
  * Scope `auth:read`. In end-user mode the list is bound to the signed-in
1523
- * user regardless of `userId` (the verified principal wins). */
1523
+ * user regardless of `userId` (the verified principal wins). Each
1524
+ * session says `state` — `active` while its access token is valid,
1525
+ * `idle` when only its refresh token is — and `refresh_expires_at`
1526
+ * (null for a canary session, which never refreshes). Today only
1527
+ * `active` sessions are listed; idle devices are listed (and counted by
1528
+ * `session.maxConcurrent`) from the release the changelog's Coming next
1529
+ * names. */
1524
1530
  list: async (userId) => (await this.call('GET', `/v1/auth/sessions?user_id=${encodeURIComponent(userId)}`)).data.sessions,
1525
1531
  },
1526
1532
  password: {
@@ -2532,13 +2538,19 @@ export class Vxil {
2532
2538
  * download; omitted = raster images inline, everything else attachment.
2533
2539
  * `filename` sets the name the browser saves (sanitised server-side:
2534
2540
  * control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
2535
- * RFC 6266 `filename*`), default the upload's filename. */
2541
+ * RFC 6266 `filename*`), default the upload's filename. `user_id`
2542
+ * (narrowing only): minted only when the object is that end user's
2543
+ * personal upload, else 404 — a server acting for one user never hands
2544
+ * out someone else's file. */
2536
2545
  downloadUrl: async (objectId, opts = {}) => {
2537
2546
  const q = [];
2538
2547
  if (opts.disposition !== undefined)
2539
2548
  q.push(`disposition=${encodeURIComponent(opts.disposition)}`);
2540
2549
  if (opts.filename !== undefined)
2541
2550
  q.push(`filename=${encodeURIComponent(opts.filename)}`);
2551
+ // narrowing only: minted only when the object is this end user's personal upload (else 404)
2552
+ if (opts.user_id !== undefined)
2553
+ q.push(`user_id=${encodeURIComponent(opts.user_id)}`);
2542
2554
  const qs = q.join('&');
2543
2555
  return (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url${qs ? `?${qs}` : ''}`)).data.download_url;
2544
2556
  },
@@ -3146,19 +3158,34 @@ export class Vxil {
3146
3158
  * subscription — use `cancel`; a production store row ends when the store
3147
3159
  * cancels or refunds it). Never touches a provider; a revoked RevenueCat
3148
3160
  * row is never revived by a later sandbox delivery or restore (a real
3149
- * production purchase still entitles the user). Credits the row
3150
- * already granted stay. */
3161
+ * production purchase still entitles the user). Revoke the user's
3162
+ * restored (`<app user id>:<product>`) row too if they have one: it is a
3163
+ * separate row. Credits the row already granted stay. */
3151
3164
  revokeSubscription: async (subscriptionId) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/revoke`)).data,
3152
3165
  /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
3153
- * fold them through the same conditional upsert a webhook uses (never a
3154
- * second write path). `dry_run` diffs without writing. Capped 30/min per
3155
- * project (429 rate_limited). The migration backfill (`vxil migrate
3156
- * payments --from-provider …`) drives this per customer. */
3166
+ * fold them through the same conditional upsert a webhook uses (a stale
3167
+ * snapshot never moves a newer row). `dry_run` diffs without writing.
3168
+ * Capped 30/min per project (429 rate_limited). The migration backfill
3169
+ * (`vxil migrate payments --from-provider …`) drives this per customer.
3170
+ *
3171
+ * RevenueCat: the subscriber read has no original transaction id, so a
3172
+ * snapshot is matched to the webhook row of the SAME store purchase — an
3173
+ * ended product only by its exact store transaction (else it is listed in
3174
+ * `not_folded` and nothing is written); a live one also by a live row of the
3175
+ * same store, environment and current product. With no match a live
3176
+ * product gets its own row (`<app user id>:<product>`) that ends at its
3177
+ * own period end and that the purchase's first webhook takes over. Emits
3178
+ * `payments.subscription.<status>` (`event_type: 'subscription.synced'`)
3179
+ * for each row it changes and `payments.entitlement.changed` (`reason:
3180
+ * 'subscription.synced'`) when access changed. */
3157
3181
  syncSubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/sync', input)).data,
3158
3182
  /** The server leg of "Restore Purchases": in end-user mode the verified
3159
3183
  * principal's OWN provider state is re-read (no user id needed); in server
3160
3184
  * mode pass `user_id`. 3 per hour per user (429). Returns the sync outcome
3161
- * plus the fresh entitlement view in one answer. */
3185
+ * plus the fresh entitlement view in one answer. The same matching and
3186
+ * events as `syncSubscriptions`, with `event_type` / `reason`
3187
+ * `'subscription.restored'`; in end-user mode an unmatched ended product
3188
+ * is listed in `not_folded` as `<id>: not_restored`. */
3162
3189
  restoreSubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/restore', input ?? {})).data,
3163
3190
  /** SERVER-ONLY. Account merge: move EVERY provider's subscriptions,
3164
3191
  * customer links and available credit balances of `from_user_id` onto
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.36.0",
3
+ "version": "0.37.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).",