@extenshi/pay 0.7.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/LICENSE +21 -0
- package/README.md +260 -0
- package/dist/api/mock.d.ts +35 -0
- package/dist/api/mock.d.ts.map +1 -0
- package/dist/api/pay-api.d.ts +16 -0
- package/dist/api/pay-api.d.ts.map +1 -0
- package/dist/api/transport.d.ts +52 -0
- package/dist/api/transport.d.ts.map +1 -0
- package/dist/core/config.d.ts +5 -0
- package/dist/core/config.d.ts.map +1 -0
- package/dist/core/event-emitter.d.ts +10 -0
- package/dist/core/event-emitter.d.ts.map +1 -0
- package/dist/core/extenshi-pay.d.ts +90 -0
- package/dist/core/extenshi-pay.d.ts.map +1 -0
- package/dist/core/identity.d.ts +13 -0
- package/dist/core/identity.d.ts.map +1 -0
- package/dist/core/index.d.ts +25 -0
- package/dist/core/index.d.ts.map +1 -0
- package/dist/core/storage.d.ts +42 -0
- package/dist/core/storage.d.ts.map +1 -0
- package/dist/core.d.mts +821 -0
- package/dist/core.d.ts +821 -0
- package/dist/core.esm.js +1681 -0
- package/dist/core.esm.js.map +1 -0
- package/dist/core.js +1806 -0
- package/dist/core.js.map +1 -0
- package/dist/core.mjs +1744 -0
- package/dist/core.mjs.map +1 -0
- package/dist/extenshi-pay-lite.esm.js +1664 -0
- package/dist/extenshi-pay-lite.esm.js.map +1 -0
- package/dist/extenshi-pay-lite.js +1743 -0
- package/dist/extenshi-pay-lite.js.map +1 -0
- package/dist/extenshi-pay-lite.min.js +7 -0
- package/dist/extenshi-pay-lite.min.js.map +1 -0
- package/dist/extenshi-pay-lite.mjs +1727 -0
- package/dist/extenshi-pay-lite.mjs.map +1 -0
- package/dist/extenshi-pay.cjs.js +2632 -0
- package/dist/extenshi-pay.cjs.js.map +1 -0
- package/dist/extenshi-pay.d.ts +32 -0
- package/dist/extenshi-pay.d.ts.map +1 -0
- package/dist/extenshi-pay.esm.js +2496 -0
- package/dist/extenshi-pay.esm.js.map +1 -0
- package/dist/extenshi-pay.esm.min.js +7 -0
- package/dist/extenshi-pay.esm.min.js.map +1 -0
- package/dist/extenshi-pay.js +2638 -0
- package/dist/extenshi-pay.js.map +1 -0
- package/dist/extenshi-pay.min.js +7 -0
- package/dist/extenshi-pay.min.js.map +1 -0
- package/dist/extenshi-pay.min.mjs +7 -0
- package/dist/extenshi-pay.min.mjs.map +1 -0
- package/dist/extenshi-pay.mjs +2559 -0
- package/dist/extenshi-pay.mjs.map +1 -0
- package/dist/index.d.mts +937 -0
- package/dist/index.d.ts +937 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/lite.d.mts +659 -0
- package/dist/lite.d.ts +659 -0
- package/dist/lite.d.ts.map +1 -0
- package/dist/payment/checkout.d.ts +47 -0
- package/dist/payment/checkout.d.ts.map +1 -0
- package/dist/payment/entitlement.d.ts +76 -0
- package/dist/payment/entitlement.d.ts.map +1 -0
- package/dist/payment/features.d.ts +12 -0
- package/dist/payment/features.d.ts.map +1 -0
- package/dist/payment/recovery.d.ts +29 -0
- package/dist/payment/recovery.d.ts.map +1 -0
- package/dist/payment/signature.d.ts +12 -0
- package/dist/payment/signature.d.ts.map +1 -0
- package/dist/paywall/billing-profile-picker.d.ts +8 -0
- package/dist/paywall/billing-profile-picker.d.ts.map +1 -0
- package/dist/paywall/format.d.ts +13 -0
- package/dist/paywall/format.d.ts.map +1 -0
- package/dist/paywall/index.d.ts +9 -0
- package/dist/paywall/index.d.ts.map +1 -0
- package/dist/paywall/license-panel.d.ts +10 -0
- package/dist/paywall/license-panel.d.ts.map +1 -0
- package/dist/paywall/renderer.d.ts +55 -0
- package/dist/paywall/renderer.d.ts.map +1 -0
- package/dist/paywall/seller-details.d.ts +5 -0
- package/dist/paywall/seller-details.d.ts.map +1 -0
- package/dist/paywall/strings.d.ts +10 -0
- package/dist/paywall/strings.d.ts.map +1 -0
- package/dist/paywall/templates.d.ts +14 -0
- package/dist/paywall/templates.d.ts.map +1 -0
- package/dist/paywall.d.mts +160 -0
- package/dist/paywall.d.ts +160 -0
- package/dist/paywall.esm.js +442 -0
- package/dist/paywall.esm.js.map +1 -0
- package/dist/paywall.js +462 -0
- package/dist/paywall.js.map +1 -0
- package/dist/paywall.mjs +442 -0
- package/dist/paywall.mjs.map +1 -0
- package/dist/types/config.d.ts +62 -0
- package/dist/types/config.d.ts.map +1 -0
- package/dist/types/contract.d.ts +172 -0
- package/dist/types/contract.d.ts.map +1 -0
- package/dist/types/entitlement.d.ts +71 -0
- package/dist/types/entitlement.d.ts.map +1 -0
- package/dist/types/errors.d.ts +31 -0
- package/dist/types/errors.d.ts.map +1 -0
- package/dist/types/events.d.ts +29 -0
- package/dist/types/events.d.ts.map +1 -0
- package/dist/types/index.d.ts +7 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/paywall.d.ts +37 -0
- package/dist/types/paywall.d.ts.map +1 -0
- package/dist/utils/logger.d.ts +16 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/version.d.ts +3 -0
- package/dist/version.d.ts.map +1 -0
- package/package.json +115 -0
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,937 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire contract between the SDK and catalog-bff `pay.*`.
|
|
3
|
+
*
|
|
4
|
+
* SOURCE OF TRUTH: `shared-types/pay.ts` in the extenshi.io monorepo. The SDK
|
|
5
|
+
* ships with zero runtime dependencies and must not import that workspace, so
|
|
6
|
+
* the types and constants it needs are copied here under identical names.
|
|
7
|
+
* `canonicalJson` is copied VERBATIM: the BFF signs its output and the SDK
|
|
8
|
+
* verifies it, so both sides must produce byte-identical strings
|
|
9
|
+
* (pinned by tests/unit/canonical-json.test.ts). When `shared-types/pay.ts`
|
|
10
|
+
* changes, mirror the change here.
|
|
11
|
+
*/
|
|
12
|
+
/** Bumped only when an older SDK could misread the response. */
|
|
13
|
+
declare const PAY_CONTRACT_VERSION = 1;
|
|
14
|
+
declare const PAY_GATEWAYS: readonly ["stripe", "paddle", "lemonsqueezy"];
|
|
15
|
+
type PayGatewayId = (typeof PAY_GATEWAYS)[number];
|
|
16
|
+
/**
|
|
17
|
+
* The only credential an extension bundle carries. It is public by
|
|
18
|
+
* construction (anyone can unzip the .crx), so it must grant nothing beyond
|
|
19
|
+
* "read this project's offer" and "start a checkout for this project".
|
|
20
|
+
*/
|
|
21
|
+
declare const PAY_PUBLISHABLE_KEY_PREFIX = "pk_ext_";
|
|
22
|
+
declare const PAY_PUBLISHABLE_KEY_HEX_LENGTH = 32;
|
|
23
|
+
declare function isPayPublishableKey(value: unknown): value is string;
|
|
24
|
+
declare const PAY_OFFER_KINDS: readonly ["one_time", "subscription", "lifetime"];
|
|
25
|
+
type PayOfferKind = (typeof PAY_OFFER_KINDS)[number];
|
|
26
|
+
declare const PAY_OFFER_INTERVALS: readonly ["month", "year"];
|
|
27
|
+
type PayOfferInterval = (typeof PAY_OFFER_INTERVALS)[number];
|
|
28
|
+
/** ISO-4217 lowercase, matching what every gateway returns. */
|
|
29
|
+
declare const PAY_CURRENCIES: readonly ["usd", "eur", "gbp"];
|
|
30
|
+
type PayCurrency = (typeof PAY_CURRENCIES)[number];
|
|
31
|
+
/** `sku` is author-chosen and stable; it is what `requireFeature()` keys on. */
|
|
32
|
+
declare const PAY_SKU_RE: RegExp;
|
|
33
|
+
/**
|
|
34
|
+
* active — paid and not expired
|
|
35
|
+
* grace — subscription past_due: keep access for a short window so a card
|
|
36
|
+
* hiccup does not lock a paying user out mid-session
|
|
37
|
+
* expired — was active, no longer is
|
|
38
|
+
* none — never had it
|
|
39
|
+
*/
|
|
40
|
+
declare const PAY_ENTITLEMENT_STATUSES: readonly ["active", "grace", "expired", "none"];
|
|
41
|
+
type PayEntitlementStatus = (typeof PAY_ENTITLEMENT_STATUSES)[number];
|
|
42
|
+
interface PayOfferDto {
|
|
43
|
+
sku: string;
|
|
44
|
+
kind: PayOfferKind;
|
|
45
|
+
interval: PayOfferInterval | null;
|
|
46
|
+
amountMinor: number;
|
|
47
|
+
currency: PayCurrency;
|
|
48
|
+
title: string;
|
|
49
|
+
description: string | null;
|
|
50
|
+
features: string[];
|
|
51
|
+
}
|
|
52
|
+
interface PayOfferResponse {
|
|
53
|
+
/** Optional during rolling upgrades; never infer this from the project name. */
|
|
54
|
+
seller?: PaySellerPublic | null;
|
|
55
|
+
v: typeof PAY_CONTRACT_VERSION;
|
|
56
|
+
projectName: string;
|
|
57
|
+
provider: PayGatewayId;
|
|
58
|
+
/** False while the seller cannot take money; the SDK renders the offer read-only. */
|
|
59
|
+
checkoutEnabled: boolean;
|
|
60
|
+
/** Optional for older servers; show recovery only when explicitly enabled. */
|
|
61
|
+
recoveryEnabled?: boolean;
|
|
62
|
+
offers: PayOfferDto[];
|
|
63
|
+
/** Base64 Ed25519 public key for `SignedEntitlement.signature`; null when unsigned. */
|
|
64
|
+
entitlementPublicKey: string | null;
|
|
65
|
+
}
|
|
66
|
+
interface PayEntitlementItem {
|
|
67
|
+
/** Optional for old signed caches and older servers. */
|
|
68
|
+
title?: string;
|
|
69
|
+
kind?: PayOfferKind;
|
|
70
|
+
subscriptions?: Array<{
|
|
71
|
+
status: string;
|
|
72
|
+
cancelAtPeriodEnd: boolean;
|
|
73
|
+
currentPeriodEnd: string | null;
|
|
74
|
+
}>;
|
|
75
|
+
sku: string;
|
|
76
|
+
status: PayEntitlementStatus;
|
|
77
|
+
/** ISO timestamp; null for lifetime / one-time grants. */
|
|
78
|
+
expiresAt: string | null;
|
|
79
|
+
features: string[];
|
|
80
|
+
}
|
|
81
|
+
interface PayEntitlementPayload {
|
|
82
|
+
v: typeof PAY_CONTRACT_VERSION;
|
|
83
|
+
/** Signed application scope; prevents moving a grant to another application. */
|
|
84
|
+
publishableKey: string;
|
|
85
|
+
endUserRef: string;
|
|
86
|
+
entitlements: PayEntitlementItem[];
|
|
87
|
+
/** ISO timestamp the projection was computed at; the SDK uses it for cache age. */
|
|
88
|
+
issuedAt: string;
|
|
89
|
+
}
|
|
90
|
+
interface SignedEntitlement {
|
|
91
|
+
payload: PayEntitlementPayload;
|
|
92
|
+
/** Base64 Ed25519 signature over the canonical JSON of `payload`; null when the server has no key. */
|
|
93
|
+
signature: string | null;
|
|
94
|
+
alg: 'ed25519' | null;
|
|
95
|
+
}
|
|
96
|
+
type PayCheckoutClaim = {
|
|
97
|
+
state: 'pending';
|
|
98
|
+
} | {
|
|
99
|
+
state: 'complete';
|
|
100
|
+
entitlement: SignedEntitlement;
|
|
101
|
+
} | {
|
|
102
|
+
state: 'expired';
|
|
103
|
+
} | {
|
|
104
|
+
state: 'canceled';
|
|
105
|
+
};
|
|
106
|
+
interface PayCheckoutSession {
|
|
107
|
+
url: string;
|
|
108
|
+
sessionId: string;
|
|
109
|
+
/** ISO timestamp. */
|
|
110
|
+
expiresAt: string;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* The `endUserRef` an SDK mints on first run and keeps in `chrome.storage`.
|
|
114
|
+
* Opaque, random, never derived from anything identifying.
|
|
115
|
+
*/
|
|
116
|
+
declare const PAY_END_USER_REF_RE: RegExp;
|
|
117
|
+
/** Typed error codes the BFF throws; dojo and the SDK match on `cause.code`. */
|
|
118
|
+
declare const PAY_ERRORS: {
|
|
119
|
+
readonly SELLER_NOT_CONNECTED: "PAY_SELLER_NOT_CONNECTED";
|
|
120
|
+
readonly SELLER_NOT_ACTIVE: "PAY_SELLER_NOT_ACTIVE";
|
|
121
|
+
readonly AGREEMENT_REQUIRED: "PAY_AGREEMENT_REQUIRED";
|
|
122
|
+
readonly OFFER_NOT_FOUND: "PAY_OFFER_NOT_FOUND";
|
|
123
|
+
readonly OFFER_LIMIT: "PAY_OFFER_LIMIT";
|
|
124
|
+
readonly PRICE_TOO_LOW: "PAY_PRICE_TOO_LOW";
|
|
125
|
+
readonly GATEWAY_UNAVAILABLE: "PAY_GATEWAY_UNAVAILABLE";
|
|
126
|
+
readonly RATE_LIMITED: "PAY_RATE_LIMITED";
|
|
127
|
+
readonly INVALID_KEY: "PAY_INVALID_KEY";
|
|
128
|
+
};
|
|
129
|
+
type PayErrorCode = (typeof PAY_ERRORS)[keyof typeof PAY_ERRORS];
|
|
130
|
+
/**
|
|
131
|
+
* Canonical JSON for signing: keys sorted recursively, no whitespace. Both
|
|
132
|
+
* the BFF (sign) and the SDK (verify) must produce byte-identical output for
|
|
133
|
+
* the same payload, so the rule lives in the shared contract.
|
|
134
|
+
*/
|
|
135
|
+
declare function canonicalJson(value: unknown): string;
|
|
136
|
+
interface PayRestoreSessionResponse {
|
|
137
|
+
sessionId: string;
|
|
138
|
+
expiresAt: string;
|
|
139
|
+
url: string;
|
|
140
|
+
}
|
|
141
|
+
type PayRestoreClaimResponse = {
|
|
142
|
+
state: 'pending';
|
|
143
|
+
} | {
|
|
144
|
+
state: 'complete';
|
|
145
|
+
endUserRef: string;
|
|
146
|
+
entitlement: SignedEntitlement;
|
|
147
|
+
};
|
|
148
|
+
/** A project-scoped billing profile; provider identifiers are never exposed. */
|
|
149
|
+
interface PayPortalAccount {
|
|
150
|
+
id: string;
|
|
151
|
+
label: string;
|
|
152
|
+
createdAt: string;
|
|
153
|
+
subscriptions: Array<{
|
|
154
|
+
title: string;
|
|
155
|
+
status: string;
|
|
156
|
+
cancelAtPeriodEnd: boolean;
|
|
157
|
+
currentPeriodEnd: string | null;
|
|
158
|
+
}>;
|
|
159
|
+
}
|
|
160
|
+
interface PayPortalResponse {
|
|
161
|
+
url: string | null;
|
|
162
|
+
/** Present when the buyer must choose among multiple billing profiles. */
|
|
163
|
+
accounts?: PayPortalAccount[];
|
|
164
|
+
}
|
|
165
|
+
/** Public author-provided contact details. Not a claim of identity verification. */
|
|
166
|
+
interface PaySellerPublic {
|
|
167
|
+
displayName: string;
|
|
168
|
+
/** HTTPS support page or plain email address. */
|
|
169
|
+
supportUrl: string;
|
|
170
|
+
termsUrl: string | null;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
declare const ERROR_CODES: {
|
|
174
|
+
readonly INVALID_CONFIG: "INVALID_CONFIG";
|
|
175
|
+
readonly INVALID_REQUEST: "INVALID_REQUEST";
|
|
176
|
+
readonly NETWORK_ERROR: "NETWORK_ERROR";
|
|
177
|
+
readonly TIMEOUT: "TIMEOUT";
|
|
178
|
+
readonly VERIFICATION_UNAVAILABLE: "VERIFICATION_UNAVAILABLE";
|
|
179
|
+
readonly INVALID_RESPONSE: "INVALID_RESPONSE";
|
|
180
|
+
readonly RATE_LIMITED: "RATE_LIMITED";
|
|
181
|
+
readonly INVALID_KEY: "INVALID_KEY";
|
|
182
|
+
readonly SELLER_NOT_ACTIVE: "SELLER_NOT_ACTIVE";
|
|
183
|
+
readonly OFFER_NOT_FOUND: "OFFER_NOT_FOUND";
|
|
184
|
+
readonly GATEWAY_UNAVAILABLE: "GATEWAY_UNAVAILABLE";
|
|
185
|
+
readonly CHECKOUT_UNAVAILABLE: "CHECKOUT_UNAVAILABLE";
|
|
186
|
+
readonly PAYWALL_UNAVAILABLE: "PAYWALL_UNAVAILABLE";
|
|
187
|
+
readonly UNKNOWN: "UNKNOWN";
|
|
188
|
+
};
|
|
189
|
+
type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
|
|
190
|
+
interface ExtenshiPayErrorOptions {
|
|
191
|
+
retryAfterSec?: number;
|
|
192
|
+
httpStatus?: number;
|
|
193
|
+
cause?: unknown;
|
|
194
|
+
}
|
|
195
|
+
declare class ExtenshiPayError extends Error {
|
|
196
|
+
readonly code: ErrorCode;
|
|
197
|
+
readonly retryAfterSec: number | undefined;
|
|
198
|
+
readonly httpStatus: number | undefined;
|
|
199
|
+
readonly cause: unknown;
|
|
200
|
+
constructor(code: ErrorCode, message: string, options?: ExtenshiPayErrorOptions);
|
|
201
|
+
static from(error: unknown, fallback?: ErrorCode): ExtenshiPayError;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
|
|
205
|
+
/** Reserved for future routing; today every environment talks to the same BFF. */
|
|
206
|
+
type Environment = 'production' | 'sandbox' | 'development';
|
|
207
|
+
interface ThemeConfig {
|
|
208
|
+
/** `auto` follows `prefers-color-scheme`. */
|
|
209
|
+
mode?: 'light' | 'dark' | 'auto';
|
|
210
|
+
primaryColor?: string;
|
|
211
|
+
fontFamily?: string;
|
|
212
|
+
borderRadius?: string;
|
|
213
|
+
/** Appended verbatim inside the paywall's shadow root. */
|
|
214
|
+
customCss?: string;
|
|
215
|
+
}
|
|
216
|
+
/** Offline development data used when `mock: true`. */
|
|
217
|
+
interface MockData {
|
|
218
|
+
entitlements?: PayEntitlementItem[];
|
|
219
|
+
offers?: PayOfferDto[];
|
|
220
|
+
projectName?: string;
|
|
221
|
+
/** Defaults to true. */
|
|
222
|
+
checkoutEnabled?: boolean;
|
|
223
|
+
/** How many `claimSession` polls answer `pending` before a mock checkout completes (default 1). */
|
|
224
|
+
claimAfterPolls?: number;
|
|
225
|
+
}
|
|
226
|
+
interface ExtenshiPayConfig {
|
|
227
|
+
/** `pk_ext_` + 32 hex characters, from the project's Monetization tab. */
|
|
228
|
+
publishableKey: string;
|
|
229
|
+
/** Defaults to `https://bff.extenshi.io`. */
|
|
230
|
+
apiUrl?: string;
|
|
231
|
+
/** Bundled raw Ed25519 public key (base64). Enables verified cache use after an offline restart. */
|
|
232
|
+
entitlementPublicKey?: string;
|
|
233
|
+
environment?: Environment;
|
|
234
|
+
/** Shorthand for `logLevel: 'debug'`. */
|
|
235
|
+
debug?: boolean;
|
|
236
|
+
logLevel?: LogLevel;
|
|
237
|
+
/** How long a fetched entitlement is served without a network round-trip (default 1 hour). */
|
|
238
|
+
cacheTtlMs?: number;
|
|
239
|
+
/** BCP-47 tag such as `en` or `de-DE`; sent to the backend for checkout/offer copy and used for price formatting. */
|
|
240
|
+
locale?: string;
|
|
241
|
+
mock?: boolean;
|
|
242
|
+
mockData?: MockData;
|
|
243
|
+
onReady?: () => void;
|
|
244
|
+
onError?: (error: ExtenshiPayError) => void;
|
|
245
|
+
theme?: ThemeConfig;
|
|
246
|
+
}
|
|
247
|
+
interface ResolvedConfig {
|
|
248
|
+
publishableKey: string;
|
|
249
|
+
apiUrl: string;
|
|
250
|
+
entitlementPublicKey: string | null;
|
|
251
|
+
environment: Environment;
|
|
252
|
+
debug: boolean;
|
|
253
|
+
logLevel: LogLevel;
|
|
254
|
+
cacheTtlMs: number;
|
|
255
|
+
locale: string | null;
|
|
256
|
+
mock: boolean;
|
|
257
|
+
mockData: MockData | null;
|
|
258
|
+
theme: ThemeConfig;
|
|
259
|
+
}
|
|
260
|
+
declare const DEFAULT_API_URL = "https://bff.extenshi.io";
|
|
261
|
+
declare const DEFAULT_CACHE_TTL_MS: number;
|
|
262
|
+
declare const MAX_CACHE_TTL_MS: number;
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* HTTP transport for the BFF's tRPC endpoint (`/api/trpc/<procedure>`).
|
|
266
|
+
*
|
|
267
|
+
* Queries are header-less GETs with `?input=<json>` (a CORS "simple request",
|
|
268
|
+
* so no preflight); mutations POST a JSON body. The only things that leave the
|
|
269
|
+
* extension are payment inputs and optional recovery session/proof inputs
|
|
270
|
+
* and the browser's standard headers — `credentials: 'omit'` keeps cookies out.
|
|
271
|
+
* Queries are retried on network / 5xx errors; mutations never are.
|
|
272
|
+
*/
|
|
273
|
+
|
|
274
|
+
type ProcedureKind = 'query' | 'mutation';
|
|
275
|
+
interface Transport {
|
|
276
|
+
call<T>(procedure: string, kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
|
|
277
|
+
}
|
|
278
|
+
interface HttpTransportOptions {
|
|
279
|
+
apiUrl: string;
|
|
280
|
+
/** Per-attempt timeout (default 10 s). */
|
|
281
|
+
timeoutMs?: number;
|
|
282
|
+
/** Extra attempts for queries (default 1). */
|
|
283
|
+
retries?: number;
|
|
284
|
+
fetchImpl?: typeof fetch;
|
|
285
|
+
}
|
|
286
|
+
declare const TRPC_PATH = "/api/trpc";
|
|
287
|
+
interface TrpcErrorShape {
|
|
288
|
+
message?: string;
|
|
289
|
+
code?: number;
|
|
290
|
+
data?: {
|
|
291
|
+
code?: string;
|
|
292
|
+
httpStatus?: number;
|
|
293
|
+
cause?: {
|
|
294
|
+
code?: string;
|
|
295
|
+
retryAfterSec?: number;
|
|
296
|
+
};
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* The BFF's error formatter does not forward `cause` for `pay.*` errors, so the
|
|
301
|
+
* tRPC code + message is the primary signal; `data.cause.code` is honoured when
|
|
302
|
+
* present so a future BFF that forwards it needs no SDK change.
|
|
303
|
+
*/
|
|
304
|
+
declare function trpcErrorToPayError(error: TrpcErrorShape, httpStatus?: number): ExtenshiPayError;
|
|
305
|
+
declare class HttpTransport implements Transport {
|
|
306
|
+
private readonly apiUrl;
|
|
307
|
+
private readonly timeoutMs;
|
|
308
|
+
private readonly retries;
|
|
309
|
+
private readonly fetchImpl;
|
|
310
|
+
constructor(options: HttpTransportOptions);
|
|
311
|
+
call<T>(procedure: string, kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
|
|
312
|
+
private request;
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* In-memory stand-in for the BFF, used when `mock: true`. Lets an extension be
|
|
317
|
+
* developed with no backend: offers and entitlements come from `mockData`, a
|
|
318
|
+
* mock checkout completes after `claimAfterPolls` polls and grants the SKU.
|
|
319
|
+
*/
|
|
320
|
+
|
|
321
|
+
type SessionState = 'open' | 'complete' | 'canceled' | 'expired';
|
|
322
|
+
interface MockSession {
|
|
323
|
+
sku: string;
|
|
324
|
+
polls: number;
|
|
325
|
+
state: SessionState;
|
|
326
|
+
}
|
|
327
|
+
declare class MockTransport implements Transport {
|
|
328
|
+
private entitlements;
|
|
329
|
+
private readonly offers;
|
|
330
|
+
private readonly projectName;
|
|
331
|
+
private readonly checkoutEnabled;
|
|
332
|
+
private readonly claimAfterPolls;
|
|
333
|
+
readonly sessions: Map<string, MockSession>;
|
|
334
|
+
constructor(data?: MockData);
|
|
335
|
+
call<T>(procedure: string, _kind: ProcedureKind, input: Record<string, unknown>): Promise<T>;
|
|
336
|
+
/** Test/dev helpers. */
|
|
337
|
+
setEntitlements(items: PayEntitlementItem[]): void;
|
|
338
|
+
cancelSession(sessionId: string): void;
|
|
339
|
+
expireSession(sessionId: string): void;
|
|
340
|
+
private offerResponse;
|
|
341
|
+
private createCheckout;
|
|
342
|
+
private claim;
|
|
343
|
+
private grant;
|
|
344
|
+
private envelope;
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
/** Typed wrapper over the SDK-facing `pay.*` procedures. Nothing else is ever called. */
|
|
348
|
+
|
|
349
|
+
declare class PayApi {
|
|
350
|
+
private readonly transport;
|
|
351
|
+
private readonly publishableKey;
|
|
352
|
+
constructor(transport: Transport, publishableKey: string);
|
|
353
|
+
createRestoreSession(claimChallenge: string): Promise<PayRestoreSessionResponse>;
|
|
354
|
+
claimRestoreSession(sessionId: string, claimSecret: string): Promise<PayRestoreClaimResponse>;
|
|
355
|
+
getOffer(locale?: string | null): Promise<PayOfferResponse>;
|
|
356
|
+
createCheckout(sku: string, endUserRef: string, locale?: string | null): Promise<PayCheckoutSession>;
|
|
357
|
+
claimSession(sessionId: string, endUserRef: string): Promise<PayCheckoutClaim>;
|
|
358
|
+
getEntitlement(endUserRef: string): Promise<SignedEntitlement>;
|
|
359
|
+
getPortalUrl(endUserRef: string, customerId?: string): Promise<PayPortalResponse>;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* Persistent key/value storage for the SDK's own namespace.
|
|
364
|
+
*
|
|
365
|
+
* Preference order: `chrome.storage.local` (Chrome/Edge), `browser.storage.local`
|
|
366
|
+
* (Firefox), `localStorage` (non-extension contexts such as a dev page), then
|
|
367
|
+
* memory. Both promise-returning (MV3, Firefox) and callback-only (MV2) storage
|
|
368
|
+
* APIs are supported.
|
|
369
|
+
*/
|
|
370
|
+
interface StorageAdapter {
|
|
371
|
+
get(key: string): Promise<unknown>;
|
|
372
|
+
set(key: string, value: unknown): Promise<void>;
|
|
373
|
+
remove(key: string): Promise<void>;
|
|
374
|
+
}
|
|
375
|
+
type Items = Record<string, unknown>;
|
|
376
|
+
interface StorageArea {
|
|
377
|
+
get(keys: string, callback?: (items: Items) => void): unknown;
|
|
378
|
+
set(items: Items, callback?: () => void): unknown;
|
|
379
|
+
remove(keys: string, callback?: () => void): unknown;
|
|
380
|
+
}
|
|
381
|
+
declare class ExtensionStorage implements StorageAdapter {
|
|
382
|
+
private readonly area;
|
|
383
|
+
constructor(area: StorageArea);
|
|
384
|
+
get(key: string): Promise<unknown>;
|
|
385
|
+
set(key: string, value: unknown): Promise<void>;
|
|
386
|
+
remove(key: string): Promise<void>;
|
|
387
|
+
}
|
|
388
|
+
declare class LocalStorageAdapter implements StorageAdapter {
|
|
389
|
+
private readonly store;
|
|
390
|
+
constructor(store: Storage);
|
|
391
|
+
get(key: string): Promise<unknown>;
|
|
392
|
+
set(key: string, value: unknown): Promise<void>;
|
|
393
|
+
remove(key: string): Promise<void>;
|
|
394
|
+
}
|
|
395
|
+
declare class MemoryStorage implements StorageAdapter {
|
|
396
|
+
private readonly map;
|
|
397
|
+
get(key: string): Promise<unknown>;
|
|
398
|
+
set(key: string, value: unknown): Promise<void>;
|
|
399
|
+
remove(key: string): Promise<void>;
|
|
400
|
+
}
|
|
401
|
+
declare function createStorage(): StorageAdapter;
|
|
402
|
+
|
|
403
|
+
type PaywallMode = 'modal' | 'inline' | 'sidebar' | 'fullscreen' | 'minimal';
|
|
404
|
+
/** Every user-visible string the SDK adds on top of the templates (English only; iteration 12 T9 swaps locales). */
|
|
405
|
+
interface PaywallStrings {
|
|
406
|
+
title: string;
|
|
407
|
+
description: string;
|
|
408
|
+
upgrade: string;
|
|
409
|
+
cancel: string;
|
|
410
|
+
dismiss: string;
|
|
411
|
+
remindLater: string;
|
|
412
|
+
continueFree: string;
|
|
413
|
+
checkoutUnavailable: string;
|
|
414
|
+
periodMonth: string;
|
|
415
|
+
periodYear: string;
|
|
416
|
+
periodOnce: string;
|
|
417
|
+
footer: string;
|
|
418
|
+
restorePurchase: string;
|
|
419
|
+
}
|
|
420
|
+
interface PaywallOptions {
|
|
421
|
+
/** Template to render (default `modal`). */
|
|
422
|
+
mode?: PaywallMode;
|
|
423
|
+
/** Offer to feature; defaults to the first active offer. */
|
|
424
|
+
sku?: string;
|
|
425
|
+
title?: string;
|
|
426
|
+
description?: string;
|
|
427
|
+
/** Overrides the offer's `features[]`. */
|
|
428
|
+
features?: string[];
|
|
429
|
+
/** Free-tier bullets for the comparison templates (`inline`, `fullscreen`). */
|
|
430
|
+
freeFeatures?: string[];
|
|
431
|
+
theme?: ThemeConfig;
|
|
432
|
+
/** Mount point for `inline` mode (default `document.body`). */
|
|
433
|
+
container?: HTMLElement;
|
|
434
|
+
strings?: Partial<PaywallStrings>;
|
|
435
|
+
onUpgrade?: (sku: string) => void;
|
|
436
|
+
onClose?: () => void;
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
type EntitlementSource = 'network' | 'cache' | 'mock' | 'none';
|
|
440
|
+
/** The SDK's view of the server projection, with `expiresAt` applied locally. */
|
|
441
|
+
interface Entitlement {
|
|
442
|
+
items: PayEntitlementItem[];
|
|
443
|
+
/** Union of `features[]` over active/grace items. */
|
|
444
|
+
features: string[];
|
|
445
|
+
/** True only when the Ed25519 signature was checked against the project's key. */
|
|
446
|
+
verified: boolean;
|
|
447
|
+
issuedAt: string | null;
|
|
448
|
+
/** `Date.now()` of the last successful fetch, or null when nothing was ever fetched. */
|
|
449
|
+
fetchedAt: number | null;
|
|
450
|
+
/** Paid access is paused until a successful online check, not a license expiry. */
|
|
451
|
+
requiresOnlineCheck?: boolean;
|
|
452
|
+
/** Local offline-access deadline; null for mock mode or no cached license. */
|
|
453
|
+
offlineUntil?: number | null;
|
|
454
|
+
source: EntitlementSource;
|
|
455
|
+
}
|
|
456
|
+
interface GetEntitlementOptions {
|
|
457
|
+
/** Skip the cache TTL and hit the network. */
|
|
458
|
+
force?: boolean;
|
|
459
|
+
}
|
|
460
|
+
type CheckoutState = 'complete' | 'canceled' | 'expired' | 'timeout';
|
|
461
|
+
interface CheckoutResult {
|
|
462
|
+
state: CheckoutState;
|
|
463
|
+
sku: string;
|
|
464
|
+
sessionId: string;
|
|
465
|
+
entitlement?: Entitlement;
|
|
466
|
+
}
|
|
467
|
+
interface CheckoutOptions {
|
|
468
|
+
locale?: string;
|
|
469
|
+
/** Stop polling `claimSession` after this long (default 10 minutes). */
|
|
470
|
+
timeoutMs?: number;
|
|
471
|
+
/** Poll interval (default 2 seconds). */
|
|
472
|
+
pollIntervalMs?: number;
|
|
473
|
+
/** Override how the hosted checkout URL is opened (default: `chrome.tabs.create`, then `window.open`). */
|
|
474
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
475
|
+
}
|
|
476
|
+
interface RequireFeatureOptions {
|
|
477
|
+
/** Full bundle only: show the paywall when the feature is locked (default true). */
|
|
478
|
+
showPaywall?: boolean;
|
|
479
|
+
onUnlock?: () => void;
|
|
480
|
+
onCancel?: () => void;
|
|
481
|
+
/** Paywall options used when `showPaywall` is true. */
|
|
482
|
+
paywall?: PaywallOptions;
|
|
483
|
+
}
|
|
484
|
+
interface RestoreOptions {
|
|
485
|
+
timeoutMs?: number;
|
|
486
|
+
pollIntervalMs?: number;
|
|
487
|
+
signal?: AbortSignal;
|
|
488
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
489
|
+
}
|
|
490
|
+
type RestoreResult = {
|
|
491
|
+
state: 'complete';
|
|
492
|
+
entitlement: Entitlement;
|
|
493
|
+
} | {
|
|
494
|
+
state: 'timeout' | 'expired' | 'canceled';
|
|
495
|
+
};
|
|
496
|
+
interface CustomerPortalOptions {
|
|
497
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
498
|
+
/** Return a listed profile ID, or null to cancel. Required by Lite for multiple profiles. */
|
|
499
|
+
selectAccount?: (accounts: PayPortalAccount[]) => string | null | Promise<string | null>;
|
|
500
|
+
}
|
|
501
|
+
interface LicenseSummary {
|
|
502
|
+
projectName: string | null;
|
|
503
|
+
seller: PaySellerPublic | null;
|
|
504
|
+
entitlement: Entitlement;
|
|
505
|
+
recoveryEnabled: boolean;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
interface ExtenshiPayEvents {
|
|
509
|
+
ready: {
|
|
510
|
+
endUserRef: string;
|
|
511
|
+
};
|
|
512
|
+
'entitlement:changed': Entitlement;
|
|
513
|
+
'checkout:started': {
|
|
514
|
+
sku: string;
|
|
515
|
+
sessionId: string;
|
|
516
|
+
url: string;
|
|
517
|
+
};
|
|
518
|
+
'checkout:completed': {
|
|
519
|
+
sku: string;
|
|
520
|
+
sessionId: string;
|
|
521
|
+
entitlement: Entitlement;
|
|
522
|
+
};
|
|
523
|
+
'checkout:canceled': {
|
|
524
|
+
sku: string;
|
|
525
|
+
sessionId: string;
|
|
526
|
+
};
|
|
527
|
+
'checkout:expired': {
|
|
528
|
+
sku: string;
|
|
529
|
+
sessionId: string;
|
|
530
|
+
};
|
|
531
|
+
error: ExtenshiPayError;
|
|
532
|
+
}
|
|
533
|
+
type ExtenshiPayEventName = keyof ExtenshiPayEvents;
|
|
534
|
+
|
|
535
|
+
/**
|
|
536
|
+
* Hosted checkout flow.
|
|
537
|
+
*
|
|
538
|
+
* `pay.createCheckout` returns a URL on the seller's provider; the SDK opens
|
|
539
|
+
* it in a new tab (`chrome.tabs.create`, falling back to `window.open`) and
|
|
540
|
+
* polls `pay.claimSession` every 2 s for up to 10 min — and immediately when
|
|
541
|
+
* the extension regains focus — until the webhook has landed. A pending
|
|
542
|
+
* session is persisted so a restarted service worker / reopened popup can
|
|
543
|
+
* finish the claim on the next `initialize()`.
|
|
544
|
+
*/
|
|
545
|
+
|
|
546
|
+
declare const CHECKOUT_POLL_INTERVAL_MS = 2000;
|
|
547
|
+
declare const CHECKOUT_TIMEOUT_MS: number;
|
|
548
|
+
type OpenUrl = (url: string) => void | Promise<void>;
|
|
549
|
+
type Emit = <K extends keyof ExtenshiPayEvents>(event: K, payload: ExtenshiPayEvents[K]) => void;
|
|
550
|
+
interface CheckoutManagerOptions {
|
|
551
|
+
api: PayApi;
|
|
552
|
+
storage: StorageAdapter;
|
|
553
|
+
publishableKey: string;
|
|
554
|
+
locale: string | null;
|
|
555
|
+
getEndUserRef: () => Promise<string>;
|
|
556
|
+
/** Verifies + stores the envelope from a completed session. */
|
|
557
|
+
onComplete: (envelope: SignedEntitlement) => Promise<Entitlement>;
|
|
558
|
+
emit: Emit;
|
|
559
|
+
openUrl?: OpenUrl;
|
|
560
|
+
now?: () => number;
|
|
561
|
+
}
|
|
562
|
+
declare function openInNewTab(url: string): Promise<void>;
|
|
563
|
+
declare class CheckoutManager {
|
|
564
|
+
private readonly options;
|
|
565
|
+
private active;
|
|
566
|
+
private readonly now;
|
|
567
|
+
constructor(options: CheckoutManagerOptions);
|
|
568
|
+
get pendingKey(): string;
|
|
569
|
+
isActive(): boolean;
|
|
570
|
+
open(sku: string, options?: CheckoutOptions): Promise<CheckoutResult>;
|
|
571
|
+
/** Finishes a checkout that was started before a restart; null when there is nothing to resume. */
|
|
572
|
+
resumePending(): Promise<CheckoutResult | null>;
|
|
573
|
+
private poll;
|
|
574
|
+
private settle;
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
/**
|
|
578
|
+
* Entitlement cache + refresh.
|
|
579
|
+
*
|
|
580
|
+
* The cached envelope is a cache OF the server projection, never a second
|
|
581
|
+
* source of truth: it is verified when stored and re-verified on load (once
|
|
582
|
+
* the project's public key is known), served without a round-trip while the
|
|
583
|
+
* TTL holds, served for up to 48 hours after signed issuance when the network is down, and expired
|
|
584
|
+
* locally by `expiresAt`. Background refresh polls at most every 15 minutes
|
|
585
|
+
* and backs off exponentially on errors.
|
|
586
|
+
*/
|
|
587
|
+
|
|
588
|
+
declare const MIN_REFRESH_INTERVAL_MS: number;
|
|
589
|
+
declare const MAX_REFRESH_BACKOFF_MS: number;
|
|
590
|
+
interface EntitlementManagerOptions {
|
|
591
|
+
api: PayApi;
|
|
592
|
+
storage: StorageAdapter;
|
|
593
|
+
publishableKey: string;
|
|
594
|
+
cacheTtlMs: number;
|
|
595
|
+
source?: EntitlementSource;
|
|
596
|
+
getEndUserRef: () => Promise<string>;
|
|
597
|
+
/** Base64 raw Ed25519 public key from `getOffer`, or null when unknown/unsigned. */
|
|
598
|
+
getPublicKey: () => Promise<string | null>;
|
|
599
|
+
onChange?: (entitlement: Entitlement) => void;
|
|
600
|
+
onError?: (error: ExtenshiPayError) => void;
|
|
601
|
+
now?: () => number;
|
|
602
|
+
}
|
|
603
|
+
declare class EntitlementManager {
|
|
604
|
+
private readonly options;
|
|
605
|
+
private held;
|
|
606
|
+
private inflight;
|
|
607
|
+
private timer;
|
|
608
|
+
private refreshGeneration;
|
|
609
|
+
private deadlineTimer;
|
|
610
|
+
private refreshIntervalMs;
|
|
611
|
+
private backoffMs;
|
|
612
|
+
private autoRefresh;
|
|
613
|
+
private readonly online;
|
|
614
|
+
private lastFingerprint;
|
|
615
|
+
private readonly now;
|
|
616
|
+
private readonly source;
|
|
617
|
+
constructor(options: EntitlementManagerOptions);
|
|
618
|
+
get storageKey(): string;
|
|
619
|
+
/** Loads the persisted envelope (unverified until `reverify()`); no network. */
|
|
620
|
+
load(): Promise<Entitlement | null>;
|
|
621
|
+
/** Re-checks the loaded envelope against the project's key; discards it when the signature is invalid. */
|
|
622
|
+
reverify(): Promise<void>;
|
|
623
|
+
getCached(): Entitlement | null;
|
|
624
|
+
isFresh(): boolean;
|
|
625
|
+
get(options?: {
|
|
626
|
+
force?: boolean;
|
|
627
|
+
}): Promise<Entitlement>;
|
|
628
|
+
/** Fetches the projection from the backend, verifies and stores it. */
|
|
629
|
+
refresh(): Promise<Entitlement>;
|
|
630
|
+
/** Verifies and stores an envelope obtained elsewhere (e.g. from `claimSession`). */
|
|
631
|
+
accept(envelope: SignedEntitlement, source?: EntitlementSource): Promise<Entitlement>;
|
|
632
|
+
/** Drain an older installation refresh before changing identity. */
|
|
633
|
+
settleRefresh(): Promise<void>;
|
|
634
|
+
clear(): Promise<void>;
|
|
635
|
+
startAutoRefresh(intervalMs?: number): void;
|
|
636
|
+
stopAutoRefresh(): void;
|
|
637
|
+
private scheduleDeadline;
|
|
638
|
+
private schedule;
|
|
639
|
+
private safePublicKey;
|
|
640
|
+
private discard;
|
|
641
|
+
private fingerprint;
|
|
642
|
+
private notifyIfChanged;
|
|
643
|
+
private offlineDeadline;
|
|
644
|
+
private snapshot;
|
|
645
|
+
}
|
|
646
|
+
|
|
647
|
+
/** Pure helpers over the entitlement projection. Features come from the items' `features[]`. */
|
|
648
|
+
|
|
649
|
+
declare function isLive(item: PayEntitlementItem): boolean;
|
|
650
|
+
/** An item past its `expiresAt` reads as expired without a network round-trip. */
|
|
651
|
+
declare function applyLocalExpiry(items: PayEntitlementItem[], now?: number): PayEntitlementItem[];
|
|
652
|
+
declare function collectFeatures(items: PayEntitlementItem[]): string[];
|
|
653
|
+
declare function isEntitled(entitlement: Entitlement, sku?: string): boolean;
|
|
654
|
+
declare function hasFeature(entitlement: Entitlement, feature: string): boolean;
|
|
655
|
+
declare function checkFeatures(entitlement: Entitlement, features: string[]): Record<string, boolean>;
|
|
656
|
+
declare const EMPTY_ENTITLEMENT: Entitlement;
|
|
657
|
+
|
|
658
|
+
/** Email stays on the hosted page. Only this extension context holds the claim secret. */
|
|
659
|
+
|
|
660
|
+
/** storage.local is exposed to content scripts by default. Never put a recovery proof there. */
|
|
661
|
+
declare function createRecoveryStorage(): StorageAdapter;
|
|
662
|
+
interface RecoveryManagerOptions {
|
|
663
|
+
api: PayApi;
|
|
664
|
+
storage: StorageAdapter;
|
|
665
|
+
publishableKey: string;
|
|
666
|
+
onComplete: (endUserRef: string, envelope: SignedEntitlement) => Promise<Entitlement>;
|
|
667
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
668
|
+
now?: () => number;
|
|
669
|
+
}
|
|
670
|
+
declare class RecoveryManager {
|
|
671
|
+
private readonly options;
|
|
672
|
+
private active;
|
|
673
|
+
private stopped;
|
|
674
|
+
private wake;
|
|
675
|
+
constructor(options: RecoveryManagerOptions);
|
|
676
|
+
get pendingKey(): string;
|
|
677
|
+
isActive(): boolean;
|
|
678
|
+
stop(): void;
|
|
679
|
+
open(options?: RestoreOptions): Promise<RestoreResult>;
|
|
680
|
+
resumePending(): Promise<RestoreResult | null>;
|
|
681
|
+
private poll;
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
/**
|
|
685
|
+
* Ed25519 verification of the entitlement projection.
|
|
686
|
+
*
|
|
687
|
+
* Tamper resistance, not DRM. Trust comes from the developer's bundled key or
|
|
688
|
+
* a key fetched over HTTPS, never from editable extension storage. Callers must
|
|
689
|
+
* deny access for both invalid and unverified envelopes outside explicit mocks.
|
|
690
|
+
*/
|
|
691
|
+
|
|
692
|
+
type SignatureVerdict = 'valid' | 'invalid' | 'unverified';
|
|
693
|
+
declare function base64ToBytes(base64: string): Uint8Array<ArrayBuffer>;
|
|
694
|
+
declare function verifyEntitlementSignature(envelope: SignedEntitlement, publicKeyBase64: string | null): Promise<SignatureVerdict>;
|
|
695
|
+
|
|
696
|
+
declare class Logger {
|
|
697
|
+
private level;
|
|
698
|
+
private readonly prefix;
|
|
699
|
+
configure(options: {
|
|
700
|
+
logLevel?: LogLevel;
|
|
701
|
+
debug?: boolean;
|
|
702
|
+
}): void;
|
|
703
|
+
error(message: string, ...args: unknown[]): void;
|
|
704
|
+
warn(message: string, ...args: unknown[]): void;
|
|
705
|
+
info(message: string, ...args: unknown[]): void;
|
|
706
|
+
debug(message: string, ...args: unknown[]): void;
|
|
707
|
+
private enabled;
|
|
708
|
+
}
|
|
709
|
+
declare const logger: Logger;
|
|
710
|
+
|
|
711
|
+
/** Kept in sync with package.json by tests/unit/version.test.ts. */
|
|
712
|
+
declare const VERSION = "0.7.0";
|
|
713
|
+
|
|
714
|
+
/** Same shape the BFF accepts (`en`, `de-DE`, `zh-Hant`). */
|
|
715
|
+
declare const LOCALE_RE: RegExp;
|
|
716
|
+
declare function resolveConfig(input: ExtenshiPayConfig): ResolvedConfig;
|
|
717
|
+
|
|
718
|
+
type Listener<T> = (payload: T) => void;
|
|
719
|
+
declare class EventEmitter<Events extends object> {
|
|
720
|
+
private readonly listeners;
|
|
721
|
+
on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
|
|
722
|
+
once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
|
|
723
|
+
off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
|
|
724
|
+
emit<K extends keyof Events>(event: K, payload: Events[K]): void;
|
|
725
|
+
removeAll(): void;
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
/**
|
|
729
|
+
* `ExtenshiPayLite` — entitlement, feature gating and hosted checkout, without
|
|
730
|
+
* the paywall UI. This is what the `lite` bundle exports; the full `ExtenshiPay`
|
|
731
|
+
* extends it with `getOffer()` / `showPaywall()`.
|
|
732
|
+
*
|
|
733
|
+
* Data that leaves the extension: `publishableKey`, `endUserRef`, `sku`,
|
|
734
|
+
* `locale` and checkout session IDs. Explicit recovery also sends its session ID,
|
|
735
|
+
* challenge and claim secret (POST body). Email stays on the hosted page.
|
|
736
|
+
*/
|
|
737
|
+
|
|
738
|
+
/** Injection points for tests and unusual hosts. */
|
|
739
|
+
interface ExtenshiPayDeps {
|
|
740
|
+
storage?: StorageAdapter;
|
|
741
|
+
/** Trusted extension-only storage; never share this adapter with content scripts. */
|
|
742
|
+
recoveryStorage?: StorageAdapter;
|
|
743
|
+
transport?: Transport;
|
|
744
|
+
fetch?: typeof fetch;
|
|
745
|
+
openUrl?: (url: string) => void | Promise<void>;
|
|
746
|
+
now?: () => number;
|
|
747
|
+
}
|
|
748
|
+
declare class ExtenshiPayLite {
|
|
749
|
+
static readonly version = "0.7.0";
|
|
750
|
+
protected readonly config: ResolvedConfig;
|
|
751
|
+
protected readonly emitter: EventEmitter<ExtenshiPayEvents>;
|
|
752
|
+
protected readonly storage: StorageAdapter;
|
|
753
|
+
protected readonly api: PayApi;
|
|
754
|
+
protected readonly entitlements: EntitlementManager;
|
|
755
|
+
protected readonly checkout: CheckoutManager;
|
|
756
|
+
protected readonly recovery: RecoveryManager;
|
|
757
|
+
private readonly now;
|
|
758
|
+
private endUserRef;
|
|
759
|
+
private endUserRefPromise;
|
|
760
|
+
private offer;
|
|
761
|
+
private offerInflight;
|
|
762
|
+
private readyPromise;
|
|
763
|
+
private destroyed;
|
|
764
|
+
constructor(config: ExtenshiPayConfig, deps?: ExtenshiPayDeps);
|
|
765
|
+
get version(): string;
|
|
766
|
+
/**
|
|
767
|
+
* Mints/loads `endUserRef`, loads the cached entitlement, re-verifies it and
|
|
768
|
+
* refreshes it when stale. Resolves once `isPaid()` can answer; network
|
|
769
|
+
* failures fall back to the cache and are reported through `error`.
|
|
770
|
+
*/
|
|
771
|
+
initialize(): Promise<void>;
|
|
772
|
+
private doInitialize;
|
|
773
|
+
private afterReady;
|
|
774
|
+
/** The anonymous, random id this install is known by. */
|
|
775
|
+
getEndUserRef(): Promise<string>;
|
|
776
|
+
getCachedEntitlement(): Entitlement | null;
|
|
777
|
+
getEntitlement(options?: GetEntitlementOptions): Promise<Entitlement>;
|
|
778
|
+
/** True when any active/grace entitlement exists, or the given `sku` is active/grace. */
|
|
779
|
+
isPaid(sku?: string): Promise<boolean>;
|
|
780
|
+
hasFeature(feature: string): Promise<boolean>;
|
|
781
|
+
checkFeatures(features: string[]): Promise<Record<string, boolean>>;
|
|
782
|
+
/** Resolves true when the feature is (or becomes) unlocked. */
|
|
783
|
+
requireFeature(feature: string, options?: RequireFeatureOptions): Promise<boolean>;
|
|
784
|
+
/** Lite has no UI: a locked feature stays locked. The full SDK shows the paywall here. */
|
|
785
|
+
protected onFeatureLocked(_feature: string, _options: RequireFeatureOptions): Promise<boolean>;
|
|
786
|
+
/** Opens hosted checkout for `sku` in a new tab and resolves when the session settles. */
|
|
787
|
+
openCheckout(sku: string, options?: CheckoutOptions): Promise<CheckoutResult>;
|
|
788
|
+
/** Opens email verification on the hosted page. No email is collected inside the extension. */
|
|
789
|
+
restorePurchase(options?: RestoreOptions): Promise<RestoreResult>;
|
|
790
|
+
/** Read-only license view. Entitlements retain cache/signature/offline semantics. */
|
|
791
|
+
getLicenseSummary(options?: GetEntitlementOptions): Promise<LicenseSummary>;
|
|
792
|
+
/** Opens the provider's self-service portal; resolves null when the provider has none. */
|
|
793
|
+
openCustomerPortal(options?: CustomerPortalOptions): Promise<string | null>;
|
|
794
|
+
on<K extends keyof ExtenshiPayEvents>(event: K, listener: Listener<ExtenshiPayEvents[K]>): () => void;
|
|
795
|
+
once<K extends keyof ExtenshiPayEvents>(event: K, listener: Listener<ExtenshiPayEvents[K]>): () => void;
|
|
796
|
+
off<K extends keyof ExtenshiPayEvents>(event: K, listener: Listener<ExtenshiPayEvents[K]>): void;
|
|
797
|
+
onEntitlementChange(listener: Listener<Entitlement>): () => void;
|
|
798
|
+
clearCache(): Promise<void>;
|
|
799
|
+
/** Stops background refresh and drops listeners. */
|
|
800
|
+
destroy(): void;
|
|
801
|
+
/** Offer + signing key. Public in the full SDK (`getOffer`), internal here. */
|
|
802
|
+
protected fetchOffer(force?: boolean): Promise<PayOfferResponse>;
|
|
803
|
+
private getPublicKey;
|
|
804
|
+
protected reportError(error: unknown): ExtenshiPayError;
|
|
805
|
+
}
|
|
806
|
+
|
|
807
|
+
/**
|
|
808
|
+
* `endUserRef` — the only identity the SDK has.
|
|
809
|
+
*
|
|
810
|
+
* A random UUID minted on first run and kept in the SDK's storage namespace.
|
|
811
|
+
* It is never derived from anything identifying (no fingerprint, no e-mail,
|
|
812
|
+
* no extension-supplied user id) and remains the installation identifier. Explicit recovery also sends a
|
|
813
|
+
* random session ID and proof; it never derives identity from an email locally.
|
|
814
|
+
*/
|
|
815
|
+
|
|
816
|
+
declare const END_USER_REF_STORAGE_KEY = "extenshi-pay:endUserRef";
|
|
817
|
+
declare function mintEndUserRef(): string;
|
|
818
|
+
declare function getOrCreateEndUserRef(storage: StorageAdapter): Promise<string>;
|
|
819
|
+
|
|
820
|
+
/** Full SDK: everything in `ExtenshiPayLite` plus the offer and the paywall UI. */
|
|
821
|
+
|
|
822
|
+
declare class ExtenshiPay extends ExtenshiPayLite {
|
|
823
|
+
private disposed;
|
|
824
|
+
private licensePanel;
|
|
825
|
+
private billingProfiles;
|
|
826
|
+
private paywall;
|
|
827
|
+
private paywallSession;
|
|
828
|
+
openCustomerPortal(options?: CustomerPortalOptions): Promise<string | null>;
|
|
829
|
+
destroy(): void;
|
|
830
|
+
showLicense(): Promise<void>;
|
|
831
|
+
getOffer(options?: {
|
|
832
|
+
force?: boolean;
|
|
833
|
+
}): Promise<PayOfferResponse>;
|
|
834
|
+
/**
|
|
835
|
+
* Renders the paywall and resolves `true` when a checkout started from it
|
|
836
|
+
* completes, `false` when the user closes it. The offer is fetched via
|
|
837
|
+
* `getOffer()`; if that fails the paywall still renders with checkout disabled.
|
|
838
|
+
*/
|
|
839
|
+
showPaywall(options?: PaywallOptions): Promise<boolean>;
|
|
840
|
+
hidePaywall(): void;
|
|
841
|
+
isPaywallVisible(): boolean;
|
|
842
|
+
protected onFeatureLocked(_feature: string, options: RequireFeatureOptions): Promise<boolean>;
|
|
843
|
+
private renderer;
|
|
844
|
+
private handleRestore;
|
|
845
|
+
private handleUpgrade;
|
|
846
|
+
private settlePaywall;
|
|
847
|
+
}
|
|
848
|
+
|
|
849
|
+
interface FormattedPrice {
|
|
850
|
+
/** Currency symbol/code as the locale renders it (`$`, `€`, `US$`). */
|
|
851
|
+
currency: string;
|
|
852
|
+
/** Numeric part (`9.99`, `9,99`). */
|
|
853
|
+
amount: string;
|
|
854
|
+
/** The whole formatted price (`$9.99`). */
|
|
855
|
+
full: string;
|
|
856
|
+
}
|
|
857
|
+
declare function formatPrice(amountMinor: number, currency: string, locale?: string | null): FormattedPrice;
|
|
858
|
+
declare function periodLabel(offer: PayOfferDto, strings: PaywallStrings): string;
|
|
859
|
+
|
|
860
|
+
/**
|
|
861
|
+
* The one paywall renderer.
|
|
862
|
+
*
|
|
863
|
+
* Renders a template from `@extenshi/paywall-templates` into a Shadow DOM
|
|
864
|
+
* host so the templates' resets never leak into the extension page (and vice
|
|
865
|
+
* versa). Placeholders (`{{title}}`, `{{price}}` …) are filled from the offer
|
|
866
|
+
* and the strings dictionary, every value HTML-escaped; buttons are bound with
|
|
867
|
+
* `addEventListener` on `data-ep-action` (no inline handlers, no scripts).
|
|
868
|
+
*/
|
|
869
|
+
|
|
870
|
+
interface PaywallView {
|
|
871
|
+
mode: PaywallMode;
|
|
872
|
+
title: string;
|
|
873
|
+
description: string;
|
|
874
|
+
features: string[];
|
|
875
|
+
freeFeatures: string[];
|
|
876
|
+
brandName: string;
|
|
877
|
+
offer: PayOfferDto | null;
|
|
878
|
+
checkoutEnabled: boolean;
|
|
879
|
+
mock?: boolean;
|
|
880
|
+
recoveryEnabled?: boolean;
|
|
881
|
+
seller?: PaySellerPublic | null;
|
|
882
|
+
locale: string | null;
|
|
883
|
+
theme: ThemeConfig;
|
|
884
|
+
strings: Partial<PaywallStrings>;
|
|
885
|
+
container?: HTMLElement;
|
|
886
|
+
}
|
|
887
|
+
interface PaywallRendererCallbacks {
|
|
888
|
+
onUpgrade: (sku: string) => void;
|
|
889
|
+
onClose: () => void;
|
|
890
|
+
onRestore?: () => void;
|
|
891
|
+
}
|
|
892
|
+
declare const PAYWALL_HOST_CLASS = "extenshi-paywall-host";
|
|
893
|
+
declare function escapeHtml(value: string): string;
|
|
894
|
+
declare function substitute(html: string, content: Record<string, string>): string;
|
|
895
|
+
declare function buildContent(view: PaywallView, strings: PaywallStrings): Record<string, string>;
|
|
896
|
+
declare function themeCss(theme: ThemeConfig): string;
|
|
897
|
+
declare function resolveThemeMode(theme: ThemeConfig): 'light' | 'dark';
|
|
898
|
+
declare class PaywallRenderer {
|
|
899
|
+
private readonly callbacks;
|
|
900
|
+
private host;
|
|
901
|
+
private keyHandler;
|
|
902
|
+
constructor(callbacks: PaywallRendererCallbacks);
|
|
903
|
+
isVisible(): boolean;
|
|
904
|
+
/** Returns the host element; its shadow root holds the rendered template. */
|
|
905
|
+
show(view: PaywallView): HTMLElement;
|
|
906
|
+
hide(): void;
|
|
907
|
+
private prune;
|
|
908
|
+
private bind;
|
|
909
|
+
private reveal;
|
|
910
|
+
private close;
|
|
911
|
+
}
|
|
912
|
+
|
|
913
|
+
/**
|
|
914
|
+
* Every string the SDK adds on top of the templates. English only for now;
|
|
915
|
+
* iteration 12 T9 / 13 replaces this dictionary per locale. Do not add
|
|
916
|
+
* promotional claims here without marketing/legal review (see
|
|
917
|
+
* .claude/modules/paywall-templates.md).
|
|
918
|
+
*/
|
|
919
|
+
|
|
920
|
+
declare const DEFAULT_STRINGS: PaywallStrings;
|
|
921
|
+
|
|
922
|
+
/**
|
|
923
|
+
* The five templates from `@extenshi/paywall-templates`, inlined at build
|
|
924
|
+
* time by build/paywall-templates-plugin.mjs. No runtime fetch, no
|
|
925
|
+
* `web_accessible_resources`, no remote code.
|
|
926
|
+
*/
|
|
927
|
+
|
|
928
|
+
interface PaywallTemplate {
|
|
929
|
+
html: string;
|
|
930
|
+
css: string;
|
|
931
|
+
}
|
|
932
|
+
declare const PAYWALL_SHARED_CSS: string;
|
|
933
|
+
declare const PAYWALL_TEMPLATES: Record<PaywallMode, PaywallTemplate>;
|
|
934
|
+
declare const PAYWALL_MODES: PaywallMode[];
|
|
935
|
+
|
|
936
|
+
export { CHECKOUT_POLL_INTERVAL_MS, CHECKOUT_TIMEOUT_MS, CheckoutManager, DEFAULT_API_URL, DEFAULT_CACHE_TTL_MS, DEFAULT_STRINGS, EMPTY_ENTITLEMENT, END_USER_REF_STORAGE_KEY, ERROR_CODES, EntitlementManager, EventEmitter, ExtenshiPay, ExtenshiPayError, ExtenshiPayLite, ExtensionStorage, HttpTransport, LOCALE_RE, LocalStorageAdapter, Logger, MAX_CACHE_TTL_MS, MAX_REFRESH_BACKOFF_MS, MIN_REFRESH_INTERVAL_MS, MemoryStorage, MockTransport, PAYWALL_HOST_CLASS, PAYWALL_MODES, PAYWALL_SHARED_CSS, PAYWALL_TEMPLATES, 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, PayApi, PaywallRenderer, RecoveryManager, TRPC_PATH, VERSION, applyLocalExpiry, base64ToBytes, buildContent, canonicalJson, checkFeatures, collectFeatures, createRecoveryStorage, createStorage, ExtenshiPay as default, escapeHtml, formatPrice, getOrCreateEndUserRef, hasFeature, isEntitled, isLive, isPayPublishableKey, logger, mintEndUserRef, openInNewTab, periodLabel, resolveConfig, resolveThemeMode, substitute, themeCss, trpcErrorToPayError, verifyEntitlementSignature };
|
|
937
|
+
export type { CheckoutManagerOptions, CheckoutOptions, CheckoutResult, CheckoutState, CustomerPortalOptions, Entitlement, EntitlementManagerOptions, EntitlementSource, Environment, ErrorCode, ExtenshiPayConfig, ExtenshiPayDeps, ExtenshiPayErrorOptions, ExtenshiPayEventName, ExtenshiPayEvents, FormattedPrice, GetEntitlementOptions, HttpTransportOptions, LicenseSummary, Listener, LogLevel, MockData, PayCheckoutClaim, PayCheckoutSession, PayCurrency, PayEntitlementItem, PayEntitlementPayload, PayEntitlementStatus, PayErrorCode, PayGatewayId, PayOfferDto, PayOfferInterval, PayOfferKind, PayOfferResponse, PayPortalAccount, PayPortalResponse, PayRestoreClaimResponse, PayRestoreSessionResponse, PaySellerPublic, PaywallMode, PaywallOptions, PaywallRendererCallbacks, PaywallStrings, PaywallTemplate, PaywallView, ProcedureKind, RecoveryManagerOptions, RequireFeatureOptions, ResolvedConfig, RestoreOptions, RestoreResult, SignatureVerdict, SignedEntitlement, StorageAdapter, ThemeConfig, Transport };
|