palbase 0.8.1 → 0.9.0

package/types/web/src/index.d.ts

@@ -2,13 +2,19 @@ export { createClient, type ClientOptions, type PalbaseClient } from './client.j
 export type { Auth, CredentialsLike, SignInResult, User } from './auth.js';
 export { localStore, memoryStore, SessionChangedError, type AuthEvent, type RefreshMode, type Session, type SessionEndReason, type SessionStore } from './session.js';
 export { Channel, RealtimeSocket, type ChannelOptions, type PushReply } from './socket.js';
-export { Analytics, type AnalyticsOptions } from './analytics.js';
+export { Analytics, type AnalyticsOptions, type People } from './analytics.js';
+export { Consent, type ConsentKeyInfo, type ConsentListener, type ConsentOptions, type ConsentRegion, type ConsentState } from './consent.js';
+export { Installation } from './installation.js';
 export type { AgentEvent, ChatAttachment, ChatEvent, ChatGoal, ChatItem, ChatMessageView, ChatPart, ChatPartsPage, ChatPartsQuery, ChatResponse, ChatState, ChatStreamPart, ChatThinking, ChatToolCall, ChatVoice, GatewayChat, GoalEvent, HistoryEvent, HistoryItem, Publication, ThinkingEvent, ToolEvent, TranscriptEvent, TurnEnd, TurnEvent, VoiceEvent, } from './chat.js';
 export { connectVoice, type StartedVoice, type VoiceConnection, type VoiceOptions } from './voice.js';
-export { Purchases, redemptionToken, type CheckoutSource, type CustomerInfo, type CustomerInfoListener, type MergeGrant, type Offerings, type RedemptionLink } from './purchases.js';
+export { Purchases, redemptionToken, type CheckoutSource, type CustomerInfo, type CustomerInfoListener, type GrantInfo, type MergeGrant, type OfferView, type Offerings, type Redeemed, type RedemptionLink, } from './purchases.js';
+export { Notify, WebPush, type PushPermission, type PushSubscribeOptions } from './notify.js';
+export { Flags, type FlagSource, type FlagsListener } from './flags.js';
+export { Inbox, type InboxItem, type InboxListOptions, type InboxPage, type InboxView, type InboxViewOptions } from './inbox.js';
+export { InApp, SESSION_START, type InAppOptions } from './inapp.js';
 export type { Paywall, PaywallRenderOptions } from './paywall/placement.js';
 export type { PaywallAttribute } from './paywall/attributes.js';
-export type { PaywallPackage, PaywallView } from './paywall/render.js';
+export type { PaywallPackage, PaywallView } from './screen/render.js';
 export { PalbaseError } from '../../internal/src/transport.js';
 export { BackendError, isBackendError, type BackendErrorKind, type FieldError } from './backend-error.js';
 export type { BackendBase, CallOptions, UploadOptions, UploadProgress } from './backends.js';

package/types/web/src/installation.d.ts

@@ -0,0 +1,16 @@
+/** The header the install's secret is sent in, on the calls that act for the device itself. */
+export declare const INSTALLATION_SECRET_HEADER = "X-Palbase-Installation-Secret";
+/** The header the install's label is sent in. */
+export declare const INSTALLATION_HEADER = "X-Palbase-Installation";
+/** The install's secret: for the calls that act for the device itself, and only those. */
+export declare function secretOf(installation: Installation): string;
+/** Whether this page made the install: a new one, which the project holds nothing of. */
+export declare function madeHere(installation: Installation): boolean;
+export declare class Installation {
+    /** The installation id: this browser's, for this project, until its storage is cleared. */
+    readonly id: string;
+    constructor(origin: string);
+}
+/** The label a secret makes: the first 16 bytes of its SHA-256, base64url. */
+export declare function labelOf(secret: string): string;
+export declare function sha256(data: Uint8Array): Uint8Array;

package/types/web/src/message/index.d.ts

@@ -0,0 +1,5 @@
+export { MESSAGE_COMPONENTS, MESSAGE_SCHEMA, countdownValues, messageResolution as resolveMessageWithPaths, resolveMessage, type Appearance, type MessageDefinition, type MessageResolveOptions, type Platform, type ResolvedMessage, type ResolvedNode, type ResolvedPresentation, type ResolvedStyle, type Resolution, } from '../screen/resolve.js';
+export { renderMessage, type MessageActionTaken, type MessageHandlers, type MessageInput, type MessageState, type MessageView } from '../screen/render.js';
+export { presentMessage, type MessageCloseReason, type PresentedMessage, type PresentHandlers, type PresentOptions } from './present.js';
+export { assetId, fontFamily, htmlDocument, prepareAssets, unzip, type PreparedAsset, type ScreenAssetRef } from '../screen/assets.js';
+export { ICONS as MESSAGE_ICONS } from '../screen/icons.js';

package/types/web/src/message/present.d.ts

@@ -0,0 +1,20 @@
+import { type MessageHandlers, type MessageInput, type MessageView } from '../screen/render.js';
+/** How a message closed: a close button, an action that closes it, a tap outside, a swipe, its time, Escape, or the app. */
+export type MessageCloseReason = 'button' | 'action' | 'outside' | 'swipe' | 'timeout' | 'escape' | 'app';
+export interface PresentHandlers extends Omit<MessageHandlers, 'onClose'> {
+    /** Told once, when it has closed, with how. */
+    onClose?(reason: MessageCloseReason): void;
+}
+export interface PresentOptions {
+    /** The element it is shown in: the page's body unless given. */
+    root?: HTMLElement;
+}
+export interface PresentedMessage {
+    readonly view: MessageView;
+    /** How it closed, once it has. */
+    readonly closed: Promise<MessageCloseReason>;
+    /** Closes it: the app's reason (a navigation, another message). */
+    close(): void;
+}
+/** Shows a message over the page. A card is not shown so (it throws): an inbox draws it in its list. */
+export declare function presentMessage(input: MessageInput, handlers?: PresentHandlers, options?: PresentOptions): PresentedMessage;

package/types/web/src/notify.d.ts

@@ -0,0 +1,67 @@
+import type { Transport } from '../../internal/src/transport.js';
+import { type Installation } from './installation.js';
+import type { SessionManager } from './session.js';
+import type { Consent } from './consent.js';
+import type { Purchases } from './purchases.js';
+import { Inbox } from './inbox.js';
+import { InApp } from './inapp.js';
+/** Where the browser is with pushes: allowed, refused, not asked yet, or a browser without them. */
+export type PushPermission = 'granted' | 'denied' | 'default' | 'unsupported';
+export interface PushSubscribeOptions {
+    /** The service worker that shows the pushes: the app's copy of palbase/web/push-sw.js at its origin; `/palbase-sw.js` unless given. */
+    serviceWorker?: string;
+    /** The worker's scope: its folder unless given. */
+    scope?: string;
+}
+type Globals = {
+    navigator?: {
+        serviceWorker?: ServiceWorkerContainer;
+        language?: string;
+    };
+    Notification?: {
+        permission: NotificationPermission;
+        requestPermission(): Promise<NotificationPermission>;
+    };
+    PushManager?: unknown;
+};
+/** This browser's pushes. */
+export declare class WebPush {
+    private api;
+    private session;
+    private installation;
+    private baseUrl;
+    private publishableKey;
+    private g;
+    private registered;
+    /** The registration again for a change of who is signed in, while it runs. */
+    changing: Promise<unknown>;
+    constructor(transport: Transport, session: SessionManager, installation: Installation, baseUrl: string, publishableKey: string, g?: Globals);
+    /** Whether this browser takes pushes at all (a service worker, the Push API, notifications). */
+    supported(): boolean;
+    /** Whether the person allowed this site's notifications. */
+    permission(): PushPermission;
+    /** The service worker's address: the app's copy of push-sw.js, told the project's address and publishable key it reports with. */
+    workerUrl(path?: string): string;
+    /**
+     * Asks the person for notifications (call it from a tap), subscribes this browser and registers it: true when it
+     * takes pushes now, false when the person refused or the browser has none.
+     */
+    subscribe(opts?: PushSubscribeOptions): Promise<boolean>;
+    /** Stops this browser's pushes: its subscription ends, and the project forgets the device as it next pushes it. */
+    unsubscribe(): Promise<void>;
+    /** Registers the browser's subscription again (as the app starts, or as people sign in and out): nothing when it has none. */
+    refresh(): Promise<void>;
+    private current;
+    private register;
+}
+/** pb.notify: the project's notifications, as this app takes them. */
+export declare class Notify {
+    /** This browser's pushes (Web Push). */
+    readonly push: WebPush;
+    /** The signed-in person's inbox, the same on each of their devices. */
+    readonly inbox: Inbox;
+    /** The project's in-app campaigns, shown in this page once started. */
+    readonly inApp: InApp;
+    constructor(transport: Transport, session: SessionManager, installation: Installation, consent: Consent, purchases: Purchases, baseUrl: string, publishableKey: string);
+}
+export {};

package/types/web/src/paywall/index.d.ts

@@ -1,7 +1,7 @@
-export { PAYWALL_COMPONENTS, PAYWALL_SCHEMA, countdownValues, packagesOf, resolution as resolvePaywallWithPaths, resolve as resolvePaywall, type Appearance, type PackageValues, type PaywallDefinition, type Platform, type ResolvedNode, type ResolvedPaywall, type ResolvedStyle, type Resolution, type ResolveOptions, } from './resolve.js';
-export { renderPaywall, type PaywallHandlers, type PaywallInput, type PaywallPackage, type PaywallState, type PaywallView } from './render.js';
-export { assetId, fontFamily, htmlDocument, prepareAssets, unzip, type PaywallAssetRef, type PreparedAsset } from './assets.js';
+export { PAYWALL_COMPONENTS, PAYWALL_SCHEMA, countdownValues, packagesOf, resolution as resolvePaywallWithPaths, resolve as resolvePaywall, type Appearance, type PackageValues, type PaywallDefinition, type Platform, type ResolvedNode, type ResolvedPaywall, type ResolvedStyle, type Resolution, type ResolveOptions, } from '../screen/resolve.js';
+export { renderPaywall, type PaywallHandlers, type PaywallInput, type PaywallPackage, type PaywallState, type PaywallView } from '../screen/render.js';
+export { assetId, fontFamily, htmlDocument, prepareAssets, unzip, type PreparedAsset, type ScreenAssetRef as PaywallAssetRef } from '../screen/assets.js';
 export { attributesHeader, type PaywallAttribute } from './attributes.js';
 export { formatPeriod, formatPrice, packageValues, parseDuration, type PricedPackage } from './prices.js';
-export { ICONS as PAYWALL_ICONS } from './icons.js';
+export { ICONS as PAYWALL_ICONS } from '../screen/icons.js';
 export { Paywall, defaultPaywall, type PaywallRenderOptions } from './placement.js';

package/types/web/src/paywall/placement.d.ts

@@ -1,10 +1,11 @@
 import type { purchases as purchasesModule } from '../../../internal/src/modules/index.js';
-import { type PreparedAsset } from './assets.js';
+import { type PreparedAsset } from '../screen/assets.js';
 import { type PaywallAttribute } from './attributes.js';
 import { type PricedPackage } from './prices.js';
-import { type PaywallHandlers, type PaywallPackage, type PaywallView } from './render.js';
-import { type Appearance, type PackageValues, type PaywallDefinition } from './resolve.js';
+import { type PaywallHandlers, type PaywallPackage, type PaywallView } from '../screen/render.js';
+import { type Appearance, type PackageValues, type PaywallDefinition } from '../screen/resolve.js';
 type Offerings = purchasesModule.Offerings;
+type OfferView = purchasesModule.OfferView;
 type Api = ReturnType<typeof purchasesModule.client>;
 export interface PaywallRenderOptions {
     /** Stripe sends the customer back here after buying (one of the project's registered apps). */
@@ -36,6 +37,7 @@ interface PaywallDeps {
         plan: string;
         successUrl: string;
         cancelUrl: string;
+        offer?: string;
     }): Promise<string>;
     expose(paywall: Paywall): Promise<void>;
 }
@@ -49,6 +51,8 @@ export declare class Paywall {
     readonly assets: Record<string, PreparedAsset>;
     /** What the paywall sells on the web, priced as the catalog prices it. */
     readonly offerings: Offerings;
+    /** The offers its packages are sold with that the signed-in customer may take now: bought with, and priced by. */
+    readonly offers: OfferView[];
     /** The paywall and the version shown, the experiment's variant or the placement's rule that chose it; absent for the SDK's own. */
     readonly shown: {
         paywallId: string;
@@ -58,7 +62,7 @@ export declare class Paywall {
     } | undefined;
     private deps;
     private exposed;
-    constructor(placement: string, source: Paywall['source'], definition: PaywallDefinition, offerings: Offerings, shown: Paywall['shown'], deps: PaywallDeps, assets?: Record<string, PreparedAsset>);
+    constructor(placement: string, source: Paywall['source'], definition: PaywallDefinition, offerings: Offerings, shown: Paywall['shown'], deps: PaywallDeps, assets?: Record<string, PreparedAsset>, offers?: OfferView[]);
     /** The store's values of each package the paywall sells, in a language: what its texts' variables read. */
     packages(locale: string): Record<string, PackageValues>;
     /**
@@ -69,8 +73,8 @@ export declare class Paywall {
      */
     render(container: HTMLElement, opts: PaywallRenderOptions): PaywallView;
 }
-/** The packages the web sells of those named, priced as its catalog prices them. */
-export declare function webPackages(offerings: Offerings, keys: readonly string[], locale: string): PricedPackage[];
+/** The packages the web sells of those named, priced as its catalog prices them — and as the offer each is sold with prices it, by key. */
+export declare function webPackages(offerings: Offerings, keys: readonly string[], locale: string, offers?: ReadonlyMap<string, OfferView>): PricedPackage[];
 /**
  * The SDK's own paywall, where nothing is published: every plan the web
  * sells (the first six) as a card — its product, period and price —, the
@@ -81,12 +85,7 @@ export declare function defaultPaywall(offerings: Offerings): PaywallDefinition
 /** This browser's installation id: who a paywall is shown to before anyone signs in — the same experiment variant every time. */
 export declare function installationId(ref: string): string;
 /** The placement's paywall (see Purchases.paywall). */
-export declare function loadPaywall(api: Api, ref: string, placement: string, checkout: (opts: {
-    product: string;
-    plan: string;
-    successUrl: string;
-    cancelUrl: string;
-}) => Promise<string>, ask?: {
+export declare function loadPaywall(api: Api, ref: string, placement: string, checkout: PaywallDeps['checkout'], ask?: {
     signal?: AbortSignal;
     fetch?: (input: string, init?: RequestInit) => Promise<Response>;
     /** What the app says of the person, for the placement's targeting rules. */

package/types/web/src/paywall/prices.d.ts

@@ -1,4 +1,4 @@
-import type { PackageValues } from './resolve.js';
+import type { PackageValues } from '../screen/resolve.js';
 /** A package as a channel sells it: its product's name there, its price and, for a subscription, its period and trial. */
 export interface PricedPackage {
     /** `<product>.<plan>` */
@@ -16,6 +16,10 @@ export interface PricedPackage {
         mode: string;
         duration: string;
     };
+    /** The catalog's offer it is sold with while the customer may take it: the percent off its price — all of it for a free trial —, its `{{offer_price}}`. */
+    offer?: {
+        percentOff: number;
+    };
 }
 interface Duration {
     count: number;
@@ -34,7 +38,8 @@ export declare function formatPeriod(d: Duration, locale: string): string;
  * subscription saves a month against the dearest a month of the packages
  * given in its currency (none for the dearest, nor below 1%); a package
  * that is not a subscription has no `{{period}}`, `{{price_per_month}}` or
- * `{{savings}}`, and one without a free trial no `{{trial}}`.
+ * `{{savings}}`, one without a free trial no `{{trial}}`, and one sold
+ * with no offer no `{{offer_price}}` (the resolver makes it the price).
  */
 export declare function packageValues(packages: readonly PricedPackage[], locale: string): Record<string, PackageValues>;
 export {};

package/types/web/src/purchases.d.ts

@@ -8,6 +8,9 @@ type P = typeof purchasesModule;
 export type CustomerInfo = purchasesModule.CustomerInfo;
 export type Offerings = purchasesModule.Offerings;
 export type MergeGrant = purchasesModule.MergeGrant;
+export type OfferView = purchasesModule.OfferView;
+export type GrantInfo = purchasesModule.GrantInfo;
+export type Redeemed = purchasesModule.Redeemed;
 export type RedemptionLink = purchasesModule.RedemptionLink;
 /** Where a checkout is opened: an app linking out to buy on the web says its platform and its store's storefront (ISO 3166-1 alpha-3: `USA`). */
 export type CheckoutSource = purchasesModule.CheckoutSource;
@@ -74,6 +77,11 @@ export declare class Purchases {
      * kept in this tab's sessionStorage, which the redirect to Stripe and back
      * keeps. `source` says where the checkout was opened, when an app links
      * out.
+     *
+     * `offer` buys it with one of the signed-in customer's offers on that plan
+     * (offers()): its discount — the coupon code that opened it, when one did,
+     * shown on Stripe's page — or its free trial. One that is not theirs to take
+     * there, or asked with no one signed in, is refused (403 offer_not_open).
      */
     checkout(opts: {
         product: string;
@@ -81,6 +89,7 @@ export declare class Purchases {
         successUrl: string;
         cancelUrl: string;
         source?: CheckoutSource;
+        offer?: string;
     }): Promise<string>;
     /**
      * On a checkout's success page, for a buyer with no account: the one-time
@@ -109,6 +118,29 @@ export declare class Purchases {
      * error's `body.resent` says so.
      */
     redeem(link: string): Promise<CustomerInfo>;
+    /**
+     * The catalog's offers the signed-in customer may take now — each once:
+     * live, for everyone or an audience they are in (having allowed
+     * personalization), or opened to them by a coupon they redeemed. A
+     * discount or a trial is bought with (checkout's `offer`, on one of its
+     * web plans); a grant is claimed (claimOffer).
+     */
+    offers(): Promise<OfferView[]>;
+    /** Tells the project the app showed the customer an offer: the first time is counted in the offer's figures. */
+    offerShown(key: string): Promise<void>;
+    /**
+     * Takes a grant offer: its entitlement, for its duration from now — onCustomerInfo hears it. Refused for a guest
+     * (403 account_required) and for an offer that is not the customer's to take now.
+     */
+    claimOffer(key: string): Promise<GrantInfo>;
+    /**
+     * Redeems a code the customer typed, in any case — once a customer: what it opened, a grant given at once, a
+     * discount or a trial theirs to buy from now (offers() lists it with the coupon). A refusal is a PalbaseError
+     * with the module's code: coupon_not_found (404); coupon_redeemed, code_used (409); coupon_ended,
+     * coupon_exhausted, offer_ended (410); sign_in_required (403: a guest); redeem_at_app_store (422: an App Store
+     * offer code, redeemed in the App Store); too_many_attempts (429: too many codes tried — after retryAfter).
+     */
+    redeemCoupon(code: string): Promise<Redeemed>;
     /** Stripe's customer portal for what the customer bought on the web: the URL to send them to, and back to returnUrl. */
     portal(returnUrl: string): Promise<string>;
     /**

package/types/web/src/{paywall → screen}/assets.d.ts

@@ -1,5 +1,5 @@
-/** An asset as the answer lists it (PaywallAssetRef). */
-export interface PaywallAssetRef {
+/** An asset as the answer lists it (purchases' PaywallAssetRef, notify's InAppAssetRef). */
+export interface ScreenAssetRef {
     id: string;
     kind: 'image' | 'video' | 'font' | 'html';
     url: string;
@@ -8,7 +8,7 @@ export interface PaywallAssetRef {
 }
 /** An asset ready to draw. */
 export interface PreparedAsset {
-    kind: PaywallAssetRef['kind'];
+    kind: ScreenAssetRef['kind'];
     /** Where its checked bytes are: an object URL (or, unchecked, the https address Studio's preview draws from). */
     url: string;
     /** A font's family, registered with the page's fonts. */
@@ -28,17 +28,17 @@ export interface PrepareOptions {
 }
 /**
  * Downloads and checks every asset; those that pass are ready to draw, by
- * id. Done when the paywall is fetched, before it is shown: what is shown
+ * id. Done when the screen is fetched, before it is shown: what is shown
  * then draws from memory.
  */
-export declare function prepareAssets(refs: readonly PaywallAssetRef[], opts?: PrepareOptions): Promise<Record<string, PreparedAsset>>;
+export declare function prepareAssets(refs: readonly ScreenAssetRef[], opts?: PrepareOptions): Promise<Record<string, PreparedAsset>>;
 /**
  * What an asset's bytes are, among the formats its kind takes — the type its
  * object URL is given: an image is PNG, JPEG or WebP; a video MP4, QuickTime
  * or WebM; a font WOFF2, WOFF, TrueType or OpenType; an HTML block a zip.
  * Undefined for anything else: the asset is not drawn.
  */
-export declare function formatOf(kind: PaywallAssetRef['kind'], b: Uint8Array): string | undefined;
+export declare function formatOf(kind: ScreenAssetRef['kind'], b: Uint8Array): string | undefined;
 /** The files of a zip, by path: stored and deflated entries (what the server takes). */
 export declare function unzip(bytes: Uint8Array): Promise<Map<string, Uint8Array>>;
 /** The content security of an HTML block: it loads what is inside its document, and nothing from anywhere else. */

package/types/web/src/screen/render.d.ts

@@ -0,0 +1,186 @@
+import { type PreparedAsset } from './assets.js';
+import { type Appearance, type MessageDefinition, type PackageValues, type PaywallDefinition, type Platform } from './resolve.js';
+/** A package of the catalog: what the purchase button buys. */
+export interface PaywallPackage {
+    product: string;
+    plan: string;
+    /** The catalog's offer it is bought with: the one it is sold with, while the customer may take it. */
+    offer?: string;
+}
+/** What a paywall is drawn from. */
+export interface PaywallInput {
+    definition: PaywallDefinition;
+    /** The reader's language (`tr-TR`). */
+    locale: string;
+    appearance: Appearance;
+    /** Where it is drawn: the web, unless a preview draws another platform's. */
+    platform?: Platform;
+    /** The store's values of each package, by `<product>.<plan>`; a package without any is drawn, not sold. */
+    packages: Record<string, PackageValues>;
+    /** The packages whose introductory offer the customer can still take. */
+    eligible?: readonly string[];
+    /** The catalog's offers the customer may take now: a package sold with one is bought with it, its `{{offer_price}}` the offer's (its values'). */
+    offers?: readonly string[];
+    /** The app's own addresses of `terms` and `privacy` (https); a button or link to one is not drawn without it. */
+    links?: {
+        terms?: string;
+        privacy?: string;
+    };
+    /** The definition's assets ready to draw, by id (prepareAssets): one missing is drawn without. */
+    assets?: Record<string, PreparedAsset>;
+    /** The state to draw: a preview sets it; an app leaves it to the person. */
+    state?: PaywallState;
+    /** Entrances as components appear (true); never when the system asks for less motion. */
+    animate?: boolean;
+    /** Draws as if the system asked for less motion (a preview's choice); the system's own otherwise. */
+    reduceMotion?: boolean;
+}
+/** What the person has done to the paywall, and its clock. */
+export interface PaywallState {
+    /** The package the person selected. */
+    selected?: string;
+    /** Each tabs component's tab, and each switch's side, by the component's path. */
+    tabs?: Record<string, string>;
+    switches?: Record<string, boolean>;
+    /** The sheet open, by its id. */
+    sheet?: string | null;
+    /** When the paywall opened (ms since the epoch): a countdown from its opening counts from here. */
+    openedAt?: number;
+    /** A moment to draw, held still (ms since the epoch); the clock runs when absent. */
+    now?: number;
+}
+export interface PaywallHandlers {
+    /** The purchase button, for its package (the one selected, unless it names one) and the offer it is bought with; the button waits while a promise it returns runs. */
+    onPurchase(pkg: PaywallPackage): void | Promise<void>;
+    /** A restore button; without this one is not drawn (the web restores nothing: Stripe's purchases are the account's). */
+    onRestore?(): void | Promise<void>;
+    /** A close button; without this one is not drawn (a close inside a sheet closes the sheet). */
+    onClose?(): void;
+    /** A link the person opened; without this the browser opens it in a new tab. */
+    onLink?(url: string): void;
+    /** Told when the person picks another package. */
+    onSelect?(pkg: PaywallPackage): void;
+    /** The paywall's own words, which the definition does not hold: the app's, in its language. */
+    labels?: {
+        packages?: string;
+        close?: string;
+        restore?: string;
+    };
+    /** An offer code button: the web has none to redeem, so without this one is not drawn. */
+    onOfferCode?(): void | Promise<void>;
+    /** Told whenever the state changes: a preview keeps its controls with it. */
+    onState?(state: PaywallState): void;
+    /** A designer's canvas: a click picks the component under it (its definition path) instead of acting. */
+    editor?: {
+        onPick(path: string): void;
+    };
+}
+export interface PaywallView {
+    /** The package selected now. */
+    readonly selected: PaywallPackage | null;
+    /** Selects a package (`<product>.<plan>`) as the person would. */
+    select(key: string): void;
+    /** Removes it from the page. */
+    destroy(): void;
+    /** Draws it again from what changed: a new definition, the other appearance, another language, new prices or assets, a state to show. */
+    update(input: Partial<PaywallInput>): void;
+    /** The state drawn now. */
+    readonly state: PaywallState;
+    /** Marks a component (by path) as a designer's canvas does; null clears it. */
+    highlight(path: string | null): void;
+    /** Plays every entrance again. */
+    replay(): void;
+}
+/** What a message is drawn from. */
+export interface MessageInput {
+    definition: MessageDefinition;
+    /** The reader's language (`tr-TR`). */
+    locale: string;
+    appearance: Appearance;
+    /** Where it is drawn: the web, unless a preview draws another platform's. */
+    platform?: Platform;
+    /** The values its sender gave, by name (`{{first_name}}`, `{{order}}` …): a text or an address naming one without a value is not drawn. */
+    variables?: Readonly<Record<string, string>>;
+    /** The definition's assets ready to draw, by id (prepareAssets): one missing is drawn without. */
+    assets?: Record<string, PreparedAsset>;
+    /** The state to draw: a preview sets it; an app leaves it to the person. */
+    state?: MessageState;
+    /** Entrances as components appear (true); never when the system asks for less motion. */
+    animate?: boolean;
+    /** Draws as if the system asked for less motion (a preview's choice); the system's own otherwise. */
+    reduceMotion?: boolean;
+}
+/** What the person has done to the message — a tab, a switch's side, a sheet open — and its clock. */
+export type MessageState = Omit<PaywallState, 'selected'>;
+/** A button's action as the person took it, with where the button is: what a campaign counts as a click. */
+export interface MessageActionTaken {
+    type: 'close' | 'open_url' | 'deep_link' | 'request_push' | 'show_paywall' | 'custom' | 'sheet' | 'offer';
+    url?: string;
+    link?: string;
+    placement?: string;
+    name?: string;
+    value?: string;
+    sheet?: string;
+    offer?: string;
+    /** Whether the message closes as it is taken. */
+    dismiss: boolean;
+    /** The button's path in the definition (`root.children[2]`), and its id when it has one. */
+    path: string;
+    id?: string;
+}
+export interface MessageHandlers {
+    /** The message closes: its close button, or an action that closes it; without this a close button is not drawn (one inside a sheet closes the sheet). */
+    onClose?(): void;
+    /** Told of every action the person takes, before it is taken. */
+    onAction?(action: MessageActionTaken): void;
+    /** An https address (open_url); without this the browser opens it in a new tab. */
+    onLink?(url: string): void;
+    /** A link of the app's (deep_link); without this the page goes to it. */
+    onDeepLink?(link: string): void;
+    /** The system's push prompt, asked after the message's own ask; without this its button is not drawn. The button waits while a promise it returns runs. */
+    onRequestPush?(): void | Promise<void>;
+    /** The paywall of a placement; without this its button is not drawn. */
+    onShowPaywall?(placement: string): void | Promise<void>;
+    /** One of the catalog's offers, by key: bought with, or its grant claimed. Without this its button is not drawn; the button waits while a promise it returns runs. */
+    onOffer?(offer: string): void | Promise<void>;
+    /** The app's own code, by name; without this its button is not drawn. */
+    onCustom?(name: string, value?: string): void;
+    /** The message's own words, which the definition does not hold: the app's, in its language. */
+    labels?: {
+        close?: string;
+    };
+    /** Told whenever the state changes: a preview keeps its controls with it. */
+    onState?(state: MessageState): void;
+    /** A designer's canvas: a click picks the component under it (its definition path) instead of acting. */
+    editor?: {
+        onPick(path: string): void;
+    };
+}
+export interface MessageView {
+    /** Removes it from the page. */
+    destroy(): void;
+    /** Draws it again from what changed: a new definition, the other appearance, another language, new values or assets, a state to show. */
+    update(input: Partial<MessageInput>): void;
+    /** The state drawn now. */
+    readonly state: MessageState;
+    /** Marks a component (by path) as a designer's canvas does; null clears it. */
+    highlight(path: string | null): void;
+    /** Plays every entrance again. */
+    replay(): void;
+}
+/**
+ * A link the app opens: an https address, or one of an app's own scheme — never one the browser would run or read
+ * (javascript:, data:, file: …). The server's check (kernel/screen, deepLink) holds a definition to it; a renderer
+ * given a definition from anywhere else holds itself to it too.
+ */
+export declare const appLink: (s: unknown) => s is string;
+/** Draws a paywall into a container (its content is replaced). */
+export declare function renderPaywall(container: HTMLElement, input: PaywallInput, handlers: PaywallHandlers): PaywallView;
+/**
+ * Draws a message into a container (its content is replaced): its content
+ * only — what shows it over the app, at an edge or in a list is the
+ * container's (presentMessage, an inbox's card).
+ */
+export declare function renderMessage(container: HTMLElement, input: MessageInput, handlers: MessageHandlers): MessageView;
+/** The paywall's styles in its shadow root: a constructed sheet where the browser has them, a style element elsewhere. */
+export declare function adoptStyle(doc: Document, shadow: ShadowRoot, css: string): void;

package/types/web/src/{paywall → screen}/resolve.d.ts

@@ -1,5 +1,8 @@
-import type { purchases } from '../../../internal/src/modules/index.js';
+import type { notify, purchases } from '../../../internal/src/modules/index.js';
 export type PaywallDefinition = purchases.PaywallDefinition;
+export type MessageDefinition = notify.MessageDefinition;
+/** What a screen is for: a paywall sells the catalog's packages; a message is shown in the app, or as a card of its inbox. */
+export type ScreenKind = 'paywall' | 'message';
 export type Platform = 'ios' | 'android' | 'web';
 export type Appearance = 'light' | 'dark';
 /** What the store gave a package, as the variables of its texts: `{{price}}` … */
@@ -10,9 +13,12 @@ export interface PackageValues {
     trial?: string;
     savings?: string;
     product_name?: string;
+    /** The price of the package's offer while the customer may take it (ResolveOptions.offers). */
+    offer_price?: string;
 }
-/** The schema this renderer draws: what the SDK asks the server for (X-Palbase-Paywall-Schema). */
+/** The schema this renderer draws: what the SDK asks the server for (X-Palbase-Paywall-Schema, X-Palbase-Screen-Schema). */
 export declare const PAYWALL_SCHEMA = 2;
+export declare const MESSAGE_SCHEMA = 2;
 export interface ResolveOptions {
     /** The app's language (`tr-TR`). */
     locale: string;
@@ -22,6 +28,8 @@ export interface ResolveOptions {
     packages: Record<string, PackageValues>;
     /** The packages whose introductory offer (a trial) the customer can still take. */
     eligible?: readonly string[];
+    /** The catalog's offers the customer may take now (GET /purchases/offers): a package sold with one is bought with it, its {{offer_price}} the offer's price. */
+    offers?: readonly string[];
     /** The package the customer selected; absent, the paywall's own selection. */
     selected?: string;
     /** The tab shown in every tabs component, and each switch's side — the paywall's defaults when absent. */
@@ -34,6 +42,11 @@ export interface ResolveOptions {
     openedSecondsAgo?: number;
     now?: number;
 }
+/** A message resolved: what its texts name is its sender's values — no packages, nothing selected. */
+export interface MessageResolveOptions extends Omit<ResolveOptions, 'packages' | 'eligible' | 'offers' | 'selected'> {
+    /** The values its sender gave: `{{first_name}}`, `{{order}}` …; a text naming one it gave none for is not drawn. */
+    variables?: Readonly<Record<string, string>>;
+}
 /** A component resolved: its type, its fields with every token and default resolved. */
 export type ResolvedNode = {
     type: string;
@@ -115,9 +128,8 @@ export interface ResolvedTypeStyle {
     letter_spacing: number;
     text_style: string;
 }
-/** The definition as drawn, the contract's resolved tree. */
-export interface ResolvedPaywall {
-    selected: string;
+/** A definition as drawn, the contract's resolved tree: what every kind's has. */
+export interface ResolvedScreen {
     theme: {
         colors: Record<string, string>;
         typography: Record<string, ResolvedTypeStyle>;
@@ -129,9 +141,32 @@ export interface ResolvedPaywall {
     footer?: ResolvedNode;
     sheets?: Record<string, ResolvedNode>;
 }
+/** A paywall as drawn: the package selected, too. */
+export interface ResolvedPaywall extends ResolvedScreen {
+    selected: string;
+}
+/** How a message is shown, with its type's fields and their defaults (contracts/message/README.md). */
+export type ResolvedPresentation = {
+    type: 'modal';
+    dismissible: boolean;
+    backdrop: string;
+} | {
+    type: 'fullscreen';
+} | {
+    type: 'banner';
+    position: 'top' | 'bottom';
+    dismissible: boolean;
+    auto_dismiss_seconds?: number;
+} | {
+    type: 'card';
+};
+/** A message as drawn: how it is shown, too. */
+export interface ResolvedMessage extends ResolvedScreen {
+    presentation: ResolvedPresentation;
+}
 /** Beside the tree: where in the definition each node is (its path, as the server's problems name it), and what is not part of the tree. */
-export interface Resolution {
-    tree: ResolvedPaywall;
+export interface Resolution<T extends ResolvedScreen = ResolvedPaywall> {
+    tree: T;
     /** A node's path in the definition: `root.children[2]`, `sheets.offer.root`. */
     pathOf(node: object): string | undefined;
     /** The tab shown in each tabs component and each switch's side, by path. */
@@ -173,12 +208,25 @@ type Spec = Record<string, Field>;
 export declare const COMPONENT_FIELDS: Record<string, Spec>;
 /** The components a definition has, by type. */
 export declare const PAYWALL_COMPONENTS: readonly string[];
+export declare const MESSAGE_COMPONENTS: readonly string[];
+/**
+ * A value as a part of an address: every byte of its UTF-8 but a letter, a
+ * digit and -._~ as %XX (contracts/message/README.md) — a value never adds a
+ * part, a query or a fragment.
+ */
+export declare function pathPart(value: string): string;
 /** {{countdown}} and its parts for a time left, in seconds. */
 export declare function countdownValues(left: number): Record<string, string>;
 /** Every package a definition sells, `<product>.<plan>`, in the order it names them: the header, the root, the footer, then its sheets. */
 export declare function packagesOf(definition: PaywallDefinition): string[];
-/** A definition as drawn (contracts/paywall/README.md). */
+/** The offer each package of a definition is sold with, by `<product>.<plan>`: its first package component's `offer`. */
+export declare function packageOffers(definition: PaywallDefinition | MessageDefinition): Map<string, string>;
+/** A paywall's definition as drawn (contracts/paywall/README.md). */
 export declare function resolve(definition: PaywallDefinition, opts: ResolveOptions): ResolvedPaywall;
 /** The same, with each node's path in the definition and the state the renderer keeps. */
 export declare function resolution(definition: PaywallDefinition, opts: ResolveOptions): Resolution;
+/** A message's definition as drawn (contracts/message/README.md). */
+export declare function resolveMessage(definition: MessageDefinition, opts: MessageResolveOptions): ResolvedMessage;
+/** The same, with each node's path in the definition and the state the renderer keeps. */
+export declare function messageResolution(definition: MessageDefinition, opts: MessageResolveOptions): Resolution<ResolvedMessage>;
 export {};