palbase 0.2.0 → 0.3.1

package/types/internal/src/modules/storage.d.ts

@@ -262,7 +262,7 @@ export type StorageObject = {
  */
 export type StorageStats = {
     /**
-     * Every bucket of the project, by name; an empty one with zeros.
+     * Every bucket of the project, by name; an empty one with zeros. A platform module's own bucket is listed with its share too, though the project does not reach it otherwise: _ai holds the pictures its agents' tools returned, deleted with their chat (or once a one-shot answer is answered) — counted in the project's storage as its other files are.
      */
     buckets: StorageStatsBucket[];
     /**

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

@@ -30,6 +30,12 @@ export interface ClientOptions {
      * Off unless given; events the app captures (`analytics.capture`) go either way.
      */
     analytics?: boolean | AnalyticsOptions;
+    /**
+     * The app's version, as its users see it ("2.4.1"): said with a paywall's
+     * request, for a placement's targeting rules that read it. Nothing is said
+     * without one.
+     */
+    appVersion?: string;
 }
 /**
  * The app's client. A backend's generated Palbe module (palbase apps:sync)

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

@@ -5,6 +5,7 @@ export { Channel, RealtimeSocket, type PushReply } from './socket.js';
 export { Analytics, type AnalyticsOptions } from './analytics.js';
 export { Purchases, type CustomerInfo, type CustomerInfoListener, type MergeGrant, type Offerings } from './purchases.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 { PalbaseError } from '../../internal/src/transport.js';
 export { BackendError, isBackendError, type BackendErrorKind, type FieldError } from './backend-error.js';

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

@@ -0,0 +1,51 @@
+/** An asset as the answer lists it (PaywallAssetRef). */
+export interface PaywallAssetRef {
+    id: string;
+    kind: 'image' | 'video' | 'font' | 'html';
+    url: string;
+    sha256: string;
+    bytes: number;
+}
+/** An asset ready to draw. */
+export interface PreparedAsset {
+    kind: PaywallAssetRef['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. */
+    family?: string;
+    /** An HTML block's document, every file of its zip inside it. */
+    html?: string;
+}
+/** The family a font asset is registered under. */
+export declare const fontFamily: (id: string) => string;
+/** The id an `asset:<id>` names; undefined for anything else. */
+export declare function assetId(src: unknown): string | undefined;
+export interface PrepareOptions {
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    signal?: AbortSignal;
+    /** Where a font is registered: the page's fonts unless given. */
+    fonts?: FontFaceSet;
+}
+/**
+ * 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
+ * then draws from memory.
+ */
+export declare function prepareAssets(refs: readonly PaywallAssetRef[], 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;
+/** 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. */
+export declare const HTML_BLOCK_CSP = "default-src 'none'; img-src data:; media-src data:; font-src data:; style-src 'unsafe-inline' data:; script-src 'unsafe-inline' data:";
+/**
+ * An HTML block's document: its index.html with every file it names — a
+ * src, an href, a url() in its styles — written into it, and a policy that
+ * lets it load nothing else. Undefined without an index.html.
+ */
+export declare function htmlDocument(files: Map<string, Uint8Array>): string | undefined;

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

@@ -0,0 +1,13 @@
+/** An attribute's value: a text, a number or a yes/no. */
+export type PaywallAttribute = string | number | boolean;
+export declare const MAX_ATTRIBUTES = 20;
+export declare const MAX_ATTRIBUTES_BYTES = 2048;
+export declare const MAX_ATTRIBUTE_TEXT_BYTES = 256;
+/**
+ * The attributes as the header carries them; undefined for none. Throws
+ * `invalid_attributes` for what the module would refuse: more than 20, a key
+ * that is not a letter then letters, digits and `_ . -` (40 at most), a text
+ * over 256 bytes, a number that is not finite, a value of another kind, or
+ * more than 2 KiB of them together.
+ */
+export declare function attributesHeader(attributes: Readonly<Record<string, PaywallAttribute>> | undefined): string | undefined;

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

@@ -1,5 +1,7 @@
-export { PAYWALL_COMPONENTS, PAYWALL_SCHEMA, initialPackage, packagesOf, paywallLanguage, resolve as resolvePaywall, type Appearance, type PackageValues, type PaywallDefinition, type ResolveOptions, type ResolvedComponent, type ResolvedPaywall, type ResolvedTheme, } from './resolve.js';
-export { renderPaywall, type PaywallHandlers, type PaywallInput, type PaywallPackage, type PaywallView } from './render.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 './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 { 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 { Paywall, defaultPaywall, type PaywallRenderOptions } from './placement.js';

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

@@ -1,4 +1,6 @@
 import type { purchases as purchasesModule } from '../../../internal/src/modules/index.js';
+import { type PreparedAsset } from './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';
@@ -13,7 +15,7 @@ export interface PaywallRenderOptions {
     appearance?: Appearance;
     /** The browser's language unless given. */
     locale?: string;
-    /** The app's terms and privacy policy (https), for the definition's `terms` and `privacy` links. */
+    /** The app's terms and privacy policy (https), for the definition's `terms` and `privacy` buttons. */
     links?: {
         terms?: string;
         privacy?: string;
@@ -43,17 +45,20 @@ export declare class Paywall {
     /** The server's answer now, the copy kept from before when it could not be asked, or the SDK's own from the catalog (nothing published there). */
     readonly source: 'server' | 'cache' | 'default';
     readonly definition: PaywallDefinition;
+    /** The paywall's assets, downloaded and checked: those that passed, by id. */
+    readonly assets: Record<string, PreparedAsset>;
     /** What the paywall sells on the web, priced as the catalog prices it. */
     readonly offerings: Offerings;
-    /** The paywall and the version shown, and the experiment's variant; absent for the SDK's own. */
+    /** 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;
         version: number;
         variant?: string;
+        ruleId?: string;
     } | undefined;
     private deps;
     private exposed;
-    constructor(placement: string, source: Paywall['source'], definition: PaywallDefinition, offerings: Offerings, shown: Paywall['shown'], deps: PaywallDeps);
+    constructor(placement: string, source: Paywall['source'], definition: PaywallDefinition, offerings: Offerings, shown: Paywall['shown'], deps: PaywallDeps, assets?: Record<string, PreparedAsset>);
     /** The store's values of each package the paywall sells, in a language: what its texts' variables read. */
     packages(locale: string): Record<string, PackageValues>;
     /**
@@ -68,9 +73,9 @@ export declare class Paywall {
 export declare function webPackages(offerings: Offerings, keys: readonly string[], locale: string): PricedPackage[];
 /**
  * The SDK's own paywall, where nothing is published: every plan the web
- * sells (the first six), the purchase button with the selected one's price,
- * and the legal links — plain, in the system's colors. Null when the web
- * sells nothing.
+ * sells (the first six) as a card — its product, period and price —, the
+ * purchase button and the legal links; plain, in the system's colors. Null
+ * when the web sells nothing.
  */
 export declare function defaultPaywall(offerings: Offerings): PaywallDefinition | null;
 /** This browser's installation id: who a paywall is shown to before anyone signs in — the same experiment variant every time. */
@@ -81,5 +86,14 @@ export declare function loadPaywall(api: Api, ref: string, placement: string, ch
     plan: string;
     successUrl: string;
     cancelUrl: string;
-}) => Promise<string>, signal?: AbortSignal): Promise<Paywall | null>;
+}) => Promise<string>, ask?: {
+    signal?: AbortSignal;
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    /** What the app says of the person, for the placement's targeting rules. */
+    attributes?: Readonly<Record<string, PaywallAttribute>>;
+    /** The language the app shows, when it is not the browser's. */
+    locale?: string;
+    /** The app's version, when the client was given one. */
+    appVersion?: string;
+}): Promise<Paywall | null>;
 export {};

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

@@ -1,31 +1,58 @@
-import { type Appearance, type PackageValues, type PaywallDefinition } from './resolve.js';
-/** What a paywall is drawn from: its definition, and the moment it is drawn in. */
+import { type PreparedAsset } from './assets.js';
+import { type PaywallDefinition, type Platform, type Appearance, type PackageValues } from './resolve.js';
+/** A package of the catalog: what the purchase button buys. */
+export interface PaywallPackage {
+    product: string;
+    plan: 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 app's own addresses of the definition's `terms` and `privacy` links (https); such a link is not drawn without one. */
+    /** The packages whose introductory offer the customer can still take. */
+    eligible?: 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;
 }
-/** A package of the catalog: what the purchase button buys. */
-export interface PaywallPackage {
-    product: string;
-    plan: string;
+/** 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 the package selected; the button waits while a promise it returns runs. */
+    /** The purchase button, for its package (the one selected, unless it names one); the button waits while a promise it returns runs. */
     onPurchase(pkg: PaywallPackage): void | Promise<void>;
-    /** The restore button; without one the paywall draws none (the web restores nothing: Stripe's purchases are the account's). */
+    /** A restore button; without this one is not drawn (the web restores nothing: Stripe's purchases are the account's). */
     onRestore?(): void | Promise<void>;
-    /** The close button; without one the paywall draws none. */
+    /** 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 one, the browser opens it in a new tab. */
+    /** 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;
@@ -35,20 +62,32 @@ export interface PaywallHandlers {
         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;
-    /** Draws it again from what changed: a new definition, the other appearance, another language, new prices. */
-    update(input: Partial<PaywallInput>): 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;
 }
-/** An https address, with a host and no credentials: the only images and links a paywall shows. */
-export declare function isHttps(s: unknown): s is string;
-/** Black or white, whichever reads on a color: a badge's text. */
-export declare function readableOn(hex: string): string;
 /** Draws a paywall into a container (its content is replaced). */
 export declare function renderPaywall(container: HTMLElement, input: PaywallInput, handlers: PaywallHandlers): PaywallView;
+/** 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/resolve.d.ts

@@ -1,7 +1,6 @@
 import type { purchases } from '../../../internal/src/modules/index.js';
 export type PaywallDefinition = purchases.PaywallDefinition;
-/** The newest schema of definition this renderer draws: what the SDK asks the server for (X-Palbase-Paywall-Schema). */
-export declare const PAYWALL_SCHEMA = 1;
+export type Platform = 'ios' | 'android' | 'web';
 export type Appearance = 'light' | 'dark';
 /** What the store gave a package, as the variables of its texts: `{{price}}` … */
 export interface PackageValues {
@@ -12,138 +11,174 @@ export interface PackageValues {
     savings?: string;
     product_name?: string;
 }
+/** The schema this renderer draws: what the SDK asks the server for (X-Palbase-Paywall-Schema). */
+export declare const PAYWALL_SCHEMA = 2;
 export interface ResolveOptions {
-    /** The app's language (`tr-TR`): the definition's own, else its language without the region, else its default. */
+    /** The app's language (`tr-TR`). */
     locale: string;
     appearance: Appearance;
+    platform: Platform;
     /** The store's values of each package, by `<product>.<plan>`. */
     packages: Record<string, PackageValues>;
-    /**
-     * The package selected now (`<product>.<plan>`), once the person picked
-     * one; the one the definition marks, else the first, when absent or not
-     * one of its packages.
-     */
+    /** The packages whose introductory offer (a trial) the customer can still take. */
+    eligible?: 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. */
+    tab?: string;
+    switch?: 'on' | 'off';
+    /** One tabs component's tab, or one switch's side, by the component's path (`root.children[3]`): what the person chose. */
+    tabs?: Record<string, string>;
+    switches?: Record<string, boolean>;
+    /** A countdown's time left: how long ago the paywall opened, and the moment it is drawn (ms since the epoch). */
+    openedSecondsAgo?: number;
+    now?: number;
 }
-export interface ResolvedTheme {
-    background: string;
-    surface: string;
-    text: string;
-    muted: string;
-    accent: string;
-    on_accent: string;
-    badge: string;
-    radius: number;
-    font: 'system' | 'rounded' | 'serif';
-}
-type Base = {
+/** A component resolved: its type, its fields with every token and default resolved. */
+export type ResolvedNode = {
+    type: string;
     id?: string;
+    style?: ResolvedStyle;
+    animation?: ResolvedAnimation;
+    [field: string]: unknown;
 };
-export type Align = 'start' | 'center' | 'end' | 'stretch';
-export type ResolvedStack = Base & {
-    type: 'stack';
-    axis: 'vertical' | 'horizontal' | 'z';
-    spacing: number;
-    align: Align;
-    padding: number;
-    corner: number;
-    background?: string;
-    children: ResolvedComponent[];
-};
-export type TextStyle = 'large_title' | 'title' | 'headline' | 'body' | 'callout' | 'caption' | 'footnote';
-export type ResolvedText = Base & {
-    type: 'text';
-    text: string;
-    style: TextStyle;
+export interface ResolvedEdges {
+    top: number;
+    bottom: number;
+    leading: number;
+    trailing: number;
+}
+export interface ResolvedCorners {
+    top_leading: number;
+    top_trailing: number;
+    bottom_leading: number;
+    bottom_trailing: number;
+}
+export type ResolvedStop = {
     color: string;
-    align: 'start' | 'center' | 'end';
-    weight?: 'regular' | 'medium' | 'semibold' | 'bold';
+    at: number;
 };
-export type ResolvedImage = Base & {
+export type ResolvedFill = {
+    type: 'color';
+    color: string;
+} | {
+    type: 'linear';
+    angle: number;
+    stops: ResolvedStop[];
+} | {
+    type: 'radial';
+    center_x: number;
+    center_y: number;
+    radius: number;
+    stops: ResolvedStop[];
+} | {
     type: 'image';
     src: string;
     fit: 'fit' | 'fill';
-    corner: number;
-    aspect?: number;
-    height?: number;
-    alt?: string;
+} | {
+    type: 'video';
+    src: string;
+    poster?: string;
+    loop: boolean;
 };
-export type ResolvedIcon = Base & {
-    type: 'icon';
-    name: string;
-    color: string;
+export interface ResolvedStyle {
+    padding?: ResolvedEdges;
+    margin?: ResolvedEdges;
+    width?: number | string;
+    height?: number | string;
+    max_width?: number;
+    background?: ResolvedFill;
+    border?: {
+        width: number;
+        color: string;
+    };
+    corners?: ResolvedCorners;
+    shadow?: {
+        color: string;
+        radius: number;
+        x: number;
+        y: number;
+    };
+    opacity?: number;
+}
+export interface ResolvedAnimation {
+    type: 'fade' | 'slide_up' | 'slide_down' | 'slide_leading' | 'slide_trailing' | 'scale';
+    duration_ms: number;
+    delay_ms: number;
+    easing: 'ease_out' | 'ease_in_out' | 'spring';
+}
+export interface ResolvedTypeStyle {
+    font: string;
     size: number;
-};
-export type ResolvedFeature = {
-    icon: string;
-    text: string;
-};
-export type ResolvedFeatures = Base & {
-    type: 'features';
-    items: ResolvedFeature[];
-    icon_color: string;
-    color: string;
-    spacing: number;
-};
-export type ResolvedPackage = {
-    product: string;
-    plan: string;
-    selected: boolean;
-    title?: string;
-    detail?: string;
-    badge?: string;
-};
-export type ResolvedPackages = Base & {
-    type: 'packages';
-    layout: 'list' | 'cards' | 'segmented';
-    items: ResolvedPackage[];
-};
-export type ResolvedPurchaseButton = Base & {
-    type: 'purchase_button';
-    text: string;
-    sub_text?: string;
-};
-export type ResolvedRestoreButton = Base & {
-    type: 'restore_button';
-    text?: string;
-};
-export type ResolvedLink = Base & {
-    type: 'link';
-    text: string;
-    url: string;
-};
-export type ResolvedCloseButton = Base & {
-    type: 'close_button';
-    color: string;
-};
-export type ResolvedSpacer = Base & {
-    type: 'spacer';
-    size?: number;
-};
-export type ResolvedDivider = Base & {
-    type: 'divider';
-    color: string;
-};
-export type ResolvedComponent = ResolvedStack | ResolvedText | ResolvedImage | ResolvedIcon | ResolvedFeatures | ResolvedPackages | ResolvedPurchaseButton | ResolvedRestoreButton | ResolvedLink | ResolvedCloseButton | ResolvedSpacer | ResolvedDivider;
-/** The definition as drawn: the palette of the appearance and the tree, nothing left to look up. */
+    weight: number;
+    line_height?: number;
+    letter_spacing: number;
+    text_style: string;
+}
+/** The definition as drawn, the contract's resolved tree. */
 export interface ResolvedPaywall {
-    theme: ResolvedTheme;
-    root: ResolvedComponent;
+    selected: string;
+    theme: {
+        colors: Record<string, string>;
+        typography: Record<string, ResolvedTypeStyle>;
+        radii: Record<string, number>;
+        spacing: Record<string, number>;
+    };
+    header?: ResolvedNode;
+    root?: ResolvedNode;
+    footer?: ResolvedNode;
+    sheets?: Record<string, ResolvedNode>;
+}
+/** 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;
+    /** 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. */
+    tabs: Record<string, string>;
+    switches: Record<string, boolean>;
+    /** Each sheet's title, in the language drawn. */
+    sheetTitles: Record<string, string>;
+    /** The time a counting countdown has left, by path: the renderer ticks while any does. */
+    countdowns: Record<string, number>;
+    /** The language the definition is drawn in. */
+    language: string;
 }
-/** Each component of the schema, by type: what a definition may hold and this renderer draws. */
+type Value = 'plain' | 'color' | 'textColor' | 'spacing' | 'radius';
+type Field = {
+    kind: 'value';
+    value: Value;
+    def?: unknown;
+    required?: boolean;
+} | {
+    kind: 'text';
+    required?: boolean;
+} | {
+    kind: 'list';
+    item: string;
+    required?: boolean;
+} | {
+    kind: 'object';
+    item: string;
+    required?: boolean;
+} | {
+    kind: 'component';
+    required?: boolean;
+} | {
+    kind: 'components';
+} | {
+    kind: 'edges' | 'corners' | 'fill';
+};
+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[];
-/** The package a definition selects at first: the one it marks, else the first of its packages component. */
-export declare function initialPackage(root: unknown): string;
-/** Every package a definition sells, `<product>.<plan>`, in its order. */
-export declare function packagesOf(root: unknown): string[];
-/** The language a definition is drawn in for an app's: its own, else without the region, else the default. */
-export declare function paywallLanguage(definition: PaywallDefinition, locale: 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). */
 export declare function resolve(definition: PaywallDefinition, opts: ResolveOptions): ResolvedPaywall;
-/**
- * The same, with a component that is not drawn left in its place as null:
- * two resolutions of one definition line up child by child, so the renderer
- * changes only what a new selection changed.
- */
-export declare function resolveAligned(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;
 export {};

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

@@ -1,7 +1,8 @@
 import { purchases as purchasesModule } from '../../internal/src/modules/index.js';
-import type { Transport } from '../../internal/src/transport.js';
+import type { Fetch, Transport } from '../../internal/src/transport.js';
 import type { SessionManager } from './session.js';
 import type { RealtimeSocket } from './socket.js';
+import type { PaywallAttribute } from './paywall/attributes.js';
 import { type Paywall } from './paywall/placement.js';
 type P = typeof purchasesModule;
 export type CustomerInfo = purchasesModule.CustomerInfo;
@@ -15,26 +16,44 @@ export declare class Purchases {
     private session;
     private socket;
     private ref;
+    /** What a paywall's assets are downloaded with: the app's fetch, when it gave one. */
+    private fetch;
+    /** The app's version, when it gave one: a paywall's request says it. */
+    private appVersion;
     private listeners;
     private watch;
     private following;
     /** What listeners were last told: undefined until the first read (or sign-out) is known. */
     private last;
-    constructor(transport: Transport, session: SessionManager, socket: RealtimeSocket, ref: string);
+    constructor(transport: Transport, session: SessionManager, socket: RealtimeSocket, ref: string, fetch?: Fetch, appVersion?: string);
     /** Everything the signed-in customer has, read now (the first read makes the user a customer). */
     me(): Promise<CustomerInfo>;
     /** The paywall's catalog: each product's text and price on a channel — the web's unless another is named. */
     offerings(channel?: 'ios' | 'android' | 'web'): Promise<Offerings>;
     /**
      * The paywall the project shows at a placement — the place in the app it
-     * names (`onboarding`, `settings`) — to draw with render(). Its version
-     * is the newest published in a schema this SDK draws (an experiment's
+     * names (`onboarding`, `settings`) — to draw with render(), its assets
+     * downloaded and checked first. Its version is the newest published in a
+     * schema this SDK draws (an experiment's
      * variant while one runs there, the same for this person every time); the
      * browser keeps it, to ask again with its ETag and to show offline. With
      * nothing published there it is the SDK's own, of every plan the web
      * sells; null when the web sells nothing.
+     *
+     * Which paywall a placement shows may depend on its targeting rules: they
+     * read what the request says of the app (the web, the SDK, the version the
+     * client was made with, where it is asked from), its language — the
+     * browser's, or `locale` when the app shows another — and `attributes`,
+     * what the app says of the person
+     * (`{ plan: 'free', sessions: 12 }`: texts, numbers, yes/no). An attribute
+     * the module would refuse throws `invalid_attributes` before anything is
+     * asked. Targeting picks what to show; it is not access control: the
+     * country, the attributes and the versions are what the app says of
+     * itself, so no price or region entitlement may hang on them.
      */
     paywall(placement: string, opts?: {
+        attributes?: Readonly<Record<string, PaywallAttribute>>;
+        locale?: string;
         signal?: AbortSignal;
     }): Promise<Paywall | null>;
     /**