@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.
Files changed (2) hide show
  1. package/README.md +113 -487
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,505 +1,131 @@
1
1
  # @outmarket-ai/react-sdk
2
2
 
3
- Embed the **real** Outmarket workflow surface (the workflow catalog, the input
4
- form, and the full conversation with chat, charts, artifacts, citations and the
5
- PDF/source viewer) inside any React 19 application as composable components. The
6
- SDK renders the same components Outmarket ships in-app, against live data. No
7
- Next.js required.
8
-
9
- Outmarket **allow-lists your origin**, so the SDK calls the Outmarket backend
10
- **directly from the browser; no proxy or backend shim is required.** The SDK
11
- targets Outmarket **production** by default, so you configure nothing about the
12
- backend. To use Outmarket's QA or staging environment, or to route a backend
13
- through your own proxy, pass the provider's `environment` and `apiUrls` props
14
- (see [Environments and API URLs](#environments-and-api-urls)).
15
-
16
- ## Install
17
-
18
- The package is public on the npm registry; no npm account or token is needed:
19
-
20
- ```bash
21
- npm install @outmarket-ai/react-sdk
22
- ```
23
-
24
- **License.** Proprietary — see [`LICENSE`](./LICENSE). Being able to download the
25
- package does not grant a right to use it: use requires Outmarket.ai's written
26
- approval, and the package must be used exactly as published (no modification) and
27
- not redistributed, except inside the compiled build of your approved application.
28
-
29
- `react` and `react-dom` (>= 19) are **peer dependencies**: the SDK uses the copy
30
- your app already provides.
31
-
32
- ## Versions and release channels
33
-
34
- The SDK is published on three npm dist-tags:
35
-
36
- | Tag | Builds | Install |
37
- | --- | --- | --- |
38
- | `latest` | **Production.** Published automatically from Outmarket's `release` branch. Use this one. | `npm install @outmarket-ai/react-sdk` |
39
- | `beta` | **QA previews.** Published automatically from Outmarket's `qa-release` branch, ahead of production, as prereleases (`X.Y.Z-beta.N`). | `npm install @outmarket-ai/react-sdk@beta` |
40
- | `alpha` | **Stage builds.** Published automatically from Outmarket's `main` branch (what runs on stage), as prereleases (`X.Y.Z-alpha.N`). The newest and least tested; expect several a day. | `npm install @outmarket-ai/react-sdk@alpha` |
41
-
42
- Versions follow semver: a breaking change bumps the major version, a new
43
- feature the minor, and a fix the patch. A push to any of these branches
44
- publishes a new version only when the package's contents change. Alpha and beta
45
- numbers are independent (`1.3.0-alpha.7` and `1.3.0-beta.0` can coexist). A
46
- range such as `^1.2.0` never resolves to a prerelease; install one by its tag or
47
- exact version.
48
-
49
- ## Sign-in: the session your backend mints
50
-
51
- Your user signs in to your app. Your **backend** then asks Outmarket for that
52
- user's session and hands it to your page, which passes it to the SDK unchanged.
53
-
54
- ### 1. Mint the session on your server
55
-
56
- ```bash
57
- curl -X POST https://gateway.outmarket.ai/api/v1/auth/sessions \
58
- -H "Authorization: Bearer $OM_EMBED_API_KEY" \
59
- -H 'Content-Type: application/json' \
60
- -d '{"email":"jane@example.com"}'
61
- ```
62
-
63
- - **The API key stays on your server.** A tenant admin creates it in Outmarket
64
- with the `auth` scope (a full-access `*` key works too; give this key no
65
- more than it needs) and an IP allowlist of your servers' static egress IPs,
66
- each entry no wider than /16 for IPv4 or /32 for IPv6. Creating that key is
67
- how a tenant opts in to user sign-in; there is nothing else to turn on.
68
- Never send the key to a browser, and never put it in a variable your bundler
69
- exposes to the page (`VITE_*`, `NEXT_PUBLIC_*` and the like). Requests from a
70
- browser are refused.
71
- - **Take the email from your own server-side record of the signed-in user**,
72
- and only an address your app has verified that user owns: a confirmed email,
73
- or a verified claim from your identity provider. Look it up on your server
74
- from the user's id in your session. Never take it from a request body, a
75
- query string, a cookie the browser can set, or a profile field the user can
76
- change without verifying it again. Whoever can make your backend mint for an
77
- email acts as that member, tenant Admins and SuperAdmins included. The user
78
- must already be a member of the tenant the key belongs to. Some members get
79
- `user_not_eligible` instead, among them BillingAdmins and Outmarket accounts.
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>`: mount once
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
- Called before any `<OutmarketProvider>` has rendered on the page, it loads the
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
- ### The surface components
424
-
425
- | Component | Props | Emits |
87
+ | Prop | Type | Description |
426
88
  | --- | --- | --- |
427
- | `<OutmarketWorkflowsList>` | `module: 'commercial_lines' \| 'personal_lines' \| 'benefits'` | `onSelectWorkflow(workflowId)` |
428
- | `<OutmarketWorkflowForm>` | `workflowId: string` | `onConversationCreated(conversationId)` (the form shows a spinner) |
429
- | `<OutmarketWorkflowConversation>` | `conversationId: string` | Nothing (renders chat, charts, artifacts, citations, PDF/source) |
430
- | `<OutmarketWorkflowHistory>` | `workflowId: string` | `onSelectConversation(conversationId)` |
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
- `OutmarketSession`, `OutmarketProviderProps`, `OutmarketEnvironment`,
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
- ## Advanced: the config global
104
+ The SDK has no routing: your app decides what to show after each callback.
452
105
 
453
- > Most apps do not need this section: use the provider's `environment` and
454
- > `apiUrls` props. It documents the older mechanism, which keeps working.
106
+ ### `signOut()`
455
107
 
456
- The SDK resolves all runtime configuration from a single global,
457
- `globalThis.__OM_EMBED_CONFIG__` (raw `NEXT_PUBLIC_*` keys), seeded with the
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
- ```ts
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
- When the provider gets `environment` or `apiUrls`, its values win over the
475
- global's for the keys a preset sets (the base URLs, the app environment, and the
476
- client keys and flags of that environment); a key no preset sets, such as
477
- `NEXT_PUBLIC_PDF_WORKER_URL`, keeps your value. Without either prop, the provider uses the global as it is. Like the
478
- props, the global is read once per page load, when the SDK's components load.
479
- The `OutmarketConfig` type documents each setting and the raw key you set for it:
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
- | `OutmarketConfig` field | Raw key on `__OM_EMBED_CONFIG__` |
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
- All defaults are client-public (public hostnames and `NEXT_PUBLIC` client keys);
492
- **no session token is ever baked into the bundle.**
122
+ Step 4 can answer:
493
123
 
494
- See `host-demo/` for a runnable example that points the SDK at a local `/omproxy`
495
- stage proxy with `environment="staging"` and `/omproxy` `apiUrls`. Its dev server stands in for your backend: start it with
496
- `OM_EMBED_API_KEY` set and it mints sessions at `POST /host-api/embed-session`
497
- (`host-demo/mint-embed-session.mjs` does the same from the command line). That
498
- route mints a session for any email it is sent, tenant Admins and SuperAdmins
499
- included. It turns away other machines and other sites' pages, but not other
500
- programs on your machine: its checks read headers that any local program can
501
- set, and so can a tunnel or proxy that forwards to it from this machine. Run
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@outmarket-ai/react-sdk",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0-alpha.2",
4
4
  "description": "Embed the real Outmarket workflow surface (catalog + single workflow) in any React app.",
5
5
  "private": false,
6
6
  "type": "module",