palbase 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,149 @@
+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 Appearance = 'light' | 'dark';
+/** What the store gave a package, as the variables of its texts: `{{price}}` … */
+export interface PackageValues {
+    price?: string;
+    price_per_month?: string;
+    period?: string;
+    trial?: string;
+    savings?: string;
+    product_name?: string;
+}
+export interface ResolveOptions {
+    /** The app's language (`tr-TR`): the definition's own, else its language without the region, else its default. */
+    locale: string;
+    appearance: Appearance;
+    /** 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.
+     */
+    selected?: string;
+}
+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 = {
+    id?: string;
+};
+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;
+    color: string;
+    align: 'start' | 'center' | 'end';
+    weight?: 'regular' | 'medium' | 'semibold' | 'bold';
+};
+export type ResolvedImage = Base & {
+    type: 'image';
+    src: string;
+    fit: 'fit' | 'fill';
+    corner: number;
+    aspect?: number;
+    height?: number;
+    alt?: string;
+};
+export type ResolvedIcon = Base & {
+    type: 'icon';
+    name: string;
+    color: 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. */
+export interface ResolvedPaywall {
+    theme: ResolvedTheme;
+    root: ResolvedComponent;
+}
+/** Each component of the schema, by type: what a definition may hold and this renderer draws. */
+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;
+/** 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;
+export {};

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

@@ -0,0 +1,86 @@
+import { purchases as purchasesModule } from '../../internal/src/modules/index.js';
+import type { Transport } from '../../internal/src/transport.js';
+import type { SessionManager } from './session.js';
+import type { RealtimeSocket } from './socket.js';
+import { type Paywall } from './paywall/placement.js';
+type P = typeof purchasesModule;
+export type CustomerInfo = purchasesModule.CustomerInfo;
+export type Offerings = purchasesModule.Offerings;
+export type MergeGrant = purchasesModule.MergeGrant;
+/** Told what the customer has: on the first read, then each time it changes; null while no one is signed in. */
+export type CustomerInfoListener = (info: CustomerInfo | null) => void;
+export declare class Purchases {
+    /** Every client operation of the purchases contract, through the session's transport. */
+    readonly api: ReturnType<P['client']>;
+    private session;
+    private socket;
+    private ref;
+    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);
+    /** 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
+     * 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.
+     */
+    paywall(placement: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Paywall | null>;
+    /**
+     * Opens Stripe Checkout for the signed-in customer (not a guest) to buy a
+     * product's plan sold on the web: the URL to send them to. Stripe sends
+     * them back to successUrl or cancelUrl — one of the project's registered
+     * apps. The purchase is theirs once Stripe reports it: onCustomerInfo hears it.
+     */
+    checkout(opts: {
+        product: string;
+        plan: string;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<string>;
+    /** 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>;
+    /**
+     * Asked with a guest's session, before it signs in to an existing account:
+     * the proof — good for 5 minutes — that whoever signs in held the guest.
+     * Spent with merge() once signed in. Refused for a session that is not a
+     * guest's (403 guest_required).
+     */
+    mergeGrant(): Promise<MergeGrant>;
+    /**
+     * With the account's session: everything the guest bought goes to the
+     * account, for good; what the account has now. Asked again with the same
+     * grant, it is the same merge.
+     */
+    merge(grant: MergeGrant | string): Promise<CustomerInfo>;
+    /**
+     * Listens to what the signed-in customer has: told it once read, then each
+     * time it changes — a purchase in any store, a renewal or its end, a
+     * refund, credits spent — and null while no one is signed in; a new user
+     * signing in is read anew. The first listener joins the customer's realtime
+     * channel, the last one's unsubscribe leaves it. A read that fails is left
+     * until the next change.
+     */
+    onCustomerInfo(listener: CustomerInfoListener): () => void;
+    private start;
+    private stop;
+    private follow;
+    private unfollow;
+    private changed;
+    private held;
+    private read;
+    private offer;
+    private tell;
+}
+export {};

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

@@ -0,0 +1,61 @@
+import type { RealtimeSocket } from './socket.js';
+/** One event of a room, as a generated module's union has it. */
+export type RoomEvent = {
+    event: string;
+    payload: unknown;
+};
+/**
+ * A room, as the generator writes one. `send` and `event` carry types alone —
+ * their values are never read: `room.send('say', { … })` is checked against
+ * the message's shape, and a handler's event against the room's events.
+ */
+export interface RoomDescriptor<E extends RoomEvent, S, P extends readonly string[] = readonly string[]> {
+    /** The channel pattern the backend declared: `ai:{sessionId}`. */
+    pattern: string;
+    /** The `{param}` names, in the pattern's order: a join takes exactly these. */
+    params: P;
+    /** The declared event names: what a handle listens to. */
+    events: readonly string[];
+    /** The declared message names: what a handle sends. */
+    messages: readonly string[];
+    send: S;
+    event: E;
+}
+/** What `on` returns: called, it stops that callback (`off` does the same). */
+export type RoomSubscription = () => void;
+/** A live room. Hold it for as long as the view is on screen, and `leave` it when the view goes: an occupied room is one its backend is still running for. */
+export interface RoomHandle<E extends RoomEvent, S> {
+    /** The channel this handle is on: `ai:42`. */
+    readonly topic: string;
+    /** Every event the room declares, as a union to switch over. */
+    on(handler: (event: E) => void): RoomSubscription;
+    /** One event by its name, its payload typed. */
+    on<K extends E['event']>(event: K, handler: (payload: Extract<E, {
+        event: K;
+    }>['payload']) => void): RoomSubscription;
+    /** Stops one callback. */
+    off(subscription: RoomSubscription): void;
+    /**
+     * Sends one declared message and waits for the room's backend to take it;
+     * rejects with a RoomError — its reason — when it did not.
+     */
+    send<K extends keyof S & string>(message: K, payload: S[K]): Promise<void>;
+    /** Drops every callback of this handle and lets go of the room; the channel is left with its last handle. */
+    leave(): void;
+}
+/**
+ * Why a room did not do what was asked. `reason` is the server's: for a join,
+ * `unauthorized` (the backend did not let the user in) or `unavailable` (it
+ * could not be asked: try again); for a message, the reason the backend gave,
+ * `forbidden` when it gave none or the user may only listen, `rate_limited`,
+ * `unavailable`. When no answer came it is `no reply` or `socket closed` —
+ * the message may have been taken — and `not joined` when nothing was sent:
+ * the handle left, its socket closed (a sign-out, another user's sign-in), or
+ * the socket dropped and is being opened again.
+ */
+export declare class RoomError extends Error {
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}
+/** Joins `room` on `socket`: resolves once the backend let the user in, rejects with a RoomError when it did not. */
+export declare function joinRoom<E extends RoomEvent, S, P extends readonly string[]>(socket: RealtimeSocket, room: RoomDescriptor<E, S, P>, params: Record<P[number], string>): Promise<RoomHandle<E, S>>;

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

@@ -0,0 +1,91 @@
+export interface Session {
+    accessToken: string;
+    refreshToken: string;
+    /** Epoch milliseconds the access token stops being accepted. */
+    expiresAt: number;
+    /** The user the session is (the access token's sub). */
+    userId: string;
+    user?: unknown;
+}
+export interface SessionStore {
+    load(): Session | null | Promise<Session | null>;
+    save(session: Session): void | Promise<void>;
+    clear(): void | Promise<void>;
+    /** Shared with other tabs (localStorage): refreshes take a lock across them. */
+    readonly shared?: boolean;
+    /** Calls back when another tab changed the stored session; returns the unsubscribe. */
+    watch?(onChange: () => void): () => void;
+}
+export type AuthEvent = 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'SIGNED_OUT' | 'SESSION_EXPIRED';
+export interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+/** The session changed under a call (another tab signed out, or in as someone else): the call is not made again. */
+export declare class SessionChangedError extends Error {
+    readonly code = "session_changed";
+    constructor(message: string);
+}
+export declare function memoryStore(): SessionStore;
+/**
+ * localStorage under one key. Storage that cannot be read or written (full,
+ * blocked, a private mode) keeps the session in memory for this page rather
+ * than losing it.
+ */
+export declare function localStore(key: string): SessionStore;
+/** The user an access token is: its sub claim (read, not verified — the server verifies). */
+export declare function subjectOf(accessToken: string): string;
+/** A refusal of the refresh token itself (rotated away, revoked, expired): the session is over. */
+export type IsRejected = (e: unknown) => boolean;
+export interface SessionManagerOptions {
+    now?: () => number;
+    lockName?: string;
+    refreshTimeoutMs?: number;
+}
+export declare class SessionManager {
+    private current;
+    private loaded;
+    private inflight;
+    private listeners;
+    private store;
+    private refresher;
+    private isRejected;
+    private now;
+    private lockName;
+    private refreshTimeoutMs;
+    constructor(store: SessionStore, refresher: (refreshToken: string) => Promise<TokenPair>, isRejected: IsRejected, opts?: SessionManagerOptions);
+    session(): Promise<Session | null>;
+    /** The session as it is now, without waiting (null before the store has loaded). */
+    snapshot(): Session | null;
+    onChange(listener: (event: AuthEvent, session: Session | null) => void): () => void;
+    /** A new session (SIGNED_IN: this user's alone, never the previous one's profile) or a refreshed one. */
+    set(pair: TokenPair, event: 'SIGNED_IN' | 'TOKEN_REFRESHED', user?: {
+        id?: string;
+    }): Promise<Session>;
+    /** The profile of the user it was read for; dropped when someone else is signed in by now. */
+    setUser(user: unknown, readFor: Session | null): Promise<void>;
+    /**
+     * Ends this tab's session. The store is cleared when it holds this user's
+     * session — the one this tab holds or the same user's, refreshed by another
+     * tab: a sign-out signs the user out of every tab. It is left alone only
+     * when it holds another user's (someone else signed in since).
+     */
+    clear(event: 'SIGNED_OUT' | 'SESSION_EXPIRED'): Promise<void>;
+    /** The access token to send now; undefined when no one is signed in. */
+    accessToken(): Promise<string | undefined>;
+    /** One refresh at a time — in this tab, and across tabs when the store is shared. */
+    refresh(): Promise<Session>;
+    /**
+     * What another tab did to the stored session: signed out (this tab signs
+     * out), signed in as someone else (this tab says SIGNED_OUT then
+     * SIGNED_IN, and the caller must not repeat its call), or refreshed it for
+     * the same user (taken as it is). Undefined when the store still holds this
+     * tab's session.
+     */
+    private adoptStored;
+    /** Another tab wrote the store: follow it now rather than at the next refresh. */
+    private reconcile;
+    private withTimeout;
+    private emit;
+}

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

@@ -0,0 +1,87 @@
+export type Frame = [joinRef: string | null, ref: string | null, topic: string, event: string, payload: Record<string, unknown>];
+export interface SocketOptions {
+    /** https://<ref>.<domain> */
+    baseUrl: string;
+    publishableKey: string;
+    accessToken: () => Promise<string | undefined>;
+    /** The WebSocket constructor (globalThis.WebSocket by default). */
+    webSocket?: typeof WebSocket;
+    /** Pauses before each reconnection attempt, in ms; the last repeats. Jittered ±20%. */
+    backoff?: number[];
+    heartbeatMs?: number;
+    replyTimeoutMs?: number;
+}
+export type ChannelState = 'closed' | 'joining' | 'joined' | 'refused';
+/**
+ * What became of a push: the server's answer — `ok` with its response, or
+ * `error` with `{ reason }` — or, when none came, `timeout` (`no reply`: the
+ * server may have taken it) or `error` with `socket closed` or `not joined`.
+ */
+export interface PushReply {
+    status: string;
+    response: Record<string, unknown>;
+}
+type Listener = (payload: Record<string, unknown>) => void;
+export declare class Channel {
+    state: ChannelState;
+    /** Why the server refused the last join, when it did. */
+    refusal?: Record<string, unknown>;
+    joinRef: string | null;
+    private listeners;
+    private closers;
+    private joinWaiters;
+    readonly name: string;
+    private socket;
+    constructor(name: string, socket: RealtimeSocket);
+    get topic(): string;
+    /** Resolves once joined; rejects with the server's reason when refused. */
+    join(): Promise<void>;
+    leave(): void;
+    /**
+     * Sends one event on the joined channel and resolves with what became of it
+     * (PushReply) — never rejects for an answer, whatever it says. A channel
+     * that is not joined sends nothing. The server answers what it takes or
+     * refuses of a room's message and what it refuses of any other; a broadcast
+     * it took on a channel that is no room is answered by no one.
+     */
+    push(event: string, payload: Record<string, unknown>): Promise<PushReply>;
+    /** Listens to an event on this channel (a broadcast is the event "broadcast"); returns the unsubscribe. */
+    on(event: string, listener: Listener): () => void;
+    /**
+     * Listens for the end of what was joined here as the socket's user: the
+     * socket closed for good (the user signed out, or someone signed in) — not a
+     * drop, after which the channel is joined again. Returns the unsubscribe.
+     */
+    onClosed(listener: () => void): () => void;
+}
+export declare class RealtimeSocket {
+    private ws;
+    private opening;
+    private ref;
+    private channels;
+    private replies;
+    private heartbeat;
+    private heartbeatRef;
+    private reconnectTimer;
+    private attempts;
+    private closedByUs;
+    /** Counted for the app's own diagnostics: how many times the socket was opened again after a drop. */
+    reconnects: number;
+    private opts;
+    constructor(opts: SocketOptions);
+    channel(name: string): Channel;
+    /** Closes the socket; every channel is closed (the app joins again — as the next user, if one signs in). */
+    disconnect(): void;
+    /** A new token for every joined channel (the session was refreshed). */
+    tokenChanged(): Promise<void>;
+    private open;
+    private dropped;
+    private sendJoin;
+    private awaitReply;
+    private receive;
+    private push;
+    private nextRef;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+export {};

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

@@ -0,0 +1,49 @@
+export interface PalbaseViteOptions {
+    /** The app's slug (palbase apps:list): its file in palbase/. */
+    app: string;
+    /** Each mode the app is built in (vite --mode), and the environment it is built against. */
+    environments: Record<string, string>;
+    /** Where palbase apps:sync writes; palbase by default. */
+    dir?: string;
+    /** The app's tsconfig, from its root: tsconfig.app.json where there is one, else tsconfig.json. */
+    tsconfig?: string;
+    /** Type-check the app against its environment before a build (true). */
+    typecheck?: boolean;
+}
+interface Warning {
+    code?: string;
+    exporter?: string;
+    id?: string;
+    message: string;
+}
+type Warn = (w: Warning) => void;
+/** What a hook may ask of the bundler: to resolve an import as from another file. */
+interface ResolveContext {
+    resolve(source: string, importer: string, options: {
+        skipSelf: boolean;
+    }): Promise<unknown>;
+}
+/** What the plugin is to Vite: its hooks, typed here so the package needs no Vite of its own. */
+export interface PalbaseVitePlugin {
+    name: string;
+    enforce: 'pre';
+    config(user: {
+        build?: {
+            rollupOptions?: {
+                onwarn?: (w: Warning, warn: Warn) => void;
+            };
+        };
+    }, env: {
+        mode: string;
+        command?: string;
+    }): unknown;
+    configResolved(config: {
+        root: string;
+        mode: string;
+        command?: string;
+    }): void;
+    buildStart(): Promise<void>;
+    resolveId(this: ResolveContext, source: string, importer?: string): string | null | Promise<unknown>;
+}
+export declare function palbase(options: PalbaseViteOptions): PalbaseVitePlugin;
+export {};