@extenshi/pay 0.9.0 → 0.11.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 (74) hide show
  1. package/README.md +128 -17
  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 +9 -4
  5. package/dist/api/pay-api.d.ts.map +1 -1
  6. package/dist/core/config.d.ts.map +1 -1
  7. package/dist/core/extenshi-pay.d.ts +60 -5
  8. package/dist/core/extenshi-pay.d.ts.map +1 -1
  9. package/dist/core/index.d.ts +3 -1
  10. package/dist/core/index.d.ts.map +1 -1
  11. package/dist/core/storage.d.ts +6 -0
  12. package/dist/core/storage.d.ts.map +1 -1
  13. package/dist/core.d.mts +268 -26
  14. package/dist/core.d.ts +268 -26
  15. package/dist/core.js +566 -44
  16. package/dist/core.js.map +1 -1
  17. package/dist/core.mjs +562 -45
  18. package/dist/core.mjs.map +1 -1
  19. package/dist/extenshi-pay-lite.js +555 -44
  20. package/dist/extenshi-pay-lite.js.map +1 -1
  21. package/dist/extenshi-pay-lite.min.js +3 -3
  22. package/dist/extenshi-pay-lite.min.js.map +1 -1
  23. package/dist/extenshi-pay-lite.mjs +555 -44
  24. package/dist/extenshi-pay-lite.mjs.map +1 -1
  25. package/dist/extenshi-pay.cjs.js +670 -57
  26. package/dist/extenshi-pay.cjs.js.map +1 -1
  27. package/dist/extenshi-pay.d.ts +11 -1
  28. package/dist/extenshi-pay.d.ts.map +1 -1
  29. package/dist/extenshi-pay.js +670 -57
  30. package/dist/extenshi-pay.js.map +1 -1
  31. package/dist/extenshi-pay.min.js +3 -3
  32. package/dist/extenshi-pay.min.js.map +1 -1
  33. package/dist/extenshi-pay.min.mjs +3 -3
  34. package/dist/extenshi-pay.min.mjs.map +1 -1
  35. package/dist/extenshi-pay.mjs +666 -58
  36. package/dist/extenshi-pay.mjs.map +1 -1
  37. package/dist/index.d.mts +285 -26
  38. package/dist/index.d.ts +285 -26
  39. package/dist/lite.d.mts +212 -13
  40. package/dist/lite.d.ts +212 -13
  41. package/dist/lite.d.ts.map +1 -1
  42. package/dist/payment/cloud-backup.d.ts +35 -0
  43. package/dist/payment/cloud-backup.d.ts.map +1 -0
  44. package/dist/payment/entitlement.d.ts +21 -5
  45. package/dist/payment/entitlement.d.ts.map +1 -1
  46. package/dist/payment/recovery.d.ts +4 -2
  47. package/dist/payment/recovery.d.ts.map +1 -1
  48. package/dist/payment/signature.d.ts +29 -3
  49. package/dist/payment/signature.d.ts.map +1 -1
  50. package/dist/payment/trial.d.ts +55 -0
  51. package/dist/payment/trial.d.ts.map +1 -0
  52. package/dist/paywall/i18n.d.ts +3 -0
  53. package/dist/paywall/i18n.d.ts.map +1 -1
  54. package/dist/paywall/renderer.d.ts +7 -0
  55. package/dist/paywall/renderer.d.ts.map +1 -1
  56. package/dist/paywall.d.mts +7 -0
  57. package/dist/paywall.d.ts +7 -0
  58. package/dist/paywall.js +54 -14
  59. package/dist/paywall.js.map +1 -1
  60. package/dist/paywall.mjs +54 -14
  61. package/dist/paywall.mjs.map +1 -1
  62. package/dist/types/config.d.ts +27 -1
  63. package/dist/types/config.d.ts.map +1 -1
  64. package/dist/types/contract.d.ts +35 -0
  65. package/dist/types/contract.d.ts.map +1 -1
  66. package/dist/types/entitlement.d.ts +37 -1
  67. package/dist/types/entitlement.d.ts.map +1 -1
  68. package/dist/types/events.d.ts +5 -1
  69. package/dist/types/events.d.ts.map +1 -1
  70. package/dist/types/paywall.d.ts +10 -0
  71. package/dist/types/paywall.d.ts.map +1 -1
  72. package/dist/version.d.ts +1 -1
  73. package/dist/version.d.ts.map +1 -1
  74. package/package.json +3 -2
package/dist/core.d.ts CHANGED
@@ -100,6 +100,16 @@ interface PayEntitlementItem {
100
100
  expiresAt: string | null;
101
101
  features: string[];
102
102
  }
103
+ /**
104
+ * The installation's free trial on the server clock: one per installation per application,
105
+ * started at its first license read. Absent when the application has no trial.
106
+ */
107
+ interface PayTrial {
108
+ /** ISO time of the first license read while the application had a trial. */
109
+ startedAt: string;
110
+ /** ISO `startedAt` plus the application's current trial length. */
111
+ endsAt: string;
112
+ }
103
113
  interface PayEntitlementPayload {
104
114
  v: typeof PAY_CONTRACT_VERSION;
105
115
  /** Signed application scope; prevents moving a grant to another application. */
@@ -108,6 +118,10 @@ interface PayEntitlementPayload {
108
118
  entitlements: PayEntitlementItem[];
109
119
  /** ISO timestamp the projection was computed at; the SDK uses it for cache age. */
110
120
  issuedAt: string;
121
+ /** Optional: only for an application with a trial, and absent from older servers. */
122
+ trial?: PayTrial;
123
+ /** Optional: seconds of offline access after `issuedAt`; absent from older servers (48 hours). */
124
+ offlineSeconds?: number;
111
125
  }
112
126
  interface SignedEntitlement {
113
127
  payload: PayEntitlementPayload;
@@ -161,12 +175,33 @@ interface PayRestoreSessionResponse {
161
175
  expiresAt: string;
162
176
  url: string;
163
177
  }
178
+ /**
179
+ * `storage`: the buyer turns on the cloud copy of the extension's settings. The
180
+ * hosted page shows the storage disclosure; the claim records consent. Additive:
181
+ * a session without a purpose is a plain restore.
182
+ */
183
+ declare const PAY_RESTORE_PURPOSES: readonly ["restore", "storage"];
184
+ type PayRestorePurpose = (typeof PAY_RESTORE_PURPOSES)[number];
185
+ /**
186
+ * Outcome for the cloud copy of settings, present in a complete claim only when
187
+ * the application offers it. A token is returned once; a retried claim rotates it.
188
+ */
189
+ type PayStorageGrant = {
190
+ state: 'granted';
191
+ token: string;
192
+ } | {
193
+ state: 'unavailable';
194
+ reason: 'NO_CONSENT' | 'LICENSE_REQUIRED';
195
+ };
196
+ /** From `shared-types/storage.ts`: `est_` + 32 random bytes, base64url. */
197
+ declare const STORAGE_TOKEN_RE: RegExp;
164
198
  type PayRestoreClaimResponse = {
165
199
  state: 'pending';
166
200
  } | {
167
201
  state: 'complete';
168
202
  endUserRef: string;
169
203
  entitlement: SignedEntitlement;
204
+ storage?: PayStorageGrant;
170
205
  };
171
206
  /** A project-scoped billing profile; provider identifiers are never exposed. */
172
207
  interface PayPortalAccount {
@@ -253,6 +288,20 @@ interface MockData {
253
288
  * paywall previews the checkbox). `null` previews a seller outside the EEA/UK.
254
289
  */
255
290
  withdrawalWaiver?: PayWithdrawalWaiver | null;
291
+ /**
292
+ * Seller details for the paywall, the license panel and the waiver text.
293
+ * Omitted, the offer carries none (as from an older server); `null`
294
+ * previews a seller without public details, so the paywall disables purchase.
295
+ */
296
+ seller?: PaySellerPublic | null;
297
+ /**
298
+ * Previews a server trial: `days` long, started at `startedAt` (default: when the mock is
299
+ * created). Omitted, the mock application has no trial.
300
+ */
301
+ trial?: {
302
+ days: number;
303
+ startedAt?: string;
304
+ };
256
305
  }
257
306
  interface ExtenshiPayConfig {
258
307
  /** `pk_ext_` + 32 hex characters, from the project's Monetization tab. */
@@ -274,6 +323,15 @@ interface ExtenshiPayConfig {
274
323
  onReady?: () => void;
275
324
  onError?: (error: ExtenshiPayError) => void;
276
325
  theme?: ThemeConfig;
326
+ /** Days before the trial's end that `trial:ending` fires (default 2; 0 turns it off). */
327
+ trialEndingDays?: number;
328
+ /**
329
+ * Keep the trial's start date in `storage.sync` and send it back on license checks, so
330
+ * other devices on the same synced browser account share the trial (default true).
331
+ * Only the date is synced, never the installation id. A reinstall still restarts the
332
+ * trial: uninstalling clears `storage.sync`.
333
+ */
334
+ syncTrialStart?: boolean;
277
335
  }
278
336
  interface ResolvedConfig {
279
337
  publishableKey: string;
@@ -287,10 +345,13 @@ interface ResolvedConfig {
287
345
  mock: boolean;
288
346
  mockData: MockData | null;
289
347
  theme: ThemeConfig;
348
+ trialEndingDays: number;
349
+ syncTrialStart: boolean;
290
350
  }
291
351
  declare const DEFAULT_API_URL = "https://bff.extenshi.io";
292
352
  declare const DEFAULT_CACHE_TTL_MS: number;
293
353
  declare const MAX_CACHE_TTL_MS: number;
354
+ declare const DEFAULT_TRIAL_ENDING_DAYS = 2;
294
355
 
295
356
  type PaywallMode = 'modal' | 'inline' | 'sidebar' | 'fullscreen' | 'minimal';
296
357
  /**
@@ -350,6 +411,16 @@ interface PaywallOptions {
350
411
  onUpgrade?: (sku: string, consent?: UpgradeConsent) => void;
351
412
  onClose?: () => void;
352
413
  }
414
+ /** `showTrialEnded()`: the paywall with the trial-ended heading, plus an optional feedback button. */
415
+ interface TrialEndedOptions extends PaywallOptions {
416
+ /**
417
+ * Your feedback form (HTTPS). The SDK opens it with `src=trial_end` added and nothing that
418
+ * identifies the installation. Any other URL is left out and reported through `error`.
419
+ */
420
+ feedbackFormUrl?: string;
421
+ /** Label of the feedback button (default: "Share feedback" in the user's language). */
422
+ feedbackLabel?: string;
423
+ }
353
424
 
354
425
  type EntitlementSource = 'network' | 'cache' | 'mock' | 'none';
355
426
  /** The SDK's view of the server projection, with `expiresAt` applied locally. */
@@ -366,8 +437,33 @@ interface Entitlement {
366
437
  requiresOnlineCheck?: boolean;
367
438
  /** Local offline-access deadline; null for mock mode or no cached license. */
368
439
  offlineUntil?: number | null;
440
+ /**
441
+ * Set when the device clock differed from the server's by more than 5 minutes at the last
442
+ * license check. With `requiresOnlineCheck` on a connected device, ask the user to correct
443
+ * the date and time instead of asking them to connect.
444
+ */
445
+ clockSkew?: ClockSkew | null;
369
446
  source: EntitlementSource;
370
447
  }
448
+ interface ClockSkew {
449
+ /** `ahead`: the device clock is later than the server's. */
450
+ direction: 'ahead' | 'behind';
451
+ /** Size of the difference in milliseconds. */
452
+ ms: number;
453
+ }
454
+ /** `getTrial()`: the free trial from the verified license, on the server's clock. */
455
+ interface TrialState {
456
+ /** True while the trial runs and the license was checked within the last 48 hours, as for paid access. */
457
+ active: boolean;
458
+ /** ISO time of the installation's first license check while the application had a trial. */
459
+ startedAt: string;
460
+ /** ISO time the trial ends. */
461
+ endsAt: string;
462
+ /** Whole days left, rounded up; 0 once the trial has ended. */
463
+ daysLeft: number;
464
+ /** The trial has days left but the license was not checked within 48 hours: connect to resume it. */
465
+ requiresOnlineCheck: boolean;
466
+ }
371
467
  interface GetEntitlementOptions {
372
468
  /** Skip the cache TTL and hit the network. */
373
469
  force?: boolean;
@@ -423,10 +519,21 @@ interface RestoreOptions {
423
519
  pollIntervalMs?: number;
424
520
  signal?: AbortSignal;
425
521
  openUrl?: (url: string) => void | Promise<void>;
522
+ /**
523
+ * `storage` also turns on the cloud copy of settings: the hosted page shows
524
+ * the storage disclosure first. `enableCloudBackup()` passes it. Default: a plain restore.
525
+ */
526
+ purpose?: PayRestorePurpose;
426
527
  }
528
+ /**
529
+ * The cloud copy of settings after a completed restore: `on` (the token is
530
+ * stored), or why it is off. Absent when the application does not offer it.
531
+ */
532
+ type CloudBackupState = 'on' | 'no_consent' | 'license_required';
427
533
  type RestoreResult = {
428
534
  state: 'complete';
429
535
  entitlement: Entitlement;
536
+ cloudBackup?: CloudBackupState;
430
537
  } | {
431
538
  state: 'timeout' | 'expired' | 'canceled';
432
539
  };
@@ -514,11 +621,15 @@ declare class MockTransport implements Transport {
514
621
  private readonly checkoutEnabled;
515
622
  private readonly claimAfterPolls;
516
623
  private readonly withdrawalWaiver;
624
+ private readonly seller;
625
+ private trial;
517
626
  readonly sessions: Map<string, MockSession>;
518
627
  constructor(data?: MockData);
519
628
  call<T>(procedure: string, _kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
520
629
  /** Test/dev helpers. */
521
630
  setEntitlements(items: PayEntitlementItem[]): void;
631
+ /** Previews a server trial of `days` from `startedAt` (default now); `null` removes it. */
632
+ setTrial(days: number | null, startedAt?: string): void;
522
633
  cancelSession(sessionId: string): void;
523
634
  expireSession(sessionId: string): void;
524
635
  private offerResponse;
@@ -534,8 +645,12 @@ declare class PayApi {
534
645
  private readonly transport;
535
646
  private readonly publishableKey;
536
647
  constructor(transport: Transport, publishableKey: string);
537
- /** `locale` opens the hosted recovery page (and its email) in the user's language. */
538
- createRestoreSession(claimChallenge: string, locale?: string | null): Promise<PayRestoreSessionResponse>;
648
+ /**
649
+ * `locale` opens the hosted recovery page (and its email) in the user's language.
650
+ * `purpose` is sent only for `storage`: a plain restore keeps the request older
651
+ * BFFs know, and their non-strict zod input strips the key anyway.
652
+ */
653
+ createRestoreSession(claimChallenge: string, locale?: string | null, purpose?: PayRestorePurpose): Promise<PayRestoreSessionResponse>;
539
654
  claimRestoreSession(sessionId: string, claimSecret: string): Promise<PayRestoreClaimResponse>;
540
655
  getOffer(locale?: string | null): Promise<PayOfferResponse>;
541
656
  /**
@@ -545,7 +660,8 @@ declare class PayApi {
545
660
  */
546
661
  createCheckout(sku: string, endUserRef: string, locale?: string | null, withdrawalWaiver?: WithdrawalWaiverConsent): Promise<PayCheckoutSession>;
547
662
  claimSession(sessionId: string, endUserRef: string): Promise<PayCheckoutClaim>;
548
- getEntitlement(endUserRef: string): Promise<SignedEntitlement>;
663
+ /** `trialStartedHint`: the trial start kept in storage.sync; the server only lets it move a start earlier. */
664
+ getEntitlement(endUserRef: string, trialStartedHint?: string | null): Promise<SignedEntitlement>;
549
665
  getPortalUrl(endUserRef: string, customerId?: string, locale?: string | null): Promise<PayPortalResponse>;
550
666
  }
551
667
 
@@ -588,6 +704,12 @@ declare class MemoryStorage implements StorageAdapter {
588
704
  set(key: string, value: unknown): Promise<void>;
589
705
  remove(key: string): Promise<void>;
590
706
  }
707
+ /**
708
+ * The browser's synced storage (`storage.sync`), or null outside an extension. The SDK keeps
709
+ * only the trial start there (never `endUserRef`), so devices on one synced account share the
710
+ * trial. Uninstalling clears it from the account, so it does not survive a reinstall.
711
+ */
712
+ declare function createSyncStorage(): StorageAdapter | null;
591
713
  declare function createStorage(): StorageAdapter;
592
714
 
593
715
  interface ExtenshiPayEvents {
@@ -613,6 +735,10 @@ interface ExtenshiPayEvents {
613
735
  sku: string;
614
736
  sessionId: string;
615
737
  };
738
+ /** Once per installation and trial, `trialEndingDays` before the end, while the user has no paid access. */
739
+ 'trial:ending': TrialState;
740
+ /** Once per installation and trial, when it has ended, while the user has no paid access. */
741
+ 'trial:ended': TrialState;
616
742
  error: ExtenshiPayError;
617
743
  }
618
744
  type ExtenshiPayEventName = keyof ExtenshiPayEvents;
@@ -659,13 +785,72 @@ declare class CheckoutManager {
659
785
  private settle;
660
786
  }
661
787
 
788
+ /**
789
+ * Cloud copy of the extension's settings (`@extenshi/storage`). Pay owns the
790
+ * token: only a verified restore claim issues it; this module keeps it in the
791
+ * SDK's storage (`storage.local`) and revokes it. `@extenshi/storage` reads it
792
+ * through `cloudBackupToken()`. The token is never logged and never answered to
793
+ * a content script: route those calls to the background.
794
+ */
795
+
796
+ interface CloudBackupOptions {
797
+ storage: StorageAdapter;
798
+ publishableKey: string;
799
+ apiUrl: string;
800
+ fetch?: typeof fetch;
801
+ /** Mock mode: forget the token locally, never call the network. */
802
+ mock?: boolean;
803
+ }
804
+ declare class CloudBackup {
805
+ private readonly options;
806
+ private readonly fetchImpl;
807
+ constructor(options: CloudBackupOptions);
808
+ get storageKey(): string;
809
+ /** Stores or clears the token from a verified claim. Never throws: the licence is already restored. */
810
+ accept(grant: PayStorageGrant | undefined): Promise<CloudBackupState | undefined>;
811
+ token(): Promise<string | null>;
812
+ /** Revokes this installation's token. A token the server no longer knows (401) is forgotten too. */
813
+ disable(): Promise<void>;
814
+ /** Deletes the buyer's cloud copy and turns the backup off on every device. */
815
+ delete(): Promise<void>;
816
+ private assertTrustedContext;
817
+ private throwUnlessOk;
818
+ private request;
819
+ }
820
+
821
+ /**
822
+ * Ed25519 verification of the entitlement projection.
823
+ *
824
+ * Tamper resistance, not DRM. Callers must deny access for both invalid and
825
+ * unverified envelopes outside explicit mocks.
826
+ *
827
+ * Which keys are trusted, in order (`PublicKeySource`, built in core/extenshi-pay.ts):
828
+ * 1. the key the server returned over HTTPS in this session;
829
+ * 2. the bundled `entitlementPublicKey`, when the developer configured one. It pins
830
+ * verification without a round-trip: a key read from extension storage is then never used;
831
+ * 3. without a bundled key, the server key saved in `storage.local` next to the
832
+ * license cache, so a restart with no network can still verify the cache.
833
+ * When none of them verifies an envelope the server is asked for its current key once
834
+ * (a rotated key), and that answer decides.
835
+ */
836
+
837
+ type SignatureVerdict = 'valid' | 'invalid' | 'unverified';
838
+ declare function base64ToBytes(base64: string): Uint8Array<ArrayBuffer>;
839
+ declare function verifyEntitlementSignature(envelope: SignedEntitlement, publicKeyBase64: string | null): Promise<SignatureVerdict>;
840
+ interface PublicKeySource {
841
+ /** Keys trusted without a round-trip, in the order above. */
842
+ known(): Promise<string[]>;
843
+ /** The server's current key, fetched now; null when the server signs nothing. Rejects when unreachable. */
844
+ fetchCurrent(): Promise<string | null>;
845
+ }
846
+
662
847
  /**
663
848
  * Entitlement cache + refresh.
664
849
  *
665
850
  * The cached envelope is a cache OF the server projection, never a second
666
851
  * source of truth: it is verified when stored and re-verified on load (once
667
852
  * the project's public key is known), served without a round-trip while the
668
- * TTL holds, served for up to 48 hours after signed issuance when the network is down, and expired
853
+ * TTL holds, served after signed issuance for the signed `offlineSeconds` (48 hours when absent) when the network is down, and expired
669
854
  * locally by `expiresAt`. Background refresh polls at most every 15 minutes
670
855
  * and backs off exponentially on errors.
671
856
  */
@@ -679,9 +864,13 @@ interface EntitlementManagerOptions {
679
864
  cacheTtlMs: number;
680
865
  source?: EntitlementSource;
681
866
  getEndUserRef: () => Promise<string>;
682
- /** Base64 raw Ed25519 public key from `getOffer`, or null when unknown/unsigned. */
683
- getPublicKey: () => Promise<string | null>;
867
+ /** The trusted Ed25519 keys, in order, and how to ask the server for its current one. */
868
+ keys: PublicKeySource;
684
869
  onChange?: (entitlement: Entitlement) => void;
870
+ /** After every accepted envelope, changed or not (the trial is not part of `onChange`). */
871
+ onAccepted?: () => void;
872
+ /** The synced trial start to send with a refresh; null when there is none. */
873
+ getTrialStartHint?: () => Promise<string | null>;
685
874
  onError?: (error: ExtenshiPayError) => void;
686
875
  now?: () => number;
687
876
  }
@@ -689,6 +878,8 @@ declare class EntitlementManager {
689
878
  private readonly options;
690
879
  private held;
691
880
  private inflight;
881
+ /** Device clock against the server's at the last license check; null within 5 minutes. */
882
+ private clockSkew;
692
883
  private timer;
693
884
  private refreshGeneration;
694
885
  private deadlineTimer;
@@ -705,7 +896,11 @@ declare class EntitlementManager {
705
896
  load(): Promise<Entitlement | null>;
706
897
  /** Re-checks the loaded envelope against the project's key; discards it when the signature is invalid. */
707
898
  reverify(): Promise<void>;
899
+ /** The key the held license was verified with; null when there is none or it is unverified. */
900
+ get verifiedKey(): string | null;
708
901
  getCached(): Entitlement | null;
902
+ /** The server trial in the held license; null without one, or while the license is unverified. */
903
+ getTrial(): TrialState | null;
709
904
  isFresh(): boolean;
710
905
  get(options?: {
711
906
  force?: boolean;
@@ -721,11 +916,13 @@ declare class EntitlementManager {
721
916
  stopAutoRefresh(): void;
722
917
  private scheduleDeadline;
723
918
  private schedule;
724
- private safePublicKey;
919
+ private measureClockSkew;
725
920
  private discard;
726
921
  private fingerprint;
727
922
  private notifyIfChanged;
728
923
  private offlineDeadline;
924
+ /** The signed allowance of the held license, or 48 hours when it names none. */
925
+ private offlineAgeMs;
729
926
  private snapshot;
730
927
  }
731
928
 
@@ -751,6 +948,8 @@ interface RecoveryManagerOptions {
751
948
  storage: StorageAdapter;
752
949
  publishableKey: string;
753
950
  onComplete: (endUserRef: string, envelope: SignedEntitlement) => Promise<Entitlement>;
951
+ /** Runs after `onComplete` accepted the entitlement, with the claim's storage grant (if any). */
952
+ onStorageGrant?: (grant: PayStorageGrant | undefined) => Promise<CloudBackupState | undefined>;
754
953
  openUrl?: (url: string) => void | Promise<void>;
755
954
  now?: () => number;
756
955
  }
@@ -768,18 +967,6 @@ declare class RecoveryManager {
768
967
  private poll;
769
968
  }
770
969
 
771
- /**
772
- * Ed25519 verification of the entitlement projection.
773
- *
774
- * Tamper resistance, not DRM. Trust comes from the developer's bundled key or
775
- * a key fetched over HTTPS, never from editable extension storage. Callers must
776
- * deny access for both invalid and unverified envelopes outside explicit mocks.
777
- */
778
-
779
- type SignatureVerdict = 'valid' | 'invalid' | 'unverified';
780
- declare function base64ToBytes(base64: string): Uint8Array<ArrayBuffer>;
781
- declare function verifyEntitlementSignature(envelope: SignedEntitlement, publicKeyBase64: string | null): Promise<SignatureVerdict>;
782
-
783
970
  declare class Logger {
784
971
  private level;
785
972
  private readonly prefix;
@@ -796,7 +983,7 @@ declare class Logger {
796
983
  declare const logger: Logger;
797
984
 
798
985
  /** Kept in sync with package.json by tests/unit/version.test.ts. */
799
- declare const VERSION = "0.9.0";
986
+ declare const VERSION = "0.11.0";
800
987
 
801
988
  /** Same shape the BFF accepts (`en`, `de-DE`, `zh-Hant`). */
802
989
  declare const LOCALE_RE: RegExp;
@@ -818,13 +1005,17 @@ declare class EventEmitter<Events extends object> {
818
1005
  * extends it with `getOffer()` / `showPaywall()`.
819
1006
  *
820
1007
  * Data that leaves the extension: `publishableKey`, `endUserRef`, `sku`,
821
- * `locale` and checkout session IDs. Explicit recovery also sends its session ID,
822
- * challenge and claim secret (POST body). Email stays on the hosted page.
1008
+ * `locale`, checkout session IDs and, with a server trial, the trial start date
1009
+ * the server issued (`trialStartedHint`, kept in storage.sync). Explicit recovery also sends its session ID,
1010
+ * challenge and claim secret (POST body). Email stays on the hosted page. With cloud backup, the
1011
+ * storage token goes only to `/v1/storage` (as a bearer), never in a message to a content script.
823
1012
  */
824
1013
 
825
1014
  /** Injection points for tests and unusual hosts. */
826
1015
  interface ExtenshiPayDeps {
827
1016
  storage?: StorageAdapter;
1017
+ /** Where the trial start is synced (default `storage.sync`); null turns syncing off. */
1018
+ syncStorage?: StorageAdapter | null;
828
1019
  /** Trusted extension-only storage; never share this adapter with content scripts. */
829
1020
  recoveryStorage?: StorageAdapter;
830
1021
  transport?: Transport;
@@ -833,7 +1024,7 @@ interface ExtenshiPayDeps {
833
1024
  now?: () => number;
834
1025
  }
835
1026
  declare class ExtenshiPayLite {
836
- static readonly version = "0.9.0";
1027
+ static readonly version = "0.11.0";
837
1028
  protected readonly config: ResolvedConfig;
838
1029
  protected readonly emitter: EventEmitter<ExtenshiPayEvents>;
839
1030
  protected readonly storage: StorageAdapter;
@@ -841,11 +1032,21 @@ declare class ExtenshiPayLite {
841
1032
  protected readonly entitlements: EntitlementManager;
842
1033
  protected readonly checkout: CheckoutManager;
843
1034
  protected readonly recovery: RecoveryManager;
1035
+ private readonly backup;
1036
+ /** `deps.openUrl`, for tabs the full SDK opens outside checkout and recovery. */
1037
+ protected readonly openUrl: ((url: string) => void | Promise<void>) | undefined;
1038
+ private readonly trial;
1039
+ /** storage.sync for the trial start; null when off, in mock mode, or outside an extension. */
1040
+ private readonly syncStorage;
844
1041
  private readonly now;
845
1042
  private endUserRef;
846
1043
  private endUserRefPromise;
847
1044
  private offer;
848
1045
  private offerInflight;
1046
+ /** The signing key the server returned in this session; never one read from storage. */
1047
+ private serverKey;
1048
+ /** Trust order for license signatures; see payment/signature.ts. */
1049
+ private readonly keys;
849
1050
  private readyPromise;
850
1051
  private destroyed;
851
1052
  constructor(config: ExtenshiPayConfig, deps?: ExtenshiPayDeps);
@@ -862,6 +1063,13 @@ declare class ExtenshiPayLite {
862
1063
  getEndUserRef(): Promise<string>;
863
1064
  getCachedEntitlement(): Entitlement | null;
864
1065
  getEntitlement(options?: GetEntitlementOptions): Promise<Entitlement>;
1066
+ /**
1067
+ * The free trial the application set on the server, from the verified license, or null when
1068
+ * there is none (or the license could not be verified yet). Answers offline from the cached
1069
+ * license; like paid access, `active` needs a license check within 48 hours. `isPaid()` and
1070
+ * `hasFeature()` do not include the trial: grant trial access with `(await getTrial())?.active`.
1071
+ */
1072
+ getTrial(options?: GetEntitlementOptions): Promise<TrialState | null>;
865
1073
  /** True when any active/grace entitlement exists, or the given `sku` is active/grace. */
866
1074
  isPaid(sku?: string): Promise<boolean>;
867
1075
  hasFeature(feature: string): Promise<boolean>;
@@ -893,6 +1101,23 @@ declare class ExtenshiPayLite {
893
1101
  openCheckout(sku: string, options?: CheckoutOptions): Promise<CheckoutResult>;
894
1102
  /** Opens email verification on the hosted page. No email is collected inside the extension. */
895
1103
  restorePurchase(options?: RestoreOptions): Promise<RestoreResult>;
1104
+ /**
1105
+ * Turns on the cloud copy of the extension's settings (`@extenshi/storage`): the
1106
+ * hosted restore page shows the storage disclosure and the buyer confirms with
1107
+ * the code from the purchase email. `cloudBackup` in the result says whether it is
1108
+ * on. Buyers only; consent is recorded by the server.
1109
+ */
1110
+ enableCloudBackup(options?: Omit<RestoreOptions, 'purpose'>): Promise<RestoreResult>;
1111
+ /**
1112
+ * The storage token for `ExtenshiStorage.create({ cloud: { getToken } })`, or null
1113
+ * while cloud backup is off on this installation. Extension pages and background
1114
+ * only: it rejects in a content script, and must never be sent to one.
1115
+ */
1116
+ cloudBackupToken(): Promise<string | null>;
1117
+ /** Turns cloud backup off on this installation: revokes its token. The cloud copy stays. */
1118
+ disableCloudBackup(): Promise<void>;
1119
+ /** Deletes the buyer's cloud copy and turns cloud backup off on every installation. */
1120
+ deleteCloudBackup(): Promise<void>;
896
1121
  /** Read-only license view. Entitlements retain cache/signature/offline semantics. */
897
1122
  getLicenseSummary(options?: GetEntitlementOptions): Promise<LicenseSummary>;
898
1123
  /** Opens the provider's self-service portal; resolves null when the provider has none. */
@@ -906,7 +1131,24 @@ declare class ExtenshiPayLite {
906
1131
  destroy(): void;
907
1132
  /** Offer + signing key. Public in the full SDK (`getOffer`), internal here. */
908
1133
  protected fetchOffer(force?: boolean): Promise<PayOfferResponse>;
909
- private getPublicKey;
1134
+ private get serverKeyStorageKey();
1135
+ private readSavedServerKey;
1136
+ /**
1137
+ * Keeps the server's key next to the license cache so a restart with no network can verify it.
1138
+ * Not with a bundled key: that one already covers the restart, and storage stays untrusted.
1139
+ */
1140
+ private rememberServerKey;
1141
+ /**
1142
+ * A license verified with the saved key alone is checked against the server once per start:
1143
+ * when the server's key differs (rotation, or an edited storage) the license is fetched again,
1144
+ * and dropped if it does not verify. Offline, the saved key stands until `offlineUntil`.
1145
+ */
1146
+ private confirmSavedServerKey;
1147
+ private get trialStartKey();
1148
+ /** The synced trial start, or null (none, malformed, or storage.sync unavailable). */
1149
+ private readTrialStartHint;
1150
+ /** Syncs the verified trial start, keeping the earliest one seen. Never the installation id. */
1151
+ private rememberTrialStart;
910
1152
  protected reportError(error: unknown): ExtenshiPayError;
911
1153
  }
912
1154
 
@@ -923,5 +1165,5 @@ declare const END_USER_REF_STORAGE_KEY = "extenshi-pay:endUserRef";
923
1165
  declare function mintEndUserRef(): string;
924
1166
  declare function getOrCreateEndUserRef(storage: StorageAdapter): Promise<string>;
925
1167
 
926
- export { CHECKOUT_POLL_INTERVAL_MS, CHECKOUT_TIMEOUT_MS, CheckoutManager, DEFAULT_API_URL, DEFAULT_CACHE_TTL_MS, EMPTY_ENTITLEMENT, END_USER_REF_STORAGE_KEY, ERROR_CODES, EntitlementManager, EventEmitter, ExtenshiPayError, ExtenshiPayLite, ExtensionStorage, HttpTransport, LOCALE_RE, LocalStorageAdapter, Logger, MAX_CACHE_TTL_MS, MAX_REFRESH_BACKOFF_MS, MIN_REFRESH_INTERVAL_MS, MemoryStorage, MockTransport, PAY_CONTRACT_VERSION, PAY_CURRENCIES, PAY_END_USER_REF_RE, PAY_ENTITLEMENT_STATUSES, PAY_ERRORS, PAY_GATEWAYS, PAY_OFFER_INTERVALS, PAY_OFFER_KINDS, PAY_PUBLISHABLE_KEY_HEX_LENGTH, PAY_PUBLISHABLE_KEY_PREFIX, PAY_SKU_RE, PAY_WITHDRAWAL_WAIVER_VERSION, PayApi, RecoveryManager, TRPC_PATH, VERSION, applyLocalExpiry, base64ToBytes, canonicalJson, checkFeatures, collectFeatures, createRecoveryStorage, createStorage, getOrCreateEndUserRef, hasFeature, isEntitled, isLive, isPayPublishableKey, logger, mintEndUserRef, openInNewTab, resolveConfig, trpcErrorToPayError, verifyEntitlementSignature };
927
- export type { CheckoutManagerOptions, CheckoutOptions, CheckoutResult, CheckoutState, CustomerPortalOptions, Entitlement, EntitlementManagerOptions, EntitlementSource, Environment, ErrorCode, ExtenshiPayConfig, ExtenshiPayDeps, ExtenshiPayErrorOptions, ExtenshiPayEventName, ExtenshiPayEvents, GetEntitlementOptions, HttpTransportOptions, LicenseSummary, Listener, LogLevel, MockData, PayCheckoutClaim, PayCheckoutSession, PayCurrency, PayEntitlementItem, PayEntitlementPayload, PayEntitlementStatus, PayErrorCode, PayGatewayId, PayOfferDto, PayOfferInterval, PayOfferKind, PayOfferResponse, PayPortalAccount, PayPortalResponse, PayRestoreClaimResponse, PayRestoreSessionResponse, PaySellerPublic, PayWithdrawalWaiver, PaywallMode, PaywallOptions, PaywallStrings, ProcedureKind, RecoveryManagerOptions, RequireFeatureOptions, ResolvedConfig, RestoreOptions, RestoreResult, SignatureVerdict, SignedEntitlement, StorageAdapter, ThemeConfig, Transport, UpgradeConsent, WithdrawalWaiverConsent };
1168
+ export { CHECKOUT_POLL_INTERVAL_MS, CHECKOUT_TIMEOUT_MS, CheckoutManager, CloudBackup, DEFAULT_API_URL, DEFAULT_CACHE_TTL_MS, DEFAULT_TRIAL_ENDING_DAYS, EMPTY_ENTITLEMENT, END_USER_REF_STORAGE_KEY, ERROR_CODES, EntitlementManager, EventEmitter, ExtenshiPayError, ExtenshiPayLite, ExtensionStorage, HttpTransport, LOCALE_RE, LocalStorageAdapter, Logger, MAX_CACHE_TTL_MS, MAX_REFRESH_BACKOFF_MS, MIN_REFRESH_INTERVAL_MS, MemoryStorage, MockTransport, PAY_CONTRACT_VERSION, PAY_CURRENCIES, PAY_END_USER_REF_RE, PAY_ENTITLEMENT_STATUSES, PAY_ERRORS, PAY_GATEWAYS, PAY_OFFER_INTERVALS, PAY_OFFER_KINDS, PAY_PUBLISHABLE_KEY_HEX_LENGTH, PAY_PUBLISHABLE_KEY_PREFIX, PAY_RESTORE_PURPOSES, PAY_SKU_RE, PAY_WITHDRAWAL_WAIVER_VERSION, PayApi, RecoveryManager, STORAGE_TOKEN_RE, TRPC_PATH, VERSION, applyLocalExpiry, base64ToBytes, canonicalJson, checkFeatures, collectFeatures, createRecoveryStorage, createStorage, createSyncStorage, getOrCreateEndUserRef, hasFeature, isEntitled, isLive, isPayPublishableKey, logger, mintEndUserRef, openInNewTab, resolveConfig, trpcErrorToPayError, verifyEntitlementSignature };
1169
+ export type { CheckoutManagerOptions, CheckoutOptions, CheckoutResult, CheckoutState, ClockSkew, CloudBackupOptions, CloudBackupState, CustomerPortalOptions, Entitlement, EntitlementManagerOptions, EntitlementSource, Environment, ErrorCode, ExtenshiPayConfig, ExtenshiPayDeps, ExtenshiPayErrorOptions, ExtenshiPayEventName, ExtenshiPayEvents, GetEntitlementOptions, HttpTransportOptions, LicenseSummary, Listener, LogLevel, MockData, PayCheckoutClaim, PayCheckoutSession, PayCurrency, PayEntitlementItem, PayEntitlementPayload, PayEntitlementStatus, PayErrorCode, PayGatewayId, PayOfferDto, PayOfferInterval, PayOfferKind, PayOfferResponse, PayPortalAccount, PayPortalResponse, PayRestoreClaimResponse, PayRestorePurpose, PayRestoreSessionResponse, PaySellerPublic, PayStorageGrant, PayTrial, PayWithdrawalWaiver, PaywallMode, PaywallOptions, PaywallStrings, ProcedureKind, RecoveryManagerOptions, RequireFeatureOptions, ResolvedConfig, RestoreOptions, RestoreResult, SignatureVerdict, SignedEntitlement, StorageAdapter, ThemeConfig, Transport, TrialEndedOptions, TrialState, UpgradeConsent, WithdrawalWaiverConsent };