@vxil/sdk 0.35.3 → 0.37.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
@@ -215,6 +215,23 @@ export interface VxilUser {
215
215
  /** Set when the row's PII was scrubbed via DELETE /v1/users/:id?erase=true (GDPR Article 17). null = retained. */
216
216
  erased_at?: string | null;
217
217
  }
218
+ /** Rows a GDPR erase deleted per cms collection opted into on_owner_erase
219
+ * 'delete' ({ [collection]: count }; a collection that lost no rows is left
220
+ * out) — the same object as the erase event's `cms`. */
221
+ export type VxilEraseCmsCounts = Record<string, number>;
222
+ /** DELETE /v1/users/:id answer; `erased` and `cms` only with { erase: true }. */
223
+ export interface VxilUserDeleteResult {
224
+ id: string;
225
+ deleted: true;
226
+ erased?: true;
227
+ cms?: VxilEraseCmsCounts;
228
+ }
229
+ /** POST /v1/auth/users/:id/erase answer. */
230
+ export interface VxilAuthEraseResult {
231
+ user_id: string;
232
+ erased: boolean;
233
+ cms: VxilEraseCmsCounts;
234
+ }
218
235
  /** POST /v1/users and POST /v1/users/bulk entry. A full replace on upsert:
219
236
  * an omitted field is cleared on an existing user. */
220
237
  export interface VxilUserInput {
@@ -324,6 +341,10 @@ export interface FeatureConfig {
324
341
  /** cms writes only (PUT /v1/config/cms): what the write changed in
325
342
  * `features.cms.rules[]` (the App builder apps' rules). */
326
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[];
327
348
  }
328
349
  /** One rules[] entry as a cms config write reports it. */
329
350
  export interface ConfigRuleLine {
@@ -3709,10 +3730,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3709
3730
  * one (password removed, codes and links spent, social links deleted,
3710
3731
  * sessions revoked, the e-mail free at once), so one call is a full
3711
3732
  * account delete — the same as `auth.users.erase` (see guide ch. 9).
3733
+ * With { erase: true } the answer's `cms` counts the rows deleted per cms
3734
+ * collection opted into `onOwnerErase: 'delete'` (the erase event's counts;
3735
+ * a repeat erase answers {}).
3712
3736
  */
3713
3737
  delete: (id: string, opts?: {
3714
3738
  erase?: boolean;
3715
- }) => Promise<void>;
3739
+ }) => Promise<VxilUserDeleteResult>;
3716
3740
  /**
3717
3741
  * Merge a REGISTRY-ONLY user (a row you created with upsert that never
3718
3742
  * signed in) INTO another user of the tenant: its attributes fill the
@@ -4781,11 +4805,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4781
4805
  * no-op. Meant to be called from a "delete my account" server route or
4782
4806
  * vxil function (which declares `auth:write`). In END-USER mode the call
4783
4807
  * is SELF-only: `userId` must be the signed-in user, any other id throws
4784
- * 403 `server_only` (a thin client can never erase someone else). */
4785
- erase: (userId: string) => Promise<{
4786
- user_id: string;
4787
- erased: boolean;
4788
- }>;
4808
+ * 403 `server_only` (a thin client can never erase someone else).
4809
+ * `cms` counts the rows deleted per cms collection opted into
4810
+ * `onOwnerErase: 'delete'` — the same object as the `auth.user.erased`
4811
+ * event's; a repeat call deletes nothing and answers `{}`. In END-USER
4812
+ * mode it lists only the collections that user can read (an
4813
+ * `endUserAccess: 'none'` collection is erased, and counted in the
4814
+ * event, but left out of the answer). */
4815
+ erase: (userId: string) => Promise<VxilAuthEraseResult>;
4789
4816
  /** LIVE-APP MIGRATION (server only, `auth:write`; 1–500 ids per call):
4790
4817
  * give ids already registered through `users.bulk` their sign-in
4791
4818
  * identity, carrying each user's SOURCE password hash — bcrypt
@@ -6711,10 +6738,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6711
6738
  * download; omitted = raster images inline, everything else attachment.
6712
6739
  * `filename` sets the name the browser saves (sanitised server-side:
6713
6740
  * control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
6714
- * RFC 6266 `filename*`), default the upload's filename. */
6741
+ * RFC 6266 `filename*`), default the upload's filename. `user_id`
6742
+ * (narrowing only): minted only when the object is that end user's
6743
+ * personal upload, else 404 — a server acting for one user never hands
6744
+ * out someone else's file. */
6715
6745
  downloadUrl: (objectId: string, opts?: {
6716
6746
  disposition?: "inline" | "attachment";
6717
6747
  filename?: string;
6748
+ user_id?: string;
6718
6749
  }) => Promise<string>;
6719
6750
  /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
6720
6751
  * — a gallery page costs one request, not one per image. `urls[]` keeps
@@ -7677,7 +7708,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7677
7708
  tier: string;
7678
7709
  }>;
7679
7710
  /** Cancel a subscription. `atPeriodEnd` true keeps entitlements until the
7680
- * period closes; false revokes immediately and re-folds entitlements. */
7711
+ * period closes; false revokes immediately and re-folds entitlements.
7712
+ *
7713
+ * When the PROVIDER refuses the cancel on its merits, it throws a
7714
+ * VxilError with status 422 and code `provider_refused`; when the
7715
+ * provider holds the subscription for a moment (a lock that clears on its
7716
+ * own, e.g. a renewal in progress), status 409 and code `provider_locked`
7717
+ * (retry later). Both carry `details: { provider, provider_status,
7718
+ * provider_code }`, where `provider_code` is the provider's own error code
7719
+ * (Paddle: `subscription_update_when_past_due` refuses a period-end cancel
7720
+ * on a past-due subscription; fall back to `atPeriodEnd: false`). Neither
7721
+ * is auto-retried. A provider outage stays 502 `provider_error`. */
7681
7722
  cancel: (subscriptionId: string, opts?: {
7682
7723
  atPeriodEnd?: boolean;
7683
7724
  }) => Promise<{
@@ -7763,9 +7804,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7763
7804
  * was already issued in the provider's own dashboard, which vxil's running
7764
7805
  * total cannot see — the call returns 422 `refund_not_allocatable` with the
7765
7806
  * precise reason, and nothing is sent to the provider. It is deterministic:
7766
- * retrying the same refund fails the same way. A provider call that actually
7767
- * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
7768
- * (the row that went `failed`) so you can tie them to this call.
7807
+ * retrying the same refund fails the same way. A refund the PROVIDER itself
7808
+ * refuses on its merits returns 422 `provider_refused`; one it holds for a
7809
+ * moment (a lock that clears on its own) returns 409 `provider_locked`:
7810
+ * retry it later with a NEW Idempotency-Key, because the same key replays
7811
+ * this failed refund. Both carry `details: { provider, provider_status,
7812
+ * provider_code }` (`provider_code` is the provider's own error code). A
7813
+ * provider call that actually fails (an outage, a 5xx, a 429) is still 502
7814
+ * `provider_error`. Every failure body carries `refund_id` (the row that
7815
+ * went `failed`) so you can tie it to this call.
7769
7816
  *
7770
7817
  * A refund ends access in vxil but the PROVIDER subscription keeps billing
7771
7818
  * until it is cancelled. `cancel: 'period_end'` stops it at period end once
@@ -7831,8 +7878,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7831
7878
  charge_id: string | null;
7832
7879
  replayed: boolean;
7833
7880
  }>;
7834
- /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
7835
- * subscription — use `cancel`). Never touches a provider. */
7881
+ /** SERVER-ONLY. Revoke a MANUAL grant, or a sandbox / Test Store
7882
+ * RevenueCat subscription, now (409 not_manual for any other provider
7883
+ * subscription — use `cancel`; a production store row ends when the store
7884
+ * cancels or refunds it). Never touches a provider; a revoked RevenueCat
7885
+ * row is never revived by a later sandbox delivery or restore (a real
7886
+ * production purchase still entitles the user). Credits the row
7887
+ * already granted stay. */
7836
7888
  revokeSubscription: (subscriptionId: string) => Promise<{
7837
7889
  subscription_id: string;
7838
7890
  status: string;
package/dist/index.js CHANGED
@@ -675,10 +675,11 @@ export class Vxil {
675
675
  * one (password removed, codes and links spent, social links deleted,
676
676
  * sessions revoked, the e-mail free at once), so one call is a full
677
677
  * account delete — the same as `auth.users.erase` (see guide ch. 9).
678
+ * With { erase: true } the answer's `cms` counts the rows deleted per cms
679
+ * collection opted into `onOwnerErase: 'delete'` (the erase event's counts;
680
+ * a repeat erase answers {}).
678
681
  */
679
- delete: async (id, opts) => {
680
- await this.call('DELETE', `/v1/users/${encodeURIComponent(id)}${opts?.erase ? '?erase=true' : ''}`);
681
- },
682
+ delete: async (id, opts) => (await this.call('DELETE', `/v1/users/${encodeURIComponent(id)}${opts?.erase ? '?erase=true' : ''}`)).data,
682
683
  /**
683
684
  * Merge a REGISTRY-ONLY user (a row you created with upsert that never
684
685
  * signed in) INTO another user of the tenant: its attributes fill the
@@ -1338,7 +1339,13 @@ export class Vxil {
1338
1339
  * no-op. Meant to be called from a "delete my account" server route or
1339
1340
  * vxil function (which declares `auth:write`). In END-USER mode the call
1340
1341
  * is SELF-only: `userId` must be the signed-in user, any other id throws
1341
- * 403 `server_only` (a thin client can never erase someone else). */
1342
+ * 403 `server_only` (a thin client can never erase someone else).
1343
+ * `cms` counts the rows deleted per cms collection opted into
1344
+ * `onOwnerErase: 'delete'` — the same object as the `auth.user.erased`
1345
+ * event's; a repeat call deletes nothing and answers `{}`. In END-USER
1346
+ * mode it lists only the collections that user can read (an
1347
+ * `endUserAccess: 'none'` collection is erased, and counted in the
1348
+ * event, but left out of the answer). */
1342
1349
  erase: async (userId) => (await this.call('POST', `/v1/auth/users/${encodeURIComponent(userId)}/erase`, {})).data,
1343
1350
  /** LIVE-APP MIGRATION (server only, `auth:write`; 1–500 ids per call):
1344
1351
  * give ids already registered through `users.bulk` their sign-in
@@ -2525,13 +2532,19 @@ export class Vxil {
2525
2532
  * download; omitted = raster images inline, everything else attachment.
2526
2533
  * `filename` sets the name the browser saves (sanitised server-side:
2527
2534
  * control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
2528
- * RFC 6266 `filename*`), default the upload's filename. */
2535
+ * RFC 6266 `filename*`), default the upload's filename. `user_id`
2536
+ * (narrowing only): minted only when the object is that end user's
2537
+ * personal upload, else 404 — a server acting for one user never hands
2538
+ * out someone else's file. */
2529
2539
  downloadUrl: async (objectId, opts = {}) => {
2530
2540
  const q = [];
2531
2541
  if (opts.disposition !== undefined)
2532
2542
  q.push(`disposition=${encodeURIComponent(opts.disposition)}`);
2533
2543
  if (opts.filename !== undefined)
2534
2544
  q.push(`filename=${encodeURIComponent(opts.filename)}`);
2545
+ // narrowing only: minted only when the object is this end user's personal upload (else 404)
2546
+ if (opts.user_id !== undefined)
2547
+ q.push(`user_id=${encodeURIComponent(opts.user_id)}`);
2535
2548
  const qs = q.join('&');
2536
2549
  return (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url${qs ? `?${qs}` : ''}`)).data.download_url;
2537
2550
  },
@@ -3030,7 +3043,17 @@ export class Vxil {
3030
3043
  * ref. Returns the vxil subscription_id + provider sub id + status. */
3031
3044
  subscribe: async (input) => (await this.call('POST', '/v1/payments/subscriptions', input)).data,
3032
3045
  /** Cancel a subscription. `atPeriodEnd` true keeps entitlements until the
3033
- * period closes; false revokes immediately and re-folds entitlements. */
3046
+ * period closes; false revokes immediately and re-folds entitlements.
3047
+ *
3048
+ * When the PROVIDER refuses the cancel on its merits, it throws a
3049
+ * VxilError with status 422 and code `provider_refused`; when the
3050
+ * provider holds the subscription for a moment (a lock that clears on its
3051
+ * own, e.g. a renewal in progress), status 409 and code `provider_locked`
3052
+ * (retry later). Both carry `details: { provider, provider_status,
3053
+ * provider_code }`, where `provider_code` is the provider's own error code
3054
+ * (Paddle: `subscription_update_when_past_due` refuses a period-end cancel
3055
+ * on a past-due subscription; fall back to `atPeriodEnd: false`). Neither
3056
+ * is auto-retried. A provider outage stays 502 `provider_error`. */
3034
3057
  cancel: async (subscriptionId, opts) => (await this.call('DELETE', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}${opts?.atPeriodEnd ? '?at_period_end=true' : ''}`)).data,
3035
3058
  /** List subscriptions (the cancel enabler — discover the subscription_id);
3036
3059
  * optionally scoped to one user / status. Each row carries its own
@@ -3080,9 +3103,15 @@ export class Vxil {
3080
3103
  * was already issued in the provider's own dashboard, which vxil's running
3081
3104
  * total cannot see — the call returns 422 `refund_not_allocatable` with the
3082
3105
  * precise reason, and nothing is sent to the provider. It is deterministic:
3083
- * retrying the same refund fails the same way. A provider call that actually
3084
- * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
3085
- * (the row that went `failed`) so you can tie them to this call.
3106
+ * retrying the same refund fails the same way. A refund the PROVIDER itself
3107
+ * refuses on its merits returns 422 `provider_refused`; one it holds for a
3108
+ * moment (a lock that clears on its own) returns 409 `provider_locked`:
3109
+ * retry it later with a NEW Idempotency-Key, because the same key replays
3110
+ * this failed refund. Both carry `details: { provider, provider_status,
3111
+ * provider_code }` (`provider_code` is the provider's own error code). A
3112
+ * provider call that actually fails (an outage, a 5xx, a 429) is still 502
3113
+ * `provider_error`. Every failure body carries `refund_id` (the row that
3114
+ * went `failed`) so you can tie it to this call.
3086
3115
  *
3087
3116
  * A refund ends access in vxil but the PROVIDER subscription keeps billing
3088
3117
  * until it is cancelled. `cancel: 'period_end'` stops it at period end once
@@ -3118,8 +3147,13 @@ export class Vxil {
3118
3147
  * `until` reaches past a live same-tier manual row (a grant or a pass with
3119
3148
  * an end) starts where that row ends — `since` names that start. */
3120
3149
  grantSubscription: async (input) => (await this.call('POST', '/v1/payments/subscriptions/grant', input)).data,
3121
- /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
3122
- * subscription — use `cancel`). Never touches a provider. */
3150
+ /** SERVER-ONLY. Revoke a MANUAL grant, or a sandbox / Test Store
3151
+ * RevenueCat subscription, now (409 not_manual for any other provider
3152
+ * subscription — use `cancel`; a production store row ends when the store
3153
+ * cancels or refunds it). Never touches a provider; a revoked RevenueCat
3154
+ * row is never revived by a later sandbox delivery or restore (a real
3155
+ * production purchase still entitles the user). Credits the row
3156
+ * already granted stay. */
3123
3157
  revokeSubscription: async (subscriptionId) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/revoke`)).data,
3124
3158
  /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
3125
3159
  * fold them through the same conditional upsert a webhook uses (never a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.35.3",
3
+ "version": "0.37.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).",