@tesouro/embedded-components-react 0.2.1

package/README.md

@@ -0,0 +1,528 @@
+# tesouro-embedded-components-react
+
+This package is the public npm surface for Tesouro embedded React widgets.
+
+## Consuming the package
+
+`@tesouro/embedded-components-react` is an ESM package for bundler-based React
+apps (Vite, webpack, esbuild, Next.js). `react` and `react-dom` (v19) are peer
+dependencies.
+
+```bash
+npm install @tesouro/embedded-components-react
+# or: yarn add @tesouro/embedded-components-react
+```
+
+**Import the stylesheet once** at your app's entry point — widgets render
+unstyled without it:
+
+```ts
+import '@tesouro/embedded-components-react/styles.css';
+```
+
+Then render a widget inside a provider that establishes its authenticated scope:
+
+```tsx
+import '@tesouro/embedded-components-react/styles.css';
+import {
+  RootWidgetProvider,
+  BankAccountsWidget,
+} from '@tesouro/embedded-components-react';
+
+export function App() {
+  return (
+    <RootWidgetProvider
+      baseUrl="https://api.tesouro.com"
+      widgetToken="wt_live_…"
+      organizationId="org_…"
+    >
+      <BankAccountsWidget />
+    </RootWidgetProvider>
+  );
+}
+```
+
+Every provider and widget prop is fully typed in the shipped declarations, so
+your editor documents the full auth/config model inline — per-widget
+`WidgetProvider`, config inheritance, token refresh, and the built-in error
+boundary.
+
+### Entry points
+
+| Import path                                     | What you get                                                               |
+| ----------------------------------------------- | -------------------------------------------------------------------------- |
+| `@tesouro/embedded-components-react`            | All widgets plus `RootWidgetProvider` / `WidgetProvider`.                  |
+| `@tesouro/embedded-components-react/styles.css` | The widget stylesheet — see [About the stylesheet](#about-the-stylesheet). |
+| `@tesouro/embedded-components-react/core`       | Framework-agnostic token utilities (`createWidgetTokenManager`).           |
+| `@tesouro/embedded-components-react/monite-sdk` | Monite SDK surface for Monite-backed widgets.                              |
+
+### About the stylesheet
+
+The stylesheet is host-safe by design. It ships **no
+global CSS reset**: Tailwind's Preflight is omitted and instead re-expressed
+scoped under the `.tesouro-embedded` wrapper that every widget renders, and all
+utilities are `ttw`-prefixed — so loading it won't restyle your host page or
+collide with your own Tailwind. Design tokens (`--ttw-*`) are declared on
+`:root`/`.dark`; dark mode follows an ancestor `.dark` class, and the widget
+font can be white-labeled via `--ttw-font-family`.
+
+<!-- BEGIN GENERATED REFERENCE -->
+
+## Providers
+
+Every widget renders inside a provider that establishes its authenticated
+scope. Place a **`RootWidgetProvider`** once near the root of your app; use a
+**`WidgetProvider`** to override config (token, base URL, UI framework) for a
+subtree, or as a standalone root when you mount a single widget on its own. For
+automatic token rotation, use **`WidgetTokenRefreshProvider`** (or the bundled
+**`RefreshingRootWidgetProvider`**). Providers wrap their subtree in a built-in
+error boundary and expose the resolved config through the `useWidgetConfig`,
+`useWidgetLoading`, `useWidgetError`, and `useRefetchWidget` hooks; non-React
+hosts can seed config through the global store (`setGlobalWidgetConfig`).
+
+### `RootWidgetProvider`
+
+App-level provider. Resolves `baseUrl` / `widgetToken` / `organizationId` (falling back to the global store), calls the widget init endpoint once a base URL and token both resolve, and shares the response with every descendant.
+
+#### Props
+
+| Prop             | Type                                         | Description                                                                                                                                                                                                                        |
+| ---------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`        | `string`                                     | Base URL of the Tesouro embedded API (e.g. `"https://api.tesouro.com"`). Falls back to `global.baseUrl` when omitted.                                                                                                              |
+| `widgetToken`    | `string \| null`                             | Bearer token for widget auth. Falls back to `global.widgetToken` when omitted. Pass `null` to suppress auth.                                                                                                                       |
+| `organizationId` | `string \| null`                             | Org ID forwarded to data-access hooks. Falls back to `global.organizationId` when omitted; if still unset, defaults to `initResponse.organizationId` once the fetch resolves. Pass `null` to clear org scoping (never falls back). |
+| `configClient`   | `(client: EmbeddedClient) => EmbeddedClient` | Optional post-creation hook for the HTTP client. Called after the built-in auth interceptor. Falls back to `global.configClient`.                                                                                                  |
+| `linkComponent`  | `LinkComponent`                              | Host link component widgets use to render navigational links. Falls back to `global.linkComponent`.                                                                                                                                |
+| `uiFramework`    | `'shadcn' \| 'tecton' \| null`               | UI framework the widget UI layer renders with for this tree. Falls back to `global.uiFramework`, then to `'shadcn'`. See UI framework selection.                                         |
+| `implementation` | `'native' \| 'monite' \| null`               | Which implementation the widgets render with for this tree. Falls back to `global.implementation`, then to `'native'`. See Implementation selection.                                   |
+| `analytics`      | `boolean`                                    | Enables anonymous analytics for this provider tree (default `true`). `RootWidgetProvider` is the analytics owner; set `false` to disable capture and skip loading PostHog.                                                         |
+| `children`       | `ReactNode`                                  | The React subtree that consumes the widget context.                                                                                                                                                                                |
+
+### `WidgetProvider`
+
+Mid-tree or standalone provider. With no props it is a transparent pass-through that inherits everything from its parent; set `baseUrl` or `widgetToken` and it fetches its own init response for that subtree; with no provider ancestor it behaves as a standalone root — the right pattern for a single embedded widget.
+
+#### Props
+
+| Prop             | Type                                               | Description                                                                                                                                                                                                                                                                                                                 |
+| ---------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`        | `string`                                           | Override the base URL for this subtree. Recreates the HTTP client. When omitted, inherits from the nearest ancestor.                                                                                                                                                                                                        |
+| `widgetToken`    | `string \| null`                                   | Override the widget token for this subtree. Triggers a new `/api/widget-gateway/init` fetch. Pass `null` to suppress auth at this level. When omitted, inherits from parent.                                                                                                                                                |
+| `organizationId` | `string \| null`                                   | Override the org ID for this subtree. Does **not** trigger a re-fetch on its own. When omitted, inherits from parent; if unset through the whole cascade, defaults to this level's `initResponse.organizationId` (an ancestor's explicit org wins over it). Pass `null` to explicitly clear org scoping (never falls back). |
+| `configClient`   | `(client: EmbeddedClient) => EmbeddedClient`       | Optional post-creation hook for the scoped HTTP client. Only called when this provider creates its own client (i.e. not in pass-through mode). When omitted, inherits from parent.                                                                                                                                          |
+| `linkComponent`  | `LinkComponent`                                    | Override the host link component for this subtree. When omitted, inherits from parent.                                                                                                                                                                                                                                      |
+| `uiFramework`    | `'shadcn' \| 'tecton' \| null`                     | Override the UI framework for this subtree. When omitted (or `null`), inherits the nearest ancestor's selection, defaulting to `'shadcn'`. See UI framework selection.                                                                                                            |
+| `implementation` | `'native' \| 'monite' \| null`                     | Override the implementation for this subtree. When omitted (or `null`), inherits the nearest ancestor's selection, defaulting to `'native'`. See Implementation selection.                                                                                                      |
+| `errorFallback`  | `ReactNode \| (props: FallbackProps) => ReactNode` | Custom fallback for the built-in error boundary in this subtree. A `ReactNode` is rendered as-is; a function receives `{ error, resetErrorBoundary }`. Defaults to a generic `role="alert"` message.                                                                                                                        |
+| `onError`        | `(error: unknown, info: ErrorInfo) => void`        | Optional telemetry hook. Runs once per caught error before the fallback renders.                                                                                                                                                                                                                                            |
+| `analytics`      | `boolean`                                          | Enables anonymous analytics (default `true`). Honored only when this is a standalone analytics owner (no `RootWidgetProvider` ancestor); on a nested provider it is a no-op.                                                                                                                                                |
+| `children`       | `ReactNode`                                        | The React subtree that consumes the overridden context.                                                                                                                                                                                                                                                                     |
+
+### `WidgetTokenRefreshProvider`
+
+Owns the token-refresh lifecycle: calls your `fetcher`, proactively refreshes before expiry, and exposes the live token via `useWidgetToken()` to feed into a `RootWidgetProvider`.
+
+#### Props
+
+| Prop          | Type                                                   | Default | Description                                                                                                                                                                                                                                                                                                                                |
+| ------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fetcher`     | `() => Promise<{ widgetToken: string; exp?: number }>` | —       | Required. Called on mount and whenever a refresh is scheduled or requested. `exp` is unix seconds; if omitted, no proactive refresh is scheduled.                                                                                                                                                                                          |
+| `leadSeconds` | `number`                                               | `60`    | Schedule the next refresh `leadSeconds` before `exp`. Lower this if your tokens have a very short lifetime.                                                                                                                                                                                                                                |
+| `onToken`     | `(widgetToken: string) => void`                        | —       | Optional callback fired once per **distinct** token produced by the manager. Useful for telemetry, persistence, or — for non-React hosts (web components, cross-React-root setups) — mirroring the token into the global store via `updateGlobalWidgetConfig`. React consumers should drive `widgetToken` from `useWidgetToken()` instead. |
+| `children`    | `ReactNode`                                            | —       | The React subtree that consumes the manager via `useWidgetToken()`.                                                                                                                                                                                                                                                                        |
+
+### `RefreshingRootWidgetProvider`
+
+Bundles `WidgetTokenRefreshProvider` + `RootWidgetProvider` and wires the live token through automatically — the recommended one-provider setup. Takes the `RootWidgetProvider` props (minus `widgetToken`) plus the refresh provider’s.
+
+#### Props
+
+| Prop             | Source                       | Notes                                                                                                                                            |
+| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `baseUrl`        | `RootWidgetProvider`         | Falls back to the global store when omitted.                                                                                                     |
+| `organizationId` | `RootWidgetProvider`         | Pass `null` to clear the org scope; falls back to the global store when omitted.                                                                 |
+| `configClient`   | `RootWidgetProvider`         | Optional post-creation hook for the scoped HTTP client.                                                                                          |
+| `linkComponent`  | `RootWidgetProvider`         | Component used in place of plain `<a>` tags inside widgets.                                                                                      |
+| `uiFramework`    | `RootWidgetProvider`         | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade.                                                                          |
+| `implementation` | `RootWidgetProvider`         | `'native'` (default) or `'monite'`; inherits down the provider cascade.                                                                          |
+| `analytics`      | `RootWidgetProvider`         | Enables anonymous analytics (default `true`); set `false` to disable capture.                                                                    |
+| `fetcher`        | `WidgetTokenRefreshProvider` | Required.                                                                                                                                        |
+| `leadSeconds`    | `WidgetTokenRefreshProvider` | Default `60`.                                                                                                                                    |
+| `onToken`        | `WidgetTokenRefreshProvider` | Fires once per distinct token; useful for telemetry, persistence, or — for non-React hosts — mirroring the token via `updateGlobalWidgetConfig`. |
+| `children`       | —                            | Render inside both providers' contexts (so `useWidgetToken()` and `useWidgetConfig()` both work in descendants).                                 |
+
+## Components
+
+Every widget below also accepts the shared auth/scope props from
+`WidgetProviderProps` (see [Providers](#providers)), so it can inherit config
+from a parent provider or take it directly. Only each widget’s own props are
+listed here.
+
+### BankAccountsWidget
+
+A self-contained banking widget for listing Tesouro bank accounts, creating an account, and viewing account details.
+
+#### Props
+
+| Prop                        | Type                                       | Default        | Description                                                                     |
+| --------------------------- | ------------------------------------------ | -------------- | ------------------------------------------------------------------------------- |
+| `labels`                    | `Partial<BankAccountsWidgetLabels>`        | English labels | Overrides list/create-account UI copy.                                          |
+| `accountDetailsLabels`      | `Partial<AccountDetailsWidgetLabels>`      | English labels | Overrides the internal account details UI copy.                                 |
+| `featureLabels`             | `Partial<BankAccountsWidgetFeatureLabels>` | English labels | Overrides feature-level copy (account fallback name, balance/total formatting). |
+| `selectedAccountId`         | `string`                                   | `undefined`    | Controls the open details account.                                              |
+| `defaultSelectedAccountId`  | `string`                                   | `undefined`    | Initial uncontrolled details account.                                           |
+| `onSelectedAccountIdChange` | `(id: string \| undefined) => void`        | `undefined`    | Called when the user opens details or goes back.                                |
+
+### BillPayWidget
+
+A Monite-backed bill pay widget wrapped in Tesouro widget auth and theming.
+
+#### Props
+
+| Prop                 | Type                                 | Default      | Description                                     |
+| -------------------- | ------------------------------------ | ------------ | ----------------------------------------------- |
+| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Pass-through | Customizes Monite's page title action region.   |
+| `finopsThemeColors`  | `FinopsThemeColors`                  | `undefined`  | Optional Monite theme color overrides.          |
+
+### CounterpartsWidget
+
+A self-contained widget for managing an organization's customers or vendors with searchable lists, money columns, details, editing, and deletion.
+
+#### Props
+
+| Prop              | Type                     | Default             | Description                                                                                  |
+| ----------------- | ------------------------ | ------------------- | -------------------------------------------------------------------------------------------- |
+| `counterpartType` | `'customer' \| 'vendor'` | —                   | Required. Selects receivables/customer copy and queries or payables/vendor copy and queries. |
+| `pageSizeOptions` | `number[]`               | `[10, 25, 50, 100]` | Page-size choices shown by the table.                                                        |
+
+| Prop                | Type                                     | Description                                                                                                      |
+| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `screenLabels`      | `Partial<CounterpartsScreenLabels>`      | Table title, columns, search/filter, empty, error, access-restricted, and row-action copy.                       |
+| `formLabels`        | `Partial<CounterpartFormSheetLabels>`    | Create/edit counterpart form copy.                                                                               |
+| `detailsLabels`     | `Partial<CounterpartDetailsSheetLabels>` | Details sheet sections, summary labels, subtitle/entity/reminder/payment-method labels, row labels, and actions. |
+| `bankAccountLabels` | `Partial<BankAccountFormSheetLabels>`    | Vendor payment-method form copy.                                                                                 |
+| `addressLabels`     | `Partial<AddressFormSheetLabels>`        | Address form copy.                                                                                               |
+| `deleteLabels`      | `Partial<ConfirmDeleteDialogLabels>`     | Delete-dialog copy.                                                                                              |
+| `messageLabels`     | `Partial<CounterpartMessageLabels>`      | Validation, API failure, and delete-prompt messages produced by feature logic.                                   |
+
+### ExpenseManagementWidget
+
+A composite expense widget for receipt upload, matching slots, approval policies, and transaction requirements.
+
+#### Props
+
+| Prop                  | Type                       | Default                  | Description                                        |
+| --------------------- | -------------------------- | ------------------------ | -------------------------------------------------- |
+| `labels`              | `Partial<Labels>`          | English labels           | Overrides tab and heading copy.                    |
+| `receiptUpload`       | `UploadReceiptWidgetProps` | `undefined`              | Enables the default receipt upload control.        |
+| `receiptsContent`     | `ReactNode`                | Upload widget or empty   | Replaces the receipts tab content.                 |
+| `matchingContent`     | `ReactNode`                | Empty                    | Supplies host-owned matching UI without URL state. |
+| `policiesContent`     | `ReactNode`                | Approval policies widget | Replaces the policies tab content.                 |
+| `requirementsContent` | `ReactNode`                | Requirements widget      | Replaces the requirements tab content.             |
+
+### ExpenseApprovalPoliciesWidget
+
+Lets an organization view and manage its expense approval rules — each rule maps an amount range to an outcome (auto-approve or require approval) and, where approval is required, the approving roles. It is backed by the embedded REST API.
+
+#### Props
+
+_No props beyond the shared [auth/scope props](#providers)._
+
+### ExpenseRequirementsWidget
+
+An editable settings surface for an organization's transaction validation rules. It lets an admin toggle whether a receipt and a description/memo are required on expenses, set per-field amount thresholds, and save the changes back to the embedded REST API.
+
+#### Props
+
+_No props beyond the shared [auth/scope props](#providers)._
+
+### BalancesWidget
+
+A self-contained widget that loads embedded bank accounts for the organization, shows up to a configurable number of account balance rows, optionally aggregates a total when multiple accounts exist, and can link out to a host “view all accounts” destination.
+
+#### Props
+
+| Prop                     | Type                            | Default | Description                                                                 |
+| ------------------------ | ------------------------------- | ------- | --------------------------------------------------------------------------- |
+| `maxAccounts`            | `number`                        | `5`     | Maximum rows rendered in-card; additional accounts use the view-all CTA.    |
+| `labels`                 | `Partial<BalancesWidgetLabels>` | —       | Override shell copy (title, errors, view-all label, total balance tooltip). |
+| `onBalanceRowClick`      | `(accountId: string) => void`   | —       | When set, balance rows are clickable and receive the account id.            |
+| `onViewAllAccountsClick` | `() => void`                    | —       | When set and more than `maxAccounts` exist, shows **View all accounts**.    |
+
+### InsightsWidget
+
+A self-contained widget that derives onboarding-style insights from embedded and external bank account data, persists dismissed insight ids via the embed **user-data** API, and exposes optional host callbacks for routing and linking external accounts.
+
+#### Props
+
+| Prop                         | Type                             | Default | Description                                                                                         |
+| ---------------------------- | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `routingEnabled`             | `boolean`                        | `false` | Controlled switch state for the routing onboarding insight.                                         |
+| `onRoutingToggleChange`      | `(enabled: boolean) => void`     | —       | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. |
+| `onLinkExternalAccountClick` | `() => void`                     | —       | When set, the connect-external-account insight shows a **Link account** CTA.                        |
+| `labels`                     | `Partial<InsightsWidgetLabels>`  | —       | Shell copy (tabs, empty, error).                                                                    |
+| `singleInsightLabels`        | `Partial<SingleInsightLabels>`   | —       | Per-row UI strings (e.g. dismiss aria label).                                                       |
+| `featureLabels`              | `Partial<InsightsFeatureLabels>` | —       | Generated insight body copy and action labels.                                                      |
+
+### GLCodeTableWidget
+
+A self-contained widget that fetches and displays a paginated, sortable table of General Ledger (GL) codes. It handles its own API communication, loading and error states, server-side sorting, and cursor-based pagination — the host application only needs to supply auth credentials and optional UI callbacks.
+
+#### Props
+
+| Prop               | Type                         | Description                                                                                                                  |
+| ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `labels`           | `Partial<GlCodeTableLabels>` | Override any subset of UI strings (column headers, action labels, empty/error state copy). Merged with the English defaults. |
+| `onEdit`           | `(row: GlCode) => void`      | When provided, adds an **Edit** action to the row dropdown menu.                                                             |
+| `onDelete`         | `(row: GlCode) => void`      | When provided, adds a **Delete** action to the row dropdown menu.                                                            |
+| `onAddIntegration` | `() => void`                 | Renders an **Add integration** button in the empty state.                                                                    |
+| `onImportCsv`      | `() => void`                 | Renders an **Import CSV** button in the empty state.                                                                         |
+| `learnMoreHref`    | `string`                     | Renders a **Learn more** link in the empty state.                                                                            |
+
+### HelpWidget
+
+A self-contained Help widget: a static FAQ accordion with an optional "Contact Us" card. It renders no network requests — all content comes from props, defaulting to the built-in English FAQ so the widget works with no configuration.
+
+#### Props
+
+| Prop         | Type                        | Default                 | Description                                                                         |
+| ------------ | --------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
+| `faq`        | `HelpFaqSection[]`          | `HELP_FAQ_EN`           | FAQ content to render, grouped into titled sections.                                |
+| `bankName`   | `string`                    | `undefined`             | Bank/provider name interpolated into the contact line.                              |
+| `contactUrl` | `string`                    | `undefined`             | When set, renders a "Contact Us" card linking here. Omit to hide it.                |
+| `labels`     | `Partial<HelpWidgetLabels>` | `HELP_WIDGET_LABELS_EN` | Display-string overrides, merged over `HELP_WIDGET_LABELS_EN` (FAQ + contact copy). |
+
+### InvoicingWidget
+
+A self-contained invoicing widget that renders the Monite SDK receivables experience (invoices, quotes, and credit notes) against your widget auth — the host only supplies credentials and optional theming.
+
+#### Props
+
+| Prop                 | Type                                 | Default     | Description                                                                                                                                                         |
+| -------------------- | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `finopsThemeColors`  | `FinopsThemeColors`                  | `undefined` | Overrides the Monite theme's primary colors. Omit to use Monite defaults.                                                                                           |
+| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Passthrough | Wraps the page header region. The default returns its children unchanged; supply a wrapper to add a title, branding, or toolbar around the widget's action buttons. |
+
+### LinkedAccountsWidget
+
+A self-contained widget that lists and manages external bank accounts, including connect, edit, micro-deposit initiation, micro-deposit validation, and unlink actions.
+
+#### Props
+
+| Prop            | Type                                         | Default        | Description                                                                                                                                                                                 |
+| --------------- | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels`        | `Partial<LinkedAccountsWidgetLabels>`        | English labels | Overrides visible UI copy such as button, dialog, empty-state, loading, and error labels. Unspecified labels fall back to defaults.                                                         |
+| `featureLabels` | `Partial<LinkedAccountsWidgetFeatureLabels>` | English labels | Overrides strings produced by the feature layer, such as row title fallback, account-number subtitle fragments, and the success toast messages shown after editing or unlinking an account. |
+
+### OnboardingWidget
+
+A self-contained widget that walks an applicant through the embedded bank-account onboarding flow: business details, personal details, optional additional owners, and a result screen. It owns all REST mutations (`createApplication`, `updateApplication`, `verifyBusiness`, `submitApplication`), step navigation, validation, and KYC dispatch — the host application only supplies auth credentials and two callbacks.
+
+#### Props
+
+| Prop                                        | Type                      | Required | Description                                                                                                                                                                                              |
+| ------------------------------------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onEmbeddedOnboardingCompletedSuccessfully` | `() => void`              | Yes      | Called when the application is submitted and approved.                                                                                                                                                   |
+| `onNavigateToDashboard`                     | `() => void`              | Yes      | Called when the user clicks the dashboard CTA on the result screen.                                                                                                                                      |
+| `open`                                      | `boolean`                 | No       | Controlled open state for the modal. When provided the host owns open/close and must update it via `onOpenChange`. Omit for uncontrolled mode.                                                           |
+| `defaultOpen`                               | `boolean`                 | No       | Initial open state when uncontrolled. Defaults to `true` so the modal renders on mount. Ignored when `open` is set.                                                                                      |
+| `onOpenChange`                              | `(open: boolean) => void` | No       | Notified whenever the modal opens or closes — fires on overlay click, escape key, the close button, and any controlled state update. Used both as the change handler in controlled mode and a side hook. |
+| `labels`                                    | `OnboardingWidgetLabels`  | No       | Per-step label overrides — see Labels section. Accepts a `modalTitle` override for the modal's accessible title (default: `Bank account onboarding`).                                                    |
+| `bankLogoSrc`                               | `string`                  | No       | URL for the bank logo rendered on the result screen; falls back to bank name text.                                                                                                                       |
+| `termsHref`                                 | `string`                  | No       | URL for the Terms of Use document linked in step 1.                                                                                                                                                      |
+| `privacyHref`                               | `string`                  | No       | URL for the Privacy Policy document linked in step 1.                                                                                                                                                    |
+| `electronicCommunicationHref`               | `string`                  | No       | URL for the Electronic Communication document linked in step 1.                                                                                                                                          |
+| `patriotActHref`                            | `string`                  | No       | URL for the Patriot Act document linked in step 1.                                                                                                                                                       |
+
+### ProductsWidget
+
+A self-contained widget for managing an organization's products and services: it lists them in a filterable, sortable, cursor-paginated table and handles creating, editing, viewing, and deleting them — including full measure-unit management. The host only supplies auth credentials and optional label overrides.
+
+#### Props
+
+| Prop                      | Type                                     | Description                                          |
+| ------------------------- | ---------------------------------------- | ---------------------------------------------------- |
+| `pageSizeOptions`         | `number[]`                               | Rows-per-page choices (default `[10, 25, 50, 100]`). |
+| `screenLabels`            | `Partial<ProductsScreenLabels>`          | Table/header/filter/empty/error copy.                |
+| `formLabels`              | `Partial<ProductFormSheetLabels>`        | Create/edit form copy.                               |
+| `detailsLabels`           | `Partial<ProductDetailsSheetLabels>`     | Details sheet copy.                                  |
+| `deleteLabels`            | `Partial<ProductDeleteDialogLabels>`     | Product delete confirmation copy.                    |
+| `measureUnitsLabels`      | `Partial<MeasureUnitsManagerLabels>`     | Measure-units manager copy.                          |
+| `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | Measure-unit delete confirmation copy.               |
+| `messageLabels`           | `Partial<ProductMessageLabels>`          | Validation / error messages produced by the widget.  |
+
+### ProfileWidget
+
+A self-contained, read-only profile card for the current entity user. It shows a personal tab (name, email, phone) and a business tab (legal name, company address, company phone, company email) backed by the embedded REST API.
+
+#### Props
+
+| Prop            | Type                     | Description                                                            |
+| --------------- | ------------------------ | ---------------------------------------------------------------------- |
+| `labels`        | `Partial<Labels>`        | Overrides the card's own copy (loading announcement).                  |
+| `featureLabels` | `Partial<FeatureLabels>` | Overrides tab labels, field labels, banner alt text, and the subtitle. |
+
+### ReceivablesWidget
+
+A self-contained native widget for listing, creating, editing, and acting on customer receivables.
+
+#### Props
+
+| Prop                      | Type                                                 | Default                                  | Description                                                                                                     |
+| ------------------------- | ---------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `defaultTab`              | `ReceivablesWidgetTab`                               | `'invoices'`                             | Initial tab when that tab is enabled. If it is omitted or disabled, the widget starts on the first enabled tab. |
+| `enabledTabs`             | `ReceivablesWidgetTab[]`                             | `['invoices', 'quotes', 'credit_notes']` | Tabs visible to the user. Duplicate or unknown values are ignored.                                              |
+| `pageSizeOptions`         | `number[]`                                           | `[10, 25, 50, 100]`                      | Rows-per-page choices shown by the table. The first page loads with a page size of `10`.                        |
+| `onReceivableCreated`     | `(id: string, type: ReceivableDocumentType) => void` | `undefined`                              | Called after create or clone succeeds. The widget switches to the new document's tab and opens its details.     |
+| `onReceivableOpened`      | `(id: string, type: ReceivableDocumentType) => void` | `undefined`                              | Called when the user opens a row's detail sheet.                                                                |
+| `onTemplateSettingsClick` | `() => void`                                         | `undefined`                              | Shows a template settings action in the header and calls this handler when selected.                            |
+
+| Prop                       | Type                                     | Default          | Description                                                                                                         |
+| -------------------------- | ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `screenLabels`             | `Partial<ReceivablesScreenLabels>`       | English defaults | Overrides table, tab, filter, empty, error, action, and status badge copy.                                          |
+| `formLabels`               | `Partial<ReceivableFormSheetLabels>`     | English defaults | Overrides create/edit form labels and button copy.                                                                  |
+| `detailsLabels`            | `Partial<ReceivableDetailsSheetLabels>`  | English defaults | Overrides detail sheet headings, actions, empty copy, and status badge copy.                                        |
+| `sendLabels`               | `Partial<ReceivableSendDialogLabels>`    | English defaults | Overrides send-email dialog labels and buttons.                                                                     |
+| `paymentLabels`            | `Partial<ReceivablePaymentDialogLabels>` | English defaults | Overrides manual payment dialog labels and buttons.                                                                 |
+| `actionLabels`             | `Partial<ReceivableActionDialogLabels>`  | English defaults | Overrides generic confirmation dialog buttons. Action-specific title and body copy come from `messageLabels`.       |
+| `productFormLabels`        | `Partial<ProductFormSheetLabels>`        | English defaults | Overrides inline product creation copy from the shared product catalog flow.                                        |
+| `counterpartFormLabels`    | `Partial<CounterpartFormSheetLabels>`    | English defaults | Overrides inline customer creation copy from the shared counterpart-management flow.                                |
+| `measureUnitsLabels`       | `Partial<MeasureUnitsManagerLabels>`     | English defaults | Overrides measure-unit manager copy used by the product creation flow.                                              |
+| `measureUnitDeleteLabels`  | `Partial<MeasureUnitDeleteDialogLabels>` | English defaults | Overrides measure-unit delete confirmation copy.                                                                    |
+| `messageLabels`            | `Partial<ReceivableMessageLabels>`       | English defaults | Overrides validation, fallback, summary, activity, and action-confirmation messages generated by the feature layer. |
+| `productMessageLabels`     | `Partial<ProductMessageLabels>`          | English defaults | Overrides product flow validation and error messages.                                                               |
+| `counterpartMessageLabels` | `Partial<CounterpartMessageLabels>`      | English defaults | Overrides customer flow validation and error messages.                                                              |
+
+### ReceiptMatchWidget
+
+A slide-out wizard for attaching uploaded receipts to bank-card transactions. It lists the signed-in user's unmatched receipts, lets them pick a transaction per receipt, and persists each match against the embedded REST API.
+
+#### Props
+
+| Prop                        | Type         | Default     | Description                                                                                                                                       |
+| --------------------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isOpen`                    | `boolean`    | `false`     | Controls sidebar visibility. The widget renders `null` while falsy and opens when true; it also closes itself when a flow finishes.               |
+| `onClose`                   | `() => void` | `undefined` | Called on every dismissal (Done, attach, Esc, overlay). Provide it to keep your `isOpen` state in sync — the widget still self-closes if omitted. |
+| `preSelectedReceiptIds`     | `string[]`   | `[]`        | Receipt ids checked when the wizard opens, seeding the batch selection.                                                                           |
+| `targetTransactionId`       | `string`     | `undefined` | Attach mode: when set, the user picks one receipt and it is attached directly to this transaction (single-select, no transaction-search step).    |
+| `onSingleTransactionUpdate` | `() => void` | `undefined` | Called after a successful attach in `targetTransactionId` mode, before the widget closes. Use to refresh the host's view of that transaction.     |
+
+### SettingsWidget
+
+A composite settings widget that combines Monite document settings, tags, GL codes, and expense configuration.
+
+#### Props
+
+| Prop                | Type                     | Default                           | Description                                               |
+| ------------------- | ------------------------ | --------------------------------- | --------------------------------------------------------- |
+| `labels`            | `Partial<Labels>`        | English labels                    | Overrides the settings heading copy.                      |
+| `featureLabels`     | `Partial<FeatureLabels>` | English labels                    | Overrides section labels.                                 |
+| `profileContent`    | `ReactNode`              | Profile widget                    | Replaces the profile section content.                     |
+| `teamContent`       | `ReactNode`              | Empty                             | Supplies the team section content.                        |
+| `invoiceContent`    | `ReactNode`              | Monite template settings          | Replaces invoice settings content.                        |
+| `billPayContent`    | `ReactNode`              | Monite approval policies          | Replaces bill-pay settings content.                       |
+| `accountingContent` | `ReactNode`              | GL code table widget              | Replaces accounting content.                              |
+| `tagsContent`       | `ReactNode`              | Monite tags                       | Replaces tags content.                                    |
+| `expenseContent`    | `ReactNode`              | Expense policies and requirements | Replaces expense content.                                 |
+| `helpContent`       | `ReactNode`              | Help widget                       | Replaces the help section content.                        |
+| `finopsThemeColors` | `FinopsThemeColors`      | `undefined`                       | Optional Monite theme color overrides.                    |
+
+### TagsWidget
+
+A self-contained widget for managing an organization's tags: it lists tags in a sortable, cursor-paginated table and handles creating, editing, and deleting them — including each tag's OCR auto-tagging keywords. The host only supplies auth credentials and optional label overrides.
+
+#### Props
+
+| Prop              | Type                             | Default             | Description                                                               |
+| ----------------- | -------------------------------- | ------------------- | ------------------------------------------------------------------------- |
+| `pageSizeOptions` | `number[]`                       | `[10, 25, 50, 100]` | Choices in the rows-per-page selector.                                    |
+| `screenLabels`    | `Partial<TagsScreenLabels>`      | `undefined`         | Override table/header/empty/error copy. Merged over the English defaults. |
+| `formLabels`      | `Partial<TagFormSheetLabels>`    | `undefined`         | Override create/edit form copy.                                           |
+| `deleteLabels`    | `Partial<TagDeleteDialogLabels>` | `undefined`         | Override delete-confirmation copy.                                        |
+| `messageLabels`   | `Partial<TagMessageLabels>`      | `undefined`         | Override validation / submit-error messages.                              |
+
+### TeamWidget
+
+A self-contained team management surface for embedded integrators. It lists organization members in a paginated table and, when the widget token carries the appropriate write scopes, enables inviting new members, editing a member's name and role, and deactivating a member.
+
+#### Props
+
+| Prop            | Type                               | Description                                                                          |
+| --------------- | ---------------------------------- | ------------------------------------------------------------------------------------ |
+| `labels`        | `Partial<TeamWidgetLabels>`        | Overrides table, detail, invite, edit, and dialog UI copy.                           |
+| `featureLabels` | `Partial<TeamWidgetFeatureLabels>` | Overrides role display names, validation messages, and deactivate confirmation copy. |
+
+### TransfersWidget
+
+A self-contained banking widget for creating book or ACH transfers and reviewing recent movement across embedded accounts.
+
+#### Props
+
+| Prop            | Type                                    | Default          | Description                                                           |
+| --------------- | --------------------------------------- | ---------------- | --------------------------------------------------------------------- |
+| `labels`        | `Partial<TransfersWidgetLabels>`        | English labels   | Override shell and modal copy.                                        |
+| `featureLabels` | `Partial<TransfersWidgetFeatureLabels>` | English defaults | Override routing copy, fallbacks, default currency, and ACH SEC code. |
+
+### UploadReceiptWidget
+
+A self-contained "Upload receipts" control: a toggle button that opens a popover with a drag-and-drop / click-to-browse file picker plus a copyable forwarding email address. It is a controlled, presentational widget — the host owns the actual upload via `onFileUpload` and toasts batch progress, success, and failure.
+
+_Standalone presentational widget — it does not take the shared auth/scope props._
+
+#### Props
+
+| Prop           | Type                                          | Default     | Description                                                                                                                                      |
+| -------------- | --------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `emailAddress` | `string`                                      | _required_  | Forwarding email address shown in the popover with a copy button; receipts emailed here are processed automatically.                             |
+| `onFileUpload` | `(file: File) => unknown \| Promise<unknown>` | `undefined` | Called once per selected file. The widget awaits each call and counts resolutions vs. rejections to drive its toasts. Omit to disable uploading. |
+| `isUploading`  | `boolean`                                     | `false`     | Host-controlled loading flag. While `true` (or while a batch is in flight) the popover shows a processing state and blocks new uploads.          |
+
+<!-- END GENERATED REFERENCE -->
+
+## UI frameworks (shadcn default, Tecton optional)
+
+Widgets render with the default shadcn/native surface out of the box — no extra
+install, no configuration. An alternate UI framework (Tecton, built on the Q2 /
+Stencil design system) is shipped as a **separate, opt-in package** so the core
+package never carries Stencil or its build-time/runtime weight:
+
+```bash
+npm i @tesouro/embedded-components-react-tecton-ui
+```
+
+```ts
+import { registerTectonUI } from '@tesouro/embedded-components-react-tecton-ui';
+registerTectonUI(); // once, at app startup
+```
+
+Then select it via the provider cascade (`uiFramework="tecton"`). Without the
+extension installed, `uiFramework="tecton"` degrades gracefully to shadcn. See
+the extension's README for setup, the migration guide, and the Turbopack /
+`@stencil/core` note that applies only when the Tecton extension is installed.
+
+### TypeScript module resolution
+
+This package ships ESM with TypeScript declarations and is intended for
+**bundler-based** consumers — Vite, webpack, esbuild, Next.js — which is how
+React apps are built. Its types are exposed through the package `exports` map, so
+set TypeScript's `"moduleResolution"` to **`"bundler"`** (the modern default) and
+every entrypoint (`.`, `./core`, `./monite-sdk`, `./lib/*`) resolves cleanly.
+
+The published declarations are **self-contained**: the build bundles each
+entrypoint's `.d.ts` (`scripts/bundle-dts.mjs`) so it inlines the internal
+workspace types instead of re-exporting them from unpublished `@tesouro-fe/*`
+packages, and only genuine dependencies (react, MUI, …) remain as bare imports.
+An ESM consumer therefore type-checks cleanly under `"bundler"` **and**
+`"node16"` / `"nodenext"`, even with `skipLibCheck: false`.
+
+Legacy `"moduleResolution": "node"` (a.k.a. `node10` / classic) is **not
+supported**: it ignores the `exports` map, and this package carries no top-level
+`types` field, so the type checker reports `TS2307` for the package and its
+subpaths. Use `"bundler"` instead — every bundler-based toolchain supports it.
+As an ESM-only package it is not `require()`-able from CommonJS.
+
+## Contributing
+
+Maintainer notes — the monorepo build/publishing model, the publish-verification
+gate, and how to run the unit tests — live in `CONTRIBUTING.md` in the source
+repository.

package/dist/core.d.ts

@@ -0,0 +1,32 @@
+type WidgetTokenFetcher = () => Promise<{
+    widgetToken: string;
+    exp?: number;
+}>;
+type WidgetTokenState = {
+    status: 'loading';
+} | {
+    status: 'ready';
+    widgetToken: string;
+    exp?: number;
+    isRefreshing: boolean;
+    lastError?: unknown;
+} | {
+    status: 'error';
+    error: unknown;
+};
+interface WidgetTokenManager {
+    start(): void;
+    stop(): void;
+    refresh(): Promise<void>;
+    getState(): WidgetTokenState;
+    subscribe(listener: () => void): () => void;
+}
+interface CreateWidgetTokenManagerOptions {
+    fetcher: WidgetTokenFetcher;
+    /** Refresh `leadSeconds` before `exp`. Default 60. */
+    leadSeconds?: number;
+}
+declare function createWidgetTokenManager(options: CreateWidgetTokenManagerOptions): WidgetTokenManager;
+
+export { createWidgetTokenManager };
+export type { CreateWidgetTokenManagerOptions, WidgetTokenFetcher, WidgetTokenManager, WidgetTokenState };

package/dist/core.js

@@ -0,0 +1,4 @@
+import { createWidgetTokenManager as a } from "./libs/tesouro-embedded-components-react/shared/util/dist/index11.js";
+export {
+  a as createWidgetTokenManager
+};