@reopt-ai/brandapp-sdk 4.6.0 → 4.7.0-rc.1
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/CHANGELOG.md +49 -1
- package/README.md +13 -13
- package/dist/ai/index.d.ts +1 -1
- package/dist/ai/index.js +1 -1
- package/dist/ai-provider/index.d.ts +1 -1
- package/dist/ai-provider/index.js +1 -1
- package/dist/analytics/index.d.ts +1 -1
- package/dist/analytics/index.js +1 -1
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.js +1 -1
- package/dist/better-auth/index.d.ts +8 -2
- package/dist/better-auth/index.js +19 -5
- package/dist/{client-CI2Y00Qx.js → client-BFl6cDAE.js} +23 -2
- package/dist/{client-tJq0U_jn.js → client-BJQzInqD.js} +4 -4
- package/dist/{client-IUSZDJio.d.ts → client-BQJepjoD.d.ts} +44 -4
- package/dist/{client-C2xE9HGZ.js → client-BZ8-vFjk.js} +4 -4
- package/dist/{client-DjLhTNsZ.js → client-Bf8mW6uO.js} +3 -3
- package/dist/client-C-LdW4gY.js +194 -0
- package/dist/{client-C6OXGMMV.d.ts → client-C2W4RAZV.d.ts} +2 -2
- package/dist/{client-7I-mz3Dw.d.ts → client-C6lx3RUQ.d.ts} +2 -2
- package/dist/{client-Ce0gs5Ma.js → client-CLZie3Ym.js} +2 -2
- package/dist/{client-yKeRJnIB.d.ts → client-CSl3o0s3.d.ts} +2 -2
- package/dist/{client-D1AFtJRw.d.ts → client-Cnq_X3Wp.d.ts} +2 -2
- package/dist/{client-Bfutv3LK.d.ts → client-Cod87ThY.d.ts} +2 -2
- package/dist/{client-BSW0Ncjj.d.ts → client-CsWSxMhB.d.ts} +2 -2
- package/dist/{client-eDd4aWDs.js → client-CslasnqK.js} +2 -2
- package/dist/{client-FM6_YJbr.js → client-DGKq4Ml5.js} +3 -3
- package/dist/{client-BzAgabAs.js → client-Db6Etco9.js} +2 -2
- package/dist/{client-Dmvtr1nS.d.ts → client-DfnaH99z.d.ts} +2 -2
- package/dist/{client-COKDtHO9.d.ts → client-MDNS9Ubf.d.ts} +2 -2
- package/dist/{client-DCqp0Bis.js → client-VKEJtLH0.js} +2 -2
- package/dist/{client-DeC127BD.js → client-_2Avom0q.js} +2 -2
- package/dist/{client-CniCGdmi.d.ts → client-xblzWFAL.d.ts} +2 -2
- package/dist/cms/index.d.ts +1 -1
- package/dist/cms/index.js +1 -1
- package/dist/{config-D3SblxWt.d.ts → config-CnFnzh7Q.d.ts} +21 -6
- package/dist/{config-BeOelISH.js → config-Dy2oBn1a.js} +13 -10
- package/dist/dev/index.d.ts +1 -1
- package/dist/eav/index.d.ts +2 -2
- package/dist/eav/index.js +2 -2
- package/dist/eav/migrate.d.ts +2 -2
- package/dist/eav/schema.d.ts +2 -2
- package/dist/feedback/index.d.ts +1 -1
- package/dist/feedback/index.js +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +1 -1
- package/dist/{http-client-Bl8u1vHN.js → http-client-CW9wXANY.js} +9 -3
- package/dist/{index-BnAYxnwq.d.ts → index-Bkci7euU.d.ts} +14 -12
- package/dist/{index-C6fyJTud.d.ts → index-Dh8XMVFF.d.ts} +2 -2
- package/dist/index.d.ts +4 -4
- package/dist/index.js +12 -12
- package/dist/keys-B2pA8EkU.d.ts +44 -0
- package/dist/keys-B_R_lsyF.js +102 -0
- package/dist/logout/index.d.ts +1 -1
- package/dist/logout/index.js +1 -1
- package/dist/machine/index.d.ts +72 -0
- package/dist/machine/index.js +4 -0
- package/dist/machine/keygen-cli.d.ts +7 -0
- package/dist/machine/keygen-cli.js +57 -0
- package/dist/plans/index.d.ts +2 -2
- package/dist/plans/index.js +1 -1
- package/dist/push/index.d.ts +1 -1
- package/dist/push/index.js +1 -1
- package/dist/{query-JPVK_8N5.js → query-DPD0WYlB.js} +2 -2
- package/dist/react/hooks.d.ts +4 -4
- package/dist/terms/index.d.ts +1 -1
- package/dist/terms/index.js +1 -1
- package/dist/testing/index.d.ts +2 -2
- package/dist/workspace/index.d.ts +39 -9
- package/dist/workspace/index.js +51 -9
- package/docs/api-reference.md +43 -24
- package/docs/dev-server.md +2 -2
- package/docs/environment.md +4 -4
- package/docs/machine.md +104 -0
- package/docs/workspace.md +12 -0
- package/package.json +17 -3
package/docs/api-reference.md
CHANGED
|
@@ -2,30 +2,31 @@
|
|
|
2
2
|
|
|
3
3
|
## Entry Points
|
|
4
4
|
|
|
5
|
-
| Import Path | Purpose
|
|
6
|
-
| ------------------------------------------- |
|
|
7
|
-
| `@reopt-ai/brandapp-sdk` | Core SDK, errors, singleton
|
|
8
|
-
| `@reopt-ai/brandapp-sdk/ai` | AI client (types, ReoptAiClient)
|
|
9
|
-
| `@reopt-ai/brandapp-sdk/auth` | User-scoped auth + cross-subdomain session helpers
|
|
10
|
-
| `@reopt-ai/brandapp-sdk/files` | File client + image URL helpers
|
|
11
|
-
| `@reopt-ai/brandapp-sdk/ai-provider` | Vercel AI SDK LanguageModelV3 provider
|
|
12
|
-
| `@reopt-ai/brandapp-sdk/eav` | EAV client, types, filter builder
|
|
13
|
-
| `@reopt-ai/brandapp-sdk/eav/schema` | Schema definition, diff, sync, JSON Schema
|
|
14
|
-
| `@reopt-ai/brandapp-sdk/eav/coerce` | Value coercion helpers
|
|
15
|
-
| `@reopt-ai/brandapp-sdk/better-auth` | Better Auth adapter + OAuth (server)
|
|
16
|
-
| `@reopt-ai/brandapp-sdk/better-auth/client` | OAuth client (browser)
|
|
17
|
-
| `@reopt-ai/brandapp-sdk/react/hooks` | TanStack Query hooks
|
|
18
|
-
| `@reopt-ai/brandapp-sdk/webhooks` | Webhook handler (HMAC verify, replay check)
|
|
19
|
-
| `@reopt-ai/brandapp-sdk/dev` | In-memory dev server (offline development)
|
|
20
|
-
| `@reopt-ai/brandapp-sdk/testing` | `createTestSDK` for Vitest fixtures
|
|
21
|
-
| `@reopt-ai/brandapp-sdk/cms` | CMS posts/post-groups/tags (read-only) + SEO / Sitemap / RSS helpers + `EditorSpec`
|
|
22
|
-
| `@reopt-ai/brandapp-sdk/terms` | Terms list (with `contentRich`), consent, withdraw
|
|
23
|
-
| `@reopt-ai/brandapp-sdk/plans` | Plan catalog + current plan + hosted checkout (subscribe/pay/cancel)
|
|
24
|
-
| `@reopt-ai/brandapp-sdk/push` | Customer device FCM/APNs token register/unregister/list
|
|
25
|
-
| `@reopt-ai/brandapp-sdk/feedback` | Customer feedback submission
|
|
26
|
-
| `@reopt-ai/brandapp-sdk/logout` | OIDC Single Logout — back-channel receiver + RP-initiated end-session
|
|
27
|
-
| `@reopt-ai/brandapp-sdk/eav/migrate` | EAV schema migration runner (`defineMigration`, `runMigrations`)
|
|
28
|
-
| `@reopt-ai/brandapp-sdk/workspace` | Platform API — workspace work tasks, webhooks, declarative resources (server-only)
|
|
5
|
+
| Import Path | Purpose |
|
|
6
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
7
|
+
| `@reopt-ai/brandapp-sdk` | Core SDK, errors, singleton |
|
|
8
|
+
| `@reopt-ai/brandapp-sdk/ai` | AI client (types, ReoptAiClient) |
|
|
9
|
+
| `@reopt-ai/brandapp-sdk/auth` | User-scoped auth + cross-subdomain session helpers |
|
|
10
|
+
| `@reopt-ai/brandapp-sdk/files` | File client + image URL helpers |
|
|
11
|
+
| `@reopt-ai/brandapp-sdk/ai-provider` | Vercel AI SDK LanguageModelV3 provider |
|
|
12
|
+
| `@reopt-ai/brandapp-sdk/eav` | EAV client, types, filter builder |
|
|
13
|
+
| `@reopt-ai/brandapp-sdk/eav/schema` | Schema definition, diff, sync, JSON Schema |
|
|
14
|
+
| `@reopt-ai/brandapp-sdk/eav/coerce` | Value coercion helpers |
|
|
15
|
+
| `@reopt-ai/brandapp-sdk/better-auth` | Better Auth adapter + OAuth (server) |
|
|
16
|
+
| `@reopt-ai/brandapp-sdk/better-auth/client` | OAuth client (browser) |
|
|
17
|
+
| `@reopt-ai/brandapp-sdk/react/hooks` | TanStack Query hooks |
|
|
18
|
+
| `@reopt-ai/brandapp-sdk/webhooks` | Webhook handler (HMAC verify, replay check) |
|
|
19
|
+
| `@reopt-ai/brandapp-sdk/dev` | In-memory dev server (offline development) |
|
|
20
|
+
| `@reopt-ai/brandapp-sdk/testing` | `createTestSDK` for Vitest fixtures |
|
|
21
|
+
| `@reopt-ai/brandapp-sdk/cms` | CMS posts/post-groups/tags (read-only) + SEO / Sitemap / RSS helpers + `EditorSpec` |
|
|
22
|
+
| `@reopt-ai/brandapp-sdk/terms` | Terms list (with `contentRich`), consent, withdraw |
|
|
23
|
+
| `@reopt-ai/brandapp-sdk/plans` | Plan catalog + current plan + hosted checkout (subscribe/pay/cancel) |
|
|
24
|
+
| `@reopt-ai/brandapp-sdk/push` | Customer device FCM/APNs token register/unregister/list |
|
|
25
|
+
| `@reopt-ai/brandapp-sdk/feedback` | Customer feedback submission |
|
|
26
|
+
| `@reopt-ai/brandapp-sdk/logout` | OIDC Single Logout — back-channel receiver + RP-initiated end-session |
|
|
27
|
+
| `@reopt-ai/brandapp-sdk/eav/migrate` | EAV schema migration runner (`defineMigration`, `runMigrations`) |
|
|
28
|
+
| `@reopt-ai/brandapp-sdk/workspace` | Platform API — workspace work tasks, webhooks, declarative resources (server-only) |
|
|
29
|
+
| `@reopt-ai/brandapp-sdk/machine` | Machine credentials — `private_key_jwt` + DPoP client, key generation, JWKS (server-only) |
|
|
29
30
|
|
|
30
31
|
> `/workspace` is a different surface — workspace scope instead of brandapp scope, its own host
|
|
31
32
|
> and audience, server-only. It has its own page: [`workspace.md`](./workspace.md).
|
|
@@ -595,6 +596,11 @@ const plans: Plan[] = await sdk.plans.list();
|
|
|
595
596
|
// The current customer's plan / entitlement (Bearer). null if none.
|
|
596
597
|
const current: CurrentPlan | null = await sdk.plans.getMyPlan(accessToken);
|
|
597
598
|
|
|
599
|
+
// The same answer for one customer with app credentials — no customer token.
|
|
600
|
+
// For background jobs, device/API-token requests, or expired customer tokens.
|
|
601
|
+
// authUserId is your Better Auth session.user.id. Server-only.
|
|
602
|
+
const theirs: CurrentPlan | null = await sdk.plans.getCustomerPlan(authUserId);
|
|
603
|
+
|
|
598
604
|
// Hosted checkout (Bearer). In sandbox mode checkoutUrl is an id.reopt.ai
|
|
599
605
|
// virtual-payment page; redirect the browser there.
|
|
600
606
|
try {
|
|
@@ -630,6 +636,19 @@ canceled.providerCanceled; // false → local subscription is definitely over (n
|
|
|
630
636
|
> simply omits them. Apple/Google (IAP) subscriptions are canceled in the store,
|
|
631
637
|
> so no remote call is made and `providerCanceled` stays `false`.
|
|
632
638
|
|
|
639
|
+
> `getCustomerPlan` and the store mirror (`PUT /plans/external-subscription`) are
|
|
640
|
+
> **app-credential routes**: the platform rejects a customer access token on them
|
|
641
|
+
> with 403 `APP_CREDENTIAL_REQUIRED`, whatever scopes that token carries. Call
|
|
642
|
+
> them from your server with Basic credentials or a `/token/mint` service token.
|
|
643
|
+
> `getCustomerPlan` throws 404 when that user has no customer link to the Brandapp
|
|
644
|
+
> (`NOT_FOUND`), and 404 with code `CUSTOMER_WITHDRAWN` when they withdrew.
|
|
645
|
+
|
|
646
|
+
> `CurrentPlan.paymentEnvironment` (`"live" | "test" | "simulation" | null`) says how the
|
|
647
|
+
> current plan was paid for and survives cancellation. Gate on it rather than on
|
|
648
|
+
> `paymentProvider`, which reads from the **active** payment link only and turns
|
|
649
|
+
> `null` the moment a customer cancels. `null` means unknown (a plan that did not
|
|
650
|
+
> come from a hosted checkout), not "unpaid".
|
|
651
|
+
|
|
633
652
|
> Live **Paddle** checkout runs through the same `createCheckout` since 3.4 —
|
|
634
653
|
> `checkoutUrl` is then a Paddle-hosted payment page (zero-price plans keep the
|
|
635
654
|
> sandbox session flow). Live **Toss** stays in the first-party brandfront flow:
|
package/docs/dev-server.md
CHANGED
|
@@ -44,7 +44,7 @@ const dev = await createDevServer({
|
|
|
44
44
|
verbose: true, // 상세 로그
|
|
45
45
|
proxy: {
|
|
46
46
|
// 선택적 원격 프록시
|
|
47
|
-
remoteUrl: "https://brand.reopt.
|
|
47
|
+
remoteUrl: "https://brand.local.reopt.io",
|
|
48
48
|
remoteCredentials: { clientId, clientSecret, brandappId },
|
|
49
49
|
routes: { ai: "passthrough" }, // AI만 원격, 나머지 로컬
|
|
50
50
|
},
|
|
@@ -102,7 +102,7 @@ AI 호출만 실제 서버로 보내고 나머지는 로컬에서 처리:
|
|
|
102
102
|
const dev = await createDevServer({
|
|
103
103
|
schema,
|
|
104
104
|
proxy: {
|
|
105
|
-
remoteUrl: "https://brand.reopt.
|
|
105
|
+
remoteUrl: "https://brand.local.reopt.io",
|
|
106
106
|
remoteCredentials: {
|
|
107
107
|
clientId: process.env.BRANDAPP_CLIENT_ID!,
|
|
108
108
|
clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
|
package/docs/environment.md
CHANGED
|
@@ -39,7 +39,7 @@ BRANDAPP_ID=01HQ8K...
|
|
|
39
39
|
|
|
40
40
|
| 변수 | Tier | 용도 | 안 주면 |
|
|
41
41
|
| ------------------------- | -------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
42
|
-
| `REOPT_BASE_URL` | 플랫폼 | 메인 API host override (EAV / AI / Files / CMS / Terms / external-auth 라우트) | prod: `https://brandapp.reopt.ai`, dev: `https://brand.reopt.
|
|
42
|
+
| `REOPT_BASE_URL` | 플랫폼 | 메인 API host override (EAV / AI / Files / CMS / Terms / external-auth 라우트) | prod: `https://brandapp.reopt.ai`, dev: `https://brand.local.reopt.io` (`NODE_ENV` 자동) |
|
|
43
43
|
| `REOPT_ID_BASE_URL` | 플랫폼 | 인증 host override (`/api/auth/*`, OIDC userinfo, Better Auth discovery) | `REOPT_BASE_URL`에서 자동 유도 (`brandapp.reopt.ai → id.reopt.ai`); 둘 다 없으면 `NODE_ENV` 분기 |
|
|
44
44
|
| `BRANDAPP_WEBHOOK_SECRET` | consumer | webhook HMAC 검증 | SDK 내부에서 자동 read 안 함 — `createWebhookHandler({ secret })`에 명시 주입 |
|
|
45
45
|
| `BRANDAPP_SDK_DEBUG` | SDK | 디버그 로그 레벨 (`trace` \| `info` \| `1`) | off (`DEBUG=*brandapp*`도 fallback으로 인식) |
|
|
@@ -63,12 +63,12 @@ BRANDAPP_ID=01HQ8K...
|
|
|
63
63
|
|
|
64
64
|
| 상황 | 메인 API host (`resolveBaseUrl`) | 인증 host (`resolveIdBaseUrl`) |
|
|
65
65
|
| -------------------------------------------- | -------------------------------- | ------------------------------------- |
|
|
66
|
-
| env 없음 + `NODE_ENV=development` | `https://brand.reopt.
|
|
66
|
+
| env 없음 + `NODE_ENV=development` | `https://brand.local.reopt.io` | `https://id.local.reopt.io` |
|
|
67
67
|
| env 없음 + `NODE_ENV=production` | `https://brandapp.reopt.ai` | `https://id.reopt.ai` |
|
|
68
68
|
| `REOPT_BASE_URL=https://my.host:3000`만 설정 | `https://my.host:3000` | `https://id.my.host:3000` (자동 유도) |
|
|
69
69
|
| `config.baseUrl: "https://x"` 인자 | `https://x` (env 무시) | `https://id.x` (자동 유도) |
|
|
70
70
|
| `config.baseUrl` + `REOPT_BASE_URL` 둘 다 | `config.baseUrl` (인자 최우선) | `config.baseUrl`에서 유도 |
|
|
71
|
-
| `config.isProduction: false` 강제 (env 없음) | `https://brand.reopt.
|
|
71
|
+
| `config.isProduction: false` 강제 (env 없음) | `https://brand.local.reopt.io` | `https://id.local.reopt.io` |
|
|
72
72
|
|
|
73
73
|
> on-prem 단일 호스트 (web + auth가 같은 도메인): `config.idBaseUrl: baseUrl` 한 줄로 해결.
|
|
74
74
|
|
|
@@ -157,7 +157,7 @@ export default async function Page() {
|
|
|
157
157
|
|
|
158
158
|
→ `NODE_ENV=production`이 설정되어 있을 수 있음. Next.js는 `next dev`에서
|
|
159
159
|
자동으로 `development`이지만, CI / 컨테이너에서는 override될 수 있음. 명시적으로
|
|
160
|
-
`config.isProduction: false` 또는 `REOPT_BASE_URL=https://brand.reopt.
|
|
160
|
+
`config.isProduction: false` 또는 `REOPT_BASE_URL=https://brand.local.reopt.io` 설정.
|
|
161
161
|
|
|
162
162
|
### `REOPT_BASE_URL`은 줬는데 OAuth/auth가 안 됨
|
|
163
163
|
|
package/docs/machine.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Machine credentials — `@reopt-ai/brandapp-sdk/machine`
|
|
2
|
+
|
|
3
|
+
Server-to-server calls into Reopt (the brandapp API, the platform API, the remote auth
|
|
4
|
+
adapter) authenticate with an **asymmetric client credential** instead of a shared secret
|
|
5
|
+
(RFC-0034). The client signs a `private_key_jwt` assertion (RFC 7523) with a private key that
|
|
6
|
+
never leaves its server, and every access token is **DPoP-bound** (RFC 9449): a stolen token is
|
|
7
|
+
useless without the key that minted its proof.
|
|
8
|
+
|
|
9
|
+
**Server-only.** `createMachineClient()` throws in a browser.
|
|
10
|
+
|
|
11
|
+
## 1. Generate a key
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npx --package @reopt-ai/brandapp-sdk reopt-keygen
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It prints one env line — `REOPT_CLIENT_PRIVATE_KEY_JWK='{…}'` — and nothing else contains the key.
|
|
18
|
+
Put it in your server env (never a browser bundle, log or commit). The `kid` is the JWK
|
|
19
|
+
thumbprint, so the same key always has the same id.
|
|
20
|
+
|
|
21
|
+
## 2. Publish the public key
|
|
22
|
+
|
|
23
|
+
Reopt fetches your JWKS from the `jwksUri` registered on the OAuth client (cached for five
|
|
24
|
+
minutes). Serve it at the canonical path:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
// app/.well-known/reopt-client-jwks.json/route.ts (Next.js)
|
|
28
|
+
import {
|
|
29
|
+
buildClientJwks,
|
|
30
|
+
readClientKeyRing,
|
|
31
|
+
} from "@reopt-ai/brandapp-sdk/machine";
|
|
32
|
+
|
|
33
|
+
export const GET = () => {
|
|
34
|
+
const ring = readClientKeyRing();
|
|
35
|
+
return ring
|
|
36
|
+
? Response.json(buildClientJwks(ring.published))
|
|
37
|
+
: new Response(null, { status: 404 });
|
|
38
|
+
};
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`CLIENT_JWKS_PATH` is `/.well-known/reopt-client-jwks.json`; register
|
|
42
|
+
`${origin}${CLIENT_JWKS_PATH}` as the client's `jwksUri` (platform console, or
|
|
43
|
+
`oauthClients.upsert({ tokenEndpointAuthMethod: "private_key_jwt", jwksUri })`).
|
|
44
|
+
|
|
45
|
+
## 3. Call Reopt
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import {
|
|
49
|
+
createMachineClient,
|
|
50
|
+
readClientKeyRing,
|
|
51
|
+
} from "@reopt-ai/brandapp-sdk/machine";
|
|
52
|
+
import { createReoptSDK } from "@reopt-ai/brandapp-sdk";
|
|
53
|
+
|
|
54
|
+
const machine = createMachineClient({
|
|
55
|
+
clientId: process.env.REOPT_CLIENT_ID!,
|
|
56
|
+
keyRing: readClientKeyRing()!, // or privateKeyJwk: {...}
|
|
57
|
+
resource: "https://brandapp.reopt.ai", // the token's audience — exactly one
|
|
58
|
+
scopes: ["brandapp:read", "eav:read"],
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
// a) hand the headers to the brandapp SDK
|
|
62
|
+
const sdk = createReoptSDK({
|
|
63
|
+
brandappId: process.env.REOPT_BRANDAPP_ID!,
|
|
64
|
+
authorization: machine.headers, // Authorization: DPoP … + DPoP proof per request
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
// b) or call any URL under the resource yourself
|
|
68
|
+
const res = await machine.fetch(
|
|
69
|
+
"https://brandapp.reopt.ai/api/v1/brandapp/<id>/eav/entities",
|
|
70
|
+
);
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
| Method | What it does |
|
|
74
|
+
| -------------------------- | ---------------------------------------------------------------------------------- |
|
|
75
|
+
| `getToken(force?)` | Cached access token, renewed 60 s before expiry; `force` discards the cache |
|
|
76
|
+
| `headers({ method, url })` | `Authorization` + `DPoP` for **that** request — the proof is bound to method + URL |
|
|
77
|
+
| `fetch(url, init?)` | `fetch` with the headers attached; a 401 refreshes the token once and retries |
|
|
78
|
+
| `invalidateToken()` | Drop the cached token (tests, diagnostics) |
|
|
79
|
+
| `kid` | The signing key's id — what Reopt will see after a rotation |
|
|
80
|
+
|
|
81
|
+
Errors are `MachineTokenError` with `code` (the server's `error`, or `token_error`) and
|
|
82
|
+
`status`. If the token endpoint hands back a Bearer token although DPoP was requested the
|
|
83
|
+
client refuses it with `dpop_not_bound` — set `dpopBoundAccessTokens` on the client.
|
|
84
|
+
|
|
85
|
+
## Rotation
|
|
86
|
+
|
|
87
|
+
1. Generate a second key and set it as `REOPT_CLIENT_PRIVATE_KEY_JWK_NEXT`. The JWKS now
|
|
88
|
+
lists both keys and signing moves to NEXT (`client.kid` changes). Reopt picks the new key up
|
|
89
|
+
within five minutes.
|
|
90
|
+
2. Move the NEXT value into `REOPT_CLIENT_PRIVATE_KEY_JWK` and delete NEXT. The old key is gone
|
|
91
|
+
from the JWKS, so any copy of it is dead.
|
|
92
|
+
|
|
93
|
+
`readClientKeyRing()` refuses a NEXT key with the same `kid` as the current one.
|
|
94
|
+
|
|
95
|
+
## Scopes and purposes
|
|
96
|
+
|
|
97
|
+
A token carries one audience (`resource`) and only the scopes the client row allows for it.
|
|
98
|
+
Machine clients are registered with a `purpose` — `machine` for server calls, `adapter` for the
|
|
99
|
+
remote Better Auth adapter (`brandapp:auth-adapter` only). Login clients (`web`, `connect`) are
|
|
100
|
+
never accepted on machine surfaces, so a leaked login secret cannot read your users' sessions.
|
|
101
|
+
|
|
102
|
+
The platform client (`@reopt-ai/brandapp-sdk/workspace`) and the OAuth login plugin
|
|
103
|
+
(`createReoptOAuth({ tokenEndpointAuthMethod: "private_key_jwt" })`) use the same key ring —
|
|
104
|
+
see [`workspace.md`](./workspace.md).
|
package/docs/workspace.md
CHANGED
|
@@ -35,6 +35,18 @@ const me = await platform.me(); // { workspaceId, source, scopes, … }
|
|
|
35
35
|
The token is cached, renewed 60s before expiry, and re-fetched once on a 401. Never ship these
|
|
36
36
|
values to a browser bundle.
|
|
37
37
|
|
|
38
|
+
**Prefer a private key over a secret** (RFC-0034). With `privateKeyJwk` / `keyRing` — or
|
|
39
|
+
`REOPT_CLIENT_PRIVATE_KEY_JWK` in the env — the client authenticates with a `private_key_jwt`
|
|
40
|
+
assertion and every request carries a DPoP proof; `clientSecret` is then not needed. Generate
|
|
41
|
+
the key with `reopt-keygen` and publish the JWKS as described in [`machine.md`](./machine.md).
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
const platform = createPlatformClient({
|
|
45
|
+
clientId: process.env.REOPT_PLATFORM_CLIENT_ID!,
|
|
46
|
+
keyRing: readClientKeyRing()!, // from "@reopt-ai/brandapp-sdk/machine"
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
38
50
|
| Config | Default |
|
|
39
51
|
| ------------- | ----------------------------------------------------------- |
|
|
40
52
|
| `platformUrl` | `REOPT_PLATFORM_URL` → `https://platform.reopt.ai` |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@reopt-ai/brandapp-sdk",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.7.0-rc.1",
|
|
4
4
|
"description": "Reopt Brandapp SDK — Better Auth adapter, OAuth login, and EAV client",
|
|
5
5
|
"author": "Reopt",
|
|
6
6
|
"license": "MIT",
|
|
@@ -93,6 +93,10 @@
|
|
|
93
93
|
"types": "./dist/workspace/index.d.ts",
|
|
94
94
|
"import": "./dist/workspace/index.js"
|
|
95
95
|
},
|
|
96
|
+
"./machine": {
|
|
97
|
+
"types": "./dist/machine/index.d.ts",
|
|
98
|
+
"import": "./dist/machine/index.js"
|
|
99
|
+
},
|
|
96
100
|
"./dev": {
|
|
97
101
|
"types": "./dist/dev/index.d.ts",
|
|
98
102
|
"import": "./dist/dev/index.js"
|
|
@@ -123,7 +127,8 @@
|
|
|
123
127
|
"hono": ">=4.0.0",
|
|
124
128
|
"react": ">=18.0.0",
|
|
125
129
|
"@reopt-ai/data-sdk": ">=0.1.1",
|
|
126
|
-
"zod": ">=4.0.0"
|
|
130
|
+
"zod": ">=4.0.0",
|
|
131
|
+
"@better-auth/core": ">=1.7.7"
|
|
127
132
|
},
|
|
128
133
|
"peerDependenciesMeta": {
|
|
129
134
|
"@ai-sdk/provider": {
|
|
@@ -149,10 +154,13 @@
|
|
|
149
154
|
},
|
|
150
155
|
"zod": {
|
|
151
156
|
"optional": true
|
|
157
|
+
},
|
|
158
|
+
"@better-auth/core": {
|
|
159
|
+
"optional": true
|
|
152
160
|
}
|
|
153
161
|
},
|
|
154
162
|
"devDependencies": {
|
|
155
|
-
"@ai-sdk/provider": "4.0.
|
|
163
|
+
"@ai-sdk/provider": "4.0.24",
|
|
156
164
|
"@reopt-ai/opt-editor": "2.0.0",
|
|
157
165
|
"@testing-library/react": "^16.3.2",
|
|
158
166
|
"@types/node": "22.13.9",
|
|
@@ -184,6 +192,12 @@
|
|
|
184
192
|
"engines": {
|
|
185
193
|
"node": ">=18"
|
|
186
194
|
},
|
|
195
|
+
"bin": {
|
|
196
|
+
"reopt-keygen": "./dist/machine/keygen-cli.js"
|
|
197
|
+
},
|
|
198
|
+
"dependencies": {
|
|
199
|
+
"jose": "^6.2.3"
|
|
200
|
+
},
|
|
187
201
|
"scripts": {
|
|
188
202
|
"build": "tsdown",
|
|
189
203
|
"dev": "tsdown --watch",
|