@tesouro/embedded-components-react 0.7.42 → 0.7.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,52 +8,139 @@ This package is the public npm surface for Tesouro embedded React widgets.
8
8
  apps (Vite, webpack, esbuild, Next.js). `react` and `react-dom` (v19) are peer
9
9
  dependencies.
10
10
 
11
+ These steps put one widget on screen: a token route on your server, a provider
12
+ in the browser, and the widget itself. The examples use the Next.js App Router.
13
+
14
+ ### Before you start
15
+
16
+ You need three credentials from Tesouro: a client ID, a client secret and a
17
+ widget secret. Authentication › User token in the
18
+ [Embedded Banking](https://docs.tesouro.com/embedded-banking/guides/authentication/user-token)
19
+ or [FinOps](https://docs.tesouro.com/finops/guides/authentication/user-token)
20
+ docs explains how to request them. All three stay on your server.
21
+
22
+ ### 1. Install
23
+
11
24
  ```bash
12
25
  npm install @tesouro/embedded-components-react
13
- # or: yarn add @tesouro/embedded-components-react
26
+ npm install @tesouro/embedded-components-widget-token
14
27
  ```
15
28
 
16
- **Import the stylesheet once** at your app's entry point. Widgets render
17
- unstyled without it:
29
+ The second package mints widget tokens and handles your secrets, so only your
30
+ server imports it.
31
+
32
+ ### 2. Add a token route
33
+
34
+ A widget acts as one of your users, authenticated by a short-lived widget token
35
+ that your server mints. This route handler, at `app/api/widget-token/route.ts`,
36
+ returns the `{ widgetToken, exp }` shape the provider in step 3 expects:
18
37
 
19
38
  ```ts
20
- import '@tesouro/embedded-components-react/styles.css';
39
+ import { NextRequest, NextResponse } from 'next/server';
40
+ import { configureCreateWidgetToken } from '@tesouro/embedded-components-widget-token';
41
+
42
+ const mintWidgetToken = configureCreateWidgetToken({
43
+ clientId: process.env.TESOURO_CLIENT_ID!,
44
+ clientSecret: process.env.TESOURO_CLIENT_SECRET!,
45
+ widgetSecret: process.env.TESOURO_WIDGET_SECRET!,
46
+ });
47
+
48
+ export async function POST(req: NextRequest) {
49
+ const session = await getSession(req);
50
+ if (!session) {
51
+ return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
52
+ }
53
+
54
+ const { widgetToken, exp } = await mintWidgetToken({
55
+ userId: session.userId,
56
+ userEmail: session.userEmail,
57
+ organizationReference: session.organizationReference,
58
+ });
59
+
60
+ return NextResponse.json(
61
+ { widgetToken, exp },
62
+ { headers: { 'Cache-Control': 'no-store' } },
63
+ );
64
+ }
21
65
  ```
22
66
 
23
- Then render a widget inside a provider that establishes its authenticated scope:
67
+ `getSession` stands in for your own server-side session check. Take the user
68
+ and their `organizationReference` (your stable ID for the business they belong
69
+ to) from that session, never from the request: the route mints a valid token
70
+ for whatever identity it's given. Never expose the three credentials to the
71
+ browser, for example through a `NEXT_PUBLIC_` variable.
72
+
73
+ [`@tesouro/embedded-components-widget-token`](https://www.npmjs.com/package/@tesouro/embedded-components-widget-token)
74
+ documents the other options, including the token lifetime.
75
+
76
+ Backend not on Node? Build the token yourself: Authentication › User token in
77
+ the [Embedded Banking](https://docs.tesouro.com/embedded-banking/guides/authentication/user-token)
78
+ or [FinOps](https://docs.tesouro.com/finops/guides/authentication/user-token)
79
+ docs specifies its claims and encryption. Your route returns the same
80
+ `{ widgetToken, exp }`.
81
+
82
+ ### 3. Add the provider
83
+
84
+ `RefreshingRootWidgetProvider` calls your route on mount, fetches a new token
85
+ shortly before `exp`, and shares the signed-in scope with every widget inside
86
+ it. It runs in the browser, so in the App Router it goes in a Client Component
87
+ that your root layout renders, such as `app/providers.tsx`. Import the
88
+ stylesheet there too: widgets render unstyled without it.
24
89
 
25
90
  ```tsx
91
+ 'use client';
92
+
26
93
  import '@tesouro/embedded-components-react/styles.css';
94
+ import type { ReactNode } from 'react';
27
95
  import {
28
- RootWidgetProvider,
29
- BankAccountsWidget,
96
+ RefreshingRootWidgetProvider,
97
+ type WidgetTokenFetcher,
30
98
  } from '@tesouro/embedded-components-react';
31
99
 
32
- export function App() {
100
+ const fetcher: WidgetTokenFetcher = async () => {
101
+ const res = await fetch('/api/widget-token', { method: 'POST' });
102
+ if (!res.ok) throw new Error('Widget token request failed');
103
+ return res.json();
104
+ };
105
+
106
+ export function Providers({ children }: { children: ReactNode }) {
33
107
  return (
34
- <RootWidgetProvider
35
- baseUrl="https://api.tesouro.com"
36
- widgetToken="wt_live_…"
37
- organizationId="org_…"
108
+ <RefreshingRootWidgetProvider
109
+ baseUrl="https://api.sandbox.tesouro.com"
110
+ fetcher={fetcher}
38
111
  >
39
- <BankAccountsWidget />
40
- </RootWidgetProvider>
112
+ {children}
113
+ </RefreshingRootWidgetProvider>
41
114
  );
42
115
  }
43
116
  ```
44
117
 
45
- `widgetToken` comes from your server, never the browser: create it with
46
- [`@tesouro/embedded-components-widget-token`](https://www.npmjs.com/package/@tesouro/embedded-components-widget-token),
47
- which keeps your client and widget secrets server-side.
118
+ Use `https://api.sandbox.tesouro.com` while you build and
119
+ `https://api.tesouro.com` in production.
120
+
121
+ ### 4. Render a widget
122
+
123
+ Any widget inside the provider is ready to use:
124
+
125
+ ```tsx
126
+ import { BankAccountsWidget } from '@tesouro/embedded-components-react';
127
+
128
+ export default function AccountsPage() {
129
+ return <BankAccountsWidget />;
130
+ }
131
+ ```
48
132
 
49
- Every provider and widget prop is typed in the shipped declarations, so your
50
- editor documents them inline.
133
+ Browse the widgets for
134
+ [Embedded Banking](https://components.tesouro.com/components?product=embedded-banking)
135
+ or [FinOps](https://components.tesouro.com/components?product=finops). Every provider
136
+ and widget prop is typed in the shipped declarations, so your editor documents
137
+ them inline.
51
138
 
52
139
  ### Entry points
53
140
 
54
141
  | Import path | What you get |
55
142
  | ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
56
- | `@tesouro/embedded-components-react` | All widgets, `WidgetSuite`, plus `RootWidgetProvider` / `WidgetProvider`. |
143
+ | `@tesouro/embedded-components-react` | All widgets, `WidgetSuite`, and the providers, including `RefreshingRootWidgetProvider`. |
57
144
  | `@tesouro/embedded-components-react/styles.css` | The widget stylesheet. See [About the stylesheet](#about-the-stylesheet). |
58
145
  | `@tesouro/embedded-components-react/core` | Framework-agnostic token utilities (`createWidgetTokenManager`). |
59
146
  | `@tesouro/embedded-components-react/monite-sdk` | Legacy surface being removed, with no compatibility promise. See [below](#monite-sdk-entry-point). |
@@ -112,7 +199,7 @@ App-level provider. Resolves `baseUrl` / `widgetToken` / `organizationId` (falli
112
199
  | `gatewayRouting` | `boolean` | Forces widget-gateway routing on (`true`) or off (`false`); unset, it applies automatically to known Tesouro API hosts. Falls back to `global.gatewayRouting`. |
113
200
  | `linkComponent` | `LinkComponent` | Host link component widgets use for navigational links. Falls back to `global.linkComponent`. |
114
201
  | `uiFramework` | `'shadcn' \| 'tecton' \| null` | UI framework for this tree; falls back to `global.uiFramework`, then `'shadcn'`. |
115
- | `implementation` | `'native' \| 'monite' \| null` | Widget implementation for this tree; falls back to `global.implementation`, then `'native'`. |
202
+ | `implementation` | `'native' \| 'monite' \| null` | Reserved for widgets with more than one build; no widget reads it today. Falls back to `global.implementation`, then `'native'`. |
116
203
  | `analytics` | `boolean` | Enables anonymous analytics (default `true`); `false` disables capture and skips loading PostHog. |
117
204
  | `unstable_initResponseOverride` | `WidgetInitResponse` | First-party hosts only: skips the init fetch and uses this object as `initResponse`. Embed integrations minting widget JWEs must leave this unset. |
118
205
  | `disclosuresAcceptance` | `ReactNode` | Accept surface shown when the user owes disclosures; pass `<AcceptDisclosuresWidget />`. Cascades to nested providers. |
@@ -134,7 +221,7 @@ Mid-tree or standalone provider. With no props it is a transparent pass-through
134
221
  | `gatewayRouting` | `boolean` | Forces widget-gateway routing on or off for this subtree's client; unset, it applies to known Tesouro API hosts. Inherits when omitted. |
135
222
  | `linkComponent` | `LinkComponent` | Overrides the host link component for this subtree. Inherits when omitted. |
136
223
  | `uiFramework` | `'shadcn' \| 'tecton' \| null` | Overrides the UI framework for this subtree; omitted or `null` inherits, defaulting to `'shadcn'`. |
137
- | `implementation` | `'native' \| 'monite' \| null` | Overrides the implementation for this subtree; omitted or `null` inherits, defaulting to `'native'`. |
224
+ | `implementation` | `'native' \| 'monite' \| null` | Reserved for widgets with more than one build; no widget reads it today. Omitted or `null` inherits, defaulting to `'native'`. |
138
225
  | `errorFallback` | `ReactNode \| (props: FallbackProps) => ReactNode` | Custom error-boundary fallback: a node, or a function receiving `{ error, resetErrorBoundary }`. |
139
226
  | `onError` | `(error: unknown, info: ErrorInfo) => void` | Telemetry hook, called once per caught error before the fallback renders. |
140
227
  | `analytics` | `boolean` | Enables anonymous analytics (default `true`); honored only in standalone mode, ignored on a nested provider. |
@@ -169,7 +256,7 @@ Bundles `WidgetTokenRefreshProvider` + `RootWidgetProvider` and wires the live t
169
256
  | `gatewayRouting` | `RootWidgetProvider` | Overrides widget-gateway routing; unset, it applies automatically for known Tesouro API hosts. |
170
257
  | `linkComponent` | `RootWidgetProvider` | Component used in place of plain `<a>` tags inside widgets. |
171
258
  | `uiFramework` | `RootWidgetProvider` | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade. |
172
- | `implementation` | `RootWidgetProvider` | `'native'` (default) or `'monite'`; inherits down the provider cascade. |
259
+ | `implementation` | `RootWidgetProvider` | Reserved for widgets with more than one build; no widget reads it today. Inherits down the cascade. |
173
260
  | `analytics` | `RootWidgetProvider` | Enables anonymous analytics (default `true`); set `false` to disable capture. |
174
261
  | `unstable_initResponseOverride` | `RootWidgetProvider` | First-party hosts only. Skips the init fetch and supplies host-authored identity for the subtree. |
175
262
  | `disclosuresAcceptance` | `RootWidgetProvider` | Accept surface shown when the user owes disclosures. Cascades to nested providers. |
@@ -1,5 +1,5 @@
1
1
  //#region ../../libs/tesouro-embedded-components-react/shared/feature/dist/lib/analytics/build-info.js
2
- var e = "@tesouro/embedded-components-react", t = "0.7.42", n = "acce50e6858601c354e5585cbdfe2b11996ec00a", r = Object.freeze({
2
+ var e = "@tesouro/embedded-components-react", t = "0.7.44", n = "234ce1938135d29ed4c73ed506a604e107db4a3e", r = Object.freeze({
3
3
  library_name: e,
4
4
  library_version: t,
5
5
  library_sha: n
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tesouro/embedded-components-react",
3
- "version": "0.7.42",
3
+ "version": "0.7.44",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "sideEffects": [