@reopt-ai/brandapp-sdk 3.0.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 +574 -0
- package/LICENSE +21 -0
- package/README.md +468 -0
- package/dist/ai/index.d.ts +314 -0
- package/dist/ai/index.js +7 -0
- package/dist/ai-provider/index.d.ts +196 -0
- package/dist/ai-provider/index.js +703 -0
- package/dist/auth/index.d.ts +76 -0
- package/dist/auth/index.js +40 -0
- package/dist/better-auth/client.d.ts +29 -0
- package/dist/better-auth/client.js +10 -0
- package/dist/better-auth/index.d.ts +82 -0
- package/dist/better-auth/index.js +145 -0
- package/dist/chunk-6FLYVNZI.js +32 -0
- package/dist/chunk-6KPKZ7ZB.js +49 -0
- package/dist/chunk-DI6QJPTQ.js +449 -0
- package/dist/chunk-E457LO5A.js +599 -0
- package/dist/chunk-F7BXBTZI.js +54 -0
- package/dist/chunk-J5Y2GSJF.js +443 -0
- package/dist/chunk-K3YVJE6E.js +96 -0
- package/dist/chunk-KU2LN5SE.js +350 -0
- package/dist/chunk-L4DHB36G.js +75 -0
- package/dist/chunk-PJZB4VP7.js +63 -0
- package/dist/chunk-REIKXSMY.js +7 -0
- package/dist/chunk-T2WXHAAC.js +54 -0
- package/dist/chunk-TUKIYH4Q.js +112 -0
- package/dist/chunk-WSEROZVO.js +81 -0
- package/dist/chunk-YRGLBM6V.js +157 -0
- package/dist/client-BkcO-0C2.d.ts +216 -0
- package/dist/client-CN5_tNOC.d.ts +147 -0
- package/dist/client-DttyeM_h.d.ts +102 -0
- package/dist/cms/index.d.ts +137 -0
- package/dist/cms/index.js +101 -0
- package/dist/config-CtxyJsDR.d.ts +397 -0
- package/dist/dev/index.d.ts +509 -0
- package/dist/dev/index.js +3071 -0
- package/dist/eav/coerce.d.ts +42 -0
- package/dist/eav/coerce.js +65 -0
- package/dist/eav/index.d.ts +214 -0
- package/dist/eav/index.js +147 -0
- package/dist/eav/migrate.d.ts +236 -0
- package/dist/eav/migrate.js +219 -0
- package/dist/eav/schema.d.ts +260 -0
- package/dist/eav/schema.js +656 -0
- package/dist/errors-5hd5ZR-M.d.ts +158 -0
- package/dist/feedback/index.d.ts +132 -0
- package/dist/feedback/index.js +5 -0
- package/dist/files/index.d.ts +54 -0
- package/dist/files/index.js +31 -0
- package/dist/index.d.ts +221 -0
- package/dist/index.js +84 -0
- package/dist/plans/index.d.ts +140 -0
- package/dist/plans/index.js +5 -0
- package/dist/push/index.d.ts +79 -0
- package/dist/push/index.js +5 -0
- package/dist/react/hooks.d.ts +376 -0
- package/dist/react/hooks.js +421 -0
- package/dist/terms/index.d.ts +79 -0
- package/dist/terms/index.js +5 -0
- package/dist/testing/index.d.ts +154 -0
- package/dist/testing/index.js +81 -0
- package/dist/typed-client-BxOVIiMU.d.ts +40 -0
- package/dist/types-6E3ZLL9X.d.ts +24 -0
- package/dist/types-DskYLVb8.d.ts +104 -0
- package/dist/types-ckmDDW3N.d.ts +129 -0
- package/dist/webhooks/index.d.ts +140 -0
- package/dist/webhooks/index.js +142 -0
- package/docs/api-reference.md +557 -0
- package/docs/cms.md +318 -0
- package/docs/dev-server.md +164 -0
- package/docs/environment.md +211 -0
- package/docs/errors.md +290 -0
- package/docs/files.md +272 -0
- package/docs/migration.md +315 -0
- package/docs/testing.md +163 -0
- package/package.json +173 -0
package/README.md
ADDED
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
# @reopt-ai/brandapp-sdk
|
|
2
|
+
|
|
3
|
+
Reopt Brandapp SDK — Better Auth adapter, OAuth login, EAV client, and type-safe schema sync.
|
|
4
|
+
|
|
5
|
+
- Edge Runtime / Cloudflare Workers / browser compatible (no `Buffer` dependency)
|
|
6
|
+
- Automatic retry with exponential backoff & `Retry-After` header support
|
|
7
|
+
- Config validation at init — fail fast on missing credentials
|
|
8
|
+
- `isProduction` auto-detected from `NODE_ENV`
|
|
9
|
+
- **Type-safe entity client** with `defineSchema` integration
|
|
10
|
+
- **Built-in pagination** (`listAll` async generator)
|
|
11
|
+
- **Lazy SDK singleton** — zero-config initialization
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @reopt-ai/brandapp-sdk
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
### Better Auth (Recommended)
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
// auth.ts
|
|
25
|
+
import { betterAuth } from "better-auth";
|
|
26
|
+
import { createReoptBetterAuth } from "@reopt-ai/brandapp-sdk/better-auth";
|
|
27
|
+
|
|
28
|
+
const reopt = createReoptBetterAuth({
|
|
29
|
+
clientId: process.env.BRANDAPP_CLIENT_ID!,
|
|
30
|
+
clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
|
|
31
|
+
brandappId: process.env.BRANDAPP_ID!,
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
export const auth = betterAuth({
|
|
35
|
+
database: reopt.database,
|
|
36
|
+
plugins: [reopt.oauth],
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
// auth-client.ts
|
|
42
|
+
import { createAuthClient } from "better-auth/client";
|
|
43
|
+
import {
|
|
44
|
+
createReoptOAuthClient,
|
|
45
|
+
REOPT_PROVIDER_ID,
|
|
46
|
+
} from "@reopt-ai/brandapp-sdk/better-auth/client";
|
|
47
|
+
|
|
48
|
+
export const authClient = createAuthClient({
|
|
49
|
+
plugins: [createReoptOAuthClient()],
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
authClient.signIn.oauth2({
|
|
53
|
+
providerId: REOPT_PROVIDER_ID,
|
|
54
|
+
callbackURL: "/dashboard",
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Unified SDK
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { createReoptSDK } from "@reopt-ai/brandapp-sdk";
|
|
62
|
+
|
|
63
|
+
const sdk = createReoptSDK({
|
|
64
|
+
clientId: process.env.BRANDAPP_CLIENT_ID!,
|
|
65
|
+
clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
|
|
66
|
+
brandappId: process.env.BRANDAPP_ID!,
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
const entities = await sdk.eav.entities.list();
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### External marketing site (1.8+)
|
|
73
|
+
|
|
74
|
+
블로그·약관·sitemap·RSS·세션 인식까지 SDK 호출만으로 외부 Next.js
|
|
75
|
+
마케팅 사이트를 운영하는 시나리오. 자세한 레퍼런스는 [`docs/cms.md`](./docs/cms.md).
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
// app/blog/[slug]/page.tsx — Server Component
|
|
79
|
+
import type { Metadata } from "next";
|
|
80
|
+
import { notFound } from "next/navigation";
|
|
81
|
+
import { createReoptSDK } from "@reopt-ai/brandapp-sdk";
|
|
82
|
+
import { toMetadata } from "@reopt-ai/brandapp-sdk/cms";
|
|
83
|
+
import { PostBody } from "./post-body"; // opt-editor StaticRenderer wrapper
|
|
84
|
+
|
|
85
|
+
const sdk = createReoptSDK({
|
|
86
|
+
/* ... */
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
export async function generateMetadata({ params }): Promise<Metadata> {
|
|
90
|
+
const { slug } = await params;
|
|
91
|
+
const post = await sdk.cms.posts.getBySlug(slug);
|
|
92
|
+
return toMetadata(post, { siteUrl: "https://www.example.com" });
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export default async function Page({ params }) {
|
|
96
|
+
const { slug } = await params;
|
|
97
|
+
const post = await sdk.cms.posts.getBySlug(slug).catch(() => null);
|
|
98
|
+
if (!post) notFound();
|
|
99
|
+
return (
|
|
100
|
+
<article>
|
|
101
|
+
<h1>{post.title}</h1>
|
|
102
|
+
<PostBody contentRich={post.document.contentRich} />
|
|
103
|
+
</article>
|
|
104
|
+
);
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
// app/sitemap.ts + app/rss.xml/route.ts
|
|
110
|
+
import type { MetadataRoute } from "next";
|
|
111
|
+
import { toRssFeed, toSitemapItems } from "@reopt-ai/brandapp-sdk/cms";
|
|
112
|
+
|
|
113
|
+
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
|
|
114
|
+
const { records } = await sdk.cms.posts.list({
|
|
115
|
+
status: "published",
|
|
116
|
+
limit: 200,
|
|
117
|
+
});
|
|
118
|
+
return toSitemapItems(records, { siteUrl: "https://www.example.com" });
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
// /rss.xml
|
|
122
|
+
export async function GET() {
|
|
123
|
+
const { records } = await sdk.cms.posts.list({
|
|
124
|
+
status: "published",
|
|
125
|
+
limit: 50,
|
|
126
|
+
});
|
|
127
|
+
const xml = toRssFeed(records, {
|
|
128
|
+
siteUrl: "https://www.example.com",
|
|
129
|
+
title: "Example Blog",
|
|
130
|
+
description: "Recent posts.",
|
|
131
|
+
});
|
|
132
|
+
return new Response(xml, {
|
|
133
|
+
headers: { "Content-Type": "application/rss+xml" },
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
// 같은 .reopt.ai 서브도메인 cookie로 사용자 세션 인식
|
|
140
|
+
import { cookies } from "next/headers";
|
|
141
|
+
import { getSessionFromCookies } from "@reopt-ai/brandapp-sdk/auth";
|
|
142
|
+
|
|
143
|
+
const cookieHeader = (await cookies())
|
|
144
|
+
.getAll()
|
|
145
|
+
.map((c) => `${c.name}=${c.value}`)
|
|
146
|
+
.join("; ");
|
|
147
|
+
const session = await getSessionFromCookies(cookieHeader, {
|
|
148
|
+
idServerUrl: "https://id.reopt.ai",
|
|
149
|
+
});
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Type-Safe Entity Client
|
|
153
|
+
|
|
154
|
+
Define a schema and get full TypeScript autocompletion on records:
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
import { createReoptSDK } from "@reopt-ai/brandapp-sdk";
|
|
158
|
+
import { defineEntity, defineSchema } from "@reopt-ai/brandapp-sdk/eav/schema";
|
|
159
|
+
|
|
160
|
+
const contacts = defineEntity({
|
|
161
|
+
name: "contacts",
|
|
162
|
+
attributes: {
|
|
163
|
+
name: { dataType: "string", label: "Name", isRequired: true },
|
|
164
|
+
email: { dataType: "email", label: "Email", isUnique: true },
|
|
165
|
+
status: {
|
|
166
|
+
dataType: "select",
|
|
167
|
+
label: "Status",
|
|
168
|
+
options: [
|
|
169
|
+
{ value: "active", label: "Active" },
|
|
170
|
+
{ value: "inactive", label: "Inactive" },
|
|
171
|
+
] as const,
|
|
172
|
+
},
|
|
173
|
+
},
|
|
174
|
+
});
|
|
175
|
+
|
|
176
|
+
const schema = defineSchema({ entities: { contacts } });
|
|
177
|
+
|
|
178
|
+
const sdk = createReoptSDK({
|
|
179
|
+
clientId: process.env.BRANDAPP_CLIENT_ID!,
|
|
180
|
+
clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
|
|
181
|
+
brandappId: process.env.BRANDAPP_ID!,
|
|
182
|
+
schema,
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
// Typed records — values are fully typed!
|
|
186
|
+
const c = sdk.eav.entity("contacts");
|
|
187
|
+
const record = await c.records.create({
|
|
188
|
+
values: { name: "John", email: "john@example.com", status: "active" },
|
|
189
|
+
});
|
|
190
|
+
record.values.name; // string
|
|
191
|
+
record.values.status; // "active" | "inactive" | undefined
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Lazy SDK Singleton
|
|
195
|
+
|
|
196
|
+
Avoid boilerplate proxy patterns — use `createLazySDK`:
|
|
197
|
+
|
|
198
|
+
```typescript
|
|
199
|
+
// lib/sdk.ts
|
|
200
|
+
import { createLazySDK } from "@reopt-ai/brandapp-sdk";
|
|
201
|
+
import schema from "./eav.schema";
|
|
202
|
+
|
|
203
|
+
export const sdk = createLazySDK(() => ({
|
|
204
|
+
clientId: process.env.BRANDAPP_CLIENT_ID!,
|
|
205
|
+
clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
|
|
206
|
+
brandappId: process.env.BRANDAPP_ID!,
|
|
207
|
+
schema,
|
|
208
|
+
}));
|
|
209
|
+
|
|
210
|
+
// Use anywhere — initializes on first access
|
|
211
|
+
await sdk.eav.entity("contacts").records.list();
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Or use the explicit init/get pattern:
|
|
215
|
+
|
|
216
|
+
```typescript
|
|
217
|
+
import { initReoptSDK, getReoptSDK } from "@reopt-ai/brandapp-sdk";
|
|
218
|
+
|
|
219
|
+
// At app startup
|
|
220
|
+
initReoptSDK({ clientId, clientSecret, brandappId, schema });
|
|
221
|
+
|
|
222
|
+
// Anywhere else
|
|
223
|
+
const sdk = getReoptSDK();
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Auto-Pagination
|
|
227
|
+
|
|
228
|
+
```typescript
|
|
229
|
+
// Iterate all records across pages
|
|
230
|
+
for await (const record of sdk.eav.records.listAll("entity-id", {
|
|
231
|
+
limit: 100,
|
|
232
|
+
})) {
|
|
233
|
+
console.log(record.values);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
// Or with typed entity client
|
|
237
|
+
for await (const record of sdk.eav.entity("contacts").records.listAll()) {
|
|
238
|
+
console.log(record.values.name); // typed!
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
// Collect to array
|
|
242
|
+
import { collectAll } from "@reopt-ai/brandapp-sdk/eav";
|
|
243
|
+
const all = await collectAll(sdk.eav.entity("contacts").records.listAll());
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### Schema Sync
|
|
247
|
+
|
|
248
|
+
Sync your schema definition to the server programmatically:
|
|
249
|
+
|
|
250
|
+
```typescript
|
|
251
|
+
import { syncSchema } from "@reopt-ai/brandapp-sdk/eav/schema";
|
|
252
|
+
|
|
253
|
+
const result = await syncSchema(sdk.eav, schema, {
|
|
254
|
+
deleteOrphans: false,
|
|
255
|
+
onProgress: (event) => console.log(event.detail),
|
|
256
|
+
});
|
|
257
|
+
// result.entities: [{ key, entityId, attributes }]
|
|
258
|
+
// result.errors: [{ key, message }]
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Type Coercion Utilities
|
|
262
|
+
|
|
263
|
+
For untyped records, use the coercion helpers:
|
|
264
|
+
|
|
265
|
+
```typescript
|
|
266
|
+
import {
|
|
267
|
+
asString,
|
|
268
|
+
asNumber,
|
|
269
|
+
asBoolean,
|
|
270
|
+
asDate,
|
|
271
|
+
asJson,
|
|
272
|
+
} from "@reopt-ai/brandapp-sdk/eav/coerce";
|
|
273
|
+
|
|
274
|
+
const name = asString(record.values.name); // string | undefined
|
|
275
|
+
const count = asNumber(record.values.count); // number | undefined
|
|
276
|
+
const active = asBoolean(record.values.active); // boolean | undefined
|
|
277
|
+
const date = asDate(record.values.date); // Date | undefined
|
|
278
|
+
const meta = asJson<Meta>(record.values.meta); // Meta | undefined
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## Exports
|
|
282
|
+
|
|
283
|
+
| Path | Main Exports | Requires `better-auth` |
|
|
284
|
+
| ------------------------ | --------------------------------------------------------------------------------- | ---------------------- |
|
|
285
|
+
| `"."` | `createReoptSDK`, `createLazySDK`, `initReoptSDK`, `getReoptSDK`, errors | No |
|
|
286
|
+
| `"./better-auth"` | `createReoptBetterAuth`, `createReoptAdapter`, `createReoptOAuth` | Yes |
|
|
287
|
+
| `"./better-auth/client"` | `createReoptOAuthClient`, `REOPT_PROVIDER_ID` | Yes |
|
|
288
|
+
| `"./eav"` | `createReoptEavClient`, `collectAll`, EAV types, `TypedEavRecord`, `EntityClient` | No |
|
|
289
|
+
| `"./eav/schema"` | `defineEntity`, `defineSchema`, `syncSchema`, `computeDiff`, schema/sync types | No |
|
|
290
|
+
| `"./eav/coerce"` | `asString`, `asNumber`, `asBoolean`, `asDate`, `asJson`, `asStringArray` | No |
|
|
291
|
+
|
|
292
|
+
> **Bundle tip.** `createReoptSDK()` eagerly wires every client (ai, auth, cms,
|
|
293
|
+
> eav, files, terms), so importing it pulls all of them into your bundle. If you
|
|
294
|
+
> only use one domain, import its factory or sub-path directly so tree-shaking
|
|
295
|
+
> drops the rest — e.g. `import { createReoptEavClient } from "@reopt-ai/brandapp-sdk/eav"`
|
|
296
|
+
> instead of the unified `createReoptSDK`. The core is edge-safe (no Node
|
|
297
|
+
> built-ins) and `sideEffects: false`, so unused sub-paths cost nothing.
|
|
298
|
+
|
|
299
|
+
## Configuration
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
{
|
|
303
|
+
clientId: string; // OAuth Client ID (required)
|
|
304
|
+
clientSecret: string; // OAuth Client Secret (required)
|
|
305
|
+
brandappId: string; // Brandapp ID (required)
|
|
306
|
+
token?: string; // Short-lived Bearer token (Phase D-2b) —
|
|
307
|
+
// overrides Basic Auth when set
|
|
308
|
+
isProduction?: boolean; // true → brandapp.reopt.ai, false → brand.reopt.de:3443
|
|
309
|
+
// default: auto-detect from NODE_ENV
|
|
310
|
+
baseUrl?: string; // Main API host override (REOPT_BASE_URL env equivalent)
|
|
311
|
+
idBaseUrl?: string; // Auth host override (REOPT_ID_BASE_URL env equivalent)
|
|
312
|
+
// auto-derived from baseUrl when omitted
|
|
313
|
+
timeout?: number; // Request timeout in ms (default: 15000;
|
|
314
|
+
// AI/Files clients default to 30000. For streaming
|
|
315
|
+
// this is an *idle* timeout — the max gap between
|
|
316
|
+
// chunks, not a cap on total generation time)
|
|
317
|
+
maxRetries?: number; // Max TOTAL attempts incl. the first (default: 3 →
|
|
318
|
+
// 1 call + up to 2 retries; 1 disables retries).
|
|
319
|
+
// Backoff is exponential with full jitter.
|
|
320
|
+
retryNonIdempotent?: boolean;
|
|
321
|
+
// Retry POST/PATCH on 5xx/network/timeout too
|
|
322
|
+
// (default false — avoids duplicate side effects;
|
|
323
|
+
// 429 is always retried regardless)
|
|
324
|
+
schema?: SchemaDef; // EAV schema for type-safe entity() client
|
|
325
|
+
debug?: boolean | "off" | "info" | "trace";
|
|
326
|
+
// Auto-detected from BRANDAPP_SDK_DEBUG / DEBUG
|
|
327
|
+
}
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
### Built-in URLs
|
|
331
|
+
|
|
332
|
+
| `isProduction` | Main API host | Auth (id) host |
|
|
333
|
+
| --------------------- | ----------------------------- | -------------------------- |
|
|
334
|
+
| `false` | `https://brand.reopt.de:3443` | `https://id.reopt.de:3443` |
|
|
335
|
+
| `true` | `https://brandapp.reopt.ai` | `https://id.reopt.ai` |
|
|
336
|
+
| `undefined` (default) | auto from `NODE_ENV` | auto from `NODE_ENV` |
|
|
337
|
+
|
|
338
|
+
## Environment Variables
|
|
339
|
+
|
|
340
|
+
SDK는 `process.env`를 자동으로 읽습니다. 필수 변수 3개만 설정하면 나머지는
|
|
341
|
+
`NODE_ENV` 기반으로 알아서 분기합니다.
|
|
342
|
+
|
|
343
|
+
**필수**
|
|
344
|
+
|
|
345
|
+
| 변수 | 용도 |
|
|
346
|
+
| ------------------------ | --------------------------------------------------- |
|
|
347
|
+
| `BRANDAPP_CLIENT_ID` | OAuth Client ID — Studio → BrandApp → 설정에서 발급 |
|
|
348
|
+
| `BRANDAPP_CLIENT_SECRET` | OAuth Client Secret (1회 노출) |
|
|
349
|
+
| `BRANDAPP_ID` | BrandApp 고유 ID |
|
|
350
|
+
|
|
351
|
+
**선택 (없으면 `NODE_ENV`로 자동 분기)**
|
|
352
|
+
|
|
353
|
+
| 변수 | 용도 | 기본값 |
|
|
354
|
+
| ------------------------- | -------------------------------------- | --------------------------------------------------------------------- |
|
|
355
|
+
| `REOPT_BASE_URL` | 메인 API host (reopt 플랫폼) | prod: `https://brandapp.reopt.ai`, dev: `https://brand.reopt.de:3443` |
|
|
356
|
+
| `REOPT_ID_BASE_URL` | 인증 host (reopt id 서버) | `REOPT_BASE_URL`에서 자동 유도 |
|
|
357
|
+
| `BRANDAPP_WEBHOOK_SECRET` | webhook HMAC 검증 | — (consumer가 `createWebhookHandler`에 명시 주입) |
|
|
358
|
+
| `BRANDAPP_SDK_DEBUG` | 디버그 로그 (`trace` \| `info` \| `1`) | off |
|
|
359
|
+
| `BRANDAPP_SDK_LOG_FORMAT` | 로그 포맷 (`json` 시 구조화) | plain |
|
|
360
|
+
|
|
361
|
+
상세 우선순위·시나리오·트러블슈팅·브라우저(`NEXT_PUBLIC_BRANDAPP_*`)·CI/CD
|
|
362
|
+
패턴은 **[docs/environment.md](./docs/environment.md)**.
|
|
363
|
+
|
|
364
|
+
> **네이밍 원칙** — `BRANDAPP_*`는 consumer 자격/식별자, `REOPT_*`는 reopt 플랫폼
|
|
365
|
+
> 호스트 정보, `BRANDAPP_SDK_*`는 SDK 자체 동작 제어.
|
|
366
|
+
|
|
367
|
+
## Error Handling
|
|
368
|
+
|
|
369
|
+
```typescript
|
|
370
|
+
import {
|
|
371
|
+
ReoptSDKError, // Base error — includes method, url, attempt in message
|
|
372
|
+
AuthError, // 401
|
|
373
|
+
BadRequestError, // 400
|
|
374
|
+
ForbiddenError, // 403
|
|
375
|
+
NotFoundError, // 404
|
|
376
|
+
ConflictError, // 409
|
|
377
|
+
ValidationError, // 422 — exposes .fieldErrors / .toFieldMap()
|
|
378
|
+
RateLimitError, // 429 (auto-retried, respects Retry-After header)
|
|
379
|
+
ServerError, // 500 (auto-retried)
|
|
380
|
+
isReoptSDKError, // Bundle-safe type guard (works across package versions)
|
|
381
|
+
} from "@reopt-ai/brandapp-sdk";
|
|
382
|
+
|
|
383
|
+
try {
|
|
384
|
+
await sdk.eav.records.get(entityId, recordId);
|
|
385
|
+
} catch (err) {
|
|
386
|
+
if (err instanceof NotFoundError) {
|
|
387
|
+
// record deleted — refresh UI
|
|
388
|
+
} else if (err instanceof ForbiddenError) {
|
|
389
|
+
// re-check auth / workspace scope
|
|
390
|
+
} else if (err instanceof ValidationError) {
|
|
391
|
+
console.log(err.toFieldMap()); // { email: "Invalid format" }
|
|
392
|
+
} else if (isReoptSDKError(err)) {
|
|
393
|
+
console.log(err.message); // "[GET https://...] Record not found"
|
|
394
|
+
console.log(err.status); // 404
|
|
395
|
+
console.log(err.code); // "NOT_FOUND"
|
|
396
|
+
console.log(err.context); // { method: "GET", url: "...", attempt: 0 }
|
|
397
|
+
}
|
|
398
|
+
throw err;
|
|
399
|
+
}
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
Retryable errors (429, 5xx) are automatically retried with exponential backoff.
|
|
403
|
+
429 responses with a `Retry-After` header use the server-specified delay instead.
|
|
404
|
+
|
|
405
|
+
Per-call cancellation and timeout:
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
// The low-level BaseHttpClient.fetch() now accepts { signal, timeout }
|
|
409
|
+
// per call, merged with any client-level signal.
|
|
410
|
+
const controller = new AbortController();
|
|
411
|
+
setTimeout(() => controller.abort(), 2_000);
|
|
412
|
+
|
|
413
|
+
await sdk.eav.records.list(entityId, query, {
|
|
414
|
+
signal: controller.signal,
|
|
415
|
+
timeout: 5_000,
|
|
416
|
+
});
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
## Webhooks
|
|
420
|
+
|
|
421
|
+
```typescript
|
|
422
|
+
import {
|
|
423
|
+
createWebhookHandler,
|
|
424
|
+
DEFAULT_WEBHOOK_TOLERANCE_MS,
|
|
425
|
+
} from "@reopt-ai/brandapp-sdk/webhooks";
|
|
426
|
+
|
|
427
|
+
// app/api/webhooks/reopt/route.ts (Next.js)
|
|
428
|
+
export const POST = createWebhookHandler({
|
|
429
|
+
secret: process.env.BRANDAPP_WEBHOOK_SECRET!,
|
|
430
|
+
handlers: {
|
|
431
|
+
contactCreated: async (payload) => { ... },
|
|
432
|
+
contactUpdated: async (payload) => { ... },
|
|
433
|
+
workflowRunCompleted: async (payload) => { ... },
|
|
434
|
+
},
|
|
435
|
+
// Default: 5 minutes. Pass 0 to disable (not recommended in production).
|
|
436
|
+
toleranceMs: DEFAULT_WEBHOOK_TOLERANCE_MS,
|
|
437
|
+
});
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Event types: `contactCreated` / `contactUpdated` / `contactDeleted` /
|
|
441
|
+
`workflowRunCompleted` / `workflowRunFailed`. Each `payload` is
|
|
442
|
+
`{ id, type, entityType, entityId, createdAt, data }`.
|
|
443
|
+
|
|
444
|
+
The handler verifies the `x-reopt-signature` header
|
|
445
|
+
(`sha256=HMAC-SHA256(secret, "{timestamp}.{body}")`) in constant time against
|
|
446
|
+
the `x-reopt-timestamp` header, rejects a missing/invalid signature or timestamp
|
|
447
|
+
(401), rejects an out-of-window timestamp (410), and awaits an optional
|
|
448
|
+
`onError(error, payload, { attempt })` callback before responding. For manual
|
|
449
|
+
verification use `verifySignature(timestamp, body, signature, secret)`.
|
|
450
|
+
|
|
451
|
+
## Runtime Compatibility
|
|
452
|
+
|
|
453
|
+
| Runtime | Supported |
|
|
454
|
+
| --------------------- | --------- |
|
|
455
|
+
| Node.js >= 18 | Yes |
|
|
456
|
+
| Vercel Edge Functions | Yes |
|
|
457
|
+
| Cloudflare Workers | Yes |
|
|
458
|
+
| Browsers (ESM) | Yes |
|
|
459
|
+
|
|
460
|
+
The SDK uses `TextEncoder` + `btoa()` for base64 encoding and `globalThis.fetch` — no Node.js-specific APIs.
|
|
461
|
+
|
|
462
|
+
## Requirements
|
|
463
|
+
|
|
464
|
+
- `better-auth` >= 1.4.0 (optional — only needed for `./better-auth` imports)
|
|
465
|
+
|
|
466
|
+
## License
|
|
467
|
+
|
|
468
|
+
MIT
|