@reopt-ai/brandapp-sdk 4.5.0-platform.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 (34) hide show
  1. package/CHANGELOG.md +28 -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-B0XUjOuP.js → client-BlKXDOUb.js} +4 -4
  9. package/dist/{client-BwgCbfXv.js → client-BnRfa5hI.js} +2 -2
  10. package/dist/{client-BIMl52kc.js → client-CU9KBiDi.js} +3 -3
  11. package/dist/{client-WxPjMNy_.js → client-Cg_gl0Gk.js} +2 -2
  12. package/dist/{client-CKi1NpMR.js → client-D9QA4f3H.js} +2 -2
  13. package/dist/{client-DNzgX_md.js → client-DLvWSpaz.js} +4 -4
  14. package/dist/{client-B270eCrs.js → client-NQ0p6XSB.js} +2 -2
  15. package/dist/{client-C2ALt685.js → client-d0EwZNc4.js} +3 -3
  16. package/dist/{client-Cv1bdMBf.js → client-ijQDMf1X.js} +2 -2
  17. package/dist/{client-BNht520A.js → client-p-tpQ1xj.js} +2 -2
  18. package/dist/cms/index.js +1 -1
  19. package/dist/{config-DkT0F-GG.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-BO5A5n4I.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-D08B_HFt.js → query-ZVC28Rp8.js} +2 -2
  29. package/dist/terms/index.js +1 -1
  30. package/dist/workspace/index.d.ts +350 -1
  31. package/dist/workspace/index.js +356 -3
  32. package/docs/api-reference.md +4 -0
  33. package/docs/workspace.md +141 -0
  34. package/package.json +1 -1
@@ -1,4 +1,4 @@
1
- import { n as SDK_VERSION } from "../config-DkT0F-GG.js";
1
+ import { n as SDK_VERSION } from "../config-DCFgtfSu.js";
2
2
  import { z } from "zod";
3
3
 
4
4
  //#region src/workspace/schemas.ts
@@ -49,7 +49,8 @@ const platformTaskStageInputSchema = z.object({
49
49
  const platformWebhookUpsertInputSchema = z.object({
50
50
  url: z.url().max(2e3),
51
51
  triggers: z.array(z.enum(PLATFORM_WEBHOOK_TRIGGERS)).min(1),
52
- secret: z.string().min(16).max(1024).optional()
52
+ secret: z.string().min(16).max(1024).optional(),
53
+ managedBy: z.literal("code").nullable().optional()
53
54
  }).strict();
54
55
  const outcomeSchema = z.enum(PLATFORM_TASK_OUTCOMES).nullable();
55
56
  const platformTaskSchema = z.object({
@@ -138,6 +139,286 @@ const platformWorkTaskStageChangedEventSchema = z.object({
138
139
  label: z.string().nullable()
139
140
  }))
140
141
  });
142
+ const PLATFORM_ADMIN_SCOPE = "workspace:admin";
143
+ const PLATFORM_MANAGED_BY_VALUES = ["code"];
144
+ /** 단계 색 어휘 — `packages/studio-ui/composites/stage-colors.ts` STAGE_COLORS와 같은 집합(apps/web 파리티 테스트가 고정) */
145
+ const PLATFORM_STAGE_COLORS = [
146
+ "slate",
147
+ "gray",
148
+ "red",
149
+ "rose",
150
+ "orange",
151
+ "amber",
152
+ "yellow",
153
+ "lime",
154
+ "green",
155
+ "emerald",
156
+ "teal",
157
+ "cyan",
158
+ "sky",
159
+ "blue",
160
+ "indigo",
161
+ "violet",
162
+ "purple",
163
+ "pink"
164
+ ];
165
+ /** `/^[a-z0-9][a-z0-9-]{0,59}$/` — 선언 파일의 키이자 URL 경로 세그먼트 */
166
+ const platformResourceKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,59}$/, "key must be lowercase letters, digits or '-' (≤60, must start with a letter or digit)");
167
+ const stageColorSchema = z.enum(PLATFORM_STAGE_COLORS);
168
+ const platformPipelineStageInputSchema = z.object({
169
+ key: platformResourceKeySchema,
170
+ label: z.string().trim().min(1).max(80),
171
+ color: stageColorSchema.optional(),
172
+ isEntry: z.boolean().optional(),
173
+ outcome: z.enum(PLATFORM_TASK_OUTCOMES).nullable().optional()
174
+ }).strict();
175
+ const platformPipelineUpsertInputSchema = z.object({
176
+ name: z.string().trim().min(1).max(120),
177
+ description: z.string().trim().max(500).nullable().optional(),
178
+ isDefault: z.boolean().optional(),
179
+ stages: z.array(platformPipelineStageInputSchema).min(1).max(50),
180
+ allowDestructive: z.boolean().optional()
181
+ }).strict().refine((value) => new Set(value.stages.map((stage) => stage.key)).size === value.stages.length, "stage keys must be unique within a pipeline").refine((value) => value.stages.filter((stage) => stage.isEntry === true).length === 1, "exactly one stage must have isEntry: true");
182
+ const platformPipelineImportInputSchema = z.object({ pipelineId: z.uuid() }).strict();
183
+ const managedBySchema = z.enum(PLATFORM_MANAGED_BY_VALUES).nullable();
184
+ const platformPipelineResourceSchema = z.object({
185
+ id: z.string(),
186
+ key: z.string().nullable(),
187
+ name: z.string(),
188
+ description: z.string().nullable(),
189
+ isDefault: z.boolean(),
190
+ isArchived: z.boolean(),
191
+ order: z.number(),
192
+ managedBy: managedBySchema,
193
+ taskCount: z.number(),
194
+ stages: z.array(z.object({
195
+ id: z.string(),
196
+ key: z.string(),
197
+ label: z.string(),
198
+ color: z.string(),
199
+ order: z.number(),
200
+ isEntry: z.boolean(),
201
+ outcome: outcomeSchema,
202
+ taskCount: z.number()
203
+ }))
204
+ });
205
+ const platformWebhookResourceSchema = z.object({
206
+ id: z.string(),
207
+ url: z.string(),
208
+ triggers: z.array(z.string()),
209
+ hasSecret: z.boolean(),
210
+ managedBy: managedBySchema
211
+ });
212
+ const platformResourcesSchema = z.object({
213
+ workspaceId: z.string(),
214
+ pipelines: z.array(platformPipelineResourceSchema),
215
+ webhooks: z.array(platformWebhookResourceSchema)
216
+ });
217
+ const platformLockAcquiredSchema = z.object({
218
+ acquired: z.literal(true),
219
+ expiresAt: z.string()
220
+ });
221
+ const platformLockReleasedSchema = z.object({ released: z.boolean() });
222
+ const PLATFORM_DOMAIN_STATUSES = [
223
+ "active",
224
+ "inactive",
225
+ "pending",
226
+ "suspended"
227
+ ];
228
+ const PLATFORM_BRANDAPP_STATUSES = [
229
+ "draft",
230
+ "active",
231
+ "suspended",
232
+ "archived"
233
+ ];
234
+ const PLATFORM_TOKEN_ENDPOINT_AUTH_METHODS = [
235
+ "client_secret_post",
236
+ "client_secret_basic",
237
+ "none"
238
+ ];
239
+ const PLATFORM_OAUTH_GRANT_TYPES = [
240
+ "authorization_code",
241
+ "refresh_token",
242
+ "client_credentials"
243
+ ];
244
+ const PLATFORM_OAUTH_APPLICATION_TYPES = ["web", "native"];
245
+ const domainStatusSchema = z.enum(PLATFORM_DOMAIN_STATUSES);
246
+ const hostnameSchema = z.string().trim().min(1).max(255).regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/, "domain must be a bare hostname");
247
+ const platformBrandUpsertInputSchema = z.object({
248
+ name: z.string().trim().min(1).max(255),
249
+ logo: z.url().max(2048).nullable().optional(),
250
+ description: z.string().trim().max(280).nullable().optional(),
251
+ isSystemBrand: z.boolean().optional(),
252
+ domain: hostnameSchema.optional()
253
+ }).strict();
254
+ const platformBrandImportInputSchema = z.object({ brandId: z.uuid() }).strict();
255
+ const platformBrandResourceSchema = z.object({
256
+ id: z.string(),
257
+ key: z.string().nullable(),
258
+ name: z.string(),
259
+ logo: z.string().nullable(),
260
+ description: z.string().nullable(),
261
+ isSystemBrand: z.boolean(),
262
+ managedBy: managedBySchema,
263
+ domains: z.array(z.object({
264
+ id: z.string(),
265
+ domain: z.string(),
266
+ isPrimary: z.boolean(),
267
+ status: domainStatusSchema
268
+ })),
269
+ brandappSlug: z.string().nullable()
270
+ });
271
+ const platformBrandappUpsertInputSchema = z.object({
272
+ name: z.string().trim().min(1).max(100),
273
+ brand: platformResourceKeySchema,
274
+ description: z.string().trim().max(500).nullable().optional(),
275
+ logo: z.url().max(2048).nullable().optional(),
276
+ aiEnabled: z.boolean().optional(),
277
+ isSystemBrandapp: z.boolean().optional(),
278
+ settings: z.record(z.string(), z.unknown()).optional()
279
+ }).strict();
280
+ const platformBrandappResourceSchema = z.object({
281
+ id: z.string(),
282
+ slug: z.string(),
283
+ name: z.string(),
284
+ description: z.string().nullable(),
285
+ logo: z.string().nullable(),
286
+ status: z.string(),
287
+ aiEnabled: z.boolean(),
288
+ isSystemBrandapp: z.boolean(),
289
+ brandId: z.string(),
290
+ brandKey: z.string().nullable(),
291
+ domainId: z.string().nullable(),
292
+ settings: z.record(z.string(), z.unknown()).nullable(),
293
+ managedBy: managedBySchema
294
+ });
295
+ const platformOAuthClientUpsertInputSchema = z.object({
296
+ brandapp: platformResourceKeySchema,
297
+ name: z.string().trim().min(1).max(255).optional(),
298
+ scopes: z.array(z.string().trim().min(1).max(64)).min(1).max(32),
299
+ grantTypes: z.array(z.enum(PLATFORM_OAUTH_GRANT_TYPES)).min(1),
300
+ redirectUris: z.array(z.url().max(500)).max(32).optional(),
301
+ postLogoutRedirectUris: z.array(z.url().max(500)).max(32).optional(),
302
+ tokenEndpointAuthMethod: z.enum(PLATFORM_TOKEN_ENDPOINT_AUTH_METHODS).optional(),
303
+ requirePKCE: z.boolean().optional(),
304
+ skipConsent: z.boolean().optional(),
305
+ enableEndSession: z.boolean().optional(),
306
+ applicationType: z.enum(PLATFORM_OAUTH_APPLICATION_TYPES).optional(),
307
+ disabled: z.boolean().optional()
308
+ }).strict().refine((value) => !value.grantTypes.includes("authorization_code") || (value.redirectUris?.length ?? 0) > 0, "authorization_code requires at least one redirectUri");
309
+ const platformOAuthClientImportInputSchema = z.object({ clientId: z.string().min(8).max(255) }).strict();
310
+ const platformOAuthClientResourceSchema = z.object({
311
+ id: z.string(),
312
+ key: z.string().nullable(),
313
+ clientId: z.string(),
314
+ name: z.string().nullable(),
315
+ brandappSlug: z.string().nullable(),
316
+ disabled: z.boolean(),
317
+ scopes: z.array(z.string()),
318
+ clientCredentialsScopes: z.array(z.string()),
319
+ grantTypes: z.array(z.string()),
320
+ redirectUris: z.array(z.string()),
321
+ postLogoutRedirectUris: z.array(z.string()),
322
+ tokenEndpointAuthMethod: z.string().nullable(),
323
+ requirePKCE: z.boolean(),
324
+ skipConsent: z.boolean(),
325
+ enableEndSession: z.boolean(),
326
+ applicationType: z.string().nullable(),
327
+ hasSecret: z.boolean(),
328
+ managedBy: managedBySchema,
329
+ clientSecret: z.string().optional()
330
+ });
331
+ const eavAttributeResourceSchema = z.object({
332
+ id: z.string(),
333
+ name: z.string(),
334
+ label: z.string(),
335
+ dataType: z.string(),
336
+ isRequired: z.boolean(),
337
+ isUnique: z.boolean(),
338
+ defaultValue: z.string().nullable(),
339
+ validation: z.unknown(),
340
+ options: z.unknown(),
341
+ sortOrder: z.number()
342
+ });
343
+ const platformEavEntityResourceSchema = z.object({
344
+ id: z.string(),
345
+ name: z.string(),
346
+ description: z.string().nullable(),
347
+ icon: z.string().nullable(),
348
+ linkedTo: z.string(),
349
+ attributes: z.array(eavAttributeResourceSchema),
350
+ recordCount: z.number()
351
+ });
352
+ const platformEavBrandappResourcesSchema = z.object({
353
+ brandappId: z.string(),
354
+ brandappSlug: z.string(),
355
+ entities: z.array(platformEavEntityResourceSchema)
356
+ });
357
+ const eavName = z.string().trim().min(1).max(100);
358
+ const platformEavSchemaOperationSchema = z.discriminatedUnion("kind", [
359
+ z.object({
360
+ kind: z.literal("addEntity"),
361
+ name: eavName,
362
+ def: z.object({
363
+ description: z.string().max(500).nullable().optional(),
364
+ icon: z.string().max(10).nullable().optional(),
365
+ linkedTo: z.enum(["brandapp", "brandappAuthUser"]).optional()
366
+ }).optional()
367
+ }).strict(),
368
+ z.object({
369
+ kind: z.literal("updateEntity"),
370
+ name: eavName,
371
+ changes: z.object({
372
+ description: z.string().max(500).nullable().optional(),
373
+ icon: z.string().max(10).nullable().optional()
374
+ }).strict()
375
+ }).strict(),
376
+ z.object({
377
+ kind: z.literal("removeEntity"),
378
+ name: eavName
379
+ }).strict(),
380
+ z.object({
381
+ kind: z.literal("addAttribute"),
382
+ entity: eavName,
383
+ name: eavName,
384
+ def: z.record(z.string(), z.unknown())
385
+ }).strict(),
386
+ z.object({
387
+ kind: z.literal("updateAttribute"),
388
+ entity: eavName,
389
+ name: eavName,
390
+ changes: z.record(z.string(), z.unknown())
391
+ }).strict(),
392
+ z.object({
393
+ kind: z.literal("removeAttribute"),
394
+ entity: eavName,
395
+ name: eavName
396
+ }).strict(),
397
+ z.object({
398
+ kind: z.literal("renameAttribute"),
399
+ entity: eavName,
400
+ oldName: eavName,
401
+ newName: eavName
402
+ }).strict()
403
+ ]);
404
+ const platformEavSchemaApplyInputSchema = z.object({
405
+ brandapp: platformResourceKeySchema.optional(),
406
+ operations: z.array(platformEavSchemaOperationSchema).max(1e3),
407
+ allowDestructive: z.boolean().optional()
408
+ }).strict();
409
+ const platformEavSchemaApplyResultSchema = z.object({
410
+ applied: z.number(),
411
+ entities: z.array(platformEavEntityResourceSchema)
412
+ });
413
+ const platformResourcesV2Schema = z.object({
414
+ workspaceId: z.string(),
415
+ pipelines: z.array(platformPipelineResourceSchema),
416
+ webhooks: z.array(platformWebhookResourceSchema),
417
+ brands: z.array(platformBrandResourceSchema),
418
+ brandapps: z.array(platformBrandappResourceSchema),
419
+ oauthClients: z.array(platformOAuthClientResourceSchema),
420
+ eav: z.array(platformEavBrandappResourcesSchema)
421
+ });
141
422
 
142
423
  //#endregion
143
424
  //#region src/workspace/client.ts
@@ -290,6 +571,13 @@ function createPlatformClient(config) {
290
571
  };
291
572
  };
292
573
  const parseData = (parse) => (value) => parse(value.data);
574
+ const parseWriteWith = (schema) => (value) => {
575
+ const envelope = value;
576
+ return {
577
+ data: schema.parse(envelope.data),
578
+ meta: platformWriteMetaSchema.parse(envelope.meta)
579
+ };
580
+ };
293
581
  return {
294
582
  /** 진단 — 이 자격이 어느 워크스페이스·source에 묶였는가 */
295
583
  me: () => request("GET", "/v1/me", { parse: parseData((v) => platformMeSchema.parse(v)) }),
@@ -303,6 +591,71 @@ function createPlatformClient(config) {
303
591
  setTaskStage: (externalId, input) => request("PATCH", `/v1/works/tasks/${encodeURIComponent(externalId)}/stage`, {
304
592
  body: input,
305
593
  parse: parseWrite
594
+ }),
595
+ upsertPipeline: (key, input) => request("PUT", `/v1/works/pipelines/${encodeURIComponent(key)}`, {
596
+ body: input,
597
+ parse: (value) => {
598
+ const envelope = value;
599
+ return {
600
+ data: platformPipelineResourceSchema.parse(envelope.data),
601
+ meta: platformWriteMetaSchema.parse(envelope.meta)
602
+ };
603
+ }
604
+ }),
605
+ deletePipeline: (key, options) => request("DELETE", `/v1/works/pipelines/${encodeURIComponent(key)}${options?.allowDestructive ? "?allowDestructive=true" : ""}`, { parse: parseData((v) => v) }),
606
+ importPipeline: (key, input) => request("POST", `/v1/works/pipelines/${encodeURIComponent(key)}/import`, {
607
+ body: input,
608
+ parse: parseData((v) => platformPipelineResourceSchema.parse(v))
609
+ })
610
+ },
611
+ resources: { list: () => request("GET", "/v1/resources", { parse: parseData((v) => platformResourcesV2Schema.parse(v)) }) },
612
+ brands: {
613
+ upsert: (key, input) => request("PUT", `/v1/brands/${encodeURIComponent(key)}`, {
614
+ body: input,
615
+ parse: parseWriteWith(platformBrandResourceSchema)
616
+ }),
617
+ import: (key, input) => request("POST", `/v1/brands/${encodeURIComponent(key)}/import`, {
618
+ body: input,
619
+ parse: parseData((v) => platformBrandResourceSchema.parse(v))
620
+ })
621
+ },
622
+ brandapps: {
623
+ upsert: (slug, input) => request("PUT", `/v1/brandapps/${encodeURIComponent(slug)}`, {
624
+ body: input,
625
+ parse: parseWriteWith(platformBrandappResourceSchema)
626
+ }),
627
+ import: (slug) => request("POST", `/v1/brandapps/${encodeURIComponent(slug)}/import`, {
628
+ body: {},
629
+ parse: parseData((v) => platformBrandappResourceSchema.parse(v))
630
+ })
631
+ },
632
+ oauthClients: {
633
+ upsert: (key, input) => request("PUT", `/v1/oauth-clients/${encodeURIComponent(key)}`, {
634
+ body: input,
635
+ parse: parseWriteWith(platformOAuthClientResourceSchema)
636
+ }),
637
+ rotateSecret: (key) => request("POST", `/v1/oauth-clients/${encodeURIComponent(key)}/rotate-secret`, {
638
+ body: {},
639
+ parse: parseData((v) => platformOAuthClientResourceSchema.parse(v))
640
+ }),
641
+ delete: (key, options) => request("DELETE", `/v1/oauth-clients/${encodeURIComponent(key)}${options?.allowDestructive ? "?allowDestructive=true" : ""}`, { parse: parseData((v) => v) }),
642
+ import: (key, input) => request("POST", `/v1/oauth-clients/${encodeURIComponent(key)}/import`, {
643
+ body: input,
644
+ parse: parseData((v) => platformOAuthClientResourceSchema.parse(v))
645
+ })
646
+ },
647
+ eav: { applySchema: (input) => request("POST", "/v1/eav/schema/apply", {
648
+ body: input,
649
+ parse: parseData((v) => platformEavSchemaApplyResultSchema.parse(v))
650
+ }) },
651
+ lock: {
652
+ acquire: (holderId) => request("POST", "/v1/lock", {
653
+ body: { holderId },
654
+ parse: parseData((v) => platformLockAcquiredSchema.parse(v))
655
+ }),
656
+ release: (holderId) => request("DELETE", "/v1/lock", {
657
+ body: { holderId },
658
+ parse: parseData((v) => platformLockReleasedSchema.parse(v))
306
659
  })
307
660
  },
308
661
  webhooks: {
@@ -331,5 +684,5 @@ function createPlatformClient(config) {
331
684
  }
332
685
 
333
686
  //#endregion
334
- export { DEFAULT_PLATFORM_SCOPES, PLATFORM_TASK_OUTCOMES, PLATFORM_TASK_PRIORITIES, PLATFORM_WEBHOOK_TRIGGERS, PlatformApiError, REOPT_PLATFORM_ID_URLS, REOPT_PLATFORM_URLS, createPlatformClient, platformErrorSchema, platformExternalIdSchema, platformMeSchema, platformPipelineSchema, platformTaskSchema, platformTaskStageInputSchema, platformTaskStageSchema, platformTaskUpsertInputSchema, platformWebhookSchema, platformWebhookUpsertInputSchema, platformWorkTaskStageChangedEventSchema, platformWriteMetaSchema, resolvePlatformUrls };
687
+ export { DEFAULT_PLATFORM_SCOPES, PLATFORM_ADMIN_SCOPE, PLATFORM_BRANDAPP_STATUSES, PLATFORM_DOMAIN_STATUSES, PLATFORM_MANAGED_BY_VALUES, PLATFORM_OAUTH_APPLICATION_TYPES, PLATFORM_OAUTH_GRANT_TYPES, PLATFORM_STAGE_COLORS, PLATFORM_TASK_OUTCOMES, PLATFORM_TASK_PRIORITIES, PLATFORM_TOKEN_ENDPOINT_AUTH_METHODS, PLATFORM_WEBHOOK_TRIGGERS, PlatformApiError, REOPT_PLATFORM_ID_URLS, REOPT_PLATFORM_URLS, createPlatformClient, platformBrandImportInputSchema, platformBrandResourceSchema, platformBrandUpsertInputSchema, platformBrandappResourceSchema, platformBrandappUpsertInputSchema, platformEavBrandappResourcesSchema, platformEavEntityResourceSchema, platformEavSchemaApplyInputSchema, platformEavSchemaApplyResultSchema, platformEavSchemaOperationSchema, platformErrorSchema, platformExternalIdSchema, platformLockAcquiredSchema, platformLockReleasedSchema, platformMeSchema, platformOAuthClientImportInputSchema, platformOAuthClientResourceSchema, platformOAuthClientUpsertInputSchema, platformPipelineImportInputSchema, platformPipelineResourceSchema, platformPipelineSchema, platformPipelineStageInputSchema, platformPipelineUpsertInputSchema, platformResourceKeySchema, platformResourcesSchema, platformResourcesV2Schema, platformTaskSchema, platformTaskStageInputSchema, platformTaskStageSchema, platformTaskUpsertInputSchema, platformWebhookResourceSchema, platformWebhookSchema, platformWebhookUpsertInputSchema, platformWorkTaskStageChangedEventSchema, platformWriteMetaSchema, resolvePlatformUrls };
335
688
  //# sourceMappingURL=index.js.map
@@ -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
 
@@ -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.5.0-platform.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",