@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.
Files changed (35) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/README.md +1 -0
  3. package/dist/ai/index.js +1 -1
  4. package/dist/ai-provider/index.js +1 -1
  5. package/dist/analytics/index.js +1 -1
  6. package/dist/auth/index.js +1 -1
  7. package/dist/better-auth/index.js +2 -2
  8. package/dist/{client-afAv7Ebi.js → client-BlKXDOUb.js} +4 -4
  9. package/dist/{client-EG1p7FL0.js → client-BnRfa5hI.js} +2 -2
  10. package/dist/{client-D_6WdWsc.js → client-CU9KBiDi.js} +3 -3
  11. package/dist/{client-DuATTvcr.js → client-Cg_gl0Gk.js} +2 -2
  12. package/dist/{client-s2uJ3OML.js → client-D9QA4f3H.js} +2 -2
  13. package/dist/{client-C4sDbXto.js → client-DLvWSpaz.js} +4 -4
  14. package/dist/{client-CuM8MNS5.js → client-NQ0p6XSB.js} +2 -2
  15. package/dist/{client-DsM84EZZ.js → client-d0EwZNc4.js} +3 -3
  16. package/dist/{client-mD6o-qVl.js → client-ijQDMf1X.js} +2 -2
  17. package/dist/{client-DYkDNPyN.js → client-p-tpQ1xj.js} +2 -2
  18. package/dist/cms/index.js +1 -1
  19. package/dist/{config-C_OFYAgP.js → config-DCFgtfSu.js} +2 -2
  20. package/dist/eav/index.js +2 -2
  21. package/dist/feedback/index.js +1 -1
  22. package/dist/files/index.js +1 -1
  23. package/dist/{http-client-BUbFBOvG.js → http-client-CHXNS9TI.js} +2 -2
  24. package/dist/index.js +12 -12
  25. package/dist/logout/index.js +1 -1
  26. package/dist/plans/index.js +1 -1
  27. package/dist/push/index.js +1 -1
  28. package/dist/{query-BkdTSuB5.js → query-ZVC28Rp8.js} +2 -2
  29. package/dist/terms/index.js +1 -1
  30. package/dist/webhooks/index.d.ts +25 -2
  31. package/dist/workspace/index.d.ts +602 -0
  32. package/dist/workspace/index.js +688 -0
  33. package/docs/api-reference.md +5 -1
  34. package/docs/workspace.md +141 -0
  35. package/package.json +10 -2
@@ -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()` | 400 |
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.4.0",
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": {