@xtandard/webhooks 0.1.1 → 0.1.3

package/dist/types-elysia2/server/cors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Framework-independent CORS for the mounted panel. When `webhooksPanel` /
+ * `createFetchHandler` is given a `cors` option, the handler answers `OPTIONS`
+ * preflights itself and attaches `Access-Control-*` headers to every response —
+ * so a **cross-origin embed** (portal on `app.example.com`, panel on
+ * `api.example.com`) works even if the host framework's CORS middleware does not
+ * wrap the mounted sub-handler.
+ *
+ * @module
+ */
+/** CORS configuration for the panel handler. */
+export interface WebhooksCorsOptions {
+    /**
+     * Allowed origin(s): a single origin (`"https://app.example.com"`), `"*"`, a
+     * list, or a predicate `(origin) => boolean`. With `credentials: true`, `"*"`
+     * is echoed back as the caller's exact origin (the browser forbids `*` +
+     * credentials).
+     */
+    origin: string | string[] | ((origin: string) => boolean);
+    /** Send `Access-Control-Allow-Credentials: true` (needed for cookie auth). Default `false`. */
+    credentials?: boolean;
+    /** Allowed methods advertised in preflight. Default `GET,HEAD,PUT,POST,DELETE,PATCH,OPTIONS`. */
+    methods?: string[];
+    /**
+     * Allowed request headers advertised in preflight. Default: reflect the
+     * request's `Access-Control-Request-Headers`, falling back to
+     * `Content-Type, Authorization`.
+     */
+    headers?: string[];
+    /** `Access-Control-Max-Age` (seconds) for the preflight cache. */
+    maxAge?: number;
+}
+/** Attach `Access-Control-*` headers to `response` for an allowed cross-origin request. */
+export declare function applyCorsHeaders(request: Request, response: Response, cors: WebhooksCorsOptions): Response;
+/** Build the `204` response for a CORS preflight (`OPTIONS`). */
+export declare function preflightResponse(request: Request, cors: WebhooksCorsOptions): Response;

package/dist/types-elysia2/server/create-fetch-handler.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The web-standard fetch handler at the heart of every framework adapter and the
+ * standalone app. Composes auth/authorization (plus portal-token scoping), the
+ * JSON admin API, static-asset serving, and SPA fallback into a single
+ * `(request: Request) => Promise<Response>` — and, by default, starts the
+ * in-process delivery dispatcher so mounting the panel is all it takes to
+ * deliver webhooks.
+ *
+ * @module
+ */
+import type { AuthProvider } from "../auth/contract.ts";
+import type { AuthorizationProvider } from "../authorization/contract.ts";
+import { type RetentionOptions, type WebhooksCore } from "../core.ts";
+import type { DeliveryErrorReporter, DeliveryListener } from "../delivery-sink.ts";
+import { type Dispatcher, type DispatcherOptions } from "../dispatcher.ts";
+import type { HookErrorReporter, WebhooksHooksInput } from "../hooks/contract.ts";
+import { type WebhooksStorage } from "../storage/contract.ts";
+import { type WebhooksCorsOptions } from "./cors.ts";
+import { type WebhooksPortalOptions } from "./routes.ts";
+/** Options for the panel handler (shared by every framework adapter). */
+export interface WebhooksPanelOptions {
+    /**
+     * Control-plane store: applications, event types, endpoints, messages, audit.
+     * Required unless a prebuilt `core` is supplied (which carries its own
+     * storage, and its `queueStorage`, as the source of truth).
+     */
+    storage?: WebhooksStorage;
+    /** Store for deliveries, attempts, and the due index. Defaults to `storage`. */
+    queueStorage?: WebhooksStorage;
+    /** Mount prefix, e.g. `"/webhooks"`. Default `""` (root). */
+    basePath?: string;
+    /** Authentication provider. Default: anonymous (no auth). */
+    auth?: AuthProvider;
+    /** Authorization provider. Default: allow all. */
+    authorization?: AuthorizationProvider;
+    /**
+     * Portal-token composition: requests bearing a valid `whpt_…` token act as a
+     * portal principal scoped to the token's application. Mint tokens
+     * server-side with `createPortalToken`. See
+     * {@link ./routes.WebhooksPortalOptions}.
+     */
+    portal?: WebhooksPortalOptions;
+    /** Block all mutating operations when true. */
+    readonly?: boolean;
+    /** UI title shown in the page and bootstrap config. */
+    title?: string;
+    /** Logo image URL shown in the navbar in place of the title wordmark. */
+    logoUrl?: string;
+    /** Override the directory the bundled UI is served from (defaults to `./ui` beside this module). */
+    uiDir?: string;
+    /** Reuse an existing core instead of constructing one. */
+    core?: WebhooksCore;
+    /**
+     * Control-plane hooks fired around admin mutations (see
+     * {@link ../hooks/contract.WebhooksHooks}). Ignored when `core` is supplied —
+     * configure hooks on that core instead.
+     */
+    hooks?: WebhooksHooksInput;
+    /** Reporter for errors thrown by `after` hooks. Default: `console.warn`. */
+    onHookError?: HookErrorReporter;
+    /**
+     * Message/audit retention policy. Ignored when a prebuilt `core` is supplied —
+     * configure it on that core instead. See {@link ../core.RetentionOptions}.
+     */
+    retention?: RetentionOptions;
+    /**
+     * Fire-and-forget sink invoked for **every** delivery attempt (metrics tap).
+     * Ignored when `core` is supplied. See {@link ../delivery-sink.DeliveryListener}.
+     */
+    onDelivery?: DeliveryListener;
+    /** Reporter for errors thrown by `onDelivery`. Default: `console.warn`. */
+    onDeliveryError?: DeliveryErrorReporter;
+    /**
+     * Enable CORS on the handler itself — answers `OPTIONS` preflights and attaches
+     * `Access-Control-*` headers to every response, so a **cross-origin** embed
+     * works regardless of the host framework. See {@link ./cors.WebhooksCorsOptions}.
+     */
+    cors?: WebhooksCorsOptions;
+    /**
+     * Delivery-engine configuration. By default the panel creates **and starts**
+     * a dispatcher so deliveries flow the moment the panel is mounted. Pass
+     * `false` to skip it entirely (split-worker deployments where a separate
+     * process runs `xtandard-webhooks dispatch` against the same storage).
+     */
+    dispatcher?: DispatcherOptions | false;
+}
+/** Return shape of {@link createFetchHandler}. */
+export interface CreateFetchHandlerResult {
+    /** Web-standard request handler. */
+    fetch(request: Request): Promise<Response>;
+    /** The underlying core (handy for `publish()`, tests, CLI, and standalone wiring). */
+    core: WebhooksCore;
+    /** The started dispatcher, or `null` when `dispatcher: false`. */
+    dispatcher: Dispatcher | null;
+    /**
+     * The admin API as an OpenAPI 3.1 document (also served at `{basePath}/api/openapi.json`).
+     * Merge it into your host app's docs — e.g. Elysia `@elysiajs/openapi` `references`.
+     */
+    openapi(): Record<string, unknown>;
+}
+/**
+ * Build the panel fetch handler.
+ *
+ * @example
+ * ```ts
+ * import { createFetchHandler } from "@xtandard/webhooks";
+ * import { createFileStorage } from "@xtandard/webhooks/storage/file";
+ *
+ * const storage = createFileStorage({ dir: "./data/webhooks" });
+ * const { fetch, core } = createFetchHandler({
+ *   storage,
+ *   basePath: "/webhooks",
+ *   title: "Acme Webhooks",
+ * });
+ *
+ * Bun.serve({ port: 3000, fetch });
+ * // Elsewhere in the app:
+ * await core.publish("acme", { eventType: "invoice.paid", payload: { id: "inv_1" } });
+ * ```
+ */
+export declare function createFetchHandler(options: WebhooksPanelOptions): CreateFetchHandlerResult;

package/dist/types-elysia2/server/openapi.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAPI 3.1 description of the admin JSON API.
+ *
+ * Exposed two ways, mirroring the flags panel:
+ *  - served at `GET {basePath}/api/openapi.json` for standalone tools (Scalar,
+ *    Swagger UI, Postman, codegen);
+ *  - returned by `createFetchHandler(...).openapi()` so you can MERGE it into
+ *    your host app's OpenAPI document (e.g. Elysia `@elysiajs/openapi`
+ *    `references`, or Hono's OpenAPI).
+ *
+ * Hand-authored — no generation dependency (flags precedent).
+ *
+ * @module
+ */
+/** Options for {@link buildOpenApiDocument}. */
+export interface OpenApiOptions {
+    /** Mount prefix used in the `servers` url (e.g. `"/webhooks"`). */
+    basePath?: string;
+    /** Document title. */
+    title?: string;
+    /** Document version (defaults to the package's API version). */
+    version?: string;
+}
+/** Build the OpenAPI 3.1 document for the admin API. Pure — safe to call anywhere. */
+export declare function buildOpenApiDocument(options?: OpenApiOptions): Record<string, unknown>;

package/dist/types-elysia2/server/render-index-html.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Renders the SPA `index.html`: injects a `<base>` tag so relative asset URLs
+ * resolve under any mount path, and a bootstrap `window.__WEBHOOKS_CONFIG__`
+ * blob. Falls back to a minimal built-in page when the UI bundle is absent
+ * (e.g. before `bun run build:ui`, or in headless tests).
+ *
+ * @module
+ */
+/** Bootstrap config injected into the page and exposed at `/config`. */
+export interface BootstrapConfig {
+    title: string;
+    basePath: string;
+    readonly: boolean;
+    /** Optional logo image URL shown in the navbar in place of the title wordmark. */
+    logoUrl?: string;
+}
+/** Read, inject into, and return the SPA index HTML (or a fallback). */
+export declare function renderIndexHtml(uiDir: string, config: BootstrapConfig): Promise<string>;

package/dist/types-elysia2/server/routes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * JSON admin API. A tiny method+pattern router over {@link WebhooksCore}, wired
+ * to authentication, authorization, and portal-token scoping. Returns `null`
+ * for non-API paths so the caller can fall through to static-asset / SPA
+ * handling.
+ *
+ * The consumer **portal** is not a separate route set — a request bearing a
+ * valid `Authorization: Bearer whpt_…` token hits this same API with its
+ * authorization force-scoped to the token's application and allowed actions
+ * (the host's own auth/authorization providers are bypassed for portal
+ * principals; portal scoping wins).
+ *
+ * @module
+ */
+import type { AuthProvider } from "../auth/contract.ts";
+import type { AuthorizationProvider, WebhooksAction } from "../authorization/contract.ts";
+import { type WebhooksCore } from "../core.ts";
+/**
+ * Portal composition for the panel: when set, requests bearing a valid
+ * `whpt_…` token act as a portal principal scoped to the token's application.
+ */
+export interface WebhooksPortalOptions {
+    /** The HMAC secret portal tokens are minted with (`createPortalToken`). */
+    secret: string;
+    /**
+     * Actions a portal principal may perform (always confined to the token's
+     * application). Defaults to {@link DEFAULT_PORTAL_ACTIONS}.
+     */
+    allow?: WebhooksAction[];
+}
+/**
+ * The default portal grant: manage own endpoints (including secrets), inspect
+ * own messages/deliveries, retry, and read the event-type catalog.
+ */
+export declare const DEFAULT_PORTAL_ACTIONS: readonly WebhooksAction[];
+/** Everything the API router needs. */
+export interface ApiContext {
+    core: WebhooksCore;
+    auth: AuthProvider;
+    authorization: AuthorizationProvider;
+    title: string;
+    readonly: boolean;
+    basePath: string;
+    logoUrl?: string;
+    /** Portal-token composition (see {@link WebhooksPortalOptions}). */
+    portal?: WebhooksPortalOptions;
+}
+/**
+ * Handle an API request. `path` is already base-path-stripped. Returns a
+ * `Response` for API/config routes, or `null` if the path is not an API route.
+ */
+export declare function handleApiRequest(request: Request, path: string, ctx: ApiContext): Promise<Response | null>;

package/dist/types-elysia2/server/static-assets.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Serves the bundled SPA's static assets from the UI output directory. Maps file
+ * extensions to content types and guards against path traversal.
+ *
+ * @module
+ */
+/** True if the path has a file extension (so a miss should 404 rather than fall through to the SPA). */
+export declare function looksLikeAsset(path: string): boolean;
+/**
+ * Try to serve `path` (base-path-stripped, leading `/`) as a static file from
+ * `uiDir`. Returns a `Response`, or `null` if the file does not exist.
+ */
+export declare function serveStaticAsset(uiDir: string, path: string): Promise<Response | null>;

package/dist/types-elysia2/signing.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Standard Webhooks symmetric (v1) signing and verification.
+ *
+ * Pure and zero-dependency (Web Crypto only) — safe on the request path and in
+ * any WinterCG runtime. Shared by the sender (the dispatcher signs outgoing
+ * deliveries) and the receiver subpath (`@xtandard/webhooks/receiver`), and
+ * compatible with any Standard Webhooks implementation, including Svix.
+ *
+ * The wire contract (https://www.standardwebhooks.com):
+ *
+ * - secrets are `whsec_` + base64-encoded key material (24–64 bytes decoded)
+ * - the signed content is `${id}.${timestamp}.${body}`
+ * - the signature is `v1,` + base64(HMAC-SHA256(key, signedContent))
+ * - `webhook-signature` may carry several space-separated signatures (secret
+ *   rotation); a receiver accepts if **any** matches
+ * - `webhook-timestamp` (unix seconds) must be within tolerance, both ways
+ *
+ * @module
+ */
+import type { WebhookEnvelope } from "./schema.ts";
+export type { WebhookEnvelope };
+/** Prefix of every symmetric Standard Webhooks secret. */
+export declare const SECRET_PREFIX = "whsec_";
+/** Thrown by {@link verify} / receiver helpers when a webhook fails verification. */
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Generate a new signing secret: `whsec_` + base64 of 24 crypto-random bytes.
+ *
+ * @example
+ * ```ts
+ * import { generateSecret } from "@xtandard/webhooks/signing";
+ *
+ * const secret = generateSecret(); // "whsec_…"
+ * ```
+ */
+export declare function generateSecret(): string;
+/**
+ * Sign one delivery attempt with one secret: `v1,` + base64(HMAC-SHA256 over
+ * `${id}.${timestamp}.${body}`). `timestamp` is unix **seconds**.
+ *
+ * @example
+ * ```ts
+ * import { sign } from "@xtandard/webhooks/signing";
+ *
+ * const signature = await sign(secret, "msg_…", 1720000000, body);
+ * // "v1,K5oZ…"
+ * ```
+ */
+export declare function sign(secret: string, id: string, timestamp: number, body: string): Promise<string>;
+/**
+ * Build the full `webhook-signature` header value: one signature per secret,
+ * space-separated (multiple entries appear during secret rotation).
+ */
+export declare function signatureHeader(secrets: string[], id: string, timestamp: number, body: string): Promise<string>;
+/** Input to {@link verify}. */
+export interface VerifyInput {
+    /** The raw request body, **exactly** as received (no re-serialization). */
+    payload: string;
+    /** Request headers; name lookup is case-insensitive. */
+    headers: Record<string, string>;
+    /** Candidate secret(s) — pass several during rotation; any match passes. */
+    secret: string | string[];
+    /** Allowed clock skew in seconds, both past and future. Default `300`. */
+    toleranceSeconds?: number;
+    /** Current unix time in seconds — injectable for tests. */
+    now?: number;
+}
+/**
+ * Verify an incoming Standard Webhooks request (from **any** compliant sender,
+ * not just this package). Checks the timestamp tolerance, then compares every
+ * `v1,` signature in the header against every candidate secret in constant
+ * time. Returns the parsed envelope on success; throws
+ * {@link WebhookVerificationError} otherwise.
+ *
+ * @example
+ * ```ts
+ * import { verify } from "@xtandard/webhooks/signing";
+ *
+ * const envelope = await verify({
+ *   payload: rawBody,
+ *   headers: { "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig },
+ *   secret: "whsec_…",
+ * });
+ * ```
+ */
+export declare function verify(input: VerifyInput): Promise<WebhookEnvelope>;

package/dist/types-elysia2/storage/contract.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Storage contracts. The base {@link WebhooksStorage} is intentionally tiny —
+ * four async methods — so users can bring their own backend. Optional
+ * capabilities (watch, transactions, compare-and-swap, native delivery-queue
+ * claiming) are separate interfaces that adapters may implement and the core
+ * feature-detects.
+ *
+ * @module
+ */
+import type { Delivery } from "../schema.ts";
+/** The minimal key/value contract every storage backend must satisfy. */
+export interface WebhooksStorage {
+    /** Read a value, or `null` if absent. */
+    getItem<T>(key: string): Promise<T | null>;
+    /** Write a value (overwriting any existing). */
+    setItem<T>(key: string, value: T): Promise<void>;
+    /** Delete a key (no-op if absent). */
+    removeItem(key: string): Promise<void>;
+    /** List all keys beginning with `prefix`. */
+    getKeys(prefix: string): Promise<string[]>;
+}
+/** A storage change event delivered to {@link WatchableWebhooksStorage.watch} callbacks. */
+export interface StorageChangeEvent {
+    type: "update" | "remove";
+    key: string;
+}
+/** Storage that can push change notifications (e.g. Redis pub/sub, fs.watch). */
+export interface WatchableWebhooksStorage extends WebhooksStorage {
+    /**
+     * Subscribe to changes under `prefix`. Resolves to an unsubscribe function.
+     */
+    watch(prefix: string, callback: (event: StorageChangeEvent) => void): Promise<() => void>;
+}
+/** Storage that supports atomic multi-key transactions. */
+export interface TransactionalWebhooksStorage extends WebhooksStorage {
+    transaction<T>(callback: (tx: WebhooksStorage) => Promise<T>): Promise<T>;
+}
+/** Storage that supports optimistic concurrency via compare-and-swap. */
+export interface CompareAndSwapWebhooksStorage extends WebhooksStorage {
+    compareAndSwap<T>(input: {
+        key: string;
+        expected: T | null;
+        next: T;
+    }): Promise<boolean>;
+}
+/**
+ * Storage that can natively claim due deliveries (sorted-set / `SKIP LOCKED`
+ * class backends). When present, the dispatcher delegates claiming entirely to
+ * the adapter instead of scanning the generic due index.
+ *
+ * The claim contract: atomically transition each returned delivery to
+ * `status: "delivering"` with `leaseUntil = now + leaseMs`, reposition its due
+ * entry at the lease expiry (so a crashed claimer's work re-surfaces), and
+ * never return the same delivery to two concurrent claimers.
+ */
+export interface DeliveryQueueStorage extends WebhooksStorage {
+    claimDue(input: {
+        now: string;
+        limit: number;
+        leaseMs: number;
+    }): Promise<Delivery[]>;
+}
+/** Runtime feature-detection: does this storage implement `watch`? */
+export declare function isWatchable(storage: WebhooksStorage): storage is WatchableWebhooksStorage;
+/** Runtime feature-detection: does this storage implement `transaction`? */
+export declare function isTransactional(storage: WebhooksStorage): storage is TransactionalWebhooksStorage;
+/** Runtime feature-detection: does this storage implement `compareAndSwap`? */
+export declare function isCompareAndSwap(storage: WebhooksStorage): storage is CompareAndSwapWebhooksStorage;
+/** Runtime feature-detection: does this storage implement `claimDue`? */
+export declare function hasDeliveryQueue(storage: WebhooksStorage): storage is DeliveryQueueStorage;
+/**
+ * Helper for adapters whose subpath requires an optional peer dependency. Throws
+ * a clear, actionable error when the peer is missing.
+ */
+export declare function requirePeer(name: string, subpath: string): never;

package/dist/types-elysia2/validation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Runtime validation for control-plane inputs, built on `valibot`.
+ *
+ * This is the **admin path** only — `publish()` performs its own minimal
+ * checks and the wire/receiver path never imports this module, so `valibot`
+ * stays off the hot paths. Validation combines structural parsing (valibot)
+ * with semantic checks (URL policy, reserved header names, reserved keys).
+ *
+ * @module
+ */
+/** Allowed characters for application keys and event type names. */
+export declare const KEY_REGEX: RegExp;
+/**
+ * Validate a caller-supplied string that becomes a **storage key segment**
+ * (e.g. an idempotency key). Rejects anything that could escape its namespace
+ * or traverse the filesystem on the file adapter: characters outside
+ * {@link KEY_REGEX}, and the dot-only segments `.` / `..`. Returns the issue
+ * list (empty when safe) so callers can fold it into a {@link ValidationError}.
+ */
+export declare function validateKeySegment(value: string, path: string): ValidationIssue[];
+/**
+ * Header names owned by the Standard Webhooks wire contract. Endpoints may not
+ * override them via static headers.
+ */
+export declare const RESERVED_HEADERS: readonly ["webhook-id", "webhook-timestamp", "webhook-signature"];
+/** A single validation problem with a dotted path into the offending data. */
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+/** Result of the `validate*` functions. */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+}
+/** Raised by {@link assertValid} when an input fails validation. Maps to HTTP 422. */
+export declare class ValidationError extends Error {
+    readonly errors: ValidationIssue[];
+    constructor(errors: ValidationIssue[]);
+}
+/** Throw a {@link ValidationError} when `result` is invalid. */
+export declare function assertValid(result: ValidationResult): void;
+/**
+ * Validate an {@link Application}: structure + reserved-key check.
+ *
+ * @example
+ * ```ts
+ * import { validateApplication } from "@xtandard/webhooks";
+ *
+ * const result = validateApplication({ key: "acme" });
+ * // result.valid === true
+ * ```
+ */
+export declare function validateApplication(input: unknown, basePath?: string): ValidationResult;
+/** Validate an {@link EventType}: structural only (the name regex carries the semantics). */
+export declare function validateEventType(input: unknown, basePath?: string): ValidationResult;
+/** Options that relax/extend the endpoint URL policy. */
+export interface UrlPolicyOptions {
+    /** Allow `http:` for non-localhost hosts (dev only; default `false`). */
+    allowInsecureUrls?: boolean;
+    /** Extra host-supplied gate; return `false` to reject (e.g. an SSRF denylist). */
+    urlPolicy?: (url: string) => boolean;
+}
+/**
+ * Validate an endpoint destination URL: parseable, `https:` (or `http:` for
+ * localhost, or anywhere when `allowInsecureUrls`), no embedded credentials,
+ * and passing the host's optional `urlPolicy` gate.
+ */
+export declare function validateEndpointUrl(url: string, options?: UrlPolicyOptions, basePath?: string): ValidationResult;
+/**
+ * Validate an {@link Endpoint} input: structure, URL policy, and static-header
+ * restrictions (the Standard Webhooks headers are reserved).
+ *
+ * @example
+ * ```ts
+ * import { validateEndpoint } from "@xtandard/webhooks";
+ *
+ * const result = validateEndpoint({ url: "https://api.example.com/hooks" });
+ * // result.valid === true
+ * ```
+ */
+export declare function validateEndpoint(input: unknown, options?: UrlPolicyOptions, basePath?: string): ValidationResult;

package/dist/types-elysia2/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Package version, used for the default dispatcher `user-agent`. Bumped by the
+ * release flow alongside `package.json`.
+ *
+ * @module
+ */
+/** The published package version. */
+export declare const VERSION = "0.1.3";

package/dist/types-react/ui/lib/portal-container.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Where Base UI portals (Select/Combobox popups, Dialogs) render.
+ *
+ * In the **standalone SPA** the stylesheet is global, so portals default to
+ * `document.body` and look right. In the **React embed** the stylesheet is
+ * scoped under `.xtandard-webhooks` (see `scripts/scope-embed-css.ts`), so
+ * anything portaled to `document.body` would fall outside the scope and render
+ * unstyled. The embed therefore points portals at its own wrapper element via
+ * {@link setPortalContainerRef}, keeping popups inside the scoped subtree.
+ *
+ * Module-level singleton (same trade-off as `setApiBase`/`setApiToken`): one
+ * embed per page. Unset → portals default to `document.body`.
+ *
+ * @module
+ */
+import type { RefObject } from "react";
+/** Point portals at `ref` (the embed wrapper). Pass `undefined` to reset to the body default. */
+export declare function setPortalContainerRef(ref: RefObject<HTMLElement | null> | undefined): void;
+/**
+ * The current portal container ref, or `undefined` when none is set (Base UI
+ * then defaults to `document.body`). Pass the result to a Base UI
+ * `*.Portal container={…}` prop.
+ */
+export declare function portalContainerRef(): RefObject<HTMLElement | null> | undefined;