@extenshi/pay 0.7.1 → 0.8.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.
Files changed (86) hide show
  1. package/README.md +11 -9
  2. package/dist/api/mock.d.ts +4 -0
  3. package/dist/api/mock.d.ts.map +1 -1
  4. package/dist/api/pay-api.d.ts +10 -3
  5. package/dist/api/pay-api.d.ts.map +1 -1
  6. package/dist/api/transport.d.ts.map +1 -1
  7. package/dist/core/config.d.ts.map +1 -1
  8. package/dist/core/extenshi-pay.d.ts +21 -2
  9. package/dist/core/extenshi-pay.d.ts.map +1 -1
  10. package/dist/core/locale.d.ts +13 -0
  11. package/dist/core/locale.d.ts.map +1 -0
  12. package/dist/core.d.mts +208 -113
  13. package/dist/core.d.ts +208 -113
  14. package/dist/core.js +204 -14
  15. package/dist/core.js.map +1 -1
  16. package/dist/core.mjs +204 -15
  17. package/dist/core.mjs.map +1 -1
  18. package/dist/extenshi-pay-lite.js +204 -14
  19. package/dist/extenshi-pay-lite.js.map +1 -1
  20. package/dist/extenshi-pay-lite.min.js +3 -2
  21. package/dist/extenshi-pay-lite.min.js.map +1 -1
  22. package/dist/extenshi-pay-lite.mjs +204 -15
  23. package/dist/extenshi-pay-lite.mjs.map +1 -1
  24. package/dist/extenshi-pay.cjs.js +1234 -180
  25. package/dist/extenshi-pay.cjs.js.map +1 -1
  26. package/dist/extenshi-pay.d.ts.map +1 -1
  27. package/dist/extenshi-pay.js +1234 -180
  28. package/dist/extenshi-pay.js.map +1 -1
  29. package/dist/extenshi-pay.min.js +3 -2
  30. package/dist/extenshi-pay.min.js.map +1 -1
  31. package/dist/extenshi-pay.min.mjs +3 -2
  32. package/dist/extenshi-pay.min.mjs.map +1 -1
  33. package/dist/extenshi-pay.mjs +1231 -181
  34. package/dist/extenshi-pay.mjs.map +1 -1
  35. package/dist/index.d.mts +268 -117
  36. package/dist/index.d.ts +268 -117
  37. package/dist/lite.d.mts +176 -82
  38. package/dist/lite.d.ts +176 -82
  39. package/dist/lite.d.ts.map +1 -1
  40. package/dist/payment/checkout.d.ts.map +1 -1
  41. package/dist/payment/recovery.d.ts +2 -0
  42. package/dist/payment/recovery.d.ts.map +1 -1
  43. package/dist/payment/withdrawal-waiver.d.ts +26 -0
  44. package/dist/payment/withdrawal-waiver.d.ts.map +1 -0
  45. package/dist/paywall/billing-profile-picker.d.ts +1 -1
  46. package/dist/paywall/billing-profile-picker.d.ts.map +1 -1
  47. package/dist/paywall/i18n.d.ts +94 -0
  48. package/dist/paywall/i18n.d.ts.map +1 -0
  49. package/dist/paywall/index.d.ts +2 -1
  50. package/dist/paywall/index.d.ts.map +1 -1
  51. package/dist/paywall/license-panel.d.ts +4 -1
  52. package/dist/paywall/license-panel.d.ts.map +1 -1
  53. package/dist/paywall/renderer.d.ts +16 -2
  54. package/dist/paywall/renderer.d.ts.map +1 -1
  55. package/dist/paywall/seller-details.d.ts +2 -1
  56. package/dist/paywall/seller-details.d.ts.map +1 -1
  57. package/dist/paywall/strings.d.ts +6 -4
  58. package/dist/paywall/strings.d.ts.map +1 -1
  59. package/dist/paywall.d.mts +93 -7
  60. package/dist/paywall.d.ts +93 -7
  61. package/dist/paywall.js +992 -41
  62. package/dist/paywall.js.map +1 -1
  63. package/dist/paywall.mjs +990 -42
  64. package/dist/paywall.mjs.map +1 -1
  65. package/dist/types/config.d.ts +6 -1
  66. package/dist/types/config.d.ts.map +1 -1
  67. package/dist/types/contract.d.ts +25 -0
  68. package/dist/types/contract.d.ts.map +1 -1
  69. package/dist/types/entitlement.d.ts +22 -0
  70. package/dist/types/entitlement.d.ts.map +1 -1
  71. package/dist/types/errors.d.ts +1 -0
  72. package/dist/types/errors.d.ts.map +1 -1
  73. package/dist/types/paywall.d.ts +15 -2
  74. package/dist/types/paywall.d.ts.map +1 -1
  75. package/dist/version.d.ts +1 -1
  76. package/package.json +2 -2
  77. package/dist/core.esm.js +0 -1681
  78. package/dist/core.esm.js.map +0 -1
  79. package/dist/extenshi-pay-lite.esm.js +0 -1664
  80. package/dist/extenshi-pay-lite.esm.js.map +0 -1
  81. package/dist/extenshi-pay.esm.js +0 -2496
  82. package/dist/extenshi-pay.esm.js.map +0 -1
  83. package/dist/extenshi-pay.esm.min.js +0 -7
  84. package/dist/extenshi-pay.esm.min.js.map +0 -1
  85. package/dist/paywall.esm.js +0 -442
  86. package/dist/paywall.esm.js.map +0 -1
package/dist/lite.d.mts CHANGED
@@ -52,6 +52,28 @@ interface PayOfferResponse {
52
52
  offers: PayOfferDto[];
53
53
  /** Base64 Ed25519 public key for `SignedEntitlement.signature`; null when unsigned. */
54
54
  entitlementPublicKey: string | null;
55
+ /**
56
+ * The language the offers' text is in when the seller translated them
57
+ * (it. 13 T10 L2); absent from older servers and for single-language offers.
58
+ */
59
+ locale?: string;
60
+ /**
61
+ * Set when the paywall must show an unticked withdrawal-waiver checkbox and
62
+ * send the accepted `version` with `createCheckout`. Null when the seller
63
+ * attested the extension is not distributed in the EEA/UK; absent from
64
+ * older servers (the SDK then shows no checkbox).
65
+ */
66
+ withdrawalWaiver?: PayWithdrawalWaiver | null;
67
+ }
68
+ /**
69
+ * Version of the buyer-facing withdrawal waiver text the paywall shows (EU/EEA
70
+ * digital content, Directive 2011/83/EU art. 16(m); UK CCR 2013 reg. 37). The
71
+ * text itself lives in the SDK dictionary under the same version; bump both
72
+ * together so a recorded consent always names the words the buyer saw.
73
+ */
74
+ declare const PAY_WITHDRAWAL_WAIVER_VERSION = "2026-10-v1";
75
+ interface PayWithdrawalWaiver {
76
+ version: string;
55
77
  }
56
78
  interface PayEntitlementItem {
57
79
  /** Optional for old signed caches and older servers. */
@@ -134,6 +156,8 @@ interface PaySellerPublic {
134
156
  /** HTTPS support page or plain email address. */
135
157
  supportUrl: string;
136
158
  termsUrl: string | null;
159
+ /** Optional for older servers: refunds section of the license terms. */
160
+ refundPolicyUrl?: string | null;
137
161
  }
138
162
 
139
163
  declare const ERROR_CODES: {
@@ -150,6 +174,7 @@ declare const ERROR_CODES: {
150
174
  readonly GATEWAY_UNAVAILABLE: "GATEWAY_UNAVAILABLE";
151
175
  readonly CHECKOUT_UNAVAILABLE: "CHECKOUT_UNAVAILABLE";
152
176
  readonly PAYWALL_UNAVAILABLE: "PAYWALL_UNAVAILABLE";
177
+ readonly WITHDRAWAL_WAIVER_REQUIRED: "WITHDRAWAL_WAIVER_REQUIRED";
153
178
  readonly UNKNOWN: "UNKNOWN";
154
179
  };
155
180
  type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
@@ -188,6 +213,11 @@ interface MockData {
188
213
  checkoutEnabled?: boolean;
189
214
  /** How many `claimSession` polls answer `pending` before a mock checkout completes (default 1). */
190
215
  claimAfterPolls?: number;
216
+ /**
217
+ * Offer's withdrawal waiver (default: required, current version, so the
218
+ * paywall previews the checkbox). `null` previews a seller outside the EEA/UK.
219
+ */
220
+ withdrawalWaiver?: PayWithdrawalWaiver | null;
191
221
  }
192
222
  interface ExtenshiPayConfig {
193
223
  /** `pk_ext_` + 32 hex characters, from the project's Monetization tab. */
@@ -224,84 +254,12 @@ interface ResolvedConfig {
224
254
  theme: ThemeConfig;
225
255
  }
226
256
 
257
+ type PaywallMode = 'modal' | 'inline' | 'sidebar' | 'fullscreen' | 'minimal';
227
258
  /**
228
- * HTTP transport for the BFF's tRPC endpoint (`/api/trpc/<procedure>`).
229
- *
230
- * Queries are header-less GETs with `?input=<json>` (a CORS "simple request",
231
- * so no preflight); mutations POST a JSON body. The only things that leave the
232
- * extension are payment inputs and optional recovery session/proof inputs
233
- * and the browser's standard headers — `credentials: 'omit'` keeps cookies out.
234
- * Queries are retried on network / 5xx errors; mutations never are.
235
- */
236
-
237
- type ProcedureKind = 'query' | 'mutation';
238
- interface Transport {
239
- call<T>(procedure: string, kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
240
- }
241
-
242
- /**
243
- * In-memory stand-in for the BFF, used when `mock: true`. Lets an extension be
244
- * developed with no backend: offers and entitlements come from `mockData`, a
245
- * mock checkout completes after `claimAfterPolls` polls and grants the SKU.
246
- */
247
-
248
- type SessionState = 'open' | 'complete' | 'canceled' | 'expired';
249
- interface MockSession {
250
- sku: string;
251
- polls: number;
252
- state: SessionState;
253
- }
254
- declare class MockTransport implements Transport {
255
- private entitlements;
256
- private readonly offers;
257
- private readonly projectName;
258
- private readonly checkoutEnabled;
259
- private readonly claimAfterPolls;
260
- readonly sessions: Map<string, MockSession>;
261
- constructor(data?: MockData);
262
- call<T>(procedure: string, _kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
263
- /** Test/dev helpers. */
264
- setEntitlements(items: PayEntitlementItem[]): void;
265
- cancelSession(sessionId: string): void;
266
- expireSession(sessionId: string): void;
267
- private offerResponse;
268
- private createCheckout;
269
- private claim;
270
- private grant;
271
- private envelope;
272
- }
273
-
274
- /** Typed wrapper over the SDK-facing `pay.*` procedures. Nothing else is ever called. */
275
-
276
- declare class PayApi {
277
- private readonly transport;
278
- private readonly publishableKey;
279
- constructor(transport: Transport, publishableKey: string);
280
- createRestoreSession(claimChallenge: string): Promise<PayRestoreSessionResponse>;
281
- claimRestoreSession(sessionId: string, claimSecret: string): Promise<PayRestoreClaimResponse>;
282
- getOffer(locale?: string | null): Promise<PayOfferResponse>;
283
- createCheckout(sku: string, endUserRef: string, locale?: string | null): Promise<PayCheckoutSession>;
284
- claimSession(sessionId: string, endUserRef: string): Promise<PayCheckoutClaim>;
285
- getEntitlement(endUserRef: string): Promise<SignedEntitlement>;
286
- getPortalUrl(endUserRef: string, customerId?: string): Promise<PayPortalResponse>;
287
- }
288
-
289
- /**
290
- * Persistent key/value storage for the SDK's own namespace.
291
- *
292
- * Preference order: `chrome.storage.local` (Chrome/Edge), `browser.storage.local`
293
- * (Firefox), `localStorage` (non-extension contexts such as a dev page), then
294
- * memory. Both promise-returning (MV3, Firefox) and callback-only (MV2) storage
295
- * APIs are supported.
259
+ * Every user-visible string the paywall adds on top of the templates. The SDK
260
+ * fills them in the configured `locale` (src/paywall/i18n.ts); pass `strings`
261
+ * to override any of them.
296
262
  */
297
- interface StorageAdapter {
298
- get(key: string): Promise<unknown>;
299
- set(key: string, value: unknown): Promise<void>;
300
- remove(key: string): Promise<void>;
301
- }
302
-
303
- type PaywallMode = 'modal' | 'inline' | 'sidebar' | 'fullscreen' | 'minimal';
304
- /** Every user-visible string the SDK adds on top of the templates (English only; iteration 12 T9 swaps locales). */
305
263
  interface PaywallStrings {
306
264
  title: string;
307
265
  description: string;
@@ -316,6 +274,13 @@ interface PaywallStrings {
316
274
  periodOnce: string;
317
275
  footer: string;
318
276
  restorePurchase: string;
277
+ /** Template headings and plan labels (were fixed English text in the templates). */
278
+ featuresHeading: string;
279
+ plansHeading: string;
280
+ freePlanName: string;
281
+ premiumPlanName: string;
282
+ popularBadge: string;
283
+ unlockHeading: string;
319
284
  }
320
285
  interface PaywallOptions {
321
286
  /** Template to render (default `modal`). */
@@ -332,7 +297,8 @@ interface PaywallOptions {
332
297
  /** Mount point for `inline` mode (default `document.body`). */
333
298
  container?: HTMLElement;
334
299
  strings?: Partial<PaywallStrings>;
335
- onUpgrade?: (sku: string) => void;
300
+ /** `consent` carries the withdrawal waiver when the paywall showed one. */
301
+ onUpgrade?: (sku: string, consent?: UpgradeConsent) => void;
336
302
  onClose?: () => void;
337
303
  }
338
304
 
@@ -364,8 +330,30 @@ interface CheckoutResult {
364
330
  sessionId: string;
365
331
  entitlement?: Entitlement;
366
332
  }
333
+ /**
334
+ * The buyer ticked the withdrawal-waiver checkbox (EU/EEA/UK digital content).
335
+ * `version` names the waiver words that were shown (`PAY_WITHDRAWAL_WAIVER_VERSION`).
336
+ */
337
+ interface WithdrawalWaiverConsent {
338
+ version: string;
339
+ accepted: true;
340
+ }
341
+ /** What a paywall upgrade click carries besides the SKU. */
342
+ interface UpgradeConsent {
343
+ withdrawalWaiver?: WithdrawalWaiverConsent;
344
+ }
367
345
  interface CheckoutOptions {
368
346
  locale?: string;
347
+ /**
348
+ * Withdrawal-waiver consent, sent with `pay.createCheckout`. The paywall
349
+ * collects it itself. When you call `openCheckout()` from your own UI, ask
350
+ * `getWithdrawalWaiver()` first: if it returns a waiver, YOUR UI must show an
351
+ * unticked checkbox with exactly its `text` and pass
352
+ * `{ version, accepted: true }` here only once the buyer ticked it. Without
353
+ * it `openCheckout()` rejects with `WITHDRAWAL_WAIVER_REQUIRED`, and so does
354
+ * the server.
355
+ */
356
+ withdrawalWaiver?: WithdrawalWaiverConsent;
369
357
  /** Stop polling `claimSession` after this long (default 10 minutes). */
370
358
  timeoutMs?: number;
371
359
  /** Poll interval (default 2 seconds). */
@@ -405,6 +393,91 @@ interface LicenseSummary {
405
393
  recoveryEnabled: boolean;
406
394
  }
407
395
 
396
+ /**
397
+ * HTTP transport for the BFF's tRPC endpoint (`/api/trpc/<procedure>`).
398
+ *
399
+ * Queries are header-less GETs with `?input=<json>` (a CORS "simple request",
400
+ * so no preflight); mutations POST a JSON body. The only things that leave the
401
+ * extension are payment inputs and optional recovery session/proof inputs
402
+ * and the browser's standard headers — `credentials: 'omit'` keeps cookies out.
403
+ * Queries are retried on network / 5xx errors; mutations never are.
404
+ */
405
+
406
+ type ProcedureKind = 'query' | 'mutation';
407
+ interface Transport {
408
+ call<T>(procedure: string, kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
409
+ }
410
+
411
+ /**
412
+ * In-memory stand-in for the BFF, used when `mock: true`. Lets an extension be
413
+ * developed with no backend: offers and entitlements come from `mockData`, a
414
+ * mock checkout completes after `claimAfterPolls` polls and grants the SKU.
415
+ */
416
+
417
+ type SessionState = 'open' | 'complete' | 'canceled' | 'expired';
418
+ interface MockSession {
419
+ sku: string;
420
+ polls: number;
421
+ state: SessionState;
422
+ /** What `createCheckout` received, for inspecting the consent in dev/tests. */
423
+ withdrawalWaiver: WithdrawalWaiverConsent | null;
424
+ }
425
+ declare class MockTransport implements Transport {
426
+ private entitlements;
427
+ private readonly offers;
428
+ private readonly projectName;
429
+ private readonly checkoutEnabled;
430
+ private readonly claimAfterPolls;
431
+ private readonly withdrawalWaiver;
432
+ readonly sessions: Map<string, MockSession>;
433
+ constructor(data?: MockData);
434
+ call<T>(procedure: string, _kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
435
+ /** Test/dev helpers. */
436
+ setEntitlements(items: PayEntitlementItem[]): void;
437
+ cancelSession(sessionId: string): void;
438
+ expireSession(sessionId: string): void;
439
+ private offerResponse;
440
+ private createCheckout;
441
+ private claim;
442
+ private grant;
443
+ private envelope;
444
+ }
445
+
446
+ /** Typed wrapper over the SDK-facing `pay.*` procedures. Nothing else is ever called. */
447
+
448
+ declare class PayApi {
449
+ private readonly transport;
450
+ private readonly publishableKey;
451
+ constructor(transport: Transport, publishableKey: string);
452
+ /** `locale` opens the hosted recovery page (and its email) in the user's language. */
453
+ createRestoreSession(claimChallenge: string, locale?: string | null): Promise<PayRestoreSessionResponse>;
454
+ claimRestoreSession(sessionId: string, claimSecret: string): Promise<PayRestoreClaimResponse>;
455
+ getOffer(locale?: string | null): Promise<PayOfferResponse>;
456
+ /**
457
+ * `withdrawalWaiver` is sent only when given. Older BFFs parse the input with
458
+ * a non-strict zod object, which strips the unknown key, so it is safe there.
459
+ * Plain-JS callers passing anything but `accepted: true` send no consent.
460
+ */
461
+ createCheckout(sku: string, endUserRef: string, locale?: string | null, withdrawalWaiver?: WithdrawalWaiverConsent): Promise<PayCheckoutSession>;
462
+ claimSession(sessionId: string, endUserRef: string): Promise<PayCheckoutClaim>;
463
+ getEntitlement(endUserRef: string): Promise<SignedEntitlement>;
464
+ getPortalUrl(endUserRef: string, customerId?: string, locale?: string | null): Promise<PayPortalResponse>;
465
+ }
466
+
467
+ /**
468
+ * Persistent key/value storage for the SDK's own namespace.
469
+ *
470
+ * Preference order: `chrome.storage.local` (Chrome/Edge), `browser.storage.local`
471
+ * (Firefox), `localStorage` (non-extension contexts such as a dev page), then
472
+ * memory. Both promise-returning (MV3, Firefox) and callback-only (MV2) storage
473
+ * APIs are supported.
474
+ */
475
+ interface StorageAdapter {
476
+ get(key: string): Promise<unknown>;
477
+ set(key: string, value: unknown): Promise<void>;
478
+ remove(key: string): Promise<void>;
479
+ }
480
+
408
481
  interface ExtenshiPayEvents {
409
482
  ready: {
410
483
  endUserRef: string;
@@ -543,6 +616,8 @@ declare class EntitlementManager {
543
616
 
544
617
  interface RecoveryManagerOptions {
545
618
  api: PayApi;
619
+ /** The user's language, for the hosted recovery page and its email. */
620
+ locale?: string | null;
546
621
  storage: StorageAdapter;
547
622
  publishableKey: string;
548
623
  onComplete: (endUserRef: string, envelope: SignedEntitlement) => Promise<Entitlement>;
@@ -594,7 +669,7 @@ interface ExtenshiPayDeps {
594
669
  now?: () => number;
595
670
  }
596
671
  declare class ExtenshiPayLite {
597
- static readonly version = "0.7.1";
672
+ static readonly version = "0.8.0";
598
673
  protected readonly config: ResolvedConfig;
599
674
  protected readonly emitter: EventEmitter<ExtenshiPayEvents>;
600
675
  protected readonly storage: StorageAdapter;
@@ -631,7 +706,26 @@ declare class ExtenshiPayLite {
631
706
  requireFeature(feature: string, options?: RequireFeatureOptions): Promise<boolean>;
632
707
  /** Lite has no UI: a locked feature stays locked. The full SDK shows the paywall here. */
633
708
  protected onFeatureLocked(_feature: string, _options: RequireFeatureOptions): Promise<boolean>;
634
- /** Opens hosted checkout for `sku` in a new tab and resolves when the session settles. */
709
+ /**
710
+ * The withdrawal waiver this offer asks for, with the exact text to show
711
+ * next to an unticked checkbox (buyer's language, seller's name filled in),
712
+ * or null when the seller attested the extension is not distributed in the
713
+ * EEA/UK. For UIs that call `openCheckout()` themselves — Lite, or a custom
714
+ * paywall; the full SDK's paywall does this for you.
715
+ */
716
+ getWithdrawalWaiver(): Promise<{
717
+ version: string;
718
+ text: string;
719
+ } | null>;
720
+ /**
721
+ * Opens hosted checkout for `sku` in a new tab and resolves when the session settles.
722
+ *
723
+ * Called directly (not from the paywall), this does NOT collect the EU/UK
724
+ * withdrawal waiver. If `getWithdrawalWaiver()` returns one, your UI must
725
+ * collect the buyer's consent and pass it as `options.withdrawalWaiver`;
726
+ * without it this rejects with `WITHDRAWAL_WAIVER_REQUIRED` (the server
727
+ * refuses such a checkout too).
728
+ */
635
729
  openCheckout(sku: string, options?: CheckoutOptions): Promise<CheckoutResult>;
636
730
  /** Opens email verification on the hosted page. No email is collected inside the extension. */
637
731
  restorePurchase(options?: RestoreOptions): Promise<RestoreResult>;
@@ -653,7 +747,7 @@ declare class ExtenshiPayLite {
653
747
  }
654
748
 
655
749
  /** Kept in sync with package.json by tests/unit/version.test.ts. */
656
- declare const VERSION = "0.7.1";
750
+ declare const VERSION = "0.8.0";
657
751
 
658
- export { ERROR_CODES, ExtenshiPayLite as ExtenshiPay, ExtenshiPayError, ExtenshiPayLite, MockTransport, VERSION, ExtenshiPayLite as default };
659
- export type { CheckoutOptions, CheckoutResult, CheckoutState, CustomerPortalOptions, Entitlement, EntitlementSource, ErrorCode, ExtenshiPayConfig, ExtenshiPayDeps, ExtenshiPayEventName, ExtenshiPayEvents, GetEntitlementOptions, LicenseSummary, MockData, PayEntitlementItem, PayEntitlementStatus, PayOfferDto, PayPortalAccount, PayPortalResponse, PaySellerPublic, RequireFeatureOptions, RestoreOptions, RestoreResult, StorageAdapter, ThemeConfig, Transport };
752
+ export { ERROR_CODES, ExtenshiPayLite as ExtenshiPay, ExtenshiPayError, ExtenshiPayLite, MockTransport, PAY_WITHDRAWAL_WAIVER_VERSION, VERSION, ExtenshiPayLite as default };
753
+ export type { CheckoutOptions, CheckoutResult, CheckoutState, CustomerPortalOptions, Entitlement, EntitlementSource, ErrorCode, ExtenshiPayConfig, ExtenshiPayDeps, ExtenshiPayEventName, ExtenshiPayEvents, GetEntitlementOptions, LicenseSummary, MockData, PayEntitlementItem, PayEntitlementStatus, PayOfferDto, PayPortalAccount, PayPortalResponse, PaySellerPublic, PayWithdrawalWaiver, RequireFeatureOptions, RestoreOptions, RestoreResult, StorageAdapter, ThemeConfig, Transport, WithdrawalWaiverConsent };