@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.
Files changed (76) hide show
  1. package/CHANGELOG.md +574 -0
  2. package/LICENSE +21 -0
  3. package/README.md +468 -0
  4. package/dist/ai/index.d.ts +314 -0
  5. package/dist/ai/index.js +7 -0
  6. package/dist/ai-provider/index.d.ts +196 -0
  7. package/dist/ai-provider/index.js +703 -0
  8. package/dist/auth/index.d.ts +76 -0
  9. package/dist/auth/index.js +40 -0
  10. package/dist/better-auth/client.d.ts +29 -0
  11. package/dist/better-auth/client.js +10 -0
  12. package/dist/better-auth/index.d.ts +82 -0
  13. package/dist/better-auth/index.js +145 -0
  14. package/dist/chunk-6FLYVNZI.js +32 -0
  15. package/dist/chunk-6KPKZ7ZB.js +49 -0
  16. package/dist/chunk-DI6QJPTQ.js +449 -0
  17. package/dist/chunk-E457LO5A.js +599 -0
  18. package/dist/chunk-F7BXBTZI.js +54 -0
  19. package/dist/chunk-J5Y2GSJF.js +443 -0
  20. package/dist/chunk-K3YVJE6E.js +96 -0
  21. package/dist/chunk-KU2LN5SE.js +350 -0
  22. package/dist/chunk-L4DHB36G.js +75 -0
  23. package/dist/chunk-PJZB4VP7.js +63 -0
  24. package/dist/chunk-REIKXSMY.js +7 -0
  25. package/dist/chunk-T2WXHAAC.js +54 -0
  26. package/dist/chunk-TUKIYH4Q.js +112 -0
  27. package/dist/chunk-WSEROZVO.js +81 -0
  28. package/dist/chunk-YRGLBM6V.js +157 -0
  29. package/dist/client-BkcO-0C2.d.ts +216 -0
  30. package/dist/client-CN5_tNOC.d.ts +147 -0
  31. package/dist/client-DttyeM_h.d.ts +102 -0
  32. package/dist/cms/index.d.ts +137 -0
  33. package/dist/cms/index.js +101 -0
  34. package/dist/config-CtxyJsDR.d.ts +397 -0
  35. package/dist/dev/index.d.ts +509 -0
  36. package/dist/dev/index.js +3071 -0
  37. package/dist/eav/coerce.d.ts +42 -0
  38. package/dist/eav/coerce.js +65 -0
  39. package/dist/eav/index.d.ts +214 -0
  40. package/dist/eav/index.js +147 -0
  41. package/dist/eav/migrate.d.ts +236 -0
  42. package/dist/eav/migrate.js +219 -0
  43. package/dist/eav/schema.d.ts +260 -0
  44. package/dist/eav/schema.js +656 -0
  45. package/dist/errors-5hd5ZR-M.d.ts +158 -0
  46. package/dist/feedback/index.d.ts +132 -0
  47. package/dist/feedback/index.js +5 -0
  48. package/dist/files/index.d.ts +54 -0
  49. package/dist/files/index.js +31 -0
  50. package/dist/index.d.ts +221 -0
  51. package/dist/index.js +84 -0
  52. package/dist/plans/index.d.ts +140 -0
  53. package/dist/plans/index.js +5 -0
  54. package/dist/push/index.d.ts +79 -0
  55. package/dist/push/index.js +5 -0
  56. package/dist/react/hooks.d.ts +376 -0
  57. package/dist/react/hooks.js +421 -0
  58. package/dist/terms/index.d.ts +79 -0
  59. package/dist/terms/index.js +5 -0
  60. package/dist/testing/index.d.ts +154 -0
  61. package/dist/testing/index.js +81 -0
  62. package/dist/typed-client-BxOVIiMU.d.ts +40 -0
  63. package/dist/types-6E3ZLL9X.d.ts +24 -0
  64. package/dist/types-DskYLVb8.d.ts +104 -0
  65. package/dist/types-ckmDDW3N.d.ts +129 -0
  66. package/dist/webhooks/index.d.ts +140 -0
  67. package/dist/webhooks/index.js +142 -0
  68. package/docs/api-reference.md +557 -0
  69. package/docs/cms.md +318 -0
  70. package/docs/dev-server.md +164 -0
  71. package/docs/environment.md +211 -0
  72. package/docs/errors.md +290 -0
  73. package/docs/files.md +272 -0
  74. package/docs/migration.md +315 -0
  75. package/docs/testing.md +163 -0
  76. package/package.json +173 -0
package/docs/cms.md ADDED
@@ -0,0 +1,318 @@
1
+ # CMS Client + Helpers
2
+
3
+ `@reopt-ai/brandapp-sdk/cms` — 외부 사이트가 reopt 자체 컨텐츠(블로그 포스트·
4
+ 태그·그룹)를 읽고, Next.js Metadata · sitemap · RSS · opt-editor 본문 렌더까지
5
+ 한 번에 채우는 read-only 표면.
6
+
7
+ > 1.8부터 cms 클라이언트는 read-only다. 컨텐츠 작성은 [Reopt Studio](https://studio.reopt.ai)가
8
+ > 담당한다. 1.7.x → 1.8 마이그레이션은 [`migration.md`](./migration.md)의 "1.7.x → 1.8.0".
9
+
10
+ ## 클라이언트
11
+
12
+ ```typescript
13
+ import { createReoptSDK } from "@reopt-ai/brandapp-sdk";
14
+
15
+ const sdk = createReoptSDK({
16
+ clientId: process.env.BRANDAPP_CLIENT_ID!,
17
+ clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
18
+ brandappId: process.env.BRANDAPP_ID!,
19
+ });
20
+
21
+ // 포스트 목록 (필터 / 검색 / 정렬 / 페이지네이션)
22
+ const { records, page, total, totalPages } = await sdk.cms.posts.list({
23
+ status: "published",
24
+ groupId: blogGroupId,
25
+ // 또는 (2.1+, env-free): groupSlug: "blog",
26
+ search: "launch", // title/content 부분 검색 (대소문자 무관)
27
+ tags: ["product", "engineering"], // OR — 하나라도 매칭
28
+ page: 1,
29
+ limit: 20,
30
+ sortBy: "publishedAt",
31
+ sortOrder: "desc",
32
+ });
33
+
34
+ // id 단건 — PostDetail (document.contentRich 포함)
35
+ const post = await sdk.cms.posts.get(postId);
36
+
37
+ // slug 단건 — `/blog/[slug]` 같은 라우트에서 id 매핑 없이 (1.8+)
38
+ const post = await sdk.cms.posts.getBySlug("hello-world");
39
+ // const post = await sdk.cms.posts.getBySlug(slug, { groupId: blogId });
40
+ // const post = await sdk.cms.posts.getBySlug(slug, { groupSlug: "blog" }); // 2.1+
41
+
42
+ // 그룹 목록/단건 — id 또는 slug
43
+ const { records: groups } = await sdk.cms.postGroups.list();
44
+ const group = await sdk.cms.postGroups.get(groupId);
45
+ const blogGroup = await sdk.cms.postGroups.getBySlug("blog"); // 2.1+
46
+
47
+ // Brand 범위에서 사용된 태그 + 사용 건수 (1.8+)
48
+ const tags = await sdk.cms.tags.list();
49
+ // const blogTags = await sdk.cms.tags.list({ groupId: blogId });
50
+ // const blogTags = await sdk.cms.tags.list({ groupSlug: "blog" }); // 2.1+
51
+ ```
52
+
53
+ ## 본문 렌더 — `EditorSpec` + opt-editor
54
+
55
+ `PostDetail.document.contentRich`의 타입은 `EditorSpec`이며 `@reopt-ai/opt-editor`의
56
+ `EditorSpec`과 구조적으로 호환된다. SDK는 opt-editor를 직접 의존하지 않으므로,
57
+ 외부 앱이 자기 프로젝트에 별도 install해 사용한다.
58
+
59
+ ```bash
60
+ npm install @reopt-ai/opt-editor
61
+ ```
62
+
63
+ ```tsx
64
+ // app/blog/[slug]/post-body.tsx
65
+ "use client";
66
+
67
+ import {
68
+ StaticRenderer,
69
+ type EditorSpec as OptSpec,
70
+ } from "@reopt-ai/opt-editor";
71
+ import type { EditorSpec } from "@reopt-ai/brandapp-sdk/cms";
72
+
73
+ // SDK와 opt-editor의 EditorSpec은 nominal하게 분리돼있어 boundary에서
74
+ // cast 한 번. 둘 다 같은 shape이라 안전하다.
75
+ export function PostBody({ contentRich }: { contentRich: EditorSpec }) {
76
+ return <StaticRenderer spec={contentRich as unknown as OptSpec} />;
77
+ }
78
+ ```
79
+
80
+ ```tsx
81
+ // app/blog/[slug]/page.tsx — server component
82
+ import { notFound } from "next/navigation";
83
+ import { PostBody } from "./post-body";
84
+
85
+ export default async function PostPage({
86
+ params,
87
+ }: {
88
+ params: Promise<{ slug: string }>;
89
+ }) {
90
+ const { slug } = await params;
91
+ const post = await sdk.cms.posts.getBySlug(slug).catch(() => null);
92
+ if (!post) notFound();
93
+ return (
94
+ <article>
95
+ <h1>{post.title}</h1>
96
+ <PostBody contentRich={post.document.contentRich} />
97
+ </article>
98
+ );
99
+ }
100
+ ```
101
+
102
+ styles는 root layout에서 한 번만 import:
103
+
104
+ ```tsx
105
+ // app/layout.tsx
106
+ import "@reopt-ai/opt-editor/styles.css";
107
+ ```
108
+
109
+ > opt-editor는 public npm(`https://registry.npmjs.org`)에 publish돼있어 별도
110
+ > registry 인증 없이 `npm install @reopt-ai/opt-editor`로 설치된다.
111
+
112
+ ## SEO 메타데이터 — `toMetadata`
113
+
114
+ `Post.seo` 필드(`metaTitle / metaDescription / metaKeywords`)가 우선이고, 없으면
115
+ `Post.title`과 `document.content`로 fallback. Next.js `Metadata`로 cast 가능하다.
116
+
117
+ ```typescript
118
+ // app/blog/[slug]/page.tsx
119
+ import type { Metadata } from "next";
120
+ import { toMetadata } from "@reopt-ai/brandapp-sdk/cms";
121
+
122
+ export async function generateMetadata({
123
+ params,
124
+ }: {
125
+ params: Promise<{ slug: string }>;
126
+ }): Promise<Metadata> {
127
+ const { slug } = await params;
128
+ const post = await sdk.cms.posts.getBySlug(slug);
129
+ return toMetadata(post, {
130
+ siteUrl: "https://www.example.com",
131
+ basePath: "/blog", // optional, default "/blog"
132
+ });
133
+ }
134
+ ```
135
+
136
+ 자동 채워지는 필드:
137
+
138
+ - `title`, `description`, `keywords`(있을 때만)
139
+ - `alternates.canonical`
140
+ - `openGraph` — `type: "article"`, `title`, `description`, `url`, `images` (coverImage),
141
+ `publishedTime`, `modifiedTime`, `authors[author.name]`
142
+ - `twitter` — `card: summary_large_image | summary` (coverImage 유무에 따라)
143
+
144
+ ## Sitemap — `toSitemapItems`
145
+
146
+ ```typescript
147
+ // app/sitemap.ts — Next.js native
148
+ import type { MetadataRoute } from "next";
149
+ import { toSitemapItems } from "@reopt-ai/brandapp-sdk/cms";
150
+
151
+ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
152
+ const { records } = await sdk.cms.posts.list({
153
+ status: "published",
154
+ limit: 200,
155
+ sortBy: "publishedAt",
156
+ sortOrder: "desc",
157
+ });
158
+ return toSitemapItems(records, {
159
+ siteUrl: "https://www.example.com",
160
+ basePath: "/blog", // default "/blog"
161
+ changeFrequency: "weekly", // default "weekly"
162
+ priority: 0.7, // default 0.7
163
+ });
164
+ }
165
+ ```
166
+
167
+ ## RSS — `toRssFeed`
168
+
169
+ RSS 2.0 XML 문자열을 반환. XML-unsafe 문자(`& < > " '`)는 자동 escape.
170
+
171
+ ```typescript
172
+ // app/rss.xml/route.ts
173
+ import { toRssFeed } from "@reopt-ai/brandapp-sdk/cms";
174
+
175
+ export const revalidate = 600;
176
+
177
+ export async function GET() {
178
+ const { records } = await sdk.cms.posts.list({
179
+ status: "published",
180
+ limit: 50,
181
+ sortBy: "publishedAt",
182
+ sortOrder: "desc",
183
+ });
184
+ const xml = toRssFeed(records, {
185
+ siteUrl: "https://www.example.com",
186
+ title: "Example Blog",
187
+ description: "Recent posts.",
188
+ basePath: "/blog", // default "/blog"
189
+ language: "ko", // default "ko"
190
+ });
191
+ return new Response(xml, {
192
+ headers: { "Content-Type": "application/rss+xml; charset=utf-8" },
193
+ });
194
+ }
195
+ ```
196
+
197
+ 각 item에 포함되는 필드: `title`, `link`, `guid` (permalink), `pubDate`
198
+ (`publishedAt` → `createdAt` fallback), `description` (`metaDescription` →
199
+ `document.content` 첫 280자 fallback), `author`, `category` (tags).
200
+
201
+ ## React 훅 (1.8+)
202
+
203
+ ```tsx
204
+ import {
205
+ usePostList,
206
+ usePost,
207
+ usePostBySlug,
208
+ useCmsTags,
209
+ usePostGroupList,
210
+ usePostGroup,
211
+ } from "@reopt-ai/brandapp-sdk/react/hooks";
212
+
213
+ const { data: posts } = usePostList(sdk, { status: "published" });
214
+ const { data: post } = usePostBySlug(sdk, slug, { groupId? });
215
+ const { data: tags } = useCmsTags(sdk, { groupId? });
216
+ ```
217
+
218
+ > 서버 컴포넌트에서 `getBySlug`를 직접 호출하는 편이 추가 hop을 피할 수 있다.
219
+ > 클라이언트에서 동적으로 detail이 필요할 때만 `usePostBySlug` 사용.
220
+
221
+ ## Slug 기반 식별 (2.1+)
222
+
223
+ `PostGroup`은 이제 brand 범위 안에서 안정적인 `slug` 식별자를 가진다. 신규 코드는
224
+ `groupId`(UUID) 대신 `groupSlug`(`"blog"`, `"changelog"` 등) 사용을 권장한다.
225
+
226
+ ```typescript
227
+ // 기존 (env-based)
228
+ const groupId = process.env.REOPT_BLOG_GROUP_ID!;
229
+ const posts = await sdk.cms.posts.list({ groupId, status: "published" });
230
+
231
+ // 신규 (env-free, group 추가 시 env 추가 불필요)
232
+ const CONTENT_GROUPS = {
233
+ blog: { slug: "blog", route: "/blog" },
234
+ changelog: { slug: "changelog", route: "/changelog" },
235
+ } as const;
236
+
237
+ const posts = await sdk.cms.posts.list({
238
+ groupSlug: CONTENT_GROUPS.blog.slug,
239
+ status: "published",
240
+ });
241
+ ```
242
+
243
+ `PostGroup.slug`는 nullable이다 — legacy row(2.1 이전에 만들어진 그룹)는
244
+ backfill 전까지 `null`일 수 있다. SDK consumer가 알고 있는 slug만 쿼리하면 안전.
245
+
246
+ ## Dev Server에서 MDX → EditorSpec 시드 (2.1+)
247
+
248
+ reopt-www 같은 마케팅 사이트가 `.mdx` 파일을 git에 owning하고 로컬에서 미리보고
249
+ 싶을 때, `@reopt-ai/brandapp-sdk/dev`의 새 seeder를 사용한다.
250
+
251
+ ```typescript
252
+ import {
253
+ createDevServer,
254
+ markdownToEditorSpec,
255
+ } from "@reopt-ai/brandapp-sdk/dev";
256
+ import { readFile } from "node:fs/promises";
257
+
258
+ const dev = await createDevServer({ port: 4300, brandappId: "reopt-www" });
259
+
260
+ // 1. PostGroup을 slug로 정의
261
+ await dev.seedPostGroups([
262
+ { slug: "blog", name: "Blog" },
263
+ { slug: "changelog", name: "Changelog" },
264
+ ]);
265
+
266
+ // 2. MDX 파일을 EditorSpec으로 변환해 시드
267
+ const md = await readFile("content/blog/hello.mdx", "utf-8");
268
+ await dev.seedPosts([
269
+ {
270
+ groupSlug: "blog",
271
+ slug: "hello-world",
272
+ title: "Hello, world",
273
+ content: md, // plain-text 검색용
274
+ contentRich: await markdownToEditorSpec(md), // production과 동일 포맷
275
+ status: "published",
276
+ publishedAt: "2026-05-19",
277
+ },
278
+ ]);
279
+
280
+ // 3. SDK는 production과 동일한 응답 반환
281
+ const post = await sdk.cms.posts.getBySlug("hello-world", {
282
+ groupSlug: "blog",
283
+ });
284
+ // post.document.contentRich는 EditorSpec — opt-editor StaticRenderer가 그대로 렌더링
285
+ ```
286
+
287
+ `markdownToEditorSpec`은 `@reopt-ai/opt-editor`의 `markdownToSpec`을 dynamic import로 호출한다. opt-editor는 SDK의 **optional peer dependency**이므로
288
+ dev/test 환경에만 설치하면 된다:
289
+
290
+ ```bash
291
+ pnpm add -D @reopt-ai/opt-editor
292
+ ```
293
+
294
+ Production 빌드에는 포함되지 않는다.
295
+
296
+ > Phase 1 범위는 순수 markdown(headings/lists/code/image/link)만 지원한다.
297
+ > MDX의 JSX 인라인 컴포넌트(`<Hero />` 등)는 Phase 2에서 opt-editor 커스텀
298
+ > element schema 등록 후 지원 예정.
299
+
300
+ `seedAll`로 한 번에:
301
+
302
+ ```typescript
303
+ await dev.seedAll({
304
+ postGroups: [{ slug: "blog", name: "Blog" }],
305
+ posts: [
306
+ /* ... */
307
+ ],
308
+ terms: [
309
+ /* ... */
310
+ ],
311
+ });
312
+ ```
313
+
314
+ ## 다음 단계
315
+
316
+ - 외부 마케팅 사이트 전체 데모: `apps/brandapp-playground/app/cms/posts/[slug]`
317
+ - 1.7 → 1.8 변경: [`migration.md`](./migration.md)
318
+ - 이미지 결합 패턴: [`files.md`](./files.md)
@@ -0,0 +1,164 @@
1
+ # Dev Server Guide
2
+
3
+ BrandApp SDK의 로컬 개발 서버를 사용하면 원격 Reopt 서버 없이 오프라인으로 개발할 수 있습니다.
4
+
5
+ ## 빠른 시작
6
+
7
+ ### 1. CLI로 프로젝트 초기화
8
+
9
+ ```bash
10
+ npx reopt brandapp init
11
+ ```
12
+
13
+ 생성되는 파일:
14
+
15
+ - `.env.development` — dev mode 환경변수
16
+ - `reopt.seed.ts` — 시드 데이터 템플릿
17
+ - `lib/dev-server.ts` — 서버 부트스트랩
18
+ - `instrumentation.ts` — Next.js 시작 훅
19
+
20
+ ### 2. 로컬 실행
21
+
22
+ ```bash
23
+ pnpm dev:local
24
+ ```
25
+
26
+ ### 3. 완료
27
+
28
+ 앱이 `http://localhost:4200`에서 시작되고, 인메모리 API 서버가 `http://localhost:4300`에서 자동 실행됩니다.
29
+
30
+ ---
31
+
32
+ ## API
33
+
34
+ ### `createDevServer(options)`
35
+
36
+ ```typescript
37
+ import { createDevServer } from "@reopt-ai/brandapp-sdk/dev";
38
+
39
+ const dev = await createDevServer({
40
+ port: 4300, // 서버 포트 (0 = 자동)
41
+ brandappId: "my-app", // BrandApp ID (default: "dev-brandapp")
42
+ dataPath: ".reopt/dev-data.json", // 데이터 영속화 경로
43
+ schema: devSchema, // EAV 스키마 (자동 시딩)
44
+ verbose: true, // 상세 로그
45
+ proxy: {
46
+ // 선택적 원격 프록시
47
+ remoteUrl: "https://brand.reopt.de:3443",
48
+ remoteCredentials: { clientId, clientSecret, brandappId },
49
+ routes: { ai: "passthrough" }, // AI만 원격, 나머지 로컬
50
+ },
51
+ });
52
+ ```
53
+
54
+ ### 반환 객체
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()` | 서버 종료 |
66
+
67
+ ### `seed(data)`
68
+
69
+ ```typescript
70
+ await dev.seed({
71
+ contacts: [
72
+ { values: { name: "Alice", email: "alice@test.com", status: "active" } },
73
+ { values: { name: "Bob", email: "bob@test.com", status: "inactive" } },
74
+ ],
75
+ orders: [{ values: { product: "Widget", amount: 100 } }],
76
+ });
77
+ ```
78
+
79
+ 엔티티 이름은 스키마에 정의된 이름과 일치해야 합니다.
80
+
81
+ ---
82
+
83
+ ## 지원하는 API
84
+
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 토큰 발급 |
93
+
94
+ ---
95
+
96
+ ## Proxy Mode
97
+
98
+ AI 호출만 실제 서버로 보내고 나머지는 로컬에서 처리:
99
+
100
+ ```typescript
101
+ const dev = await createDevServer({
102
+ schema,
103
+ proxy: {
104
+ remoteUrl: "https://brand.reopt.de:3443",
105
+ remoteCredentials: {
106
+ clientId: process.env.BRANDAPP_CLIENT_ID!,
107
+ clientSecret: process.env.BRANDAPP_CLIENT_SECRET!,
108
+ brandappId: process.env.BRANDAPP_ID!,
109
+ },
110
+ routes: {
111
+ eav: "local", // 로컬 인메모리
112
+ auth: "local", // 로컬 인메모리
113
+ ai: "passthrough", // 원격 서버로 프록시
114
+ files: "local", // 로컬 인메모리
115
+ cms: "local", // 로컬 인메모리
116
+ },
117
+ },
118
+ });
119
+ ```
120
+
121
+ CLI에서:
122
+
123
+ ```bash
124
+ reopt brandapp dev --proxy-ai
125
+ ```
126
+
127
+ ---
128
+
129
+ ## CLI 명령어
130
+
131
+ ```bash
132
+ # 프로젝트 초기화
133
+ reopt brandapp init
134
+
135
+ # 로컬 서버 시작
136
+ reopt brandapp dev --port 4300 --persist --watch
137
+
138
+ # AI 프록시 모드
139
+ reopt brandapp dev --proxy-ai
140
+
141
+ # 시드 데이터 적용
142
+ reopt brandapp seed --file ./reopt.seed.ts
143
+
144
+ # 시드 + 초기화
145
+ reopt brandapp seed --reset
146
+ ```
147
+
148
+ ---
149
+
150
+ ## Next.js 통합
151
+
152
+ `instrumentation.ts`를 사용하면 `next dev` 시작 시 dev server가 자동으로 시작됩니다:
153
+
154
+ ```typescript
155
+ // instrumentation.ts
156
+ export async function register() {
157
+ if (process.env.REOPT_DEV_MODE === "true") {
158
+ const { startDevServer } = await import("./lib/dev-server");
159
+ await startDevServer();
160
+ }
161
+ }
162
+ ```
163
+
164
+ `lib/dev-server.ts`에서 `process.env.REOPT_BASE_URL`을 자동 설정하므로, 기존 SDK 초기화 코드를 수정할 필요가 없습니다.
@@ -0,0 +1,211 @@
1
+ # Environment Variables
2
+
3
+ SDK는 `process.env`를 자동으로 읽습니다. 필수 변수 3개만 설정하면 나머지는
4
+ `NODE_ENV` 기반으로 알아서 분기합니다 — `baseUrl`, `idBaseUrl`을 매번 인자로
5
+ 넘길 필요 없습니다.
6
+
7
+ ## 네이밍 원칙 — 의미 기반 3-tier
8
+
9
+ | 접두사 | 의미 | 누가 관리 |
10
+ | ---------------- | ----------------------------------- | ------------------------------------ |
11
+ | `BRANDAPP_*` | BrandApp consumer 자격증명 / 식별자 | consumer 본인 (Studio에서 발급) |
12
+ | `REOPT_*` | Reopt 플랫폼 호스트 정보 | reopt 플랫폼 (consumer는 override만) |
13
+ | `BRANDAPP_SDK_*` | SDK 자체 동작 제어 | consumer (debug / log 토글) |
14
+
15
+ 브라우저 노출용은 `NEXT_PUBLIC_` 접두사 추가 — `NEXT_PUBLIC_BRANDAPP_*`.
16
+
17
+ ## 필수 환경변수
18
+
19
+ 3개 모두 없으면 `getReoptSDK()` 자동 초기화가 throw합니다. `createReoptSDK({ ... })`
20
+ 인자로 직접 전달하면 env 없이도 동작 가능 (인자가 env보다 우선).
21
+
22
+ | 변수 | 용도 | 발급 위치 | 없을 때 |
23
+ | ------------------------ | ------------------------------ | ------------------------------------------- | --------------------------------------------------------------------------- |
24
+ | `BRANDAPP_CLIENT_ID` | OAuth Client ID | Studio → BrandApp → 설정 → OAuth 클라이언트 | `ConfigError` throw (메시지: "Set BRANDAPP_CLIENT_ID environment variable") |
25
+ | `BRANDAPP_CLIENT_SECRET` | OAuth Client Secret (1회 노출) | 위와 동일 | 위와 동일 |
26
+ | `BRANDAPP_ID` | BrandApp 고유 ID | Studio BrandApp 상세 URL 또는 설정 화면 | 위와 동일 |
27
+
28
+ ```bash
29
+ # .env
30
+ BRANDAPP_CLIENT_ID=bac_a1b2c3d4...
31
+ BRANDAPP_CLIENT_SECRET=bas_x9y8z7w6...
32
+ BRANDAPP_ID=01HQ8K...
33
+ ```
34
+
35
+ ## 선택 환경변수 — 안 줘도 동작
36
+
37
+ 모두 합리적인 기본값으로 자동 분기됩니다. 특수한 환경(on-prem, 비표준 host,
38
+ 디버그)에서만 명시.
39
+
40
+ | 변수 | Tier | 용도 | 안 주면 |
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` 자동) |
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
+ | `BRANDAPP_WEBHOOK_SECRET` | consumer | webhook HMAC 검증 | SDK 내부에서 자동 read 안 함 — `createWebhookHandler({ secret })`에 명시 주입 |
45
+ | `BRANDAPP_SDK_DEBUG` | SDK | 디버그 로그 레벨 (`trace` \| `info` \| `1`) | off (`DEBUG=*brandapp*`도 fallback으로 인식) |
46
+ | `BRANDAPP_SDK_LOG_FORMAT` | SDK | `json` 설정 시 구조화 로그 (AI agent 친화적) | plain text |
47
+ | `NODE_ENV` | 표준 | production 여부 자동 감지 | `development` 취급 (dev URLs) |
48
+
49
+ ## 우선순위와 시나리오
50
+
51
+ ### 우선순위 (높은 순)
52
+
53
+ ```
54
+ 1. config.baseUrl / config.idBaseUrl (createReoptSDK 인자 — 최우선)
55
+ 2. REOPT_BASE_URL / REOPT_ID_BASE_URL (환경변수 명시)
56
+ 3. config.baseUrl → id 자동 유도 (`brandapp.reopt.ai → id.reopt.ai` 등; id 결정에만 적용)
57
+ 4. REOPT_BASE_URL → id 자동 유도 (위와 동일)
58
+ 5. config.isProduction (boolean override)
59
+ 6. NODE_ENV === "production" (자동 감지 — 최종 fallback)
60
+ ```
61
+
62
+ ### 시나리오별 실제 결과
63
+
64
+ | 상황 | 메인 API host (`resolveBaseUrl`) | 인증 host (`resolveIdBaseUrl`) |
65
+ | -------------------------------------------- | -------------------------------- | ------------------------------------- |
66
+ | env 없음 + `NODE_ENV=development` | `https://brand.reopt.de:3443` | `https://id.reopt.de:3443` |
67
+ | env 없음 + `NODE_ENV=production` | `https://brandapp.reopt.ai` | `https://id.reopt.ai` |
68
+ | `REOPT_BASE_URL=https://my.host:3000`만 설정 | `https://my.host:3000` | `https://id.my.host:3000` (자동 유도) |
69
+ | `config.baseUrl: "https://x"` 인자 | `https://x` (env 무시) | `https://id.x` (자동 유도) |
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` |
72
+
73
+ > on-prem 단일 호스트 (web + auth가 같은 도메인): `config.idBaseUrl: baseUrl` 한 줄로 해결.
74
+
75
+ 소스: `packages/brandapp-sdk/src/core/config.ts` — `resolveBaseUrl`,
76
+ `resolveIdBaseUrl`, `deriveIdFromBaseUrl`.
77
+
78
+ ## Webhook 변수
79
+
80
+ `BRANDAPP_WEBHOOK_SECRET`은 **SDK 내부에서 자동 read 하지 않습니다.**
81
+ `createWebhookHandler({ secret })` 인자로 consumer가 명시 주입.
82
+
83
+ ```typescript
84
+ // app/api/webhooks/reopt/route.ts
85
+ import { createWebhookHandler } from "@reopt-ai/brandapp-sdk/webhooks";
86
+
87
+ export const POST = createWebhookHandler({
88
+ secret: process.env.BRANDAPP_WEBHOOK_SECRET!,
89
+ handlers: {
90
+ contactCreated: async (payload) => {
91
+ /* ... */
92
+ },
93
+ workflowRunCompleted: async (payload) => {
94
+ /* ... */
95
+ },
96
+ },
97
+ // 기본 5분 timestamp 검증 (replay 방지). 0으로 disable 가능 (prod 권장 X).
98
+ // toleranceMs: 5 * 60 * 1000,
99
+ });
100
+ ```
101
+
102
+ > `toleranceMs` 기본 5분 — 플랫폼이 보내는 `x-reopt-timestamp` header(서명 preimage
103
+ > `"{timestamp}.{body}"`에 포함되어 위조 불가)를 검증해 replay attack 방지. 서명은
104
+ > `x-reopt-signature: sha256=…` 헤더. 자세히는 [README의 Webhooks 섹션](../README.md#webhooks).
105
+
106
+ ## 브라우저 / Next.js 변수
107
+
108
+ ### 안전 (브라우저 노출 OK)
109
+
110
+ | 변수 | 용도 |
111
+ | -------------------------------- | ---------------------------------------------------------------------------------------- |
112
+ | `NEXT_PUBLIC_BRANDAPP_CLIENT_ID` | client에서 OAuth flow 시작용. `clientSecret` 없이는 OAuth 완료 불가 (서버 callback 필수) |
113
+ | `NEXT_PUBLIC_BRANDAPP_ID` | client에서 사용자가 어느 BrandApp인지 알리는 식별자 |
114
+ | `NEXT_PUBLIC_BRANDAPP_EAV_HASH` | 빌드 시 만들어 client bundle에 inline, 런타임 schema drift 검증 (`verifyEavSchema`) |
115
+
116
+ ### ⚠️ 금지 (절대 브라우저 노출 금지)
117
+
118
+ ```
119
+ NEXT_PUBLIC_BRANDAPP_CLIENT_SECRET ❌ NEVER
120
+ NEXT_PUBLIC_BRANDAPP_WEBHOOK_SECRET ❌ NEVER
121
+ ```
122
+
123
+ `clientSecret`은 **반드시 서버에서만** 사용. Next.js에서는 다음 중 하나로 라우팅:
124
+
125
+ - **Server Components** — `app/`의 default 컴포넌트 (`"use client"` 없음)에서 SDK 호출
126
+ - **Route Handlers** — `app/api/.../route.ts`
127
+ - **Server Actions** — `"use server"` 함수
128
+
129
+ 브라우저에서 SDK가 필요한 경우 (예: 실시간 fetch), **서버 endpoint를 만들어
130
+ client는 fetch만** — `clientSecret`은 서버에만 존재.
131
+
132
+ ```typescript
133
+ // ✅ 안전한 패턴 — Server Component
134
+ import { createReoptSDK } from "@reopt-ai/brandapp-sdk";
135
+
136
+ const sdk = createReoptSDK({
137
+ clientId: process.env.BRANDAPP_CLIENT_ID!,
138
+ clientSecret: process.env.BRANDAPP_CLIENT_SECRET!, // 서버 only
139
+ brandappId: process.env.BRANDAPP_ID!,
140
+ });
141
+
142
+ export default async function Page() {
143
+ const { records } = await sdk.cms.posts.list({ status: "published" });
144
+ return <PostList posts={records} />;
145
+ }
146
+ ```
147
+
148
+ ## 트러블슈팅
149
+
150
+ ### "ReoptSDK: clientId is required" throw
151
+
152
+ → `BRANDAPP_CLIENT_ID`가 `process.env`에 없음. `.env` 파일 위치(Next.js는 프로젝트
153
+ 루트의 `.env.local`), dev 서버 재시작, `process.env` 접근 가능한 런타임
154
+ (Edge runtime에서는 `process.env` 일부 제약) 확인.
155
+
156
+ ### dev 환경에서 production URL을 호출함
157
+
158
+ → `NODE_ENV=production`이 설정되어 있을 수 있음. Next.js는 `next dev`에서
159
+ 자동으로 `development`이지만, CI / 컨테이너에서는 override될 수 있음. 명시적으로
160
+ `config.isProduction: false` 또는 `REOPT_BASE_URL=https://brand.reopt.de:3443` 설정.
161
+
162
+ ### `REOPT_BASE_URL`은 줬는데 OAuth/auth가 안 됨
163
+
164
+ → 인증은 `id.*` 호스트에서 처리. `brandapp.reopt.ai → id.reopt.ai` 같은 표준 변형은
165
+ 자동 유도되지만, 커스텀 host는 명시 필요. `REOPT_ID_BASE_URL=https://id.your.host`
166
+ 추가하거나 `config.idBaseUrl` 사용.
167
+
168
+ ### `BRANDAPP_SDK_DEBUG=1`을 줬는데 로그가 안 보임
169
+
170
+ → SDK는 `console.debug`를 사용. 브라우저는 기본 표시되지만 Node.js 일부 환경 (PM2,
171
+ 일부 logger)에서 `debug` 레벨이 필터링될 수 있음. `console.debug = console.log` 패치
172
+ 또는 `BRANDAPP_SDK_LOG_FORMAT=json`으로 JSON 출력 후 stdout 캡처.
173
+
174
+ ### Edge Runtime / Cloudflare Workers에서 env 일부 누락
175
+
176
+ → `process.env`가 부분 polyfill됨. `REOPT_BASE_URL` 등 `readEnvUrl` 호출은
177
+ `typeof process === "undefined"` 가드로 안전하게 빠짐 (기본값 사용). 필수 3개는
178
+ **플랫폼별 secret binding**으로 주입 (Workers의 `env`, Vercel Edge Config 등).
179
+
180
+ ## CI/CD 예시 — GitHub Actions
181
+
182
+ ```yaml
183
+ # .github/workflows/deploy.yml
184
+ jobs:
185
+ deploy:
186
+ runs-on: ubuntu-latest
187
+ env:
188
+ BRANDAPP_CLIENT_ID: ${{ secrets.BRANDAPP_CLIENT_ID }}
189
+ BRANDAPP_CLIENT_SECRET: ${{ secrets.BRANDAPP_CLIENT_SECRET }}
190
+ BRANDAPP_ID: ${{ secrets.BRANDAPP_ID }}
191
+ BRANDAPP_WEBHOOK_SECRET: ${{ secrets.BRANDAPP_WEBHOOK_SECRET }}
192
+ # staging 검증용 — production은 기본값으로 충분
193
+ REOPT_BASE_URL: ${{ github.ref == 'refs/heads/staging' && 'https://brand.reopt.io' || '' }}
194
+ steps:
195
+ - uses: actions/checkout@v4
196
+ - run: pnpm install
197
+ - run: pnpm build
198
+ - run: pnpm test:integration
199
+ ```
200
+
201
+ GitHub Actions secret 명명도 동일 컨벤션 권장 (`BRANDAPP_CLIENT_ID` 등) — secret →
202
+ env mapping을 1:1로 유지하면 운영 mistake 감소.
203
+
204
+ ## CLI 환경별 다중 자격증명
205
+
206
+ `@reopt-ai/cli`는 환경별 접미사 (`BRANDAPP_CLIENT_ID_PREVIEW`,
207
+ `BRANDAPP_CLIENT_ID_STAGING`, `BRANDAPP_CLIENT_ID_PROD`)와 `BRANDAPP_ENV`로
208
+ 한 프로세스에서 여러 환경의 자격을 다룹니다 — `packages/cli/README.md` 참조.
209
+
210
+ SDK 자체는 단일 자격만 인식. 여러 환경이 필요하면 SDK 인스턴스를 환경별로
211
+ 만들거나, `.env.staging` / `.env.production` 파일을 빌드 단계에서 선택.