@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.
- package/CHANGELOG.md +111 -3
- package/README.md +29 -13
- package/dist/ai/index.js +4 -3
- package/dist/ai-provider/index.js +16 -2
- package/dist/auth/index.js +4 -3
- package/dist/better-auth/index.d.ts +1 -1
- package/dist/better-auth/index.js +35 -24
- package/dist/chunk-2LSCQHAU.js +21 -0
- package/dist/{chunk-E457LO5A.js → chunk-4U4ZPPL4.js} +4 -4
- package/dist/{chunk-K3YVJE6E.js → chunk-55KHY5GH.js} +3 -3
- package/dist/{chunk-J5Y2GSJF.js → chunk-C5VTRZWX.js} +43 -28
- package/dist/{chunk-KU2LN5SE.js → chunk-FJUCWXX3.js} +4 -4
- package/dist/{chunk-TUKIYH4Q.js → chunk-H33OTQEN.js} +3 -3
- package/dist/chunk-OG7R3UAR.js +105 -0
- package/dist/{chunk-6FLYVNZI.js → chunk-PF24XU54.js} +3 -3
- package/dist/{chunk-6KPKZ7ZB.js → chunk-QN3QD67K.js} +3 -3
- package/dist/{chunk-YRGLBM6V.js → chunk-UGBBXCZE.js} +6 -6
- package/dist/{chunk-WSEROZVO.js → chunk-UVT2E6KD.js} +6 -6
- package/dist/{chunk-PJZB4VP7.js → chunk-YPLT3RFL.js} +3 -3
- package/dist/{chunk-DI6QJPTQ.js → chunk-YTKSAWV2.js} +20 -6
- package/dist/cms/index.js +10 -6
- package/dist/dev/index.d.ts +19 -0
- package/dist/dev/index.js +107 -4
- package/dist/eav/index.d.ts +1 -1
- package/dist/eav/index.js +5 -4
- package/dist/{errors-5hd5ZR-M.d.ts → errors-BjDFIyA6.d.ts} +25 -3
- package/dist/feedback/index.js +4 -3
- package/dist/files/index.js +4 -3
- package/dist/index.d.ts +10 -1
- package/dist/index.js +14 -13
- package/dist/logout/index.d.ts +106 -0
- package/dist/logout/index.js +321 -0
- package/dist/plans/index.d.ts +107 -11
- package/dist/plans/index.js +4 -3
- package/dist/push/index.js +4 -3
- package/dist/react/hooks.d.ts +5 -1
- package/dist/react/hooks.js +63 -15
- package/dist/terms/index.js +4 -3
- package/dist/testing/index.d.ts +1 -1
- package/dist/webhooks/index.d.ts +6 -3
- package/docs/api-reference.md +99 -3
- package/docs/cms.md +0 -1
- package/docs/dev-server.md +19 -18
- package/docs/errors.md +72 -15
- package/docs/logout.md +166 -0
- package/package.json +7 -1
- package/dist/chunk-T2WXHAAC.js +0 -54
package/dist/react/hooks.js
CHANGED
|
@@ -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.
|
|
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.
|
|
183
|
-
queryClient.invalidateQueries({
|
|
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.
|
|
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.
|
|
210
|
-
queryClient.invalidateQueries({
|
|
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.
|
|
221
|
-
queryClient.invalidateQueries({
|
|
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.
|
|
232
|
-
queryClient.invalidateQueries({
|
|
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.
|
|
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.
|
|
258
|
-
queryClient.invalidateQueries({
|
|
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.
|
|
269
|
-
queryClient.invalidateQueries({
|
|
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
|
});
|
package/dist/terms/index.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
export { ReoptTermsClient, createReoptTermsClient } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
3
|
-
import '../chunk-
|
|
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
|
package/dist/testing/index.d.ts
CHANGED
package/dist/webhooks/index.d.ts
CHANGED
|
@@ -87,9 +87,12 @@ declare function createWebhookHandler(config: {
|
|
|
87
87
|
secret: string;
|
|
88
88
|
handlers: WebhookHandlers;
|
|
89
89
|
/**
|
|
90
|
-
* Called when a handler throws.
|
|
91
|
-
*
|
|
92
|
-
*
|
|
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;
|
package/docs/api-reference.md
CHANGED
|
@@ -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 = {
|
|
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)
|
|
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
package/docs/dev-server.md
CHANGED
|
@@ -53,16 +53,17 @@ const dev = await createDevServer({
|
|
|
53
53
|
|
|
54
54
|
### 반환 객체
|
|
55
55
|
|
|
56
|
-
| 속성/메서드
|
|
57
|
-
|
|
|
58
|
-
| `dev.url`
|
|
59
|
-
| `dev.port`
|
|
60
|
-
| `dev.store`
|
|
61
|
-
| `dev.seed(data)`
|
|
62
|
-
| `dev.reset()`
|
|
63
|
-
| `dev.snapshot(path)`
|
|
64
|
-
| `dev.restore(path)`
|
|
65
|
-
| `dev.
|
|
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/*`
|
|
88
|
-
| **Auth** | `/api/v1/brandapp/{id}/auth/adapter`
|
|
89
|
-
| **AI** | `/api/v1/brandapp/{id}/ai/*`
|
|
90
|
-
| **Files** | `/api/v1/brandapp/{id}/files/*`
|
|
91
|
-
| **CMS** | `/api/v1/brandapp/{id}/cms/*`
|
|
92
|
-
| **OAuth** | `/api/auth/.well-known
|
|
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
|
-
| `
|
|
23
|
-
| `
|
|
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
|
|