@reopt-ai/brandapp-sdk 4.4.0 → 4.5.0
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 +39 -0
- package/README.md +1 -0
- package/dist/ai/index.js +1 -1
- package/dist/ai-provider/index.js +1 -1
- package/dist/analytics/index.js +1 -1
- package/dist/auth/index.js +1 -1
- package/dist/better-auth/index.js +2 -2
- package/dist/{client-afAv7Ebi.js → client-BlKXDOUb.js} +4 -4
- package/dist/{client-EG1p7FL0.js → client-BnRfa5hI.js} +2 -2
- package/dist/{client-D_6WdWsc.js → client-CU9KBiDi.js} +3 -3
- package/dist/{client-DuATTvcr.js → client-Cg_gl0Gk.js} +2 -2
- package/dist/{client-s2uJ3OML.js → client-D9QA4f3H.js} +2 -2
- package/dist/{client-C4sDbXto.js → client-DLvWSpaz.js} +4 -4
- package/dist/{client-CuM8MNS5.js → client-NQ0p6XSB.js} +2 -2
- package/dist/{client-DsM84EZZ.js → client-d0EwZNc4.js} +3 -3
- package/dist/{client-mD6o-qVl.js → client-ijQDMf1X.js} +2 -2
- package/dist/{client-DYkDNPyN.js → client-p-tpQ1xj.js} +2 -2
- package/dist/cms/index.js +1 -1
- package/dist/{config-C_OFYAgP.js → config-DCFgtfSu.js} +2 -2
- package/dist/eav/index.js +2 -2
- package/dist/feedback/index.js +1 -1
- package/dist/files/index.js +1 -1
- package/dist/{http-client-BUbFBOvG.js → http-client-CHXNS9TI.js} +2 -2
- package/dist/index.js +12 -12
- package/dist/logout/index.js +1 -1
- package/dist/plans/index.js +1 -1
- package/dist/push/index.js +1 -1
- package/dist/{query-BkdTSuB5.js → query-ZVC28Rp8.js} +2 -2
- package/dist/terms/index.js +1 -1
- package/dist/webhooks/index.d.ts +25 -2
- package/dist/workspace/index.d.ts +602 -0
- package/dist/workspace/index.js +688 -0
- package/docs/api-reference.md +5 -1
- package/docs/workspace.md +141 -0
- package/package.json +10 -2
package/docs/api-reference.md
CHANGED
|
@@ -25,6 +25,10 @@
|
|
|
25
25
|
| `@reopt-ai/brandapp-sdk/feedback` | Customer feedback submission |
|
|
26
26
|
| `@reopt-ai/brandapp-sdk/logout` | OIDC Single Logout — back-channel receiver + RP-initiated end-session |
|
|
27
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
|
+
|
|
30
|
+
> `/workspace` is a different surface — workspace scope instead of brandapp scope, its own host
|
|
31
|
+
> and audience, server-only. It has its own page: [`workspace.md`](./workspace.md).
|
|
28
32
|
|
|
29
33
|
## Core SDK
|
|
30
34
|
|
|
@@ -405,7 +409,7 @@ await sdk.eav.records.update(entityId, recordId, { expiresAt: null }); // TTL
|
|
|
405
409
|
| 속성/엔티티 | 100 | `LIMIT_EXCEEDED_ATTRIBUTES` |
|
|
406
410
|
| 레코드/엔티티 | 10,000 기본 (운영자 `BRANDAPP_EAV_MAX_RECORDS_PER_ENTITY`로 인상) — 만료 행 제외 | `LIMIT_EXCEEDED_RECORDS` (422) |
|
|
407
411
|
| 인메모리 후보 상한 | 10,000행 — 필터가 SQL로 못 내려가는 요청(`neq`/`not_in`/`after`/`before`, 커스텀 속성 정렬)만 해당 | `QUERY_TOO_BROAD` (422) |
|
|
408
|
-
| `list` limit | 최대 100, 기본 50 — SDK가 요청 전에 거절(`RECORDS_PAGE_LIMIT_MAX`), 여러 페이지는 `listAll()`
|
|
412
|
+
| `list` limit | 최대 100, 기본 50 — SDK가 요청 전에 거절(`RECORDS_PAGE_LIMIT_MAX`), 여러 페이지는 `listAll()` | 400 |
|
|
409
413
|
| bulk create/update/delete | 호출당 100건 | 400 |
|
|
410
414
|
| 레코드 값 직렬화 | 128KB/레코드 | `VALIDATION_ERROR` (422) |
|
|
411
415
|
| 엔티티·속성 name/label | 100자, description 500자 | 400 |
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# Workspace / Platform API (`@reopt-ai/brandapp-sdk/workspace`)
|
|
2
|
+
|
|
3
|
+
The platform API is a **different surface** from the rest of this SDK. Everything else in
|
|
4
|
+
`@reopt-ai/brandapp-sdk` speaks to a single _brandapp_ (`brandapp.reopt.ai`) with a brandapp
|
|
5
|
+
credential. This sub-path speaks to a whole _workspace_ (`platform.reopt.ai`) with a
|
|
6
|
+
**workspace-scoped machine credential**, and it is **server-only** — `createPlatformClient`
|
|
7
|
+
throws in a browser runtime.
|
|
8
|
+
|
|
9
|
+
Two things use it: your own back-end services (create Studio work tasks from your app, move
|
|
10
|
+
them through a pipeline, receive stage changes back over a webhook) and the
|
|
11
|
+
[`reopt workspace`](https://www.npmjs.com/package/@reopt-ai/cli) CLI, which reconciles a
|
|
12
|
+
declarative `reopt.workspace.ts` against these same routes.
|
|
13
|
+
|
|
14
|
+
Specs: RFC-0029 (platform API) and RFC-0030 (Platform as Code).
|
|
15
|
+
|
|
16
|
+
## Credentials
|
|
17
|
+
|
|
18
|
+
The credential is an OAuth client with `grant_type=client_credentials`, issued per workspace.
|
|
19
|
+
The client asks `id.reopt.ai` for a token and passes `resource=<platform origin>` (RFC 8707),
|
|
20
|
+
so **the host is the audience** — a brandapp or MCP token is rejected by the platform API, and
|
|
21
|
+
a platform token is rejected elsewhere.
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
import { createPlatformClient } from "@reopt-ai/brandapp-sdk/workspace";
|
|
25
|
+
|
|
26
|
+
const platform = createPlatformClient({
|
|
27
|
+
clientId: process.env.REOPT_PLATFORM_CLIENT_ID!,
|
|
28
|
+
clientSecret: process.env.REOPT_PLATFORM_CLIENT_SECRET!,
|
|
29
|
+
// scopes defaults to ["works:read", "works:write"]
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
const me = await platform.me(); // { workspaceId, source, scopes, … }
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The token is cached, renewed 60s before expiry, and re-fetched once on a 401. Never ship these
|
|
36
|
+
values to a browser bundle.
|
|
37
|
+
|
|
38
|
+
| Config | Default |
|
|
39
|
+
| ------------- | ----------------------------------------------------------- |
|
|
40
|
+
| `platformUrl` | `REOPT_PLATFORM_URL` → `https://platform.reopt.ai` |
|
|
41
|
+
| `idBaseUrl` | `REOPT_ID_BASE_URL` → `https://id.reopt.ai` |
|
|
42
|
+
| `scopes` | `DEFAULT_PLATFORM_SCOPES` = `["works:read", "works:write"]` |
|
|
43
|
+
| `timeoutMs` | `10_000` |
|
|
44
|
+
| `fetch` | `globalThis.fetch` |
|
|
45
|
+
| `requestId` | `crypto.randomUUID()` |
|
|
46
|
+
|
|
47
|
+
Filing and moving work tasks needs `works:read`/`works:write`. Everything that changes the
|
|
48
|
+
shape of the workspace — `resources`, `brands`, `brandapps`, `oauthClients`, `eav`, `lock`, and
|
|
49
|
+
the pipeline calls under `works` — additionally requires `workspace:admin`
|
|
50
|
+
(`PLATFORM_ADMIN_SCOPE`). It is deliberately a **separate key**: a service that files work
|
|
51
|
+
tasks should not be able to delete a pipeline.
|
|
52
|
+
|
|
53
|
+
## Work tasks — the common case
|
|
54
|
+
|
|
55
|
+
Your service owns the identifier; reopt owns the task. `upsertTask` is keyed by your
|
|
56
|
+
`externalId` and is idempotent, so a retry after a network failure does not create a second
|
|
57
|
+
task.
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
await platform.works.upsertTask("incident-4821", {
|
|
61
|
+
title: "결제 웹훅 3회 실패",
|
|
62
|
+
pipeline: "error-triage", // pipeline key
|
|
63
|
+
stage: "new",
|
|
64
|
+
priority: "high",
|
|
65
|
+
body: "…",
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
await platform.works.setTaskStage("incident-4821", { stage: "done" });
|
|
69
|
+
const task = await platform.works.getTask("incident-4821");
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
To hear about stage changes a human made in Studio, register a webhook for
|
|
73
|
+
`workTaskStageChanged` and validate the body with
|
|
74
|
+
`platformWorkTaskStageChangedEventSchema`.
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
await platform.webhooks.upsert({
|
|
78
|
+
url: "https://your-app.example/api/webhooks/reopt",
|
|
79
|
+
triggers: ["workTaskStageChanged"],
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Declarative resources (RFC-0030)
|
|
84
|
+
|
|
85
|
+
These back the CLI's `plan`/`apply`. Use them directly only if you are building your own
|
|
86
|
+
tooling — otherwise declare the resources in `reopt.workspace.ts` and let
|
|
87
|
+
`reopt workspace apply` call them.
|
|
88
|
+
|
|
89
|
+
| Call | Notes |
|
|
90
|
+
| -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
91
|
+
| `resources.list()` | Every resource in one round-trip — what a `plan` diffs against |
|
|
92
|
+
| `brands.upsert(key, …)` · `brands.import(key, …)` | Brand + its primary domain. **No delete route** — a person removes it in superadmin |
|
|
93
|
+
| `brandapps.upsert(slug, …)` · `brandapps.import(slug)` | `slug` is the key. Brand:Brandapp is 1:1, so rebinding is refused |
|
|
94
|
+
| `oauthClients.upsert / rotateSecret / delete / import` | See the secret rule below |
|
|
95
|
+
| `eav.applySchema({ operations })` | The whole batch runs in **one server transaction** |
|
|
96
|
+
| `works.upsertPipeline / deletePipeline / importPipeline` | Stages are matched by key; a stage missing from the input is removed |
|
|
97
|
+
| `lock.acquire(holderId)` · `lock.release(holderId)` | Workspace apply lock (Redis, 30-minute TTL) |
|
|
98
|
+
|
|
99
|
+
🔴 **The plaintext OAuth secret exists only in the create/rotate response.** The server stores
|
|
100
|
+
a hash and cannot show it again. Read `result.data.clientSecret` at that moment and put it
|
|
101
|
+
somewhere durable, or rotate.
|
|
102
|
+
|
|
103
|
+
## Destructive changes are refused by default
|
|
104
|
+
|
|
105
|
+
Deleting a pipeline that still holds tasks, dropping an EAV entity that still has records,
|
|
106
|
+
removing an attribute that still has values, or deleting an OAuth client with live tokens all
|
|
107
|
+
fail **fail-closed** with `409` and code `DESTRUCTIVE_BLOCKED`. The whole transaction is rolled
|
|
108
|
+
back — nothing partially applied. Pass `{ allowDestructive: true }` (or `allowDestructive` in
|
|
109
|
+
the EAV apply input) only when you mean it.
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
import { PlatformApiError } from "@reopt-ai/brandapp-sdk/workspace";
|
|
113
|
+
|
|
114
|
+
try {
|
|
115
|
+
await platform.works.deletePipeline("error-triage");
|
|
116
|
+
} catch (error) {
|
|
117
|
+
if (
|
|
118
|
+
error instanceof PlatformApiError &&
|
|
119
|
+
error.code === "DESTRUCTIVE_BLOCKED"
|
|
120
|
+
) {
|
|
121
|
+
// error.fields tells you what is in the way, and how much of it
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Deleting the workspace's default pipeline is refused outright (`422`) — not unlockable.
|
|
127
|
+
|
|
128
|
+
The apply lock is fail-closed too: `LOCK_HELD` (`409`) when another run holds it,
|
|
129
|
+
`LOCK_UNAVAILABLE` (`503`) when the lock store itself is unreachable. It is the same lock the
|
|
130
|
+
EAV migration runner takes, so the two cannot interleave.
|
|
131
|
+
|
|
132
|
+
## Schemas
|
|
133
|
+
|
|
134
|
+
Every request and response shape is exported as a zod schema (`platform*Schema`) alongside its
|
|
135
|
+
type, so you can validate a webhook body or a stored plan without restating the shape. `zod` is
|
|
136
|
+
an optional peer dependency used only by this sub-path.
|
|
137
|
+
|
|
138
|
+
Vocabulary constants — `PLATFORM_STAGE_COLORS`, `PLATFORM_TASK_OUTCOMES`,
|
|
139
|
+
`PLATFORM_TASK_PRIORITIES`, `PLATFORM_WEBHOOK_TRIGGERS`, `PLATFORM_ADMIN_SCOPE`,
|
|
140
|
+
`PLATFORM_MANAGED_BY_VALUES` — come from the same source the server validates against. Derive
|
|
141
|
+
from them rather than hard-coding the strings.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@reopt-ai/brandapp-sdk",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.5.0",
|
|
4
4
|
"description": "Reopt Brandapp SDK — Better Auth adapter, OAuth login, and EAV client",
|
|
5
5
|
"author": "Reopt",
|
|
6
6
|
"license": "MIT",
|
|
@@ -89,6 +89,10 @@
|
|
|
89
89
|
"types": "./dist/webhooks/index.d.ts",
|
|
90
90
|
"import": "./dist/webhooks/index.js"
|
|
91
91
|
},
|
|
92
|
+
"./workspace": {
|
|
93
|
+
"types": "./dist/workspace/index.d.ts",
|
|
94
|
+
"import": "./dist/workspace/index.js"
|
|
95
|
+
},
|
|
92
96
|
"./dev": {
|
|
93
97
|
"types": "./dist/dev/index.d.ts",
|
|
94
98
|
"import": "./dist/dev/index.js"
|
|
@@ -118,7 +122,8 @@
|
|
|
118
122
|
"better-auth": "^1.7.1",
|
|
119
123
|
"hono": ">=4.0.0",
|
|
120
124
|
"react": ">=18.0.0",
|
|
121
|
-
"@reopt-ai/data-sdk": ">=0.1.1"
|
|
125
|
+
"@reopt-ai/data-sdk": ">=0.1.1",
|
|
126
|
+
"zod": ">=4.0.0"
|
|
122
127
|
},
|
|
123
128
|
"peerDependenciesMeta": {
|
|
124
129
|
"@ai-sdk/provider": {
|
|
@@ -141,6 +146,9 @@
|
|
|
141
146
|
},
|
|
142
147
|
"@reopt-ai/data-sdk": {
|
|
143
148
|
"optional": true
|
|
149
|
+
},
|
|
150
|
+
"zod": {
|
|
151
|
+
"optional": true
|
|
144
152
|
}
|
|
145
153
|
},
|
|
146
154
|
"devDependencies": {
|