@superwall/runtime 1.1.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 +105 -0
- package/README.md +93 -0
- package/dist/bridge/base64.d.ts +9 -0
- package/dist/bridge/base64.js +34 -0
- package/dist/bridge/index.d.ts +30 -0
- package/dist/bridge/index.js +49 -0
- package/dist/bridge/transport.d.ts +14 -0
- package/dist/bridge/transport.js +43 -0
- package/dist/config.d.ts +237 -0
- package/dist/config.js +138 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +11 -0
- package/dist/localization/index.d.ts +24 -0
- package/dist/localization/index.js +71 -0
- package/dist/localization/periods.d.ts +1 -0
- package/dist/localization/periods.js +753 -0
- package/dist/mock.d.ts +74 -0
- package/dist/mock.js +206 -0
- package/dist/products.d.ts +62 -0
- package/dist/products.js +105 -0
- package/dist/session/index.d.ts +103 -0
- package/dist/session/index.js +732 -0
- package/dist/session/state.d.ts +27 -0
- package/dist/session/state.js +60 -0
- package/dist/session/types.d.ts +93 -0
- package/dist/session/types.js +1 -0
- package/dist/session/variables.d.ts +121 -0
- package/dist/session/variables.js +5 -0
- package/package.json +51 -0
- package/src/bridge/base64.ts +56 -0
- package/src/bridge/index.ts +77 -0
- package/src/bridge/transport.ts +63 -0
- package/src/config.ts +408 -0
- package/src/index.ts +57 -0
- package/src/localization/index.ts +110 -0
- package/src/localization/periods.ts +790 -0
- package/src/mock.ts +333 -0
- package/src/products.ts +221 -0
- package/src/session/index.ts +1066 -0
- package/src/session/state.ts +112 -0
- package/src/session/types.ts +123 -0
- package/src/session/variables.ts +139 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Functional Source License, Version 1.1, ALv2 Future License
|
|
2
|
+
|
|
3
|
+
## Abbreviation
|
|
4
|
+
|
|
5
|
+
FSL-1.1-ALv2
|
|
6
|
+
|
|
7
|
+
## Notice
|
|
8
|
+
|
|
9
|
+
Copyright 2026 Superwall, Inc.
|
|
10
|
+
|
|
11
|
+
## Terms and Conditions
|
|
12
|
+
|
|
13
|
+
### Licensor ("We")
|
|
14
|
+
|
|
15
|
+
The party offering the Software under these Terms and Conditions.
|
|
16
|
+
|
|
17
|
+
### The Software
|
|
18
|
+
|
|
19
|
+
The "Software" is each version of the software that we make available under
|
|
20
|
+
these Terms and Conditions, as indicated by our inclusion of these Terms and
|
|
21
|
+
Conditions with the Software.
|
|
22
|
+
|
|
23
|
+
### License Grant
|
|
24
|
+
|
|
25
|
+
Subject to your compliance with this License Grant and the Patents,
|
|
26
|
+
Redistribution and Trademark clauses below, we hereby grant you the right to
|
|
27
|
+
use, copy, modify, create derivative works, publicly perform, publicly display
|
|
28
|
+
and redistribute the Software for any Permitted Purpose identified below.
|
|
29
|
+
|
|
30
|
+
### Permitted Purpose
|
|
31
|
+
|
|
32
|
+
A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
|
|
33
|
+
means making the Software available to others in a commercial product or
|
|
34
|
+
service that:
|
|
35
|
+
|
|
36
|
+
1. substitutes for the Software;
|
|
37
|
+
|
|
38
|
+
2. substitutes for any other product or service we offer using the Software
|
|
39
|
+
that exists as of the date we make the Software available; or
|
|
40
|
+
|
|
41
|
+
3. offers the same or substantially similar functionality as the Software.
|
|
42
|
+
|
|
43
|
+
Permitted Purposes specifically include using the Software:
|
|
44
|
+
|
|
45
|
+
1. for your internal use and access;
|
|
46
|
+
|
|
47
|
+
2. for non-commercial education;
|
|
48
|
+
|
|
49
|
+
3. for non-commercial research; and
|
|
50
|
+
|
|
51
|
+
4. in connection with professional services that you provide to a licensee
|
|
52
|
+
using the Software in accordance with these Terms and Conditions.
|
|
53
|
+
|
|
54
|
+
### Patents
|
|
55
|
+
|
|
56
|
+
To the extent your use for a Permitted Purpose would necessarily infringe our
|
|
57
|
+
patents, the license grant above includes a license under our patents. If you
|
|
58
|
+
make a claim against any party that the Software infringes or contributes to
|
|
59
|
+
the infringement of any patent, then your patent license to the Software ends
|
|
60
|
+
immediately.
|
|
61
|
+
|
|
62
|
+
### Redistribution
|
|
63
|
+
|
|
64
|
+
The Terms and Conditions apply to all copies, modifications and derivatives of
|
|
65
|
+
the Software.
|
|
66
|
+
|
|
67
|
+
If you redistribute any copies, modifications or derivatives of the Software,
|
|
68
|
+
you must include a copy of or a link to these Terms and Conditions and not
|
|
69
|
+
remove any copyright notices provided in or with the Software.
|
|
70
|
+
|
|
71
|
+
### Disclaimer
|
|
72
|
+
|
|
73
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
|
|
74
|
+
IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
|
|
75
|
+
PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
|
|
76
|
+
|
|
77
|
+
IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
|
|
78
|
+
SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
|
|
79
|
+
EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
|
|
80
|
+
|
|
81
|
+
### Trademarks
|
|
82
|
+
|
|
83
|
+
Except for displaying the License Details and identifying us as the origin of
|
|
84
|
+
the Software, you have no right under these Terms and Conditions to use our
|
|
85
|
+
trademarks, trade names, service marks or product names.
|
|
86
|
+
|
|
87
|
+
## Grant of Future License
|
|
88
|
+
|
|
89
|
+
We hereby irrevocably grant you an additional license to use the Software under
|
|
90
|
+
the Apache License, Version 2.0 that is effective on the second anniversary of
|
|
91
|
+
the date we make the Software available. On or after that date, you may use the
|
|
92
|
+
Software under the Apache License, Version 2.0, in which case the following
|
|
93
|
+
will apply:
|
|
94
|
+
|
|
95
|
+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use
|
|
96
|
+
this file except in compliance with the License.
|
|
97
|
+
|
|
98
|
+
You may obtain a copy of the License at
|
|
99
|
+
|
|
100
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
101
|
+
|
|
102
|
+
Unless required by applicable law or agreed to in writing, software distributed
|
|
103
|
+
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
|
|
104
|
+
CONDITIONS OF ANY KIND, either express or implied. See the License for the
|
|
105
|
+
specific language governing permissions and limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# `@superwall/runtime`
|
|
2
|
+
|
|
3
|
+
Shared runtime core for SDK messaging — framework-agnostic.
|
|
4
|
+
|
|
5
|
+
This package is the runtime boundary shared by every paywall Superwall
|
|
6
|
+
serves — built with this framework or with the visual editor. It owns
|
|
7
|
+
transport selection, message logging, base64 message ingestion, product
|
|
8
|
+
state, localization, SDK action dispatch, and purchase promise resolution.
|
|
9
|
+
It must not import React, or anything above it in the stack.
|
|
10
|
+
|
|
11
|
+
## Layers
|
|
12
|
+
|
|
13
|
+
- **`SuperwallBridge`** — transport auto-detection (WebKit / Android / editor
|
|
14
|
+
iframe), message log, `accept` / `accept64` ingestion, `postMessage`.
|
|
15
|
+
- **`SuperwallSession`** — the runtime model on top of the bridge:
|
|
16
|
+
- product state merged from `products` + `template_variables`
|
|
17
|
+
- `device` / `user` / `params` variables, `experiment` assignment
|
|
18
|
+
- trial eligibility from `template_substitutions_prefix` ("freeTrial")
|
|
19
|
+
- locale resolution + `t()` translation from the config's message catalogs
|
|
20
|
+
- promise-based `purchase()` with timeout, resolved by transaction messages
|
|
21
|
+
- auto-scheduled trial reminder notifications on `freeTrial_start`
|
|
22
|
+
- typed events: `session.on("paywall_open", …)`, `"message"` for all
|
|
23
|
+
- **`MockSuperwallTransport`** — a simulated native SDK host for local dev,
|
|
24
|
+
dashboard previews, tests, and the build-time conformance harness.
|
|
25
|
+
|
|
26
|
+
## Usage
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { createSuperwallSession, defineSuperwallConfig } from "@superwall/runtime"
|
|
30
|
+
|
|
31
|
+
const config = defineSuperwallConfig({
|
|
32
|
+
products: { primary: "pro_3999_year" },
|
|
33
|
+
purchaseTimeoutMs: 5 * 60 * 1000,
|
|
34
|
+
notifications: {
|
|
35
|
+
trialReminder: { title: "notifications.trialTitle", body: "…", beforeTrialEndDays: 1 },
|
|
36
|
+
},
|
|
37
|
+
localization: { defaultLocale: "en", messages: { en: { notifications: { trialTitle: "…" } } } },
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
const superwall = createSuperwallSession({ config })
|
|
41
|
+
superwall.start({ sendPing: true })
|
|
42
|
+
|
|
43
|
+
const { products, device, trial, locale } = superwall.getSnapshot()
|
|
44
|
+
superwall.t("paywall.title")
|
|
45
|
+
|
|
46
|
+
const result = await superwall.purchase("primary")
|
|
47
|
+
// result.status: "completed" | "abandoned" | "failed" — never throws for flow outcomes
|
|
48
|
+
|
|
49
|
+
superwall.on("transaction_complete", (message) => {})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Purchase semantics
|
|
53
|
+
|
|
54
|
+
- `{ status: "completed", product, message }` from `transaction_complete`
|
|
55
|
+
- `{ status: "abandoned", product, message }` from `transaction_abandon`
|
|
56
|
+
- `{ status: "failed", product, reason: "timeout" }` if `timeoutMs` (or
|
|
57
|
+
`config.purchaseTimeoutMs`) elapses without a transaction message
|
|
58
|
+
|
|
59
|
+
`restore()` is fire-and-forget: the protocol has no restore-result event.
|
|
60
|
+
|
|
61
|
+
### Trial flow
|
|
62
|
+
|
|
63
|
+
The SDK signals introductory-offer eligibility via
|
|
64
|
+
`template_substitutions_prefix` (`"freeTrial"`), exposed as `snapshot.trial`
|
|
65
|
+
and `products.hasIntroductoryOffer` in conditional state.
|
|
66
|
+
`config.introductoryOfferEligibility` can force either way. On
|
|
67
|
+
`freeTrial_start` with a `trial_end_date`, the session schedules the config's
|
|
68
|
+
trial reminder (`schedule_notification`, id
|
|
69
|
+
`{paywallIdentifier}_TRIAL_STARTED`) — title/body run through `t()`.
|
|
70
|
+
|
|
71
|
+
### Mock host
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { createMockSuperwallTransport, mockOptionsFromConfig } from "@superwall/runtime"
|
|
75
|
+
|
|
76
|
+
const transport = createMockSuperwallTransport(
|
|
77
|
+
mockOptionsFromConfig(config, { purchaseOutcome: "abandoned", latencyMs: 500 })
|
|
78
|
+
)
|
|
79
|
+
const superwall = createSuperwallSession({ config, transport })
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The mock answers `ping` with `paywall_open`, `products` (one slot per config
|
|
83
|
+
entry, carrying the product identifier and nothing else — real product data
|
|
84
|
+
comes from Superwall, never from the mock), `template_variables` (products +
|
|
85
|
+
device + user + params), and trial eligibility; resolves purchase/restore
|
|
86
|
+
with transactions including `freeTrial_start`; grants permissions; answers
|
|
87
|
+
callbacks. `detectNativeSuperwallHost()` reports whether a real host is
|
|
88
|
+
present — used by `SuperwallProvider`'s `mock="auto"`.
|
|
89
|
+
|
|
90
|
+
## Tests
|
|
91
|
+
|
|
92
|
+
`bun run test:run` — fixture tests drive the session through recorded
|
|
93
|
+
message sequences and assert snapshot state; they are the protocol contract.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { TIncomingMessage } from "@superwall/protocol";
|
|
2
|
+
export declare const decodeBase64Utf8: (message: string) => string;
|
|
3
|
+
/**
|
|
4
|
+
* Deliberately lenient, matching the original runtime: every object in the
|
|
5
|
+
* batch is delivered, including messages this build doesn't recognize (newer
|
|
6
|
+
* event types, or legacy quirks like the miscased `eventName: "experiment"`).
|
|
7
|
+
* Strictly validating here would let one unknown message drop the whole batch.
|
|
8
|
+
*/
|
|
9
|
+
export declare const decodeIncomingMessages: (message: string) => TIncomingMessage[];
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Host SDKs may encode with URL-safe alphabets and without padding (e.g.
|
|
3
|
+
* Android's Base64.URL_SAFE). atob is strict, so normalize first.
|
|
4
|
+
*/
|
|
5
|
+
const normalizeBase64 = (input) => {
|
|
6
|
+
const standard = input.replace(/-/g, "+").replace(/_/g, "/").replace(/\s/g, "");
|
|
7
|
+
const remainder = standard.length % 4;
|
|
8
|
+
return remainder === 0 ? standard : standard + "=".repeat((4 - remainder) % 4);
|
|
9
|
+
};
|
|
10
|
+
export const decodeBase64Utf8 = (message) => {
|
|
11
|
+
if (typeof globalThis.atob === "function") {
|
|
12
|
+
const binary = globalThis.atob(normalizeBase64(message));
|
|
13
|
+
const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
|
|
14
|
+
return new TextDecoder().decode(bytes);
|
|
15
|
+
}
|
|
16
|
+
const buffer = globalThis.Buffer;
|
|
17
|
+
if (buffer) {
|
|
18
|
+
return buffer.from(normalizeBase64(message), "base64").toString("utf8");
|
|
19
|
+
}
|
|
20
|
+
throw new Error("No base64 decoder is available in this runtime");
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Deliberately lenient, matching the original runtime: every object in the
|
|
24
|
+
* batch is delivered, including messages this build doesn't recognize (newer
|
|
25
|
+
* event types, or legacy quirks like the miscased `eventName: "experiment"`).
|
|
26
|
+
* Strictly validating here would let one unknown message drop the whole batch.
|
|
27
|
+
*/
|
|
28
|
+
export const decodeIncomingMessages = (message) => {
|
|
29
|
+
const parsed = JSON.parse(decodeBase64Utf8(message));
|
|
30
|
+
if (!Array.isArray(parsed)) {
|
|
31
|
+
return [];
|
|
32
|
+
}
|
|
33
|
+
return parsed.filter((entry) => typeof entry === "object" && entry !== null);
|
|
34
|
+
};
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { ITransport, TIncomingHandler, TIncomingMessage, TOutgoingMessage, TransportKind } from "@superwall/protocol";
|
|
2
|
+
export type SuperwallMessageLogEntry = {
|
|
3
|
+
ts: Date;
|
|
4
|
+
msg: TIncomingMessage;
|
|
5
|
+
type: "incoming";
|
|
6
|
+
} | {
|
|
7
|
+
ts: Date;
|
|
8
|
+
msg: TOutgoingMessage;
|
|
9
|
+
type: "outgoing";
|
|
10
|
+
};
|
|
11
|
+
export type SuperwallBridgeOptions = {
|
|
12
|
+
transport?: ITransport;
|
|
13
|
+
transportKind?: TransportKind;
|
|
14
|
+
now?: () => Date;
|
|
15
|
+
onDecodeError?: (error: unknown) => void;
|
|
16
|
+
};
|
|
17
|
+
export declare class SuperwallBridge {
|
|
18
|
+
private transport;
|
|
19
|
+
private incomingHandlers;
|
|
20
|
+
private now;
|
|
21
|
+
private onDecodeError?;
|
|
22
|
+
messages: SuperwallMessageLogEntry[];
|
|
23
|
+
constructor(options?: SuperwallBridgeOptions);
|
|
24
|
+
start(): void;
|
|
25
|
+
addListener(handler: TIncomingHandler): () => void;
|
|
26
|
+
postMessage(message: TOutgoingMessage): void;
|
|
27
|
+
accept(messages: TIncomingMessage[]): void;
|
|
28
|
+
accept64(message: string): void;
|
|
29
|
+
}
|
|
30
|
+
export declare const createSuperwallBridge: (options?: SuperwallBridgeOptions) => SuperwallBridge;
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { decodeIncomingMessages } from "./base64";
|
|
2
|
+
import { createRuntimeTransport, detectRuntimeTransportKind } from "./transport";
|
|
3
|
+
export class SuperwallBridge {
|
|
4
|
+
transport;
|
|
5
|
+
incomingHandlers = [];
|
|
6
|
+
now;
|
|
7
|
+
onDecodeError;
|
|
8
|
+
messages = [];
|
|
9
|
+
constructor(options = {}) {
|
|
10
|
+
this.transport =
|
|
11
|
+
options.transport ??
|
|
12
|
+
createRuntimeTransport(options.transportKind ?? detectRuntimeTransportKind());
|
|
13
|
+
this.now = options.now ?? (() => new Date());
|
|
14
|
+
this.onDecodeError = options.onDecodeError;
|
|
15
|
+
this.transport.addListener((message) => {
|
|
16
|
+
this.messages.push({ ts: this.now(), msg: message, type: "incoming" });
|
|
17
|
+
this.incomingHandlers.forEach((handler) => {
|
|
18
|
+
handler(message);
|
|
19
|
+
});
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
start() {
|
|
23
|
+
this.transport.startListening();
|
|
24
|
+
}
|
|
25
|
+
addListener(handler) {
|
|
26
|
+
this.incomingHandlers.push(handler);
|
|
27
|
+
return () => {
|
|
28
|
+
this.incomingHandlers = this.incomingHandlers.filter((candidate) => candidate !== handler);
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
postMessage(message) {
|
|
32
|
+
this.messages.push({ ts: this.now(), msg: message, type: "outgoing" });
|
|
33
|
+
this.transport.postMessage(message);
|
|
34
|
+
}
|
|
35
|
+
accept(messages) {
|
|
36
|
+
messages.forEach((message) => {
|
|
37
|
+
this.transport.accept(message);
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
accept64(message) {
|
|
41
|
+
try {
|
|
42
|
+
this.accept(decodeIncomingMessages(message));
|
|
43
|
+
}
|
|
44
|
+
catch (error) {
|
|
45
|
+
this.onDecodeError?.(error);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
export const createSuperwallBridge = (options = {}) => new SuperwallBridge(options);
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { TransportKind, type ITransport } from "@superwall/protocol";
|
|
2
|
+
export { pendingHostMessages } from "@superwall/protocol";
|
|
3
|
+
export type RuntimeTransportDetectionOptions = {
|
|
4
|
+
search?: string;
|
|
5
|
+
};
|
|
6
|
+
export declare const detectRuntimeTransportKind: (options?: RuntimeTransportDetectionOptions) => TransportKind;
|
|
7
|
+
export declare const createRuntimeTransport: (transportKind?: TransportKind) => ITransport;
|
|
8
|
+
/**
|
|
9
|
+
* Detects the explicit `?sw_preview` opt-in that lets a page simulate the SDK
|
|
10
|
+
* without a native host present. "auto" mock mode requires it, so a built
|
|
11
|
+
* snapshot can never downgrade itself to placeholder products by accident.
|
|
12
|
+
*/
|
|
13
|
+
export declare const detectPreviewOptIn: () => boolean;
|
|
14
|
+
export declare const detectNativeSuperwallHost: () => boolean;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { buildTransport, TransportKind } from "@superwall/protocol";
|
|
2
|
+
export { pendingHostMessages } from "@superwall/protocol";
|
|
3
|
+
export const detectRuntimeTransportKind = (options = {}) => {
|
|
4
|
+
if (typeof window === "undefined" && options.search === undefined) {
|
|
5
|
+
return TransportKind.WebKitPostMessage;
|
|
6
|
+
}
|
|
7
|
+
const search = options.search ?? window.location.search;
|
|
8
|
+
const urlParams = new URLSearchParams(search);
|
|
9
|
+
if (urlParams.get("platform") === "android") {
|
|
10
|
+
return TransportKind.Android;
|
|
11
|
+
}
|
|
12
|
+
if (urlParams.get("transport") === "editor") {
|
|
13
|
+
return TransportKind.EditorIframe;
|
|
14
|
+
}
|
|
15
|
+
return TransportKind.WebKitPostMessage;
|
|
16
|
+
};
|
|
17
|
+
export const createRuntimeTransport = (transportKind = detectRuntimeTransportKind()) => buildTransport(transportKind);
|
|
18
|
+
/**
|
|
19
|
+
* Detects the explicit `?sw_preview` opt-in that lets a page simulate the SDK
|
|
20
|
+
* without a native host present. "auto" mock mode requires it, so a built
|
|
21
|
+
* snapshot can never downgrade itself to placeholder products by accident.
|
|
22
|
+
*/
|
|
23
|
+
export const detectPreviewOptIn = () => {
|
|
24
|
+
if (typeof window === "undefined") {
|
|
25
|
+
return false;
|
|
26
|
+
}
|
|
27
|
+
return new URLSearchParams(window.location.search).has("sw_preview");
|
|
28
|
+
};
|
|
29
|
+
export const detectNativeSuperwallHost = () => {
|
|
30
|
+
if (typeof window === "undefined") {
|
|
31
|
+
return false;
|
|
32
|
+
}
|
|
33
|
+
// window.webkit and SWAndroid are declared globally by @superwall/protocol's
|
|
34
|
+
// transports — the SDK-injected host contract.
|
|
35
|
+
if (window.webkit?.messageHandlers?.paywallMessageHandler) {
|
|
36
|
+
return true;
|
|
37
|
+
}
|
|
38
|
+
if (typeof SWAndroid !== "undefined" && SWAndroid) {
|
|
39
|
+
return true;
|
|
40
|
+
}
|
|
41
|
+
const urlParams = new URLSearchParams(window.location.search);
|
|
42
|
+
return urlParams.get("platform") === "android" || urlParams.get("transport") === "editor";
|
|
43
|
+
};
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
import type { SuperwallProduct } from "./products";
|
|
2
|
+
export declare const SUPERWALL_PLATFORMS: readonly ["ios", "android", "web"];
|
|
3
|
+
export type SuperwallPlatform = (typeof SUPERWALL_PLATFORMS)[number];
|
|
4
|
+
export declare const normalizePlatform: (value: string | undefined) => SuperwallPlatform | undefined;
|
|
5
|
+
/**
|
|
6
|
+
* A product slot the paywall renders, keyed by reference in
|
|
7
|
+
* `SuperwallConfig["products"]`. Product data (price, period, trial…) is
|
|
8
|
+
* SDK-owned and arrives at runtime; the mock host synthesizes it in dev.
|
|
9
|
+
*/
|
|
10
|
+
export type SuperwallProductSlot = {
|
|
11
|
+
/** Store product identifier this slot maps to (e.g. "pro_3999_year"). */
|
|
12
|
+
productId?: string;
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* One store identifier per platform the paywall ships to, for a slot whose
|
|
16
|
+
* underlying product differs by store — the same `purchase("annual")` buys
|
|
17
|
+
* the App Store product on iOS and the Play product on Android.
|
|
18
|
+
*/
|
|
19
|
+
export type SuperwallPlatformProductIds = Partial<Record<SuperwallPlatform, string>>;
|
|
20
|
+
/**
|
|
21
|
+
* A slot object, the store product identifier as shorthand, or one
|
|
22
|
+
* identifier per platform.
|
|
23
|
+
*/
|
|
24
|
+
export type SuperwallProductSlotInput = string | SuperwallProductSlot | SuperwallPlatformProductIds;
|
|
25
|
+
export declare const isPlatformProductIds: (input: SuperwallProductSlotInput) => input is SuperwallPlatformProductIds;
|
|
26
|
+
/**
|
|
27
|
+
* The store identifier a slot resolves to on a platform. A per-platform slot
|
|
28
|
+
* with no entry for the platform resolves to nothing; with no platform known
|
|
29
|
+
* at all it falls back to its first entry.
|
|
30
|
+
*/
|
|
31
|
+
export declare const productIdFor: (input: SuperwallProductSlotInput, platform?: SuperwallPlatform) => string | undefined;
|
|
32
|
+
export type SuperwallPresentationStyle = "fullscreen" | "modal" | "push" | "drawer" | "popup" | "noAnimation";
|
|
33
|
+
export type SuperwallPresentationConfig = {
|
|
34
|
+
/** How the native SDK presents the paywall. Defaults to "fullscreen". */
|
|
35
|
+
style?: SuperwallPresentationStyle;
|
|
36
|
+
/**
|
|
37
|
+
* Drawer geometry, as percentages of the screen and points. Only read when
|
|
38
|
+
* style is "drawer"; defaults to 70% height with a 15pt corner radius.
|
|
39
|
+
*/
|
|
40
|
+
drawer?: {
|
|
41
|
+
height?: number;
|
|
42
|
+
cornerRadius?: number;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* Popup geometry, as percentages of the screen and points. Only read when
|
|
46
|
+
* style is "popup"; defaults to 80% × 60% with a 15pt corner radius.
|
|
47
|
+
*/
|
|
48
|
+
popup?: {
|
|
49
|
+
width?: number;
|
|
50
|
+
height?: number;
|
|
51
|
+
cornerRadius?: number;
|
|
52
|
+
};
|
|
53
|
+
};
|
|
54
|
+
export type PaywallPresentationStyleWire = {
|
|
55
|
+
type: "FULLSCREEN" | "MODAL" | "PUSH" | "NO_ANIMATION";
|
|
56
|
+
} | {
|
|
57
|
+
type: "DRAWER";
|
|
58
|
+
height: number;
|
|
59
|
+
corner_radius: number;
|
|
60
|
+
} | {
|
|
61
|
+
type: "POPUP";
|
|
62
|
+
width: number;
|
|
63
|
+
height: number;
|
|
64
|
+
corner_radius: number;
|
|
65
|
+
};
|
|
66
|
+
export type WebCheckoutDestinationWire = "EXTERNAL" | "PAYWALL_EMBEDDED" | "PAYWALL_APPLE_PAY";
|
|
67
|
+
export type PaywallSettings = {
|
|
68
|
+
presentation_style: PaywallPresentationStyleWire;
|
|
69
|
+
feature_gating: "gated" | "non_gated";
|
|
70
|
+
on_device_cache: boolean;
|
|
71
|
+
scroll_enabled: boolean;
|
|
72
|
+
game_controller_enabled: boolean;
|
|
73
|
+
introductory_offer_eligibility: "automatic" | "always_eligible" | "always_ineligible";
|
|
74
|
+
web_checkout_destination?: WebCheckoutDestinationWire;
|
|
75
|
+
background_color_hex?: string;
|
|
76
|
+
dark_background_color_hex?: string;
|
|
77
|
+
};
|
|
78
|
+
export declare const presentationStyleWire: (presentation: SuperwallPresentationConfig | undefined) => PaywallPresentationStyleWire;
|
|
79
|
+
export declare const webCheckoutDestinationOf: (checkout: SuperwallCheckoutConfig | undefined) => WebCheckoutDestinationWire | undefined;
|
|
80
|
+
export declare const paywallSettingsOf: (config: SuperwallConfig | undefined) => PaywallSettings;
|
|
81
|
+
export type SuperwallTrialReminderStaticConfig = {
|
|
82
|
+
enabled?: boolean;
|
|
83
|
+
/** Notification title. Localizable: message keys resolve through `t()`. */
|
|
84
|
+
title: string;
|
|
85
|
+
subtitle?: string;
|
|
86
|
+
/** Notification body. Localizable: message keys resolve through `t()`. */
|
|
87
|
+
body: string;
|
|
88
|
+
/** How many days before the trial ends the reminder fires. Defaults to 1. */
|
|
89
|
+
beforeTrialEndDays?: number;
|
|
90
|
+
};
|
|
91
|
+
/** Context passed to a dynamic trial reminder function. */
|
|
92
|
+
export type SuperwallTrialReminderContext = {
|
|
93
|
+
/** When the trial ends, per the SDK. */
|
|
94
|
+
trialEndDate: Date;
|
|
95
|
+
/** Store identifier of the purchased product, when the SDK provides it. */
|
|
96
|
+
productIdentifier?: string;
|
|
97
|
+
/** The matching product, when it's one of this paywall's slots. */
|
|
98
|
+
product?: SuperwallProduct;
|
|
99
|
+
/** Translator for the active locale. */
|
|
100
|
+
t: (key: string, values?: Record<string, string | number>) => string;
|
|
101
|
+
locale: string;
|
|
102
|
+
};
|
|
103
|
+
/** What a dynamic trial reminder resolves to. */
|
|
104
|
+
export type SuperwallTrialReminderNotification = {
|
|
105
|
+
title: string;
|
|
106
|
+
subtitle?: string;
|
|
107
|
+
body: string;
|
|
108
|
+
/** Milliseconds from now until the notification fires. */
|
|
109
|
+
delayMs: number;
|
|
110
|
+
};
|
|
111
|
+
/**
|
|
112
|
+
* Static config, or a function computing the notification from the trial
|
|
113
|
+
* context (schedule time, localized copy, per-product logic). Return null
|
|
114
|
+
* from the function to skip scheduling.
|
|
115
|
+
*/
|
|
116
|
+
export type SuperwallTrialReminderConfig = SuperwallTrialReminderStaticConfig | ((context: SuperwallTrialReminderContext) => SuperwallTrialReminderNotification | null | undefined);
|
|
117
|
+
export type SuperwallNotificationsConfig = {
|
|
118
|
+
/** Auto-scheduled when the SDK reports a trial started (`freeTrial_start`). */
|
|
119
|
+
trialReminder?: SuperwallTrialReminderConfig;
|
|
120
|
+
};
|
|
121
|
+
/**
|
|
122
|
+
* Nested message catalog for one locale. Values interpolate `{name}` params:
|
|
123
|
+
* `{ paywall: { title: "Unlock {appName}" } }` → `t("paywall.title", { appName })`.
|
|
124
|
+
*/
|
|
125
|
+
export type SuperwallMessages = {
|
|
126
|
+
[key: string]: string | SuperwallMessages;
|
|
127
|
+
};
|
|
128
|
+
export type SuperwallLocalizationConfig<TLocale extends string = string> = {
|
|
129
|
+
/** Locale used when the device locale has no catalog. */
|
|
130
|
+
defaultLocale: TLocale;
|
|
131
|
+
/** Message catalogs by locale (e.g. `{ en, de, "pt-BR": ptBR }`). */
|
|
132
|
+
messages?: Record<TLocale, SuperwallMessages> & Record<string, SuperwallMessages>;
|
|
133
|
+
};
|
|
134
|
+
/**
|
|
135
|
+
* How a purchase completes on the web. Native hosts ignore it — they always
|
|
136
|
+
* buy through the store.
|
|
137
|
+
*
|
|
138
|
+
* - `external` — leave for Superwall's hosted checkout page and come back.
|
|
139
|
+
* - `sheet` — take payment in the paywall, in a sheet Superwall renders.
|
|
140
|
+
* - `applePay` — go straight to Apple Pay, falling back to the sheet where
|
|
141
|
+
* Apple Pay is unavailable.
|
|
142
|
+
*
|
|
143
|
+
* The sheet's appearance is fixed and takes nothing from the paywall around
|
|
144
|
+
* it. Payment UI that borrows a paywall's fonts and colors stops looking like
|
|
145
|
+
* payment UI, which is the one place a shopper is entitled to see something
|
|
146
|
+
* they recognize.
|
|
147
|
+
*
|
|
148
|
+
* `sheet` and `applePay` carry Stripe's payment UI into the bundle; `external`
|
|
149
|
+
* costs nothing. Read this before shipping either:
|
|
150
|
+
* https://superwall.com/docs/web-checkout
|
|
151
|
+
*/
|
|
152
|
+
export type SuperwallCheckoutMode = "external" | "sheet" | "applePay";
|
|
153
|
+
export type SuperwallCheckoutConfig = SuperwallCheckoutMode | {
|
|
154
|
+
mode: SuperwallCheckoutMode;
|
|
155
|
+
prefetch?: string | false;
|
|
156
|
+
};
|
|
157
|
+
export declare const checkoutModeOf: (checkout: SuperwallCheckoutConfig | undefined) => SuperwallCheckoutMode | undefined;
|
|
158
|
+
export declare const checkoutPrefetchOf: (checkout: SuperwallCheckoutConfig | undefined) => string | false | undefined;
|
|
159
|
+
/**
|
|
160
|
+
* A paywall's background color. The string shorthand sets light mode; the
|
|
161
|
+
* object form adds a dark-mode color. Native SDKs paint it behind the webview
|
|
162
|
+
* (and derive the loading spinner from it), and the web document paints it as
|
|
163
|
+
* the page background — so the color a shopper sees while the paywall loads
|
|
164
|
+
* matches the color it settles on.
|
|
165
|
+
*/
|
|
166
|
+
export type SuperwallBackgroundConfig = string | {
|
|
167
|
+
light: string;
|
|
168
|
+
dark?: string;
|
|
169
|
+
};
|
|
170
|
+
export type ResolvedBackground = {
|
|
171
|
+
light: string;
|
|
172
|
+
dark?: string;
|
|
173
|
+
};
|
|
174
|
+
export declare const backgroundOf: (background: SuperwallBackgroundConfig | undefined) => ResolvedBackground | undefined;
|
|
175
|
+
export type SuperwallConfig<TLocale extends string = string> = {
|
|
176
|
+
/** Product slots this paywall renders, keyed by reference. */
|
|
177
|
+
products?: Record<string, SuperwallProductSlotInput>;
|
|
178
|
+
/**
|
|
179
|
+
* How a purchase completes on the web. Omit it for native-only paywalls —
|
|
180
|
+
* nothing about checkout is bundled unless this asks for it.
|
|
181
|
+
*/
|
|
182
|
+
checkout?: SuperwallCheckoutConfig;
|
|
183
|
+
/** How the native SDK presents the paywall: style and drawer/popup geometry. */
|
|
184
|
+
presentation?: SuperwallPresentationConfig;
|
|
185
|
+
/**
|
|
186
|
+
* Background color painted behind the paywall while it loads and as the web
|
|
187
|
+
* document background. String shorthand = light mode; `{ light, dark }` adds
|
|
188
|
+
* a dark-mode color.
|
|
189
|
+
*/
|
|
190
|
+
background?: SuperwallBackgroundConfig;
|
|
191
|
+
/**
|
|
192
|
+
* Whether the feature behind the placement is gated on a purchase.
|
|
193
|
+
* Defaults to "nonGated".
|
|
194
|
+
*/
|
|
195
|
+
featureGating?: "gated" | "nonGated";
|
|
196
|
+
/** Trial eligibility handling. Defaults to "automatic" (SDK decides). */
|
|
197
|
+
introductoryOfferEligibility?: "automatic" | "alwaysEligible" | "alwaysIneligible";
|
|
198
|
+
/** Forward game controller input to the paywall. Defaults to false. */
|
|
199
|
+
gameControllerEnabled?: boolean;
|
|
200
|
+
/** Whether the webview scrolls. Defaults to true. */
|
|
201
|
+
scrollEnabled?: boolean;
|
|
202
|
+
/** Cache the paywall on device for instant presentation. Defaults to true. */
|
|
203
|
+
onDeviceCacheEnabled?: boolean;
|
|
204
|
+
/** Dismiss the paywall automatically after a completed purchase. */
|
|
205
|
+
dismissOnPurchase?: boolean;
|
|
206
|
+
/** Resolve pending purchases as failed after this many ms without a transaction. */
|
|
207
|
+
purchaseTimeoutMs?: number;
|
|
208
|
+
/** Local notifications the paywall schedules (e.g. trial reminders). */
|
|
209
|
+
notifications?: SuperwallNotificationsConfig;
|
|
210
|
+
/** Message catalogs and default locale for `t()`. */
|
|
211
|
+
localization?: SuperwallLocalizationConfig<TLocale>;
|
|
212
|
+
};
|
|
213
|
+
/**
|
|
214
|
+
* Declares the paywall's contract: product slots, presentation, gating,
|
|
215
|
+
* notifications, and localization. Consumed by the runtime session at render
|
|
216
|
+
* time and by the Superwall build pipeline at push time.
|
|
217
|
+
*/
|
|
218
|
+
export declare const defineSuperwallConfig: <TLocale extends string = string>(config: SuperwallConfig<TLocale>) => SuperwallConfig<TLocale>;
|
|
219
|
+
export declare const normalizeProductSlot: (input: SuperwallProductSlotInput, platform?: SuperwallPlatform) => SuperwallProductSlot;
|
|
220
|
+
export declare const checkoutNeedsPaymentUi: (checkout: SuperwallCheckoutConfig | undefined) => boolean;
|
|
221
|
+
/**
|
|
222
|
+
* Materializes the config's product slots as products so references exist
|
|
223
|
+
* before the SDK (or mock host) delivers real product data.
|
|
224
|
+
*/
|
|
225
|
+
export declare const productsFromConfig: (config: SuperwallConfig | undefined, platform?: SuperwallPlatform) => SuperwallProduct[];
|
|
226
|
+
/** @deprecated Use `SuperwallConfig`. */
|
|
227
|
+
export type SuperwallPaywallConfig<TLocale extends string = string> = SuperwallConfig<TLocale>;
|
|
228
|
+
/** The framework's paywall generation — v4 is the visual editor, v5 is code. */
|
|
229
|
+
export declare const SUPERWALL_GENERATION = 5;
|
|
230
|
+
/**
|
|
231
|
+
* Document semantics as `<html>` data attributes — the snapshot's half of the
|
|
232
|
+
* two-layer contract. The build stamps these statically (no flash before
|
|
233
|
+
* hydration) and `SuperwallProvider` reasserts them at runtime (dev has no
|
|
234
|
+
* build step). The platform's serve-time stylesheet (live.css) owns what they
|
|
235
|
+
* mean, so their interpretation can evolve fleet-wide without republishing.
|
|
236
|
+
*/
|
|
237
|
+
export declare const documentAttributes: (config: SuperwallConfig | undefined) => Record<string, string>;
|