@outmarket-ai/react-sdk 0.1.0-alpha.0 → 0.1.0-alpha.2
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 +113 -487
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,505 +1,131 @@
|
|
|
1
1
|
# @outmarket-ai/react-sdk
|
|
2
2
|
|
|
3
|
-
Embed
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
An Outmarket account is an address at exactly `@outmarket.ai`; an address at
|
|
81
|
-
a subdomain such as `eu.outmarket.ai`, or at `outmarket.org`, is not one.
|
|
82
|
-
- **Mint once per sign-in**, not on every page load. The SDK refreshes the
|
|
83
|
-
session itself, the way the Outmarket web app does.
|
|
84
|
-
|
|
85
|
-
The `201` response is the session:
|
|
86
|
-
|
|
87
|
-
```json
|
|
88
|
-
{
|
|
89
|
-
"access_token": "eyJhbGciOi...",
|
|
90
|
-
"refresh_token": "v1.MhT...",
|
|
91
|
-
"token_type": "bearer",
|
|
92
|
-
"expires_in": 43200,
|
|
93
|
-
"expires_at": 1790049600,
|
|
94
|
-
"user": { "id": "8c1e2f4a-...", "email": "jane@example.com", "name": "Jane Doe" },
|
|
95
|
-
"instance": { "id": "3f2a9b10-...", "name": "Acme Brokerage", "url": "https://abcd1234.supabase.co", "public_key": "..." }
|
|
96
|
-
}
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
### 2. Hand it to your page
|
|
100
|
-
|
|
101
|
-
Return the body to your page in the response to a same-origin `POST` from your
|
|
102
|
-
page. It holds the user's tokens, so never put it in a URL or query string, in
|
|
103
|
-
cached HTML, or in a log. Send it with `Cache-Control: no-store`, and do not
|
|
104
|
-
enable CORS on that route, so no other site's page can read the response.
|
|
105
|
-
|
|
106
|
-
### 3. Pass it to the SDK unchanged
|
|
107
|
-
|
|
108
|
-
```tsx
|
|
109
|
-
<OutmarketProvider session={session}>{/* surfaces */}</OutmarketProvider>
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
`session` is the only sign-in prop. There are no callbacks.
|
|
113
|
-
|
|
114
|
-
- **Reloads resume.** The SDK keeps the session in your origin's `localStorage`
|
|
115
|
-
and refreshes it there. When the page reloads and you pass the same session
|
|
116
|
-
again, the SDK keeps the refreshed one.
|
|
117
|
-
- **Switching users.** Pass the new user's session. A session for another user or
|
|
118
|
-
another tenant replaces the stored one and clears the previous user's cached
|
|
119
|
-
data. So does a newer session for the same user. A request the previous
|
|
120
|
-
user's surfaces started but had not sent yet (while the SDK refreshed the
|
|
121
|
-
session, or before a retry) is cancelled, not sent as the new user.
|
|
122
|
-
- **Other tabs.** Tabs of your app on the same origin store the session in the
|
|
123
|
-
same place, but a tab reads the values stored when it loaded, plus its own
|
|
124
|
-
writes. It does see another tab clear the session (`signOut()` in any tab) or
|
|
125
|
-
store another user's or tenant's session: it then drops its cached data and
|
|
126
|
-
shows the "session has ended" message instead of running as the other
|
|
127
|
-
session. Passing a new session, or reloading the tab with one, starts it
|
|
128
|
-
again.
|
|
129
|
-
`signOut()` ends the stored session and the session each provider in an open
|
|
130
|
-
tab is still running at that moment. Each of those stays ended on your
|
|
131
|
-
origin: a provider that mounts with it again, in any tab, shows the message
|
|
132
|
-
instead of storing it. The SDK cannot see a session your app holds in a tab
|
|
133
|
-
with no provider running it, so drop that one in your own logout.
|
|
134
|
-
- **One user in several tabs.** A tab does not see another tab's refresh: each
|
|
135
|
-
open tab refreshes the session with the refresh token it holds, and a
|
|
136
|
-
refresh spends that token. A tab still holding a token another tab spent can
|
|
137
|
-
have its refresh refused, and Outmarket can then end the session in every
|
|
138
|
-
tab, which shows the "session has ended" message. A tab that loads after a
|
|
139
|
-
refresh reads the refreshed session.
|
|
140
|
-
- **When the session ends** (after 30 days, or when Outmarket ends it), the SDK
|
|
141
|
-
shows a "session has ended" message in place of the surfaces and never
|
|
142
|
-
navigates your page. It shows once Outmarket answers one of the SDK's requests
|
|
143
|
-
as signed out. For a session Outmarket ended, that happens at the latest when
|
|
144
|
-
the SDK next refreshes it, on the first request after the access token is
|
|
145
|
-
halfway through its life. The SDK does not tell your page, so passing the same
|
|
146
|
-
session again shows the message again. Mint a new session the next time the
|
|
147
|
-
user signs in to your app.
|
|
148
|
-
- **Two-factor accounts.** A session minted this way is single-factor, so a
|
|
149
|
-
user with two-factor verification turned on sees a message asking them to
|
|
150
|
-
open Outmarket directly.
|
|
151
|
-
- **Your logout.** Call `signOut()`, then discard the session you held, in
|
|
152
|
-
every tab of your app (for example through your own `storage` event or a
|
|
153
|
-
`BroadcastChannel`):
|
|
154
|
-
|
|
155
|
-
```ts
|
|
156
|
-
import { signOut } from '@outmarket-ai/react-sdk';
|
|
157
|
-
|
|
158
|
-
await signOut(); // clears the session from this origin
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
`signOut()` clears the session from your origin and remembers the ids of the
|
|
162
|
-
sessions it ended there (the last 20, in `localStorage`), so the SDK does not
|
|
163
|
-
store them again: mint a new one for the next sign-in. From a tab that holds
|
|
164
|
-
the stored session, it also asks Outmarket to sign the session out. A tab
|
|
165
|
-
that loaded before another tab stored the session, or that still holds an
|
|
166
|
-
earlier one, cannot read the stored session's tokens, so its `signOut()`
|
|
167
|
-
skips that request. Today the request does not revoke the session anyway:
|
|
168
|
-
its tokens stay valid at Outmarket until they expire, and it can be refreshed
|
|
169
|
-
until its 30 days pass. To end a session at Outmarket, for example after a
|
|
170
|
-
suspected leak, ask Outmarket to end it, and see [Lifetimes](#lifetimes) for
|
|
171
|
-
how long its access token keeps working after that.
|
|
172
|
-
|
|
173
|
-
### Lifetimes
|
|
174
|
-
|
|
175
|
-
The session lives like a normal Outmarket sign-in. Each access token lasts until
|
|
176
|
-
its `expires_at` (up to 7 days in production; 12 hours on Outmarket's staging
|
|
177
|
-
environment, as in the example above), refresh keeps working for up to 30 days
|
|
178
|
-
from the mint, and there is no inactivity timeout. Revoking the API key stops
|
|
179
|
-
new sessions only; sessions already minted keep working until they end. Ending
|
|
180
|
-
one early is a request to Outmarket.
|
|
181
|
-
|
|
182
|
-
Ending a session stops it from being refreshed at once, but an access token
|
|
183
|
-
already issued keeps working until its `expires_at`. After a suspected leak,
|
|
184
|
-
treat the session as usable by whoever holds it until then.
|
|
185
|
-
|
|
186
|
-
### Errors
|
|
187
|
-
|
|
188
|
-
The endpoint's own refusals, listed below, have the body
|
|
189
|
-
`{"error": {"code", "message", "details": {"reason"}}}`. Branch on
|
|
190
|
-
`details.reason`:
|
|
191
|
-
|
|
192
|
-
| HTTP | `details.reason` | Meaning |
|
|
193
|
-
| --- | --- | --- |
|
|
194
|
-
| 403 | `browser_origin_not_allowed` | The request came from a browser. Call from your server. |
|
|
195
|
-
| 403 | `api_key_required` | The Bearer is not an API key. |
|
|
196
|
-
| 403 | `insufficient_scope` | The key's `sub` is not its instance's id. |
|
|
197
|
-
| 403 | `instance_unavailable` | The tenant is disabled or not available in this region. |
|
|
198
|
-
| 403 | `key_not_eligible` | The key is revoked or expired, has no IP allowlist or an allowlist entry wider than /16 (IPv4) or /32 (IPv6), or API access is off for the tenant. |
|
|
199
|
-
| 403 | `user_not_eligible` | This user cannot be signed in this way. The reason is never given. |
|
|
200
|
-
| 429 | `rate_limited` | The sign-in service is busy. Wait for `Retry-After`, then retry. |
|
|
201
|
-
| 502 | `session_unavailable` | No session could be created. Retry later. |
|
|
202
|
-
|
|
203
|
-
Other errors carry no `details.reason`, among them:
|
|
204
|
-
|
|
205
|
-
- A key whose scopes include neither `auth` nor `*` gets the standard `403` of
|
|
206
|
-
every route: `{"error": {"code": "FORBIDDEN", "message": "insufficient permissions"}}`.
|
|
207
|
-
- A body that is not valid JSON, or fails field validation (it takes one
|
|
208
|
-
field, a valid `email`), gets FastAPI's `422`: `{"detail": [...]}`.
|
|
209
|
-
|
|
210
|
-
The gateway also answers `429` with its own body when you go over its limits: 500
|
|
211
|
-
requests per minute from one IP, and 3,600 per hour and 1,296,000 per month per
|
|
212
|
-
tenant, shared with the tenant's other API keys. Honor `Retry-After` when it is
|
|
213
|
-
present.
|
|
214
|
-
|
|
215
|
-
### Keeping the session safe
|
|
216
|
-
|
|
217
|
-
The session sits in your origin's `localStorage`, so anything that runs script
|
|
218
|
-
on your page (a cross-site scripting bug, a malicious extension) can read it and
|
|
219
|
-
act as that user, the same exposure as any web sign-in. Keep your page's script
|
|
220
|
-
supply tight and set a [Content-Security-Policy](#content-security-policy).
|
|
221
|
-
|
|
222
|
-
The SDK stores the session scrambled, but with a key that any script on your
|
|
223
|
-
page, or anyone with a copy of the browser profile, can work out, so treat it
|
|
224
|
-
as plain text. Next to it, the SDK keeps three plain `localStorage` entries
|
|
225
|
-
that every tab reads: who the stored session belongs to (the user and tenant
|
|
226
|
-
ids), the stored session's id, and the ids of sessions `signOut()` ended. None
|
|
227
|
-
of them is a credential.
|
|
228
|
-
|
|
229
|
-
## Usage
|
|
230
|
-
|
|
231
|
-
One provider you mount **once**, and the **surface components** you swap between
|
|
232
|
-
yourself. There is **no routing inside the SDK**: you own navigation through each
|
|
233
|
-
component's callback. The provider talks to Outmarket production unless you pass
|
|
234
|
-
`environment` / `apiUrls` (see [Environments and API URLs](#environments-and-api-urls)).
|
|
235
|
-
On its first render it shows a small spinner while the SDK's components load.
|
|
236
|
-
Under server rendering (SSR) it renders only that spinner; the components load
|
|
237
|
-
in the browser once the page hydrates.
|
|
238
|
-
|
|
239
|
-
```tsx
|
|
240
|
-
import { useState } from 'react';
|
|
241
|
-
import {
|
|
242
|
-
OutmarketProvider,
|
|
243
|
-
OutmarketWorkflowsList,
|
|
244
|
-
OutmarketWorkflowForm,
|
|
245
|
-
OutmarketWorkflowConversation,
|
|
246
|
-
type OutmarketSession,
|
|
247
|
-
} from '@outmarket-ai/react-sdk';
|
|
248
|
-
import '@outmarket-ai/react-sdk/styles.css';
|
|
249
|
-
|
|
250
|
-
export function Workflows({ session }: { session: OutmarketSession }) {
|
|
251
|
-
const [view, setView] = useState({ kind: 'list' });
|
|
252
|
-
|
|
253
|
-
return (
|
|
254
|
-
<OutmarketProvider session={session}>
|
|
255
|
-
{view.kind === 'list' && (
|
|
256
|
-
<OutmarketWorkflowsList
|
|
257
|
-
module="commercial_lines" // or personal_lines | benefits
|
|
258
|
-
onSelectWorkflow={(workflowId) => setView({ kind: 'form', workflowId })}
|
|
259
|
-
/>
|
|
260
|
-
)}
|
|
261
|
-
|
|
262
|
-
{view.kind === 'form' && (
|
|
263
|
-
<OutmarketWorkflowForm
|
|
264
|
-
workflowId={view.workflowId}
|
|
265
|
-
// fires when the primary button (Start Workflow / Compare / Policy Check)
|
|
266
|
-
// runs and creates the conversation; the form shows a spinner until you swap.
|
|
267
|
-
onConversationCreated={(conversationId) => setView({ kind: 'conversation', conversationId })}
|
|
268
|
-
/>
|
|
269
|
-
)}
|
|
270
|
-
|
|
271
|
-
{view.kind === 'conversation' && <OutmarketWorkflowConversation conversationId={view.conversationId} />}
|
|
272
|
-
</OutmarketProvider>
|
|
273
|
-
);
|
|
274
|
-
}
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
## Environments and API URLs
|
|
278
|
-
|
|
279
|
-
The SDK talks to three Outmarket backends from the browser: the API, Nexus
|
|
280
|
-
(workflows, conversations and their streams) and the gateway. Two optional
|
|
281
|
-
provider props choose them:
|
|
282
|
-
|
|
283
|
-
```tsx
|
|
284
|
-
// Outmarket staging instead of production:
|
|
285
|
-
<OutmarketProvider session={session} environment="staging">…</OutmarketProvider>
|
|
286
|
-
|
|
287
|
-
// Production, with Nexus routed through your own server:
|
|
288
|
-
<OutmarketProvider session={session} apiUrls={{ nexus: '/outmarket/nexus/api/v1' }}>…</OutmarketProvider>
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
`environment` picks a preset: the public base URLs and client keys Outmarket's
|
|
292
|
-
web app uses in that environment. Mint the session in the same environment, with
|
|
293
|
-
an API key of a tenant there: a session from one environment does not work
|
|
294
|
-
against another.
|
|
295
|
-
|
|
296
|
-
| `environment` | API (`apiUrls.api`) | Nexus (`apiUrls.nexus`) | Gateway (`apiUrls.gateway`) |
|
|
297
|
-
| --- | --- | --- | --- |
|
|
298
|
-
| `'production'` (default) | `https://api.prod.outmarket.ai/v1` | `https://nexus.prod.outmarket.ai/api/v1` | `https://gateway.outmarket.ai/api/v1` |
|
|
299
|
-
| `'qa'` | `https://api-qa.outmarket.ai/v1` | `https://nexus-qa.outmarket.ai/api/v1` | `https://gateway.stage.outmarket.ai/api/v1` (QA has no gateway of its own yet) |
|
|
300
|
-
| `'staging'` | `https://api-g.stage.outmarket.ai/v1` | `https://nexus.stage.outmarket.ai/api/v1` | `https://gateway.stage.outmarket.ai/api/v1` |
|
|
301
|
-
|
|
302
|
-
`apiUrls` overrides any of the three on top of the preset (production when you
|
|
303
|
-
pass `apiUrls` alone). Each value is either:
|
|
304
|
-
|
|
305
|
-
- an absolute `http(s)` URL including its path, such as
|
|
306
|
-
`https://nexus.example.com/api/v1`, or
|
|
307
|
-
- a root-relative path, such as `/outmarket/nexus/api/v1`, that your own server
|
|
308
|
-
proxies to the matching Outmarket URL.
|
|
309
|
-
|
|
310
|
-
A trailing slash is dropped, and an absolute URL is used as the browser parses
|
|
311
|
-
it (scheme and host in lowercase). Anything else (a relative path, another scheme, a
|
|
312
|
-
`//host` URL, credentials, a query or a fragment) is ignored with a console
|
|
313
|
-
error, and the preset's URL is used instead; the provider never throws over it.
|
|
314
|
-
|
|
315
|
-
**The environment must allow-list your origin.** Outmarket allow-lists origins
|
|
316
|
-
per environment, so a page allow-listed for production gets CORS errors against
|
|
317
|
-
QA or staging until Outmarket adds it there too. An `apiUrls` path on your own
|
|
318
|
-
origin needs no allow-listing: your server makes the cross-origin call. Your
|
|
319
|
-
[Content-Security-Policy](#content-security-policy) must allow the hosts you
|
|
320
|
-
point at.
|
|
321
|
-
|
|
322
|
-
**Applied once per page load.** The SDK's components read the backend URLs once,
|
|
323
|
-
when their code loads, so the configuration is fixed by the first
|
|
324
|
-
`<OutmarketProvider>` that renders on the page (or by a `signOut()` called before
|
|
325
|
-
any provider rendered, which loads that code too). A later render, or a second
|
|
326
|
-
provider, with a different `environment` or `apiUrls` logs a console warning and
|
|
327
|
-
keeps using the first configuration; reload the page to switch. Pass the same
|
|
328
|
-
values to every provider on a page.
|
|
329
|
-
|
|
330
|
-
Precedence, highest first: `apiUrls`, then the `environment` preset (whenever
|
|
331
|
-
either prop is given), then values set on the
|
|
332
|
-
[`__OM_EMBED_CONFIG__` global](#advanced-the-config-global), then the production
|
|
333
|
-
defaults.
|
|
334
|
-
|
|
335
|
-
## Content-Security-Policy
|
|
336
|
-
|
|
337
|
-
The SDK calls these sources from the browser. Allow them in your page's policy,
|
|
338
|
-
no wider than shown: the session sits in `localStorage`, so a policy that admits
|
|
339
|
-
a whole CDN or every Supabase project lets injected script load from, or send the
|
|
340
|
-
session to, a place an attacker controls.
|
|
341
|
-
|
|
342
|
-
| Directive | Sources | Why |
|
|
343
|
-
| --- | --- | --- |
|
|
344
|
-
| `connect-src` | `https://api.prod.outmarket.ai` `https://nexus.prod.outmarket.ai` `https://gateway.outmarket.ai` | Outmarket's APIs, including the session refresh. For another `environment` or `apiUrls`, the hosts you point at instead |
|
|
345
|
-
| `connect-src` | `https://abcd1234.supabase.co` `wss://abcd1234.supabase.co` | Your tenant's database and live updates. Use the host of the session's `instance.url`, never `*.supabase.co` |
|
|
346
|
-
| `connect-src` | `https://featureassets.org` `https://prodregistryv2.org` `https://api.statsigcdn.com` | Feature flags |
|
|
347
|
-
| `connect-src` | `https://cdn.jsdelivr.net/npm/us-atlas@3/states-10m.json` | State outlines for charts drawn as a US map |
|
|
348
|
-
| `worker-src` | `'self'` `blob:` | The PDF worker you host yourself (see [PDF rendering](#pdf-rendering)), and small helper workers the components start from `blob:` URLs |
|
|
349
|
-
| `img-src` | `https://abcd1234.supabase.co` `data:` `blob:` | Files and previews, from the same tenant host |
|
|
350
|
-
| `style-src` | `'unsafe-inline'` | The components set inline styles |
|
|
351
|
-
|
|
352
|
-
If you keep the default CDN worker instead of hosting it yourself, add that one
|
|
353
|
-
file to your `script-src`, because pdf.js imports it into a `blob:` worker:
|
|
354
|
-
|
|
355
|
-
```text
|
|
356
|
-
https://cdn.jsdelivr.net/npm/pdfjs-dist@4.10.38/build/pdf.worker.min.mjs
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
A source whose path does not end in `/` matches only that file. Never allow all
|
|
360
|
-
of `https://cdn.jsdelivr.net` in `script-src`: it serves any npm package or
|
|
361
|
-
GitHub file, so injected markup could load an attacker's script from it. Keep
|
|
362
|
-
`blob:` out of `script-src` as well.
|
|
363
|
-
|
|
364
|
-
If a surface fails to render under your policy, the browser console names the
|
|
365
|
-
blocked source.
|
|
366
|
-
|
|
367
|
-
## PDF rendering
|
|
368
|
-
|
|
369
|
-
Citations, file previews and PDF viewers render through **react-pdf**, which needs
|
|
370
|
-
its worker at a resolvable URL. By default the SDK loads it from a versioned public
|
|
371
|
-
CDN, so it works with no setup. We recommend hosting it yourself, which keeps the
|
|
372
|
-
CDN out of your [Content-Security-Policy](#content-security-policy). The worker
|
|
373
|
-
ships in the package: copy `dist/pdf.worker.min.mjs` (also exposed as
|
|
374
|
-
`@outmarket-ai/react-sdk/pdf.worker.min.mjs`) to your origin and set the
|
|
375
|
-
URL before the first `<OutmarketProvider>` renders (before importing the SDK is
|
|
376
|
-
simplest). `environment` and `apiUrls` never change it:
|
|
377
|
-
|
|
378
|
-
```ts
|
|
379
|
-
globalThis.__OM_EMBED_CONFIG__ = {
|
|
380
|
-
...(globalThis.__OM_EMBED_CONFIG__ ?? {}),
|
|
381
|
-
NEXT_PUBLIC_PDF_WORKER_URL: '/pdf.worker.min.mjs',
|
|
382
|
-
};
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
> **ACORD form filling is not included** in the embed. It relies on a commercial
|
|
386
|
-
> PDF viewer the SDK does not bundle, so the workflow is hidden from the catalog.
|
|
387
|
-
>
|
|
388
|
-
> **No Tiptap Pro extensions ship in the package**, so you need no Tiptap
|
|
389
|
-
> subscription or registry access to install or use it.
|
|
3
|
+
Embed Outmarket workflows in your React app: the workflow catalog, each workflow's form and its
|
|
4
|
+
conversation, signed in as your user.
|
|
5
|
+
|
|
6
|
+
For a minimal working app, see [Outmarket-AI/react-sdk-example](https://github.com/Outmarket-AI/react-sdk-example).
|
|
7
|
+
|
|
8
|
+
Using the SDK requires Outmarket's approval. See the `LICENSE` file in the package.
|
|
9
|
+
|
|
10
|
+
## Setup
|
|
11
|
+
|
|
12
|
+
1. **Get your domain allow-listed.** Send your Outmarket representative every domain your app runs
|
|
13
|
+
on, for example `https://app.example.com`. Approval takes 1–2 business days. Until then the
|
|
14
|
+
browser blocks the SDK's calls to Outmarket (CORS).
|
|
15
|
+
|
|
16
|
+
2. **Create an API key.** An Outmarket System Admin creates it in **Settings → API Keys** with the
|
|
17
|
+
`auth` permission and your servers' IP addresses. Keep the key on your server: it can sign in as
|
|
18
|
+
any member of your workspace.
|
|
19
|
+
|
|
20
|
+
3. **Install the SDK.** It needs React 19.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @outmarket-ai/react-sdk
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
4. **Mint a session on your server** when a user signs in to your app:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
curl -X POST https://gateway.outmarket.ai/api/v1/auth/sessions \
|
|
30
|
+
-H "Authorization: Bearer $OUTMARKET_API_KEY" \
|
|
31
|
+
-H "Content-Type: application/json" \
|
|
32
|
+
-d '{"email":"jane@example.com"}'
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Take the email from the signed-in user's session on your server, never from anything the browser
|
|
36
|
+
sends. The user must be a member of your Outmarket workspace. Return the `201` body to your page
|
|
37
|
+
unchanged, with `Cache-Control: no-store`, and keep it out of URLs and logs. Mint once per sign-in:
|
|
38
|
+
the SDK refreshes the session itself.
|
|
39
|
+
|
|
40
|
+
5. **Render the SDK** with that session:
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
import { useState } from 'react';
|
|
44
|
+
import {
|
|
45
|
+
OutmarketProvider,
|
|
46
|
+
OutmarketWorkflowsList,
|
|
47
|
+
OutmarketWorkflowForm,
|
|
48
|
+
OutmarketWorkflowConversation,
|
|
49
|
+
type OutmarketSession,
|
|
50
|
+
} from '@outmarket-ai/react-sdk';
|
|
51
|
+
import '@outmarket-ai/react-sdk/styles.css';
|
|
52
|
+
|
|
53
|
+
type View =
|
|
54
|
+
| { kind: 'list' }
|
|
55
|
+
| { kind: 'form'; workflowId: string }
|
|
56
|
+
| { kind: 'conversation'; conversationId: string };
|
|
57
|
+
|
|
58
|
+
export function Workflows({ session }: { session: OutmarketSession }) {
|
|
59
|
+
const [view, setView] = useState<View>({ kind: 'list' });
|
|
60
|
+
|
|
61
|
+
return (
|
|
62
|
+
<OutmarketProvider session={session}>
|
|
63
|
+
{view.kind === 'list' && (
|
|
64
|
+
<OutmarketWorkflowsList
|
|
65
|
+
module="commercial_lines"
|
|
66
|
+
onSelectWorkflow={(workflowId) => setView({ kind: 'form', workflowId })}
|
|
67
|
+
/>
|
|
68
|
+
)}
|
|
69
|
+
{view.kind === 'form' && (
|
|
70
|
+
<OutmarketWorkflowForm
|
|
71
|
+
workflowId={view.workflowId}
|
|
72
|
+
onConversationCreated={(conversationId) => setView({ kind: 'conversation', conversationId })}
|
|
73
|
+
/>
|
|
74
|
+
)}
|
|
75
|
+
{view.kind === 'conversation' && <OutmarketWorkflowConversation conversationId={view.conversationId} />}
|
|
76
|
+
</OutmarketProvider>
|
|
77
|
+
);
|
|
78
|
+
}
|
|
79
|
+
```
|
|
390
80
|
|
|
391
81
|
## API
|
|
392
82
|
|
|
393
|
-
### `<OutmarketProvider
|
|
394
|
-
|
|
395
|
-
| Prop | Type | Required | Description |
|
|
396
|
-
| ----------- | ------------------------------------------ | :------: | ------------------------------------------------------------------------ |
|
|
397
|
-
| `session` | `OutmarketSession` | yes | The 201 body of `POST /api/v1/auth/sessions`, unchanged (see "Sign-in"). |
|
|
398
|
-
| `environment` | `'production' \| 'qa' \| 'staging'` | no | The Outmarket environment. Defaults to `'production'`. Applied once per page load (see [Environments and API URLs](#environments-and-api-urls)). |
|
|
399
|
-
| `apiUrls` | `{ api?: string; nexus?: string; gateway?: string }` | no | Per-API base URL overrides on top of `environment`. Applied once per page load. |
|
|
400
|
-
| `colorMode` | `'light' \| 'dark' \| 'system'` | no | Color theme. Defaults to `'light'`. |
|
|
401
|
-
| `theme` | `{ primary?: string }` | no | Brand accent (hex), mapped onto the surface's primary color. |
|
|
402
|
-
| `onReady` | `(payload: OutmarketReadyPayload) => void` | no | Fires once bootstrap resolves, with the tenant's workflows grouped by module. |
|
|
403
|
-
|
|
404
|
-
### `signOut(options?): Promise<void>`
|
|
405
|
-
|
|
406
|
-
Optional, for your own logout. Clears the session from your origin, and the
|
|
407
|
-
provider then shows its "session has ended" message in every tab. The stored
|
|
408
|
-
session and the session each provider in an open tab is still running stay
|
|
409
|
-
ended: a provider that mounts with one of them again shows the message too, so
|
|
410
|
-
pass a newly minted session for the next sign-in. From a tab that holds the
|
|
411
|
-
stored session it also asks Outmarket to sign the session out, but today that
|
|
412
|
-
request does not revoke it: its tokens stay valid at Outmarket until they
|
|
413
|
-
expire. To end a session at Outmarket, ask Outmarket.
|
|
83
|
+
### `<OutmarketProvider>`
|
|
414
84
|
|
|
415
|
-
|
|
416
|
-
SDK's components itself, which fixes the configuration for the page as it is at
|
|
417
|
-
that moment (see [Environments and API URLs](#environments-and-api-urls)). If
|
|
418
|
-
that can happen and you use a non-production environment, pass the provider's
|
|
419
|
-
values: `await signOut({ environment: 'staging' })` (also accepts `apiUrls`).
|
|
420
|
-
Otherwise the page is fixed to production until it reloads. It rejects only if
|
|
421
|
-
that code cannot load.
|
|
85
|
+
Mount it once and put the components inside it.
|
|
422
86
|
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
| Component | Props | Emits |
|
|
87
|
+
| Prop | Type | Description |
|
|
426
88
|
| --- | --- | --- |
|
|
427
|
-
|
|
|
428
|
-
|
|
|
429
|
-
|
|
|
430
|
-
|
|
|
431
|
-
|
|
432
|
-
The **form is form-only**: it never renders Outmarket's history pane. Mount
|
|
433
|
-
`<OutmarketWorkflowHistory>` wherever you want to show a workflow's past
|
|
434
|
-
conversations, and route its `onSelectConversation` into `<OutmarketWorkflowConversation>`.
|
|
435
|
-
|
|
436
|
-
Real tenant workflow ids arrive through `onReady`, or come straight from
|
|
437
|
-
`onSelectWorkflow`.
|
|
438
|
-
|
|
439
|
-
### Types
|
|
89
|
+
| `session` | `OutmarketSession` | Required. The `201` body from step 4, unchanged. |
|
|
90
|
+
| `onReady` | `({ workflowsByModule }) => void` | Called once the user's workflows have loaded, grouped by module. |
|
|
91
|
+
| `colorMode` | `'light' \| 'dark' \| 'system'` | Color mode of the components. |
|
|
92
|
+
| `theme` | `{ primary?: string }` | Your brand color, as hex. |
|
|
93
|
+
| `apiUrls` | `{ api?, nexus?, gateway? }` | Optional. Paths on your own server that forward to Outmarket's APIs, for example `{ nexus: '/outmarket/nexus/api/v1' }`. |
|
|
440
94
|
|
|
441
|
-
|
|
442
|
-
`OutmarketApiUrls`, `OutmarketWorkflowsListProps`,
|
|
443
|
-
`OutmarketWorkflowFormProps`, `OutmarketWorkflowConversationProps`,
|
|
444
|
-
`OutmarketWorkflowHistoryProps`, `OutmarketModule`, `OutmarketWorkflowInfo`,
|
|
445
|
-
`OutmarketReadyPayload`, `OutmarketConfig` (a reference type for the overridable
|
|
446
|
-
settings, see below), and the `MODULE_TITLE` lookup are all exported from the
|
|
447
|
-
package root.
|
|
95
|
+
### Components
|
|
448
96
|
|
|
449
|
-
|
|
97
|
+
| Component | Props |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| `OutmarketWorkflowsList` | `module`: `'commercial_lines'`, `'personal_lines'` or `'benefits'`. `onSelectWorkflow(workflowId)`: called when the user picks a workflow. |
|
|
100
|
+
| `OutmarketWorkflowForm` | `workflowId`. `onConversationCreated(conversationId)`: called when the user runs the workflow. |
|
|
101
|
+
| `OutmarketWorkflowConversation` | `conversationId`. |
|
|
102
|
+
| `OutmarketWorkflowHistory` | `workflowId`. `onSelectConversation(conversationId)`: called when the user opens a past run. |
|
|
450
103
|
|
|
451
|
-
|
|
104
|
+
The SDK has no routing: your app decides what to show after each callback.
|
|
452
105
|
|
|
453
|
-
|
|
454
|
-
> `apiUrls` props. It documents the older mechanism, which keeps working.
|
|
106
|
+
### `signOut()`
|
|
455
107
|
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
public production defaults at import, under any value already on it. The
|
|
459
|
-
`environment` / `apiUrls` props write their values into it on the first provider
|
|
460
|
-
render. You can also set keys on it yourself, before the first
|
|
461
|
-
`<OutmarketProvider>` renders (setting it before importing the SDK, as earlier
|
|
462
|
-
versions required, still works):
|
|
108
|
+
Call it in your own logout, then discard the session you passed. It clears the session from your
|
|
109
|
+
page; it does not end the session at Outmarket.
|
|
463
110
|
|
|
464
|
-
|
|
465
|
-
// Imported before the SDK in your entry. Prefer the provider props for base URLs.
|
|
466
|
-
globalThis.__OM_EMBED_CONFIG__ = {
|
|
467
|
-
...(globalThis.__OM_EMBED_CONFIG__ ?? {}),
|
|
468
|
-
NEXT_PUBLIC_API_BASE_URL: '/omproxy/api/v1',
|
|
469
|
-
NEXT_PUBLIC_NEXUS_BASE_URL: '/omproxy/nexus/api/v1',
|
|
470
|
-
NEXT_PUBLIC_GATEWAY_BASE_URL: '/omproxy/gateway/api/v1',
|
|
471
|
-
};
|
|
472
|
-
```
|
|
111
|
+
## Sessions
|
|
473
112
|
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
113
|
+
- The SDK keeps the session in your page's `localStorage`, so any script running on that page can
|
|
114
|
+
read it. Protect the page against cross-site scripting (XSS).
|
|
115
|
+
- When a session ends (after 30 days, or if Outmarket ends it), the components show a "session has
|
|
116
|
+
ended" message. Mint a new session the next time the user signs in.
|
|
117
|
+
- A session minted this way is single-factor, so users with two-factor verification turned on are
|
|
118
|
+
asked to open Outmarket directly.
|
|
480
119
|
|
|
481
|
-
|
|
482
|
-
| ----------------------- | ------------------------------------------- |
|
|
483
|
-
| `baseUrls.api` | `NEXT_PUBLIC_API_BASE_URL` (prefer `apiUrls.api`) |
|
|
484
|
-
| `baseUrls.nexus` | `NEXT_PUBLIC_NEXUS_BASE_URL` (prefer `apiUrls.nexus`) |
|
|
485
|
-
| `baseUrls.gateway` | `NEXT_PUBLIC_GATEWAY_BASE_URL` (prefer `apiUrls.gateway`) |
|
|
486
|
-
| `pdfWorkerUrl` | `NEXT_PUBLIC_PDF_WORKER_URL` |
|
|
487
|
-
| `statsigClientKey` | `NEXT_PUBLIC_STATSIG_CLIENT_KEY` |
|
|
488
|
-
| `secureStorageHashKey` | `NEXT_PUBLIC_SECURE_LOCAL_STORAGE_HASH_KEY` |
|
|
489
|
-
| `secureStoragePrefix` | `NEXT_PUBLIC_SECURE_LOCAL_STORAGE_PREFIX` |
|
|
120
|
+
## Errors
|
|
490
121
|
|
|
491
|
-
|
|
492
|
-
**no session token is ever baked into the bundle.**
|
|
122
|
+
Step 4 can answer:
|
|
493
123
|
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
`
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
the demo only on a machine you trust, with a key for a test tenant, and never
|
|
503
|
-
expose its port.
|
|
504
|
-
**Never copy or deploy that route.** A real backend takes the email from its own
|
|
505
|
-
signed-in user and accepts no email from the request.
|
|
124
|
+
| Response | Meaning |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| `403` `key_not_eligible` | The key is revoked or expired, or API access is off for your workspace. |
|
|
127
|
+
| `403` `user_not_eligible` | This user can't be signed in this way. The reason is never given. |
|
|
128
|
+
| `403` `browser_origin_not_allowed` | The call came from a browser. Call from your server. |
|
|
129
|
+
| `403` `{"message": "Source IP not allowed for this API key"}` | Your server's IP isn't in the key's allowed IP addresses. |
|
|
130
|
+
| `429` `rate_limited` | Too many sign-ins. Wait for `Retry-After`, then retry. |
|
|
131
|
+
| `502` `session_unavailable` | No session could be created. Retry later. |
|
package/package.json
CHANGED