@reopt-ai/brandapp-sdk 4.5.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.
Files changed (76) hide show
  1. package/CHANGELOG.md +62 -1
  2. package/README.md +13 -13
  3. package/dist/ai/index.d.ts +1 -1
  4. package/dist/ai/index.js +1 -1
  5. package/dist/ai-provider/index.d.ts +1 -1
  6. package/dist/ai-provider/index.js +1 -1
  7. package/dist/analytics/index.d.ts +1 -1
  8. package/dist/analytics/index.js +1 -1
  9. package/dist/auth/index.d.ts +1 -1
  10. package/dist/auth/index.js +1 -1
  11. package/dist/better-auth/index.d.ts +10 -9
  12. package/dist/better-auth/index.js +19 -6
  13. package/dist/{client-ijQDMf1X.js → client-BFl6cDAE.js} +23 -2
  14. package/dist/{client-DLvWSpaz.js → client-BJQzInqD.js} +4 -4
  15. package/dist/{client-IUSZDJio.d.ts → client-BQJepjoD.d.ts} +44 -4
  16. package/dist/{client-BlKXDOUb.js → client-BZ8-vFjk.js} +4 -4
  17. package/dist/{client-d0EwZNc4.js → client-Bf8mW6uO.js} +3 -3
  18. package/dist/client-C-LdW4gY.js +194 -0
  19. package/dist/{client-C6OXGMMV.d.ts → client-C2W4RAZV.d.ts} +2 -2
  20. package/dist/{client-7I-mz3Dw.d.ts → client-C6lx3RUQ.d.ts} +2 -2
  21. package/dist/{client-p-tpQ1xj.js → client-CLZie3Ym.js} +2 -2
  22. package/dist/{client-yKeRJnIB.d.ts → client-CSl3o0s3.d.ts} +2 -2
  23. package/dist/{client-D1AFtJRw.d.ts → client-Cnq_X3Wp.d.ts} +2 -2
  24. package/dist/{client-Bfutv3LK.d.ts → client-Cod87ThY.d.ts} +2 -2
  25. package/dist/{client-BSW0Ncjj.d.ts → client-CsWSxMhB.d.ts} +2 -2
  26. package/dist/{client-Cg_gl0Gk.js → client-CslasnqK.js} +2 -2
  27. package/dist/{client-CU9KBiDi.js → client-DGKq4Ml5.js} +3 -3
  28. package/dist/{client-BnRfa5hI.js → client-Db6Etco9.js} +2 -2
  29. package/dist/{client-Dmvtr1nS.d.ts → client-DfnaH99z.d.ts} +2 -2
  30. package/dist/{client-COKDtHO9.d.ts → client-MDNS9Ubf.d.ts} +2 -2
  31. package/dist/{client-D9QA4f3H.js → client-VKEJtLH0.js} +2 -2
  32. package/dist/{client-NQ0p6XSB.js → client-_2Avom0q.js} +2 -2
  33. package/dist/{client-CniCGdmi.d.ts → client-xblzWFAL.d.ts} +2 -2
  34. package/dist/cms/index.d.ts +1 -1
  35. package/dist/cms/index.js +1 -1
  36. package/dist/{config-D3SblxWt.d.ts → config-CnFnzh7Q.d.ts} +21 -6
  37. package/dist/{config-DCFgtfSu.js → config-Dy2oBn1a.js} +13 -10
  38. package/dist/dev/index.d.ts +1 -1
  39. package/dist/eav/index.d.ts +2 -2
  40. package/dist/eav/index.js +2 -2
  41. package/dist/eav/migrate.d.ts +2 -2
  42. package/dist/eav/schema.d.ts +2 -2
  43. package/dist/feedback/index.d.ts +1 -1
  44. package/dist/feedback/index.js +1 -1
  45. package/dist/files/index.d.ts +1 -1
  46. package/dist/files/index.js +1 -1
  47. package/dist/{http-client-CHXNS9TI.js → http-client-CW9wXANY.js} +9 -3
  48. package/dist/{index-BnAYxnwq.d.ts → index-Bkci7euU.d.ts} +14 -12
  49. package/dist/{index-C6fyJTud.d.ts → index-Dh8XMVFF.d.ts} +2 -2
  50. package/dist/index.d.ts +4 -4
  51. package/dist/index.js +12 -12
  52. package/dist/keys-B2pA8EkU.d.ts +44 -0
  53. package/dist/keys-B_R_lsyF.js +102 -0
  54. package/dist/logout/index.d.ts +1 -1
  55. package/dist/logout/index.js +1 -1
  56. package/dist/machine/index.d.ts +72 -0
  57. package/dist/machine/index.js +4 -0
  58. package/dist/machine/keygen-cli.d.ts +7 -0
  59. package/dist/machine/keygen-cli.js +57 -0
  60. package/dist/plans/index.d.ts +2 -2
  61. package/dist/plans/index.js +1 -1
  62. package/dist/push/index.d.ts +1 -1
  63. package/dist/push/index.js +1 -1
  64. package/dist/{query-ZVC28Rp8.js → query-DPD0WYlB.js} +2 -2
  65. package/dist/react/hooks.d.ts +4 -4
  66. package/dist/terms/index.d.ts +1 -1
  67. package/dist/terms/index.js +1 -1
  68. package/dist/testing/index.d.ts +2 -2
  69. package/dist/workspace/index.d.ts +61 -9
  70. package/dist/workspace/index.js +57 -9
  71. package/docs/api-reference.md +43 -24
  72. package/docs/dev-server.md +2 -2
  73. package/docs/environment.md +4 -4
  74. package/docs/machine.md +104 -0
  75. package/docs/workspace.md +12 -0
  76. package/package.json +19 -5
@@ -1,4 +1,6 @@
1
- import { n as SDK_VERSION } from "../config-DCFgtfSu.js";
1
+ import { n as SDK_VERSION } from "../config-Dy2oBn1a.js";
2
+ import { o as readClientKeyRing } from "../keys-B_R_lsyF.js";
3
+ import { r as createMachineClient } from "../client-C-LdW4gY.js";
2
4
  import { z } from "zod";
3
5
 
4
6
  //#region src/workspace/schemas.ts
@@ -29,6 +31,12 @@ const platformTaskStageSchema = z.object({
29
31
  outcome: z.enum(PLATFORM_TASK_OUTCOMES).nullable().optional(),
30
32
  stageId: z.uuid().optional()
31
33
  }).strict().refine(exactlyOneOf, "stage needs exactly one of outcome or stageId");
34
+ const platformCustomerUpsertInputSchema = z.object({
35
+ version: versionSchema.optional(),
36
+ name: z.string().trim().min(1).max(255),
37
+ email: z.email().max(255).nullable().optional(),
38
+ attributes: z.record(z.string().min(1).max(64), z.unknown()).optional()
39
+ }).strict();
32
40
  const platformTaskUpsertInputSchema = z.object({
33
41
  version: versionSchema,
34
42
  title: z.string().trim().min(1).max(255),
@@ -234,8 +242,20 @@ const PLATFORM_BRANDAPP_STATUSES = [
234
242
  const PLATFORM_TOKEN_ENDPOINT_AUTH_METHODS = [
235
243
  "client_secret_post",
236
244
  "client_secret_basic",
245
+ "private_key_jwt",
237
246
  "none"
238
247
  ];
248
+ /**
249
+ * RFC-0034 §2.2 — 클라이언트 용도. 한 브랜드앱에 용도당 하나.
250
+ * - `web`: 사람 로그인(authorization_code) · `connect`: 사용자 위임 연동(동의 화면)
251
+ * - `adapter`: 원격 auth 어댑터 · `machine`: 서버 간 기계 호출 — 둘 다 `private_key_jwt` + DPoP 기본
252
+ */
253
+ const PLATFORM_OAUTH_CLIENT_PURPOSES = [
254
+ "web",
255
+ "adapter",
256
+ "machine",
257
+ "connect"
258
+ ];
239
259
  const PLATFORM_OAUTH_GRANT_TYPES = [
240
260
  "authorization_code",
241
261
  "refresh_token",
@@ -294,6 +314,9 @@ const platformBrandappResourceSchema = z.object({
294
314
  });
295
315
  const platformOAuthClientUpsertInputSchema = z.object({
296
316
  brandapp: platformResourceKeySchema,
317
+ purpose: z.enum(PLATFORM_OAUTH_CLIENT_PURPOSES).optional(),
318
+ jwksUri: z.url().max(500).startsWith("https://").optional(),
319
+ dpopBoundAccessTokens: z.boolean().optional(),
297
320
  name: z.string().trim().min(1).max(255).optional(),
298
321
  scopes: z.array(z.string().trim().min(1).max(64)).min(1).max(32),
299
322
  grantTypes: z.array(z.enum(PLATFORM_OAUTH_GRANT_TYPES)).min(1),
@@ -313,6 +336,9 @@ const platformOAuthClientResourceSchema = z.object({
313
336
  clientId: z.string(),
314
337
  name: z.string().nullable(),
315
338
  brandappSlug: z.string().nullable(),
339
+ purpose: z.enum(PLATFORM_OAUTH_CLIENT_PURPOSES).nullable(),
340
+ jwksUri: z.string().nullable(),
341
+ dpopBoundAccessTokens: z.boolean(),
316
342
  disabled: z.boolean(),
317
343
  scopes: z.array(z.string()),
318
344
  clientCredentialsScopes: z.array(z.string()),
@@ -434,11 +460,11 @@ const platformResourcesV2Schema = z.object({
434
460
  */
435
461
  const REOPT_PLATFORM_URLS = {
436
462
  production: "https://platform.reopt.ai",
437
- development: "https://platform.reopt.de:3443"
463
+ development: "https://platform.local.reopt.io"
438
464
  };
439
465
  const REOPT_PLATFORM_ID_URLS = {
440
466
  production: "https://id.reopt.ai",
441
- development: "https://id.reopt.de:3443"
467
+ development: "https://id.local.reopt.io"
442
468
  };
443
469
  const DEFAULT_PLATFORM_SCOPES = ["works:read", "works:write"];
444
470
  var PlatformApiError = class PlatformApiError extends Error {
@@ -478,19 +504,33 @@ function resolvePlatformUrls(config) {
478
504
  }
479
505
  function createPlatformClient(config) {
480
506
  assertServerRuntime();
481
- if (!config.clientId || !config.clientSecret) throw new Error("createPlatformClient: clientId and clientSecret are required");
507
+ if (!config.clientId) throw new Error("createPlatformClient: clientId is required");
482
508
  const { platformUrl, idBaseUrl } = resolvePlatformUrls(config);
483
509
  const scopes = config.scopes ?? DEFAULT_PLATFORM_SCOPES;
484
510
  const fetchImpl = config.fetch ?? globalThis.fetch;
485
511
  const timeoutMs = config.timeoutMs ?? 1e4;
486
512
  const nextRequestId = config.requestId ?? (() => crypto.randomUUID());
513
+ const keyRing = config.keyRing ?? (config.privateKeyJwk ? {
514
+ signing: config.privateKeyJwk,
515
+ published: [config.privateKeyJwk]
516
+ } : null) ?? (config.clientSecret ? null : readClientKeyRing());
517
+ const machine = keyRing ? createMachineClient({
518
+ clientId: config.clientId,
519
+ keyRing,
520
+ resource: platformUrl,
521
+ scopes,
522
+ idBaseUrl,
523
+ fetch: fetchImpl,
524
+ timeoutMs
525
+ }) : null;
526
+ if (!machine && !config.clientSecret) throw new Error("createPlatformClient: clientSecret or a private key (privateKeyJwk / REOPT_CLIENT_PRIVATE_KEY_JWK) is required");
487
527
  let token = null;
488
528
  let inflight = null;
489
529
  async function fetchToken() {
490
530
  const body = new URLSearchParams({
491
531
  grant_type: "client_credentials",
492
532
  client_id: config.clientId,
493
- client_secret: config.clientSecret,
533
+ client_secret: config.clientSecret ?? "",
494
534
  scope: scopes.join(" "),
495
535
  resource: platformUrl
496
536
  });
@@ -526,12 +566,19 @@ function createPlatformClient(config) {
526
566
  return token.accessToken;
527
567
  }
528
568
  async function request(method, path, options) {
529
- const accessToken = await getToken(options.retried === true);
569
+ const url = `${platformUrl}${path}`;
570
+ const authHeaders = machine ? await (async () => {
571
+ if (options.retried) machine.invalidateToken();
572
+ return machine.headers({
573
+ method,
574
+ url
575
+ });
576
+ })() : { authorization: `Bearer ${await getToken(options.retried === true)}` };
530
577
  const requestId = nextRequestId();
531
- const res = await fetchImpl(`${platformUrl}${path}`, {
578
+ const res = await fetchImpl(url, {
532
579
  method,
533
580
  headers: {
534
- authorization: `Bearer ${accessToken}`,
581
+ ...authHeaders,
535
582
  accept: "application/json",
536
583
  "x-request-id": requestId,
537
584
  "x-sdk-version": SDK_VERSION,
@@ -675,6 +722,7 @@ function createPlatformClient(config) {
675
722
  /** 테스트·진단용 — 캐시된 토큰을 버린다 */
676
723
  invalidateToken: () => {
677
724
  token = null;
725
+ machine?.invalidateToken();
678
726
  },
679
727
  urls: {
680
728
  platformUrl,
@@ -684,5 +732,5 @@ function createPlatformClient(config) {
684
732
  }
685
733
 
686
734
  //#endregion
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 };
735
+ export { DEFAULT_PLATFORM_SCOPES, PLATFORM_ADMIN_SCOPE, PLATFORM_BRANDAPP_STATUSES, PLATFORM_DOMAIN_STATUSES, PLATFORM_MANAGED_BY_VALUES, PLATFORM_OAUTH_APPLICATION_TYPES, PLATFORM_OAUTH_CLIENT_PURPOSES, 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, platformCustomerUpsertInputSchema, 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 };
688
736
  //# sourceMappingURL=index.js.map
@@ -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:
@@ -44,7 +44,7 @@ const dev = await createDevServer({
44
44
  verbose: true, // 상세 로그
45
45
  proxy: {
46
46
  // 선택적 원격 프록시
47
- remoteUrl: "https://brand.reopt.de:3443",
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.de:3443",
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!,
@@ -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.de:3443` (`NODE_ENV` 자동) |
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.de:3443` | `https://id.reopt.de:3443` |
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.de:3443` | `https://id.reopt.de:3443` |
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.de:3443` 설정.
160
+ `config.isProduction: false` 또는 `REOPT_BASE_URL=https://brand.local.reopt.io` 설정.
161
161
 
162
162
  ### `REOPT_BASE_URL`은 줬는데 OAuth/auth가 안 됨
163
163
 
@@ -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.5.0",
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"
@@ -119,11 +123,12 @@
119
123
  "@ai-sdk/provider": ">=4.0.0",
120
124
  "@reopt-ai/opt-editor": ">=1.0.0",
121
125
  "@tanstack/react-query": ">=5.0.0",
122
- "better-auth": "^1.7.1",
126
+ "better-auth": "^1.7.4",
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,14 +154,17 @@
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.7",
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",
159
- "better-auth": "^1.7.1",
167
+ "better-auth": "^1.7.4",
160
168
  "happy-dom": "^20.8.9",
161
169
  "hono": "^4.7.0",
162
170
  "tsdown": "^0.22.14",
@@ -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",