@tesouro/embedded-components-react 0.3.42 → 0.3.44

package/dist/experimental/WidgetSuite.d.ts

@@ -1,976 +0,0 @@
-import * as React from 'react';
-import { ComponentType, AnchorHTMLAttributes, ReactNode, ErrorInfo } from 'react';
-import { FallbackProps } from 'react-error-boundary';
-
-/**
- * Copy the shell owns. The section names are deliberately absent: they arrive on
- * each `SuiteSection`, because whoever decides which sections exist is also the
- * only layer that can name them.
- */
-interface WidgetSuiteShellLabels {
-    /** Names the section menu for assistive technology. */
-    navAriaLabel: string;
-    /**
-     * Announces the placeholder shell while the caller resolves which sections
-     * exist. Read out in place of the menu, which has no items yet to name.
-     */
-    loadingAriaLabel: string;
-    /** Shown in place of the menu when the caller supplies no sections. */
-    emptyState: {
-        title: string;
-        body: string;
-    };
-}
-/**
- * `Labels` has a nested group, so a shallow `{ ...defaults, ...overrides }`
- * would let a consumer overriding one `emptyState` string drop the other. The
- * repo has no shared deep-partial type, so each labels module declares its own.
- */
-type PartialDeep<T> = {
-    [K in keyof T]?: T[K] extends object ? PartialDeep<T[K]> : T[K];
-};
-declare const WIDGET_SUITE_SHELL_LABELS_EN: WidgetSuiteShellLabels;
-
-type AuthToken = string | undefined;
-interface Auth {
-    /**
-     * Which part of the request do we use to send the auth?
-     *
-     * @default 'header'
-     */
-    in?: 'header' | 'query' | 'cookie';
-    /**
-     * A unique identifier for the security scheme.
-     *
-     * Defined only when there are multiple security schemes whose `Auth`
-     * shape would otherwise be identical.
-     */
-    key?: string;
-    /**
-     * Header or query parameter name.
-     *
-     * @default 'Authorization'
-     */
-    name?: string;
-    scheme?: 'basic' | 'bearer';
-    type: 'apiKey' | 'http';
-}
-
-interface SerializerOptions<T> {
-    /**
-     * @default true
-     */
-    explode: boolean;
-    style: T;
-}
-type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
-type ObjectStyle = 'form' | 'deepObject';
-
-type QuerySerializer = (query: Record<string, unknown>) => string;
-type BodySerializer = (body: unknown) => unknown;
-type QuerySerializerOptionsObject = {
-    allowReserved?: boolean;
-    array?: Partial<SerializerOptions<ArrayStyle>>;
-    object?: Partial<SerializerOptions<ObjectStyle>>;
-};
-type QuerySerializerOptions = QuerySerializerOptionsObject & {
-    /**
-     * Per-parameter serialization overrides. When provided, these settings
-     * override the global array/object settings for specific parameter names.
-     */
-    parameters?: Record<string, QuerySerializerOptionsObject>;
-};
-
-type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
-type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
-    /**
-     * Returns the final request URL.
-     */
-    buildUrl: BuildUrlFn;
-    getConfig: () => Config;
-    request: RequestFn;
-    setConfig: (config: Config) => Config;
-} & {
-    [K in HttpMethod]: MethodFn;
-} & ([SseFn] extends [never] ? {
-    sse?: never;
-} : {
-    sse: {
-        [K in HttpMethod]: SseFn;
-    };
-});
-interface Config$1 {
-    /**
-     * Auth token or a function returning auth token. The resolved value will be
-     * added to the request payload as defined by its `security` array.
-     */
-    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
-    /**
-     * A function for serializing request body parameter. By default,
-     * {@link JSON.stringify()} will be used.
-     */
-    bodySerializer?: BodySerializer | null;
-    /**
-     * An object containing any HTTP headers that you want to pre-populate your
-     * `Headers` object with.
-     *
-     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
-     */
-    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
-    /**
-     * The request method.
-     *
-     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
-     */
-    method?: Uppercase<HttpMethod>;
-    /**
-     * A function for serializing request query parameters. By default, arrays
-     * will be exploded in form style, objects will be exploded in deepObject
-     * style, and reserved characters are percent-encoded.
-     *
-     * This method will have no effect if the native `paramsSerializer()` Axios
-     * API function is used.
-     *
-     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
-     */
-    querySerializer?: QuerySerializer | QuerySerializerOptions;
-    /**
-     * A function validating request data. This is useful if you want to ensure
-     * the request conforms to the desired shape, so it can be safely sent to
-     * the server.
-     */
-    requestValidator?: (data: unknown) => Promise<unknown>;
-    /**
-     * A function transforming response data before it's returned. This is useful
-     * for post-processing data, e.g., converting ISO strings into Date objects.
-     */
-    responseTransformer?: (data: unknown) => Promise<unknown>;
-    /**
-     * A function validating response data. This is useful if you want to ensure
-     * the response conforms to the desired shape, so it can be safely passed to
-     * the transformers and returned to the user.
-     */
-    responseValidator?: (data: unknown) => Promise<unknown>;
-}
-
-type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config$1, 'method' | 'responseTransformer' | 'responseValidator'> & {
-    /**
-     * Fetch API implementation. You can use this option to provide a custom
-     * fetch instance.
-     *
-     * @default globalThis.fetch
-     */
-    fetch?: typeof fetch;
-    /**
-     * Implementing clients can call request interceptors inside this hook.
-     */
-    onRequest?: (url: string, init: RequestInit) => Promise<Request>;
-    /**
-     * Callback invoked when a network or parsing error occurs during streaming.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @param error The error that occurred.
-     */
-    onSseError?: (error: unknown) => void;
-    /**
-     * Callback invoked when an event is streamed from the server.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @param event Event streamed from the server.
-     * @returns Nothing (void).
-     */
-    onSseEvent?: (event: StreamEvent<TData>) => void;
-    serializedBody?: RequestInit['body'];
-    /**
-     * Default retry delay in milliseconds.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @default 3000
-     */
-    sseDefaultRetryDelay?: number;
-    /**
-     * Maximum number of retry attempts before giving up.
-     */
-    sseMaxRetryAttempts?: number;
-    /**
-     * Maximum retry delay in milliseconds.
-     *
-     * Applies only when exponential backoff is used.
-     *
-     * This option applies only if the endpoint returns a stream of events.
-     *
-     * @default 30000
-     */
-    sseMaxRetryDelay?: number;
-    /**
-     * Optional sleep function for retry backoff.
-     *
-     * Defaults to using `setTimeout`.
-     */
-    sseSleepFn?: (ms: number) => Promise<void>;
-    url: string;
-};
-interface StreamEvent<TData = unknown> {
-    data: TData;
-    event?: string;
-    id?: string;
-    retry?: number;
-}
-type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
-    stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
-};
-
-type ErrInterceptor<Err, Res, Req, Options> = (error: Err, 
-/** response may be undefined due to a network error where no response object is produced */
-response: Res | undefined, 
-/** request may be undefined, because error may be from building the request object itself */
-request: Req | undefined, options: Options) => Err | Promise<Err>;
-type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
-type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
-declare class Interceptors<Interceptor> {
-    fns: Array<Interceptor | null>;
-    clear(): void;
-    eject(id: number | Interceptor): void;
-    exists(id: number | Interceptor): boolean;
-    getInterceptorIndex(id: number | Interceptor): number;
-    update(id: number | Interceptor, fn: Interceptor): number | Interceptor | false;
-    use(fn: Interceptor): number;
-}
-interface Middleware<Req, Res, Err, Options> {
-    error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
-    request: Interceptors<ReqInterceptor<Req, Options>>;
-    response: Interceptors<ResInterceptor<Res, Req, Options>>;
-}
-
-type ResponseStyle = 'data' | 'fields';
-interface Config<T extends ClientOptions$1 = ClientOptions$1> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, Config$1 {
-    /**
-     * Base URL for all requests made by this client.
-     */
-    baseUrl?: T['baseUrl'];
-    /**
-     * Fetch API implementation. You can use this option to provide a custom
-     * fetch instance.
-     *
-     * @default globalThis.fetch
-     */
-    fetch?: typeof fetch;
-    /**
-     * Please don't use the Fetch client for Next.js applications. The `next`
-     * options won't have any effect.
-     *
-     * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
-     */
-    next?: never;
-    /**
-     * Return the response data parsed in a specified format. By default, `auto`
-     * will infer the appropriate method from the `Content-Type` response header.
-     * You can override this behavior with any of the {@link Body} methods.
-     * Select `stream` if you don't want to parse response data at all.
-     *
-     * @default 'auto'
-     */
-    parseAs?: 'arrayBuffer' | 'auto' | 'blob' | 'formData' | 'json' | 'stream' | 'text';
-    /**
-     * Should we return only data or multiple fields (data, error, response, etc.)?
-     *
-     * @default 'fields'
-     */
-    responseStyle?: ResponseStyle;
-    /**
-     * Throw an error instead of returning it in the response?
-     *
-     * @default false
-     */
-    throwOnError?: T['throwOnError'];
-}
-interface RequestOptions<TData = unknown, TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
-    responseStyle: TResponseStyle;
-    throwOnError: ThrowOnError;
-}>, Pick<ServerSentEventsOptions<TData>, 'onRequest' | 'onSseError' | 'onSseEvent' | 'sseDefaultRetryDelay' | 'sseMaxRetryAttempts' | 'sseMaxRetryDelay'> {
-    /**
-     * Any body that you want to add to your request.
-     *
-     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
-     */
-    body?: unknown;
-    path?: Record<string, unknown>;
-    query?: Record<string, unknown>;
-    /**
-     * Security mechanism(s) to use for the request.
-     */
-    security?: ReadonlyArray<Auth>;
-    url: Url;
-}
-interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
-    headers: Headers;
-    serializedBody?: string;
-}
-type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = ThrowOnError extends true ? Promise<TResponseStyle extends 'data' ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
-    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
-    request: Request;
-    response: Response;
-}> : Promise<TResponseStyle extends 'data' ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
-    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
-    error: undefined;
-} | {
-    data: undefined;
-    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
-}) & {
-    /** request may be undefined, because error may be from building the request object itself */
-    request?: Request;
-    /** response may be undefined, because error may be from building the request object itself or from a network error */
-    response?: Response;
-}>;
-interface ClientOptions$1 {
-    baseUrl?: string;
-    responseStyle?: ResponseStyle;
-    throwOnError?: boolean;
-}
-type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
-type SseFn = <TData = unknown, _TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, 'method'>) => Promise<ServerSentEventsResult<TData>>;
-type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
-type BuildUrlFn = <TData extends {
-    body?: unknown;
-    path?: Record<string, unknown>;
-    query?: Record<string, unknown>;
-    url: string;
-}>(options: TData & Options<TData>) => string;
-type Client = Client$1<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
-    interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
-};
-interface TDataShape {
-    body?: unknown;
-    headers?: unknown;
-    path?: unknown;
-    query?: unknown;
-    url: string;
-}
-type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
-type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
-
-type ClientOptions = {
-    baseUrl: 'https://api.stage.tesouro.com' | 'https://api.sandbox.stage.tesouro.com' | 'https://api.stage.business-banking.app' | 'https://api.tesouro.com' | 'https://api.sandbox.tesouro.com' | 'https://api.business-banking.app' | (string & {});
-};
-
-type EmbeddedClient = Client;
-type ExtractLiterals<T> = T extends string ? string extends T ? never : T : never;
-type BaseUrl = ExtractLiterals<ClientOptions['baseUrl']>;
-
-type LinkComponentProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
-    children?: ReactNode;
-};
-type LinkComponent = ComponentType<LinkComponentProps>;
-/**
- * The UI frameworks a widget's UI layer can render with.
- *
- * - `shadcn` — the shadcn/Tailwind implementation. This is the default and the
- *   implicit fallback, so existing consumers that select nothing keep rendering
- *   shadcn.
- * - `tecton` — the Tecton implementation.
- *
- * Declared as an `as const` object (not a TypeScript `enum`) per repo
- * convention.
- */
-declare const UIFramework: {
-    readonly Shadcn: "shadcn";
-    readonly Tecton: "tecton";
-};
-type UIFramework = (typeof UIFramework)[keyof typeof UIFramework];
-
-/**
- * The implementation a widget renders with.
- *
- * - `native` — the Tesouro-native implementation. This is the default and the
- *   implicit fallback, so consumers that select nothing keep rendering native.
- * - `monite` — the Monite SDK implementation.
- *
- * Declared as an `as const` object (not a TypeScript `enum`) per repo
- * convention.
- */
-declare const Implementation: {
-    readonly Native: "native";
-    readonly Monite: "monite";
-};
-type Implementation = (typeof Implementation)[keyof typeof Implementation];
-/**
- * The settable fields of the widget config cascade.
- *
- * This is the type accepted by {@link setGlobalWidgetConfig} and all provider props.
- * It intentionally excludes `initResponse`, which is populated automatically by the
- * provider after a successful fetch and must never be set manually.
- *
- * The `null` vs `undefined` distinction on `widgetToken` and `organizationId` is intentional:
- * - `undefined` — not set at this level; inherit from the nearest ancestor or global store.
- * - `null` — explicitly cleared; downstream sees "no value" even if an ancestor had one
- *   (e.g. after logout or deliberate de-scoping).
- *
- * @see {@link WidgetConfig} for the resolved output type (includes `initResponse`)
- * @see {@link RootWidgetProvider}
- * @see {@link WidgetProvider}
- * @see {@link setGlobalWidgetConfig}
- */
-interface WidgetConfigInput {
-    /**
-     * Base URL of the Tesouro embedded API (e.g. `"https://api.tesouro.com"`).
-     *
-     * When omitted the nearest ancestor's `baseUrl` or the global store value is used.
-     * Changing this recreates the underlying HTTP client so all subsequent requests
-     * go to the new host.
-     */
-    baseUrl?: BaseUrl;
-    /**
-     * Bearer token used to authenticate widget requests.
-     *
-     * Injected as `Authorization: Bearer <token>` on every outgoing request via an
-     * interceptor on the scoped HTTP client. Token updates are picked up immediately
-     * without recreating the client.
-     *
-     * - `string` — send this token on all requests from this level downward.
-     * - `null` — explicitly cleared; no auth header is sent and fetching is suppressed.
-     * - `undefined` — not set at this level; inherit from the nearest ancestor or global store.
-     */
-    widgetToken?: string | null;
-    /**
-     * Organization ID forwarded as the `x-organization-id` request header.
-     *
-     * Passed through {@link EmbedApiProvider} context rather than the auth interceptor,
-     * so individual data-access hooks can opt in per-request.
-     *
-     * - `string` — use this organization for downstream data requests.
-     * - `null` — explicitly cleared; queries that require an org ID will be disabled.
-     * - `undefined` — not set at this level; inherit from the nearest ancestor or global store.
-     *
-     * When `undefined` across the **whole** cascade (no prop, no ancestor, no global
-     * value), the resolved org defaults to the loaded `initResponse.organizationId`
-     * (see {@link WidgetConfig.initResponse}) once the widget-init fetch settles. This
-     * is the lowest-priority fallback — any explicit `string` or `null` at any cascade
-     * level wins, and an explicit `null` is preserved and never falls back.
-     *
-     * Only an **explicit** ancestor org is inherited. An ancestor's *init-derived*
-     * default does not propagate into a descendant that owns its own fetch (its own
-     * `baseUrl`/`widgetToken`); such a descendant defaults to its own
-     * `initResponse.organizationId` instead, so it never sends an ancestor's org with
-     * its own token.
-     */
-    organizationId?: string | null;
-    /**
-     * Optional post-creation hook for the scoped HTTP client.
-     *
-     * Called once after the provider creates its scoped {@link EmbeddedClient} and
-     * applies the built-in `Authorization: Bearer` interceptor. Receives the
-     * fully-configured client and must return the client to be used for the lifetime of
-     * this provider level — either the same instance (with additional interceptors
-     * attached) or a new client entirely.
-     *
-     * **Order:** The built-in auth interceptor is always applied first. `configClient`
-     * is called on top of it, so any interceptors you add here run after auth is set.
-     *
-     * **Any prop triggers a scoped client.** A {@link WidgetProvider} creates its own
-     * scoped client whenever any prop is set — including `configClient` alone, without
-     * `baseUrl` or `widgetToken`. Only a fully props-free pass-through provider skips
-     * client creation and never calls this function.
-     *
-     * **Stability:** The function reference is included in the client creation memo's
-     * dependency array. Passing an unstable (inline) function recreates the client on
-     * every render. Stabilize with `useCallback` or define the function outside the
-     * component.
-     *
-     * **Cascade:** Inherits from the nearest ancestor when `undefined`. A child
-     * {@link WidgetProvider} that creates its own scoped client will use the resolved
-     * `configClient` from the cascade unless it provides its own override.
-     *
-     * @example
-     * ```tsx
-     * const addLogging = useCallback(
-     *   (client: EmbeddedClient) => {
-     *     client.interceptors.request.use((req) => {
-     *       console.log('[widget]', req.method, req.url);
-     *       return req;
-     *     });
-     *     return client;
-     *   },
-     *   [],
-     * );
-     *
-     * <RootWidgetProvider
-     *   baseUrl="https://api.tesouro.com"
-     *   widgetToken={token}
-     *   configClient={addLogging}
-     * >
-     *   <App />
-     * </RootWidgetProvider>
-     * ```
-     */
-    configClient?: (client: EmbeddedClient) => EmbeddedClient;
-    /**
-     * Overrides the widget-gateway routing decision for the scoped HTTP client.
-     *
-     * Any caller reaching the Tesouro API with a widget token must route data
-     * requests through the widget gateway: prefix the path with
-     * `/api/widget-gateway/proxy` and carry the token as `X-Widget-Token`. The
-     * provider applies both automatically per request when the request origin is
-     * a known Tesouro API host (`WIDGET_GATEWAY_HOSTS`, derived from the
-     * generated `ClientOptions['baseUrl']`); `/api/widget-gateway/*` paths (the
-     * init round-trip) always pass through untouched.
-     *
-     * - `undefined` — decide from the request origin, as above. Inherits from
-     *   the nearest ancestor or global store like every other config field.
-     * - `true` — always apply the rewrite, even for an unlisted base URL (e.g. a
-     *   custom domain in front of the gateway).
-     * - `false` — never apply it. For hosts that route widget requests their own
-     *   way, such as a same-origin BFF whose `configClient` retargets every
-     *   request.
-     *
-     * Independent of {@link configClient}: a host that only adds a header keeps
-     * the built-in routing, and the built-in interceptor runs before any
-     * `configClient` interceptor.
-     */
-    gatewayRouting?: boolean;
-    /**
-     * Component the embedded widgets should render in place of plain `<a>` tags.
-     *
-     * Pass e.g. Next.js's `Link` to make in-app navigation use the host router.
-     * Cascades like other config: provider prop > nearest ancestor > global store.
-     * When no value is set anywhere, widgets fall back to a plain `<a>` element.
-     */
-    linkComponent?: LinkComponent;
-    /**
-     * Which UI framework the widget UI layer should render with.
-     *
-     * Lets a consuming context bind widgets to either the shadcn/Tailwind or the
-     * Tecton implementation behind the same outward-facing API. The selection is
-     * a presentation concern only — it cascades through the provider tree exactly
-     * like {@link linkComponent} and is read by UI libraries via `useUIFramework`;
-     * it never appears in any widget's feature-library or component props.
-     *
-     * - `'shadcn'` — the shadcn/Tailwind implementation.
-     * - `'tecton'` — the Tecton implementation.
-     * - `null` / `undefined` — not set at this level; inherit from the nearest
-     *   ancestor or global store, falling back to `shadcn` when unset everywhere.
-     *   `shadcn` is the implicit default, so existing consumers need no changes.
-     */
-    uiFramework?: UIFramework | null;
-    /**
-     * Which implementation a widget renders with.
-     *
-     * Lets a consuming context bind widgets to either the Tesouro-native or the
-     * Monite SDK implementation behind the same outward-facing API. It cascades
-     * through the provider tree exactly like {@link linkComponent} and
-     * {@link uiFramework} — provider prop > nearest ancestor > global store — and
-     * is read via `useImplementation`.
-     *
-     * - `'native'` — the Tesouro-native implementation.
-     * - `'monite'` — the Monite SDK implementation.
-     * - `null` / `undefined` — not set at this level; inherit from the nearest
-     *   ancestor or global store, falling back to `native` when unset everywhere.
-     *   `native` is the implicit default, so existing consumers need no changes.
-     */
-    implementation?: Implementation | null;
-}
-/**
- * Props shared by every analytics-owner-capable widget provider.
- *
- * Combines the full settable cascade ({@link WidgetConfigInput}) with the
- * analytics opt-out honored by analytics owners. Both {@link RootWidgetProvider}
- * and {@link WidgetProvider} build their public props on top of this; the latter
- * adds error-boundary props of its own.
- *
- * @see {@link WidgetConfigInput} for per-field cascade and `null` vs omitted semantics
- */
-interface WidgetProviderBaseProps extends WidgetConfigInput {
-    /**
-     * Opt out of all analytics capture and prevent PostHog from loading. Default `true`.
-     *
-     * Honored only by an analytics **owner** — a {@link RootWidgetProvider} or a
-     * standalone {@link WidgetProvider} with no parent provider. When `false`,
-     * owner-bound `track` calls in this subtree become no-ops and the PostHog
-     * installer is never dynamically imported for this owner's environment.
-     * Setting it on a nested {@link WidgetProvider} is ignored in v1 (a one-time
-     * `console.warn` is emitted to make the no-op discoverable).
-     */
-    analytics?: boolean;
-}
-
-/**
- * Copy for the states `WidgetProvider` renders *itself*, in place of the widget:
- * the error-boundary fallback and the disclosures gate. A host overrides any
- * subset through the `providerLabels` prop, which cascades like
- * `disclosuresAcceptance`.
- *
- * Not named `Labels` on the public surface: a widget's own `labels` prop is a
- * different thing, and these two travel together on every widget's props type.
- */
-interface WidgetProviderLabels {
-    /** Default copy for the built-in error boundary fallback. */
-    errorBoundaryFallback: string;
-    /** Heading when init reports disclosures are required and not yet accepted. */
-    disclosuresRequiredTitle: string;
-    /** Heading while a token-only refresh leaves init stale for the live token. */
-    disclosuresRefreshingTitle: string;
-    /** Supporting copy while the accept action is withheld for a stale init. */
-    disclosuresRefreshingDescription: string;
-}
-
-/**
- * Props for {@link WidgetProvider}.
- *
- * All fields are optional. When **all** are omitted the provider is a transparent
- * pass-through: no fetch is issued and all resolved values cascade unchanged from
- * the nearest ancestor.
- */
-interface WidgetProviderProps extends WidgetProviderBaseProps {
-    /**
-     * Fallback rendered when a render-time exception is caught inside this
-     * provider's subtree. Pass either a `ReactNode` (rendered directly) or a
-     * render-prop receiving `{ error, resetErrorBoundary }` from
-     * `react-error-boundary`. Default is a plain `role="alert"` div whose copy
-     * comes from `providerLabels.errorBoundaryFallback`.
-     */
-    errorFallback?: ReactNode | ((props: FallbackProps) => ReactNode);
-    /**
-     * Called once when the boundary catches an error, before the fallback
-     * renders. Use for telemetry / Sentry / partner logging. Exceptions
-     * thrown from `onError` propagate per `react-error-boundary` semantics.
-     */
-    onError?: (error: unknown, info: ErrorInfo) => void;
-    /**
-     * Accept surface shown when the caller owes disclosures — an INVITED
-     * teammate (including `NOT_REQUIRED` orgs, who still need Accept to
-     * activate) or an ACTIVE user who owes a new version. Pass
-     * `<AcceptDisclosuresWidget />`. Cascades like `linkComponent`.
-     * WidgetProvider cannot import the widget itself (cycle).
-     */
-    disclosuresAcceptance?: ReactNode;
-    /**
-     * Overrides for the copy this provider renders in place of the widget: the
-     * built-in error-boundary fallback and the disclosures gate. Any subset;
-     * unlisted keys keep their defaults. Cascades like `linkComponent`.
-     *
-     * Named `providerLabels` rather than `labels` because a widget's own
-     * `labels` prop sits alongside this one on the same props type.
-     */
-    providerLabels?: Partial<WidgetProviderLabels>;
-}
-
-/**
- * The sections the suite can offer, declared in the default menu order
- * (EMBD-4875). Order here is documentation only — the suite renders whatever
- * order its `sections` prop lists.
- */
-declare const WidgetSuiteSectionId: {
-    readonly Dashboard: "dashboard";
-    readonly Accounts: "accounts";
-    readonly Cards: "cards";
-    readonly Transfers: "transfers";
-    readonly BillPay: "bill-pay";
-    readonly Invoicing: "invoicing";
-    readonly Expenses: "expenses";
-    readonly Settings: "settings";
-};
-type WidgetSuiteSectionId = (typeof WidgetSuiteSectionId)[keyof typeof WidgetSuiteSectionId];
-/**
- * The whole surface in the shipped white-label header order
- * (`useDashboardLayout.tsx`): its banking group, then its finops group, then
- * Settings, which white label keeps in the avatar menu rather than the header.
- *
- * Exported as a constant to spread rather than wired up as a default for
- * `sections`, which stays required. A default would make a host's page
- * composition invisible at the call site and would grow silently every time a
- * section is added here. The zero-config wrapper is the intended consumer.
- */
-declare const WIDGET_SUITE_DEFAULT_SECTIONS: readonly ["dashboard", "accounts", "cards", "transfers", "bill-pay", "invoicing", "expenses", "settings"];
-
-/**
- * The section names in the suite menu.
- *
- * Keyed by section id rather than hand-listed, so adding a section to the
- * registry fails the build here until it is named — the menu can never render a
- * section with no label. The type import is erased, so this carries no runtime
- * edge back to the registry.
- *
- * Separate from the shell's own `labels` (its nav landmark name and empty
- * state), which the suite forwards untouched: the same split
- * `BillPayWidgetNative` makes between `labels` and `tabsLabels`.
- */
-type WidgetSuiteSectionLabels = Record<WidgetSuiteSectionId, string>;
-/** Copy for the heading above a section, as opposed to its menu item. */
-interface WidgetSuiteSectionTitleLabels {
-    /**
-     * The bank attribution beneath the heading. `{bankName}` is replaced with the
-     * bank `/init` names, so a translation can put it anywhere in the sentence
-     * rather than after a fixed lead-in. An override that drops the placeholder
-     * shows no name.
-     */
-    bankTagline: string;
-}
-/**
- * Copy the suite puts *inside* a section's panel, rather than in its menu or
- * heading. Each group is shaped as the props of the widget it is handed to, so
- * the merged object below can be passed down by reference.
- */
-interface WidgetSuiteContentLabels {
-    /**
-     * `CardsList` renders its own `labels.title` as the list heading, defaulting
-     * to "Cards". Two instances stack in the Cards section, so each is retitled by
-     * program.
-     */
-    creditCards: {
-        title: string;
-    };
-    debitCards: {
-        title: string;
-    };
-    /** Expenses is only a placeholder until the suite wires a read/self surface. */
-    expensePlaceholders: {
-        expensesUnavailable: string;
-    };
-}
-/**
- * Copy for the states where the suite cannot prove it may show normal content.
- *
- * Both are places the gate cannot proceed, and neither is reachable by a correct
- * integration against a healthy API.
- */
-interface WidgetSuiteDisclosureLabels {
-    /**
-     * The first init fetch failed before the disclosure flags were known. The suite
-     * must fail closed here, because an unknown requirement is not permission to
-     * show ungated sections.
-     */
-    initFailedState: {
-        title: string;
-        body: string;
-        retryButton: string;
-    };
-    /**
-     * The acceptance was recorded and the init refresh that clears the gate
-     * failed, so only our view of it is stale.
-     *
-     * The failure is the title and the reassurance is the body, in that order on
-     * purpose: `ErrorState` puts a destructive-toned glyph above the title, so
-     * leading with "accepted" reads at a glance as the acceptance having failed —
-     * the one thing this state must not imply, since a user who believes that will
-     * try to accept again.
-     */
-    refreshFailedState: {
-        title: string;
-        body: string;
-        retryButton: string;
-    };
-}
-/** Named as the shipped white-label header names them. */
-declare const WIDGET_SUITE_SECTION_LABELS_EN: WidgetSuiteSectionLabels;
-declare const WIDGET_SUITE_SECTION_TITLE_LABELS_EN: WidgetSuiteSectionTitleLabels;
-declare const WIDGET_SUITE_CONTENT_LABELS_EN: WidgetSuiteContentLabels;
-declare const WIDGET_SUITE_DISCLOSURE_LABELS_EN: WidgetSuiteDisclosureLabels;
-
-interface CardsWidgetPaginationInput {
-    paginationToken?: string;
-    pageSize?: number;
-}
-
-/**
- * The sections this widget renders itself. These ids are the public vocabulary
- * a host uses to deep-link into a section, so they are part of the package's
- * API surface — renaming one is a breaking change.
- */
-declare const SettingsSection: {
-    readonly Profile: "profile";
-    readonly Team: "team";
-    readonly Invoice: "invoice";
-    readonly Expense: "expense";
-    readonly BillPay: "bill-pay";
-    readonly Accounting: "accounting";
-    readonly Tags: "tags";
-    readonly Help: "help";
-};
-type SettingsSection = (typeof SettingsSection)[keyof typeof SettingsSection];
-/**
- * A selectable section id: one of the built-ins, or the id of a host-supplied
- * {@link SettingsWidgetAdditionalSection}. The `string & {}` arm keeps the
- * built-in literals visible to editor autocomplete while still accepting a
- * host's own id.
- */
-type SettingsWidgetSectionId = SettingsSection | (string & {});
-
-interface WidgetSuiteAccountsSelection {
-    /** The account whose details are open. `null` is the list. */
-    accountId?: string | null;
-}
-interface WidgetSuiteCardsSelection {
-    /** The card whose details panel is open. `null` closes it. */
-    cardId?: string | null;
-    /**
-     * The list's cursor and page size. Forwarded to the widget's own `pagination`
-     * and `defaultPagination`, so the suite holds no cursor of its own: leaving
-     * the section and coming back restarts the walk unless a host drives it.
-     */
-    pagination?: CardsWidgetPaginationInput;
-}
-interface WidgetSuiteSettingsSelection {
-    /**
-     * The settings section on screen. The suite holds this one, so it survives
-     * leaving the section — but hands it down as the widget's
-     * `defaultSelectedSection`, never its controlled `selectedSection`. The widget
-     * substitutes another section when this one is not available to the user and
-     * reports nothing when it does, so a controlled value could disagree with the
-     * screen with no way to recover; an initial one just loses a deep link the
-     * user could never have reached.
-     */
-    section?: SettingsWidgetSectionId;
-}
-/**
- * Where the suite is pointed, grouped by section.
- *
- * One object rather than a prop per key: it is the value a host mirrors into its
- * URL, and it groups the same way `contentLabels` does. Every key resolves
- * independently, so `selection={{ section: 'accounts' }}` drives the menu and
- * leaves the account to `defaultSelection`.
- *
- * Credit and debit cards get separate groups because the Cards section mounts
- * two `CardsWidget` instances against two endpoints, so one card id cannot
- * address both. There is no `invoicing` group: that section renders the Monite
- * `<Receivables />`, whose tab is internal state (EMBD-2171 replaces it,
- * EMBD-4979 makes the native tab controllable).
- */
-interface WidgetSuiteSelection {
-    section?: WidgetSuiteSectionId;
-    accounts?: WidgetSuiteAccountsSelection;
-    creditCards?: WidgetSuiteCardsSelection;
-    debitCards?: WidgetSuiteCardsSelection;
-    settings?: WidgetSuiteSettingsSelection;
-}
-/**
- * Where the suite can *open*, which is narrower than what it can be driven to
- * whenever a key's widget takes no initial value. Every key has both halves
- * today, so nothing is omitted; this is where the next controlled-only key goes.
- */
-type WidgetSuiteDefaultSelection = WidgetSuiteSelection;
-interface WidgetSuiteCardsSelectionSnapshot {
-    cardId: string | null;
-    pagination: CardsWidgetPaginationInput | undefined;
-}
-/**
- * The selection as the suite reports it: every key carries a value, so a host
- * reading one needs no optional chaining. Assignable to
- * {@link WidgetSuiteSelection}, so a host can hand a snapshot straight back.
- */
-interface WidgetSuiteSelectionSnapshot {
-    section: WidgetSuiteSectionId | undefined;
-    accounts: {
-        accountId: string | null;
-    };
-    creditCards: WidgetSuiteCardsSelectionSnapshot;
-    debitCards: WidgetSuiteCardsSelectionSnapshot;
-    settings: {
-        section: SettingsWidgetSectionId | undefined;
-    };
-}
-
-interface WidgetSuiteProps extends WidgetProviderProps {
-    /**
-     * Which sections the suite offers, in menu order.
-     *
-     * **Required, with no default, and staying that way.** Defaulting it to the
-     * whole registry would make a host's page composition invisible at the call
-     * site, and would grow silently every time a section is added. The wrapper
-     * that answers this once for a named integrator is a separate package with
-     * its own repo, so this prop is not waiting to acquire a default here.
-     *
-     * A section listed here is still hidden when the token does not earn it, so
-     * this is the host's ceiling rather than a promise of what renders.
-     */
-    sections: readonly WidgetSuiteSectionId[];
-    /**
-     * Where the suite is pointed, for a host that owns navigation — a URL, a
-     * router, its own state. Every key resolves on its own, so driving one leaves
-     * the rest to the suite.
-     *
-     * A key here puts the widget behind it in controlled mode for the lifetime of
-     * the mount, so supply it with `onSelectionChange` or the surface will not
-     * move when the user clicks.
-     */
-    selection?: WidgetSuiteSelection;
-    /**
-     * Where the suite opens, for a host that wants a deep link but not ownership.
-     * Read once per mount, and ignored per key when `selection` names that key.
-     *
-     * Carries every key `selection` does — see {@link WidgetSuiteDefaultSelection}.
-     */
-    defaultSelection?: WidgetSuiteDefaultSelection;
-    /**
-     * The whole selection after a person moved the suite: a menu click, a row, a
-     * card, a settings tab, a page of a card list. Every key carries a value, and
-     * the object can be handed straight back as `selection`.
-     *
-     * Never fired for the entitlement fallback, and never fired on mount, so a
-     * host mirroring this into its URL cannot overwrite the deep link it was just
-     * handed. A move that touches two keys reports once.
-     */
-    onSelectionChange?: (selection: WidgetSuiteSelectionSnapshot) => void;
-    /** Overrides for the shell's own copy — the nav landmark name, empty state. */
-    labels?: PartialDeep<WidgetSuiteShellLabels>;
-    /** Overrides for the section names in the menu. */
-    sectionLabels?: Partial<WidgetSuiteSectionLabels>;
-    /**
-     * Overrides for the section heading's own copy — today the bank tagline, whose
-     * `{bankName}` placeholder is filled with the bank `/init` names.
-     */
-    sectionTitleLabels?: Partial<WidgetSuiteSectionTitleLabels>;
-    /**
-     * Overrides for the copy inside a section's panel: the two card-list titles
-     * and the Expenses placeholder.
-     */
-    contentLabels?: PartialDeep<WidgetSuiteContentLabels>;
-    /**
-     * Overrides for the copy the disclosure gate owns: its init-failure and
-     * refresh-failure recovery. The acceptance surface carries its own labels.
-     */
-    disclosureLabels?: PartialDeep<WidgetSuiteDisclosureLabels>;
-    /**
-     * Shows a heading above each section, named as its menu item is.
-     *
-     * Defaults to `true`: the suite owns its page, and a page with a menu but no
-     * heading reads as a fragment of someone else's. Set `false` when the host
-     * already renders a heading of its own above the suite.
-     *
-     * Every section gets one: no widget heads itself any more (embedded ADR
-     * 0010), so the suite is the only thing that can name them.
-     */
-    showSectionTitle?: boolean;
-}
-/**
- * A suite of widgets bound together by navigation.
- *
- * Unlike a widget — a content area an integrator drops onto a page they own — a
- * suite owns the page it is placed on, exists once per page, and decides which
- * widgets appear on it.
- *
- * One `/init` serves the whole surface: this provider owns the fetch, and every
- * composed widget is handed no auth props, so its own provider runs in
- * pass-through mode. See `sections.tsx` for the two composition rules that
- * arrangement depends on.
- *
- * That one response also decides which state the suite is in before the shell
- * renders: placeholders while init has not settled, a closed retry state when
- * init fails before answering the disclosure flags, the acceptance surface
- * alone when the session owes the bank's disclosures, or the nav over its
- * sections. States rather than an overlay over a mounted shell — see
- * `WidgetSuiteSurface` for why each boundary sits where it does.
- *
- * Navigation is one `selection` object a host can drive key by key, published to
- * the sections through `WidgetSuiteProvider`. Only the open panel is mounted, so
- * a key the suite holds survives leaving a section and coming back and a key it
- * does not hold is lost: today Accounts remembers its open account, Cards its
- * open card and Settings its section, while Bill Pay forgets its tab and each
- * card list its cursor. That split is the widgets' current shape rather than a
- * decision — see `WidgetSuiteSelection` for the ticket behind each gap.
- */
-declare function WidgetSuite({ baseUrl, widgetToken, organizationId, configClient, gatewayRouting, linkComponent, implementation, uiFramework, errorFallback, onError, analytics, disclosuresAcceptance, providerLabels, ...innerProps }: WidgetSuiteProps): React.JSX.Element;
-
-export { WIDGET_SUITE_CONTENT_LABELS_EN, WIDGET_SUITE_DEFAULT_SECTIONS, WIDGET_SUITE_DISCLOSURE_LABELS_EN, WIDGET_SUITE_SECTION_LABELS_EN, WIDGET_SUITE_SECTION_TITLE_LABELS_EN, WIDGET_SUITE_SHELL_LABELS_EN, WidgetSuite, WidgetSuiteSectionId };
-export type { PartialDeep, WidgetSuiteAccountsSelection, WidgetSuiteCardsSelection, WidgetSuiteCardsSelectionSnapshot, WidgetSuiteContentLabels, WidgetSuiteDefaultSelection, WidgetSuiteDisclosureLabels, WidgetSuiteProps, WidgetSuiteSectionLabels, WidgetSuiteSectionTitleLabels, WidgetSuiteSelection, WidgetSuiteSelectionSnapshot, WidgetSuiteSettingsSelection, WidgetSuiteShellLabels };