@vxil/sdk 0.35.2 → 0.36.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 {
@@ -957,7 +974,9 @@ export interface PaymentsWebhookEvent {
957
974
  /** received | processed | error | sig_failed | parse_failed | reprocessed |
958
975
  * ignored (a well-formed provider type we deliberately do not fold) |
959
976
  * unowned (no end user resolvable) | rejected_environment (a sandbox event
960
- * the tenant did not opt into) — the last three are 200-acked, never folded. */
977
+ * the tenant did not opt into) | rejected_test_store (a RevenueCat Test Store
978
+ * purchase under `revenuecat.testStore: 'reject'`) — the last four are
979
+ * 200-acked, never folded. */
961
980
  outcome: string | null;
962
981
  /** the PROVIDER-reported environment of the delivery ('production' |
963
982
  * 'sandbox') — a separate axis from the API key's live/test label. */
@@ -3707,10 +3726,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3707
3726
  * one (password removed, codes and links spent, social links deleted,
3708
3727
  * sessions revoked, the e-mail free at once), so one call is a full
3709
3728
  * account delete — the same as `auth.users.erase` (see guide ch. 9).
3729
+ * With { erase: true } the answer's `cms` counts the rows deleted per cms
3730
+ * collection opted into `onOwnerErase: 'delete'` (the erase event's counts;
3731
+ * a repeat erase answers {}).
3710
3732
  */
3711
3733
  delete: (id: string, opts?: {
3712
3734
  erase?: boolean;
3713
- }) => Promise<void>;
3735
+ }) => Promise<VxilUserDeleteResult>;
3714
3736
  /**
3715
3737
  * Merge a REGISTRY-ONLY user (a row you created with upsert that never
3716
3738
  * signed in) INTO another user of the tenant: its attributes fill the
@@ -4779,11 +4801,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4779
4801
  * no-op. Meant to be called from a "delete my account" server route or
4780
4802
  * vxil function (which declares `auth:write`). In END-USER mode the call
4781
4803
  * is SELF-only: `userId` must be the signed-in user, any other id throws
4782
- * 403 `server_only` (a thin client can never erase someone else). */
4783
- erase: (userId: string) => Promise<{
4784
- user_id: string;
4785
- erased: boolean;
4786
- }>;
4804
+ * 403 `server_only` (a thin client can never erase someone else).
4805
+ * `cms` counts the rows deleted per cms collection opted into
4806
+ * `onOwnerErase: 'delete'` — the same object as the `auth.user.erased`
4807
+ * event's; a repeat call deletes nothing and answers `{}`. In END-USER
4808
+ * mode it lists only the collections that user can read (an
4809
+ * `endUserAccess: 'none'` collection is erased, and counted in the
4810
+ * event, but left out of the answer). */
4811
+ erase: (userId: string) => Promise<VxilAuthEraseResult>;
4787
4812
  /** LIVE-APP MIGRATION (server only, `auth:write`; 1–500 ids per call):
4788
4813
  * give ids already registered through `users.bulk` their sign-in
4789
4814
  * identity, carrying each user's SOURCE password hash — bcrypt
@@ -7675,7 +7700,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7675
7700
  tier: string;
7676
7701
  }>;
7677
7702
  /** Cancel a subscription. `atPeriodEnd` true keeps entitlements until the
7678
- * period closes; false revokes immediately and re-folds entitlements. */
7703
+ * period closes; false revokes immediately and re-folds entitlements.
7704
+ *
7705
+ * When the PROVIDER refuses the cancel on its merits, it throws a
7706
+ * VxilError with status 422 and code `provider_refused`; when the
7707
+ * provider holds the subscription for a moment (a lock that clears on its
7708
+ * own, e.g. a renewal in progress), status 409 and code `provider_locked`
7709
+ * (retry later). Both carry `details: { provider, provider_status,
7710
+ * provider_code }`, where `provider_code` is the provider's own error code
7711
+ * (Paddle: `subscription_update_when_past_due` refuses a period-end cancel
7712
+ * on a past-due subscription; fall back to `atPeriodEnd: false`). Neither
7713
+ * is auto-retried. A provider outage stays 502 `provider_error`. */
7679
7714
  cancel: (subscriptionId: string, opts?: {
7680
7715
  atPeriodEnd?: boolean;
7681
7716
  }) => Promise<{
@@ -7761,9 +7796,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7761
7796
  * was already issued in the provider's own dashboard, which vxil's running
7762
7797
  * total cannot see — the call returns 422 `refund_not_allocatable` with the
7763
7798
  * precise reason, and nothing is sent to the provider. It is deterministic:
7764
- * retrying the same refund fails the same way. A provider call that actually
7765
- * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
7766
- * (the row that went `failed`) so you can tie them to this call.
7799
+ * retrying the same refund fails the same way. A refund the PROVIDER itself
7800
+ * refuses on its merits returns 422 `provider_refused`; one it holds for a
7801
+ * moment (a lock that clears on its own) returns 409 `provider_locked`:
7802
+ * retry it later with a NEW Idempotency-Key, because the same key replays
7803
+ * this failed refund. Both carry `details: { provider, provider_status,
7804
+ * provider_code }` (`provider_code` is the provider's own error code). A
7805
+ * provider call that actually fails (an outage, a 5xx, a 429) is still 502
7806
+ * `provider_error`. Every failure body carries `refund_id` (the row that
7807
+ * went `failed`) so you can tie it to this call.
7767
7808
  *
7768
7809
  * A refund ends access in vxil but the PROVIDER subscription keeps billing
7769
7810
  * until it is cancelled. `cancel: 'period_end'` stops it at period end once
@@ -7829,8 +7870,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7829
7870
  charge_id: string | null;
7830
7871
  replayed: boolean;
7831
7872
  }>;
7832
- /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
7833
- * subscription — use `cancel`). Never touches a provider. */
7873
+ /** SERVER-ONLY. Revoke a MANUAL grant, or a sandbox / Test Store
7874
+ * RevenueCat subscription, now (409 not_manual for any other provider
7875
+ * subscription — use `cancel`; a production store row ends when the store
7876
+ * cancels or refunds it). Never touches a provider; a revoked RevenueCat
7877
+ * 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. */
7834
7880
  revokeSubscription: (subscriptionId: string) => Promise<{
7835
7881
  subscription_id: string;
7836
7882
  status: string;
@@ -7984,7 +8030,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7984
8030
  list: (q?: {
7985
8031
  provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
7986
8032
  event_type?: string;
7987
- outcome?: "received" | "processed" | "error" | "sig_failed" | "parse_failed" | "reprocessed" | "ignored" | "unowned" | "rejected_environment";
8033
+ outcome?: "received" | "processed" | "error" | "sig_failed" | "parse_failed" | "reprocessed" | "ignored" | "unowned" | "rejected_environment" | "rejected_test_store";
7988
8034
  /** the provider-reported environment axis (not the API key's label) */
7989
8035
  environment?: "production" | "sandbox";
7990
8036
  /** exact match on the normalised charge id (= `payments.charge.*`'s
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
@@ -3030,7 +3037,17 @@ export class Vxil {
3030
3037
  * ref. Returns the vxil subscription_id + provider sub id + status. */
3031
3038
  subscribe: async (input) => (await this.call('POST', '/v1/payments/subscriptions', input)).data,
3032
3039
  /** Cancel a subscription. `atPeriodEnd` true keeps entitlements until the
3033
- * period closes; false revokes immediately and re-folds entitlements. */
3040
+ * period closes; false revokes immediately and re-folds entitlements.
3041
+ *
3042
+ * When the PROVIDER refuses the cancel on its merits, it throws a
3043
+ * VxilError with status 422 and code `provider_refused`; when the
3044
+ * provider holds the subscription for a moment (a lock that clears on its
3045
+ * own, e.g. a renewal in progress), status 409 and code `provider_locked`
3046
+ * (retry later). Both carry `details: { provider, provider_status,
3047
+ * provider_code }`, where `provider_code` is the provider's own error code
3048
+ * (Paddle: `subscription_update_when_past_due` refuses a period-end cancel
3049
+ * on a past-due subscription; fall back to `atPeriodEnd: false`). Neither
3050
+ * is auto-retried. A provider outage stays 502 `provider_error`. */
3034
3051
  cancel: async (subscriptionId, opts) => (await this.call('DELETE', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}${opts?.atPeriodEnd ? '?at_period_end=true' : ''}`)).data,
3035
3052
  /** List subscriptions (the cancel enabler — discover the subscription_id);
3036
3053
  * optionally scoped to one user / status. Each row carries its own
@@ -3080,9 +3097,15 @@ export class Vxil {
3080
3097
  * was already issued in the provider's own dashboard, which vxil's running
3081
3098
  * total cannot see — the call returns 422 `refund_not_allocatable` with the
3082
3099
  * 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.
3100
+ * retrying the same refund fails the same way. A refund the PROVIDER itself
3101
+ * refuses on its merits returns 422 `provider_refused`; one it holds for a
3102
+ * moment (a lock that clears on its own) returns 409 `provider_locked`:
3103
+ * retry it later with a NEW Idempotency-Key, because the same key replays
3104
+ * this failed refund. Both carry `details: { provider, provider_status,
3105
+ * provider_code }` (`provider_code` is the provider's own error code). A
3106
+ * provider call that actually fails (an outage, a 5xx, a 429) is still 502
3107
+ * `provider_error`. Every failure body carries `refund_id` (the row that
3108
+ * went `failed`) so you can tie it to this call.
3086
3109
  *
3087
3110
  * A refund ends access in vxil but the PROVIDER subscription keeps billing
3088
3111
  * until it is cancelled. `cancel: 'period_end'` stops it at period end once
@@ -3118,8 +3141,13 @@ export class Vxil {
3118
3141
  * `until` reaches past a live same-tier manual row (a grant or a pass with
3119
3142
  * an end) starts where that row ends — `since` names that start. */
3120
3143
  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. */
3144
+ /** SERVER-ONLY. Revoke a MANUAL grant, or a sandbox / Test Store
3145
+ * RevenueCat subscription, now (409 not_manual for any other provider
3146
+ * subscription — use `cancel`; a production store row ends when the store
3147
+ * cancels or refunds it). Never touches a provider; a revoked RevenueCat
3148
+ * 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. */
3123
3151
  revokeSubscription: async (subscriptionId) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/revoke`)).data,
3124
3152
  /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
3125
3153
  * 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.2",
3
+ "version": "0.36.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).",