@reopt-ai/brandapp-sdk 3.0.0 → 3.3.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 (47) hide show
  1. package/CHANGELOG.md +111 -3
  2. package/README.md +29 -13
  3. package/dist/ai/index.js +4 -3
  4. package/dist/ai-provider/index.js +16 -2
  5. package/dist/auth/index.js +4 -3
  6. package/dist/better-auth/index.d.ts +1 -1
  7. package/dist/better-auth/index.js +35 -24
  8. package/dist/chunk-2LSCQHAU.js +21 -0
  9. package/dist/{chunk-E457LO5A.js → chunk-4U4ZPPL4.js} +4 -4
  10. package/dist/{chunk-K3YVJE6E.js → chunk-55KHY5GH.js} +3 -3
  11. package/dist/{chunk-J5Y2GSJF.js → chunk-C5VTRZWX.js} +43 -28
  12. package/dist/{chunk-KU2LN5SE.js → chunk-FJUCWXX3.js} +4 -4
  13. package/dist/{chunk-TUKIYH4Q.js → chunk-H33OTQEN.js} +3 -3
  14. package/dist/chunk-OG7R3UAR.js +105 -0
  15. package/dist/{chunk-6FLYVNZI.js → chunk-PF24XU54.js} +3 -3
  16. package/dist/{chunk-6KPKZ7ZB.js → chunk-QN3QD67K.js} +3 -3
  17. package/dist/{chunk-YRGLBM6V.js → chunk-UGBBXCZE.js} +6 -6
  18. package/dist/{chunk-WSEROZVO.js → chunk-UVT2E6KD.js} +6 -6
  19. package/dist/{chunk-PJZB4VP7.js → chunk-YPLT3RFL.js} +3 -3
  20. package/dist/{chunk-DI6QJPTQ.js → chunk-YTKSAWV2.js} +20 -6
  21. package/dist/cms/index.js +10 -6
  22. package/dist/dev/index.d.ts +19 -0
  23. package/dist/dev/index.js +107 -4
  24. package/dist/eav/index.d.ts +1 -1
  25. package/dist/eav/index.js +5 -4
  26. package/dist/{errors-5hd5ZR-M.d.ts → errors-BjDFIyA6.d.ts} +25 -3
  27. package/dist/feedback/index.js +4 -3
  28. package/dist/files/index.js +4 -3
  29. package/dist/index.d.ts +10 -1
  30. package/dist/index.js +14 -13
  31. package/dist/logout/index.d.ts +106 -0
  32. package/dist/logout/index.js +321 -0
  33. package/dist/plans/index.d.ts +107 -11
  34. package/dist/plans/index.js +4 -3
  35. package/dist/push/index.js +4 -3
  36. package/dist/react/hooks.d.ts +5 -1
  37. package/dist/react/hooks.js +63 -15
  38. package/dist/terms/index.js +4 -3
  39. package/dist/testing/index.d.ts +1 -1
  40. package/dist/webhooks/index.d.ts +6 -3
  41. package/docs/api-reference.md +99 -3
  42. package/docs/cms.md +0 -1
  43. package/docs/dev-server.md +19 -18
  44. package/docs/errors.md +72 -15
  45. package/docs/logout.md +166 -0
  46. package/package.json +7 -1
  47. package/dist/chunk-T2WXHAAC.js +0 -54
@@ -109,8 +109,20 @@ var keys = {
109
109
  entities: (brandappId) => [...keys.all, "entities", brandappId],
110
110
  entity: (entityId) => [...keys.all, "entity", entityId],
111
111
  records: (entityId, query) => [...keys.all, "records", entityId, query],
112
+ // Infinite lists get a DISTINCT namespace: in TanStack v5 useQuery and
113
+ // useInfiniteQuery share one QueryCache keyed by queryHash, so a shared key
114
+ // would collide (PaginatedResponse vs InfiniteData) if both hooks mount for
115
+ // the same entity+query.
116
+ recordsInfinite: (entityId, query) => [...keys.all, "recordsInfinite", entityId, query],
112
117
  record: (entityId, recordId) => [...keys.all, "record", entityId, recordId],
113
118
  recordCount: (entityId, query) => [...keys.all, "recordCount", entityId, query],
119
+ // Length-3 invalidation prefixes. partialMatchKey only prefix-matches a
120
+ // SHORTER key, so `keys.records(entityId)` (trailing `undefined`) fails to
121
+ // match a list queried WITH a query object. These match every finite /
122
+ // infinite record list + count for an entity regardless of its query object.
123
+ recordsPrefix: (entityId) => [...keys.all, "records", entityId],
124
+ recordsInfinitePrefix: (entityId) => [...keys.all, "recordsInfinite", entityId],
125
+ recordCountPrefix: (entityId) => [...keys.all, "recordCount", entityId],
114
126
  aiCredits: (brandappId) => [...keys.all, "ai", "credits", brandappId],
115
127
  aiModels: (brandappId) => [...keys.all, "ai", "models", brandappId],
116
128
  aiAgents: (brandappId) => [...keys.all, "ai", "agents", brandappId],
@@ -150,7 +162,7 @@ function useEavRecords(sdk, entityId, query, options) {
150
162
  }
151
163
  function useEavRecordsInfinite(sdk, entityId, query, options) {
152
164
  return useInfiniteQuery({
153
- queryKey: keys.records(entityId, query),
165
+ queryKey: keys.recordsInfinite(entityId, query),
154
166
  queryFn: ({ pageParam }) => sdk.eav.records.list(entityId, { ...query, page: pageParam }),
155
167
  initialPageParam: 1,
156
168
  getNextPageParam: (lastPage) => lastPage.page < lastPage.totalPages ? lastPage.page + 1 : void 0,
@@ -179,8 +191,13 @@ function useCreateRecord(sdk, entityId, options) {
179
191
  return useMutation({
180
192
  mutationFn: (input) => sdk.eav.records.create(entityId, input),
181
193
  onSuccess: () => {
182
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
183
- queryClient.invalidateQueries({ queryKey: keys.recordCount(entityId) });
194
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
195
+ queryClient.invalidateQueries({
196
+ queryKey: keys.recordsInfinitePrefix(entityId)
197
+ });
198
+ queryClient.invalidateQueries({
199
+ queryKey: keys.recordCountPrefix(entityId)
200
+ });
184
201
  },
185
202
  ...options
186
203
  });
@@ -193,7 +210,10 @@ function useUpdateRecord(sdk, entityId, options) {
193
210
  input
194
211
  }) => sdk.eav.records.update(entityId, recordId, input),
195
212
  onSuccess: (_, variables) => {
196
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
213
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
214
+ queryClient.invalidateQueries({
215
+ queryKey: keys.recordsInfinitePrefix(entityId)
216
+ });
197
217
  queryClient.invalidateQueries({
198
218
  queryKey: keys.record(entityId, variables.recordId)
199
219
  });
@@ -206,8 +226,13 @@ function useDeleteRecord(sdk, entityId, options) {
206
226
  return useMutation({
207
227
  mutationFn: (recordId) => sdk.eav.records.delete(entityId, recordId),
208
228
  onSuccess: () => {
209
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
210
- queryClient.invalidateQueries({ queryKey: keys.recordCount(entityId) });
229
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
230
+ queryClient.invalidateQueries({
231
+ queryKey: keys.recordsInfinitePrefix(entityId)
232
+ });
233
+ queryClient.invalidateQueries({
234
+ queryKey: keys.recordCountPrefix(entityId)
235
+ });
211
236
  },
212
237
  ...options
213
238
  });
@@ -217,8 +242,13 @@ function useUpsertRecord(sdk, entityId, options) {
217
242
  return useMutation({
218
243
  mutationFn: (input) => sdk.eav.records.upsert(entityId, input),
219
244
  onSuccess: () => {
220
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
221
- queryClient.invalidateQueries({ queryKey: keys.recordCount(entityId) });
245
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
246
+ queryClient.invalidateQueries({
247
+ queryKey: keys.recordsInfinitePrefix(entityId)
248
+ });
249
+ queryClient.invalidateQueries({
250
+ queryKey: keys.recordCountPrefix(entityId)
251
+ });
222
252
  },
223
253
  ...options
224
254
  });
@@ -228,8 +258,13 @@ function useBulkCreateRecords(sdk, entityId, options) {
228
258
  return useMutation({
229
259
  mutationFn: (records) => sdk.eav.records.bulkCreate(entityId, records),
230
260
  onSuccess: () => {
231
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
232
- queryClient.invalidateQueries({ queryKey: keys.recordCount(entityId) });
261
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
262
+ queryClient.invalidateQueries({
263
+ queryKey: keys.recordsInfinitePrefix(entityId)
264
+ });
265
+ queryClient.invalidateQueries({
266
+ queryKey: keys.recordCountPrefix(entityId)
267
+ });
233
268
  },
234
269
  ...options
235
270
  });
@@ -239,7 +274,10 @@ function useBulkUpdateRecords(sdk, entityId, options) {
239
274
  return useMutation({
240
275
  mutationFn: (updates) => sdk.eav.records.bulkUpdate(entityId, updates),
241
276
  onSuccess: (_data, variables) => {
242
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
277
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
278
+ queryClient.invalidateQueries({
279
+ queryKey: keys.recordsInfinitePrefix(entityId)
280
+ });
243
281
  for (const { id } of variables) {
244
282
  queryClient.invalidateQueries({
245
283
  queryKey: keys.record(entityId, id)
@@ -254,8 +292,13 @@ function useBulkDeleteRecords(sdk, entityId, options) {
254
292
  return useMutation({
255
293
  mutationFn: (ids) => sdk.eav.records.bulkDelete(entityId, ids),
256
294
  onSuccess: () => {
257
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
258
- queryClient.invalidateQueries({ queryKey: keys.recordCount(entityId) });
295
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
296
+ queryClient.invalidateQueries({
297
+ queryKey: keys.recordsInfinitePrefix(entityId)
298
+ });
299
+ queryClient.invalidateQueries({
300
+ queryKey: keys.recordCountPrefix(entityId)
301
+ });
259
302
  },
260
303
  ...options
261
304
  });
@@ -265,8 +308,13 @@ function useDeleteRecordsWhere(sdk, entityId, options) {
265
308
  return useMutation({
266
309
  mutationFn: (input) => sdk.eav.records.deleteWhere(entityId, input),
267
310
  onSuccess: () => {
268
- queryClient.invalidateQueries({ queryKey: keys.records(entityId) });
269
- queryClient.invalidateQueries({ queryKey: keys.recordCount(entityId) });
311
+ queryClient.invalidateQueries({ queryKey: keys.recordsPrefix(entityId) });
312
+ queryClient.invalidateQueries({
313
+ queryKey: keys.recordsInfinitePrefix(entityId)
314
+ });
315
+ queryClient.invalidateQueries({
316
+ queryKey: keys.recordCountPrefix(entityId)
317
+ });
270
318
  },
271
319
  ...options
272
320
  });
@@ -1,5 +1,6 @@
1
- export { ReoptTermsClient, createReoptTermsClient } from '../chunk-TUKIYH4Q.js';
2
- import '../chunk-DI6QJPTQ.js';
3
- import '../chunk-J5Y2GSJF.js';
1
+ export { ReoptTermsClient, createReoptTermsClient } from '../chunk-H33OTQEN.js';
2
+ import '../chunk-YTKSAWV2.js';
3
+ import '../chunk-2LSCQHAU.js';
4
+ import '../chunk-C5VTRZWX.js';
4
5
  //# sourceMappingURL=index.js.map
5
6
  //# sourceMappingURL=index.js.map
@@ -10,7 +10,7 @@ import '../client-CN5_tNOC.js';
10
10
  import '../feedback/index.js';
11
11
  import '../client-DttyeM_h.js';
12
12
  import '../ai/index.js';
13
- import '../errors-5hd5ZR-M.js';
13
+ import '../errors-BjDFIyA6.js';
14
14
  import '../typed-client-BxOVIiMU.js';
15
15
 
16
16
  /**
@@ -87,9 +87,12 @@ declare function createWebhookHandler(config: {
87
87
  secret: string;
88
88
  handlers: WebhookHandlers;
89
89
  /**
90
- * Called when a handler throws. Receives `attempt` so you can decide
91
- * whether to forward to a DLQ vs. let the sender retry. The handler still
92
- * returns 500 to the caller, ensuring the sender retries by default.
90
+ * Called when a handler throws. The handler still returns 500 to the caller.
91
+ * `meta.attempt` reflects the `x-reopt-delivery-attempt` header when the
92
+ * sender provides one; the current reopt sender is best-effort with no retry
93
+ * queue (it does not send that header), so `attempt` is `1` in practice —
94
+ * treat it as advisory, not a reliable retry counter. Deliveries are
95
+ * at-least-once, so dedupe on `payload.id` (see `idempotency`).
93
96
  */
94
97
  onError?: (error: Error, payload: WebhookPayload, meta: {
95
98
  attempt: number;
@@ -20,6 +20,11 @@
20
20
  | `@reopt-ai/brandapp-sdk/testing` | `createTestSDK` for Vitest fixtures |
21
21
  | `@reopt-ai/brandapp-sdk/cms` | CMS posts/post-groups/tags (read-only) + SEO / Sitemap / RSS helpers + `EditorSpec` |
22
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`) |
23
28
 
24
29
  ## Core SDK
25
30
 
@@ -43,7 +48,7 @@ const sdk = createReoptSDK({
43
48
  debug?: boolean; // Enable debug logging
44
49
  });
45
50
 
46
- // Returns: { config, ai, auth, cms, eav, files }
51
+ // Returns: { config, ai, auth, cms, eav, feedback, files, plans, push, terms }
47
52
  ```
48
53
 
49
54
  ### Errors
@@ -74,7 +79,14 @@ optional fourth argument for per-call cancellation / timeout overrides:
74
79
 
75
80
  ```typescript
76
81
  import type { FetchOptions } from "@reopt-ai/brandapp-sdk";
77
- // type FetchOptions = { signal?: AbortSignal; timeout?: number };
82
+ // type FetchOptions = {
83
+ // signal?: AbortSignal; // caller cancellation → rejects with CANCELLED
84
+ // // (err.name === "AbortError"), stops retrying
85
+ // timeout?: number; // per-call timeout override (ms)
86
+ // bearerToken?: string; // Bearer instead of Basic for this call
87
+ // idempotent?: boolean; // treat a POST/PATCH read as retryable on 5xx
88
+ // // (never set on a real mutation)
89
+ // };
78
90
  ```
79
91
 
80
92
  ## AI Client (`sdk.ai`)
@@ -462,7 +474,7 @@ export function PostBody({ contentRich }: { contentRich: EditorSpec }) {
462
474
  }
463
475
  ```
464
476
 
465
- 자세한 데모는 [`docs/cms.md`](./cms.md) 또는 `apps/brandapp-playground/app/cms/posts/[slug]` 참고.
477
+ 자세한 데모는 [`docs/cms.md`](./cms.md) 참고.
466
478
 
467
479
  ## Terms Client (`sdk.terms`)
468
480
 
@@ -481,6 +493,51 @@ const { count } = await sdk.terms.consent({ consents: [...] }, accessToken);
481
493
  const { id } = await sdk.terms.withdraw(consentId, accessToken);
482
494
  ```
483
495
 
496
+ ## Plans Client (`sdk.plans`) — catalog + hosted checkout (3.1+)
497
+
498
+ ```typescript
499
+ import {
500
+ isRequiredTermsError,
501
+ type Plan,
502
+ type CheckoutSession,
503
+ type CurrentPlan,
504
+ } from "@reopt-ai/brandapp-sdk/plans";
505
+
506
+ // Catalog — Basic Auth (or pass an accessToken to use Bearer)
507
+ const plans: Plan[] = await sdk.plans.list();
508
+
509
+ // The current customer's plan / entitlement (Bearer). null if none.
510
+ const current: CurrentPlan | null = await sdk.plans.getMyPlan(accessToken);
511
+
512
+ // Hosted checkout (Bearer). In sandbox mode checkoutUrl is an id.reopt.ai
513
+ // virtual-payment page; redirect the browser there.
514
+ try {
515
+ const checkout: CheckoutSession = await sdk.plans.createCheckout(
516
+ { planId: plans[0].id, successUrl, cancelUrl },
517
+ accessToken,
518
+ );
519
+ redirect(checkout.checkoutUrl!); // → pay, then back to successUrl/cancelUrl
520
+ } catch (e) {
521
+ if (isRequiredTermsError(e)) {
522
+ // collect consent for e.missingTermsIds via sdk.terms, then retry
523
+ } else throw e;
524
+ }
525
+
526
+ // On the return page, confirm the checkout / entitlement:
527
+ const session = await sdk.plans.getCheckout(checkout.checkoutId, accessToken);
528
+ if (session.status === "completed") {
529
+ /* granted */
530
+ }
531
+
532
+ // Cancel the current sandbox subscription (access kept until period end):
533
+ await sdk.plans.cancel(accessToken);
534
+ ```
535
+
536
+ > Live Toss/Paddle checkout is not driven through the SDK yet — `createCheckout`
537
+ > returns HTTP 409 `LIVE_MODE_UNSUPPORTED` when the Brandapp is set to live
538
+ > payments (use the first-party brandfront flow). usage-model meters are
539
+ > read-only metadata.
540
+
484
541
  ## Webhooks
485
542
 
486
543
  ```typescript
@@ -555,3 +612,42 @@ const { data: tags } = useCmsTags(sdk, { groupId? });
555
612
 
556
613
  > **1.8 변경**: `useCreatePost` / `useUpdatePost` / `useDeletePost`는 cms write
557
614
  > 표면 제거에 따라 함께 제거됐다. authoring은 Reopt Studio가 담당한다.
615
+
616
+ ## Logout — OIDC Single Logout (3.2+)
617
+
618
+ Two directions of session-termination interop with reopt. Full guide:
619
+ [`logout.md`](./logout.md).
620
+
621
+ ```typescript
622
+ import {
623
+ createBackchannelLogoutHandler,
624
+ verifyBackchannelLogoutToken,
625
+ buildEndSessionUrl,
626
+ } from "@reopt-ai/brandapp-sdk/logout";
627
+
628
+ // 1) RECEIVE — reopt POSTs a logout_token when it revokes the IdP session.
629
+ // Mount as a Web-standard Request→Response handler (Next.js/Hono/Fetch).
630
+ // app/api/auth/backchannel-logout/route.ts
631
+ export const POST = createBackchannelLogoutHandler({
632
+ onLogout: async ({ sid, sub }) => {
633
+ await revokeSessionsByReoptSid(sid); // end your derived RP sessions (idempotent)
634
+ },
635
+ });
636
+ // Responses: 200 ok · 400 invalid logout_token · 405 non-POST ·
637
+ // 501 onLogout threw (retry) · 503 verification infra unavailable (retry)
638
+ // Signature: Web Crypto Ed25519 (EdDSA), zero external deps. JWKS is fetched
639
+ // from discovery, cached, and force-refetched (throttled) on key rotation.
640
+
641
+ // verify without the HTTP wrapper (custom transport / tests):
642
+ const { sid, sub } = await verifyBackchannelLogoutToken(logoutToken, {
643
+ clientId, // or BRANDAPP_CLIENT_ID
644
+ });
645
+
646
+ // 2) TRIGGER — send the user to reopt's end_session_endpoint (RP-Initiated).
647
+ const url = buildEndSessionUrl({
648
+ idToken: session.idToken, // id_token_hint
649
+ postLogoutRedirectUri: "https://app.example.com/goodbye", // pre-registered
650
+ state: csrfToken,
651
+ });
652
+ redirect(url);
653
+ ```
package/docs/cms.md CHANGED
@@ -313,6 +313,5 @@ await dev.seedAll({
313
313
 
314
314
  ## 다음 단계
315
315
 
316
- - 외부 마케팅 사이트 전체 데모: `apps/brandapp-playground/app/cms/posts/[slug]`
317
316
  - 1.7 → 1.8 변경: [`migration.md`](./migration.md)
318
317
  - 이미지 결합 패턴: [`files.md`](./files.md)
@@ -53,16 +53,17 @@ const dev = await createDevServer({
53
53
 
54
54
  ### 반환 객체
55
55
 
56
- | 속성/메서드 | 설명 |
57
- | -------------------- | --------------------------------------- |
58
- | `dev.url` | 서버 URL (e.g. `http://localhost:4300`) |
59
- | `dev.port` | 서버 포트 |
60
- | `dev.store` | 인메모리 저장소 (InMemoryStore) |
61
- | `dev.seed(data)` | 엔티티별 레코드 시딩 |
62
- | `dev.reset()` | 전체 초기화 + 스키마 재시딩 |
63
- | `dev.snapshot(path)` | 현재 상태를 JSON 파일로 저장 |
64
- | `dev.restore(path)` | JSON 파일에서 상태 복원 |
65
- | `dev.close()` | 서버 종료 |
56
+ | 속성/메서드 | 설명 |
57
+ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
58
+ | `dev.url` | 서버 URL (e.g. `http://localhost:4300`) |
59
+ | `dev.port` | 서버 포트 |
60
+ | `dev.store` | 인메모리 저장소 (InMemoryStore) |
61
+ | `dev.seed(data)` | 엔티티별 레코드 시딩 |
62
+ | `dev.reset()` | 전체 초기화 + 스키마 재시딩 |
63
+ | `dev.snapshot(path)` | 현재 상태를 JSON 파일로 저장 |
64
+ | `dev.restore(path)` | JSON 파일에서 상태 복원 |
65
+ | `dev.mintLogoutToken(input)` | dev IdP가 서명한 실 EdDSA `logout_token` 발급 (OIDC Single Logout 핸들러 e2e 테스트용, 상세: [logout.md](./logout.md)) |
66
+ | `dev.close()` | 서버 종료 |
66
67
 
67
68
  ### `seed(data)`
68
69
 
@@ -82,14 +83,14 @@ await dev.seed({
82
83
 
83
84
  ## 지원하는 API
84
85
 
85
- | 모듈 | 엔드포인트 | 동작 |
86
- | --------- | ------------------------------------ | ----------------------------------------------------------- |
87
- | **EAV** | `/api/v1/brandapp/{id}/eav/*` | Entity/Attribute/Record CRUD + 벌크 + 필터링 + 정렬 |
88
- | **Auth** | `/api/v1/brandapp/{id}/auth/adapter` | Better Auth 어댑터 (user/session/account/verification CRUD) |
89
- | **AI** | `/api/v1/brandapp/{id}/ai/*` | Mock 텍스트/이미지 생성, 모델 목록, 크레딧 |
90
- | **Files** | `/api/v1/brandapp/{id}/files/*` | 인메모리 파일 업로드/다운로드/삭제 |
91
- | **CMS** | `/api/v1/brandapp/{id}/cms/*` | Post/PostGroup CRUD |
92
- | **OAuth** | `/api/auth/.well-known/*` | OIDC Discovery + Mock 토큰 발급 |
86
+ | 모듈 | 엔드포인트 | 동작 |
87
+ | --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
88
+ | **EAV** | `/api/v1/brandapp/{id}/eav/*` | Entity/Attribute/Record CRUD + 벌크 + 필터링 + 정렬 |
89
+ | **Auth** | `/api/v1/brandapp/{id}/auth/adapter` | Better Auth 어댑터 (user/session/account/verification CRUD) |
90
+ | **AI** | `/api/v1/brandapp/{id}/ai/*` | Mock 텍스트/이미지 생성, 모델 목록, 크레딧 |
91
+ | **Files** | `/api/v1/brandapp/{id}/files/*` | 인메모리 파일 업로드/다운로드/삭제 |
92
+ | **CMS** | `/api/v1/brandapp/{id}/cms/*` | Post/PostGroup CRUD |
93
+ | **OAuth** | `/api/auth/.well-known/*`, `/api/auth/{token,jwks,oauth2/end-session}` | OIDC Discovery + EdDSA로 서명된 mock `id_token` + JWKS + RP-initiated end-session (faithful OIDC mock) |
93
94
 
94
95
  ---
95
96
 
package/docs/errors.md CHANGED
@@ -6,21 +6,40 @@ All SDK errors extend `ReoptSDKError` and include a `.diagnostic` property with
6
6
 
7
7
  ### General
8
8
 
9
- | Error Class | Status | Code | When |
10
- | -------------------- | ------ | --------------------- | ---------------------------------------- |
11
- | `AuthError` | 401 | `AUTH_ERROR` | Invalid clientId/clientSecret |
12
- | `BadRequestError` | 400 | `BAD_REQUEST` | Malformed request (body / params) |
13
- | `ForbiddenError` | 403 | `FORBIDDEN` | No permission for the resource |
14
- | `NotFoundError` | 404 | `NOT_FOUND` | Resource does not exist (or was deleted) |
15
- | `ConflictError` | 409 | `CONFLICT` | State conflict (duplicate key, race) |
16
- | `ValidationError` | 422 | `VALIDATION_ERROR` | Field-level validation failure |
17
- | `RateLimitError` | 429 | `RATE_LIMIT` | Too many requests |
18
- | `CreditLimitError` | 402 | `CREDIT_LIMIT` | AI credit balance exhausted |
19
- | `ModelAccessError` | 403 | `MODEL_ACCESS_DENIED` | Model not available for this plan tier |
20
- | `ModelNotFoundError` | 404 | `MODEL_NOT_FOUND` | Unknown model id (typo / retired) |
21
- | `ContentFilterError` | 422 | `CONTENT_FILTER` | Blocked by moderation policy |
22
- | `ServerError` | 500 | `SERVER_ERROR` | Internal server error |
23
- | `ReoptSDKError` | varies | varies | Base class (other / future API errors) |
9
+ | Error Class | Status | Code | When |
10
+ | -------------------- | ------ | --------------------- | ------------------------------------------------------------ |
11
+ | `AuthError` | 401 | `AUTH_ERROR` | Invalid clientId/clientSecret |
12
+ | `BadRequestError` | 400 | `BAD_REQUEST` | Malformed request (body / params) |
13
+ | `ForbiddenError` | 403 | `FORBIDDEN` | No permission for the resource |
14
+ | `NotFoundError` | 404 | `NOT_FOUND` | Resource does not exist (or was deleted) |
15
+ | `ConflictError` | 409 | `CONFLICT` | State conflict (duplicate key, race) |
16
+ | `ValidationError` | 422 | `VALIDATION_ERROR` | Field-level validation failure |
17
+ | `RateLimitError` | 429 | `RATE_LIMIT` | Too many requests |
18
+ | `CreditLimitError` | 402 | `CREDIT_LIMIT` | AI credit balance exhausted |
19
+ | `ModelAccessError` | 403 | `MODEL_ACCESS_DENIED` | Model not available for this plan tier |
20
+ | `ModelNotFoundError` | 404 | `MODEL_NOT_FOUND` | Unknown model id (typo / retired) |
21
+ | `ContentFilterError` | 422 | `CONTENT_FILTER` | Blocked by moderation policy |
22
+ | `RequiredTermsError` | 422 | `REQUIRED_TERMS` | Plan checkout needs terms consent ([below](#required_terms)) |
23
+ | `ServerError` | 500 | `SERVER_ERROR` | Internal server error |
24
+ | `ReoptSDKError` | varies | varies | Base class (other / future API errors) |
25
+
26
+ `RequiredTermsError` (thrown by `sdk.plans.createCheckout`) carries
27
+ `missingTermsIds: string[]`; guard with `isRequiredTermsError(e)`.
28
+
29
+ ### Logout (OIDC Single Logout — `@reopt-ai/brandapp-sdk/logout`)
30
+
31
+ Raised by `verifyBackchannelLogoutToken` / `createBackchannelLogoutHandler`
32
+ (plain `ReoptSDKError` with a code — no dedicated subclass):
33
+
34
+ | Status | Code | When |
35
+ | ------ | --------------------------------- | --------------------------------------------------------------------- |
36
+ | 400 | `invalid_logout_token` | logout_token failed validation (bad signature / claims / structure) |
37
+ | 503 | `logout_verification_unavailable` | discovery/JWKS temporarily unreachable — **retryable**, not the token |
38
+
39
+ The handler maps `invalid_logout_token` → HTTP 400 and
40
+ `logout_verification_unavailable` → HTTP 503 (so the IdP retries instead of
41
+ treating a transient JWKS outage as a permanently bad token). See
42
+ [logout.md](./logout.md) for the full response contract.
24
43
 
25
44
  > Every subclass sets `error.name` to its own class name (e.g. `"AuthError"`,
26
45
  > `"RateLimitError"`, `"CreditLimitError"`) so log aggregation / Sentry grouping
@@ -203,6 +222,29 @@ type ErrorDiagnostic = {
203
222
  - **Fix**: Check `error.fieldErrors` for per-field details
204
223
  - **Example**: `error.toFieldMap()` returns `{ email: "Invalid email format" }`
205
224
 
225
+ <a id="required_terms"></a>
226
+
227
+ ### REQUIRED_TERMS: plan checkout needs terms consent (422)
228
+
229
+ - **Cause**: `sdk.plans.createCheckout` was called for a plan whose required
230
+ terms the customer has not yet consented to.
231
+ - **Fix**: read `error.missingTermsIds`, collect consent via `sdk.terms.list()`
232
+ \+ `sdk.terms.consent()`, then retry `createCheckout`.
233
+ - **Class**: `RequiredTermsError` — guard with `isRequiredTermsError(e)`; carries
234
+ `missingTermsIds: string[]`.
235
+
236
+ ```ts
237
+ import { isRequiredTermsError } from "@reopt-ai/brandapp-sdk";
238
+
239
+ try {
240
+ await sdk.plans.createCheckout({ planId, successUrl, cancelUrl }, token);
241
+ } catch (e) {
242
+ if (isRequiredTermsError(e)) {
243
+ // show consent UI for e.missingTermsIds, then retry
244
+ } else throw e;
245
+ }
246
+ ```
247
+
206
248
  ### FORBIDDEN: `Forbidden` / `Model tier not available` (403)
207
249
 
208
250
  - **Cause**: No permission for the resource — e.g. the requested model
@@ -272,6 +314,21 @@ type ErrorDiagnostic = {
272
314
  - **Retries**: 5xx/network/timeout failures are retried only for idempotent
273
315
  methods (GET/HEAD/PUT/DELETE) by default; POST/PATCH are not retried to avoid
274
316
  duplicate side effects (opt in via `retryNonIdempotent`). 429 is always retried.
317
+ A single read tunneled over POST can opt into retry per-call with the
318
+ `idempotent` fetch option (the Better Auth adapter uses this for
319
+ `findOne`/`findMany`/`count`).
320
+ - **Note**: `TIMEOUT` is reserved for the internal wall-clock/idle deadline. A
321
+ request you cancel via your own `AbortSignal` rejects with a distinct
322
+ `CANCELLED` error whose `name` is `"AbortError"` (the standard web
323
+ cancellation convention) and stops retrying immediately.
324
+
325
+ ### CANCELLED: caller aborted the request (0)
326
+
327
+ - **Cause**: The `AbortSignal` you passed as `FetchOptions.signal` was aborted
328
+ (e.g. React component unmount, request supersession).
329
+ - **Detect**: `err.name === "AbortError"` (or `err.code === "CANCELLED"`).
330
+ - **Note**: Distinct from `TIMEOUT` (408) — a caller cancel is not a server
331
+ timeout, and the retry loop breaks on it rather than burning retries.
275
332
 
276
333
  ## Debug Mode
277
334