@reopt-ai/brandapp-sdk 4.6.0 → 4.7.0-rc.10

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 (101) hide show
  1. package/CHANGELOG.md +275 -1
  2. package/README.md +194 -72
  3. package/dist/ai/index.d.ts +52 -2
  4. package/dist/ai/index.js +32 -2
  5. package/dist/ai-provider/index.d.ts +58 -6
  6. package/dist/ai-provider/index.js +456 -119
  7. package/dist/analytics/index.d.ts +1 -1
  8. package/dist/analytics/index.js +1 -1
  9. package/dist/auth/index.d.ts +1 -1
  10. package/dist/auth/index.js +1 -1
  11. package/dist/better-auth/client.d.ts +7 -2
  12. package/dist/better-auth/client.js +5 -4
  13. package/dist/better-auth/index.d.ts +39 -7
  14. package/dist/better-auth/index.js +47 -12
  15. package/dist/{client-DCqp0Bis.js → client-B281w6RL.js} +2 -2
  16. package/dist/{client-Bfutv3LK.d.ts → client-BL-Ljwki.d.ts} +2 -2
  17. package/dist/client-BPcoDnOd.js +194 -0
  18. package/dist/{client-BSW0Ncjj.d.ts → client-BbmslwWV.d.ts} +2 -2
  19. package/dist/{client-Ce0gs5Ma.js → client-Brv0KsDM.js} +2 -2
  20. package/dist/{client-eDd4aWDs.js → client-BxrWT0mi.js} +2 -2
  21. package/dist/client-C7z5-izC.js +745 -0
  22. package/dist/{client-IUSZDJio.d.ts → client-CD6uK0dA.d.ts} +87 -6
  23. package/dist/client-CGy4Z0JO.js +146 -0
  24. package/dist/{client-7I-mz3Dw.d.ts → client-CJFsLk3_.d.ts} +2 -2
  25. package/dist/{client-C6OXGMMV.d.ts → client-CJRjPSf7.d.ts} +2 -2
  26. package/dist/{client-D1AFtJRw.d.ts → client-CP1Jgq4R.d.ts} +139 -13
  27. package/dist/{client-FM6_YJbr.js → client-CmV48bW0.js} +3 -3
  28. package/dist/{client-tJq0U_jn.js → client-D8d3xsYm.js} +51 -12
  29. package/dist/{client-C2xE9HGZ.js → client-D97Ylva1.js} +40 -6
  30. package/dist/{client-COKDtHO9.d.ts → client-DF-tOyrY.d.ts} +2 -2
  31. package/dist/client-DlgVNj3w.d.ts +72 -0
  32. package/dist/{client-BzAgabAs.js → client-Dv7WwJr-.js} +2 -2
  33. package/dist/{client-yKeRJnIB.d.ts → client-Dwf6UuGH.d.ts} +2 -2
  34. package/dist/{client-Dmvtr1nS.d.ts → client-NUhpPkl2.d.ts} +2 -2
  35. package/dist/{client-DjLhTNsZ.js → client-ey80gKM_.js} +11 -5
  36. package/dist/{client-DeC127BD.js → client-m4e-HwMX.js} +2 -2
  37. package/dist/client-seu-0lbh.d.ts +654 -0
  38. package/dist/{client-CniCGdmi.d.ts → client-wNzcgEJu.d.ts} +2 -2
  39. package/dist/cms/index.d.ts +1 -1
  40. package/dist/cms/index.js +1 -1
  41. package/dist/{config-D3SblxWt.d.ts → config-BGT9h1OW.d.ts} +27 -10
  42. package/dist/{config-BeOelISH.js → config-DaSeKofC.js} +70 -16
  43. package/dist/dev/index.d.ts +1 -1
  44. package/dist/dev/index.js +71 -3
  45. package/dist/eav/index.d.ts +3 -3
  46. package/dist/eav/index.js +2 -2
  47. package/dist/eav/migrate.d.ts +2 -2
  48. package/dist/eav/schema.d.ts +2 -2
  49. package/dist/{errors-U3TsyWVq.d.ts → errors-D-Va8oeC.d.ts} +5 -2
  50. package/dist/feedback/index.d.ts +1 -1
  51. package/dist/feedback/index.js +1 -1
  52. package/dist/files/index.d.ts +1 -1
  53. package/dist/files/index.js +1 -1
  54. package/dist/{http-client-Bl8u1vHN.js → http-client-BCZhLtY5.js} +33 -4
  55. package/dist/{index-BnAYxnwq.d.ts → index-CaXrNTtU.d.ts} +44 -15
  56. package/dist/{index-C6fyJTud.d.ts → index-Dh8XMVFF.d.ts} +2 -2
  57. package/dist/index.d.ts +6 -6
  58. package/dist/index.js +12 -12
  59. package/dist/installation/index.d.ts +415 -0
  60. package/dist/installation/index.js +841 -0
  61. package/dist/keys-B2pA8EkU.d.ts +44 -0
  62. package/dist/keys-B_R_lsyF.js +102 -0
  63. package/dist/logout/index.d.ts +1 -1
  64. package/dist/logout/index.js +1 -1
  65. package/dist/machine/index.d.ts +3 -0
  66. package/dist/machine/index.js +4 -0
  67. package/dist/machine/keygen-cli.d.ts +7 -0
  68. package/dist/machine/keygen-cli.js +57 -0
  69. package/dist/plans/index.d.ts +2 -2
  70. package/dist/plans/index.js +1 -1
  71. package/dist/push/index.d.ts +1 -1
  72. package/dist/push/index.js +1 -1
  73. package/dist/{query-JPVK_8N5.js → query-B8Hg9bub.js} +2 -2
  74. package/dist/react/hooks.d.ts +5 -5
  75. package/dist/resource/index.d.ts +176 -0
  76. package/dist/resource/index.js +345 -0
  77. package/dist/social/index.d.ts +284 -0
  78. package/dist/social/index.js +306 -0
  79. package/dist/{sse-parser-FMjxM7sY.js → sse-parser-D65dmL4A.js} +15 -18
  80. package/dist/superadmin/index.d.ts +80 -0
  81. package/dist/superadmin/index.js +148 -0
  82. package/dist/terms/index.d.ts +1 -1
  83. package/dist/terms/index.js +1 -1
  84. package/dist/testing/index.d.ts +2 -2
  85. package/dist/types-DGAVaUCc.js +17 -0
  86. package/dist/{types-MXLudLBP.d.ts → types-FazBnzhg.d.ts} +8 -2
  87. package/dist/workspace/index.d.ts +2 -624
  88. package/dist/workspace/index.js +2 -693
  89. package/docs/api-reference.md +233 -35
  90. package/docs/dev-server.md +2 -2
  91. package/docs/environment.md +34 -19
  92. package/docs/errors.md +54 -0
  93. package/docs/installation.md +128 -0
  94. package/docs/machine.md +109 -0
  95. package/docs/resource.md +75 -0
  96. package/docs/social.md +92 -0
  97. package/docs/superadmin.md +55 -0
  98. package/docs/workspace.md +12 -0
  99. package/package.json +36 -6
  100. package/dist/client-CI2Y00Qx.js +0 -81
  101. package/dist/types-DjDRszNj.js +0 -11
package/CHANGELOG.md CHANGED
@@ -7,6 +7,280 @@ This project adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [4.7.0-rc.10] — 2026-11-02
11
+
12
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — 스트리밍 줄바꿈 결함 수정. rc.9에서 `sdk.ai.stream`으로 받은
13
+ YAML·Markdown 펜스가 한 줄로 붙었다면 이 버전으로 올린다.
14
+
15
+ ### Fixed
16
+
17
+ - SSE 파서가 줄바꿈만 있는 `text-delta`를 버리고, 줄바꿈으로 시작하는 델타의 앞머리 줄바꿈을 잃던 것.
18
+ 서버는 규격대로 `"\n"`을 `data: \ndata: \n\n`으로 보내는데 파서가 빈 `data:` 값을 "데이터 없음"으로
19
+ 읽었다 — 줄바꿈이 문법인 YAML·Markdown 펜스가 한 줄로 붙었다(`sdk.ai.stream`·`streamWithMetadata`·
20
+ `/ai-provider` 공통). `data:` 줄을 봤는지를 값과 따로 기억한다.
21
+ - dev 서버 `/ai/evaluations`의 choice 답이 고른 선택지 하나만 담은 분포(`{ [choice]: 1 }`)를 내 AI SDK
22
+ `experimental_decide`가 "complete distribution"으로 거절하던 것 — 이제 선택지 전부를 덮는다(고른 것 1, 나머지 0).
23
+ `sdk.ai.evaluate`·json-render 평가자는 영향이 없었다.
24
+
25
+ ### Docs
26
+
27
+ - AI SDK 결정 함수 이름을 `experimental_decide`로 고쳤다 — `experimental_evaluate`는 AI SDK가 deprecated로 남긴
28
+ 옛 이름인데 주석이 거꾸로 적고 있었다. 과금 호출이라 `maxRetries: 0`을 권한다.
29
+
30
+ ## [4.7.0-rc.9] — 2026-10-30
31
+
32
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — 평가(Jev)·json-render 조립(RFC-0041). 서버 평가 중계는
33
+ 플랫폼이 열기 전까지 503 `EVALUATIONS_UNAVAILABLE`이다 — 그동안은 dev 서버로 개발한다.
34
+
35
+ ### Added
36
+
37
+ - `sdk.ai.evaluate()` — 평가 모델(Jev)에 상태와 질문(choice·score·boolean, 최대 128개)을 보내 답과 확률을 받는다
38
+ (`POST /ai/evaluations`, RFC-0041). 브랜드앱 AI 설정 "평가 허용"이 켜져 있어야 하고, 답을 못 준 호출은
39
+ 과금되지 않으며, 과금 호출이라 재시도하지 않는다.
40
+ - `createBrandappEvaluator(sdk)` — json-render `experimental_composeSpec`의 `evaluate`에 그대로 꽂는 평가자.
41
+ json-render를 의존성으로 들이지 않는다(구조 호환, 테스트가 실제 `composeSpec`으로 확인).
42
+ `onEvaluation` 콜백으로 평가마다의 실제 크레딧(`creditCostMilli`)을 받는다.
43
+ - `brandapp.decisionModel()`(`/ai-provider`) — AI SDK `experimental_evaluate`용 결정 모델(`Experimental_DecisionModelV4`).
44
+ `evaluationModel()`은 옛 이름. 크레딧은 `providerMetadata.brandapp`. 중계하지 않는 모델 id는 `NoSuchModelError`.
45
+ - dev 서버 `/ai/evaluations` — 결정적인 흉내(실서버와 같은 상한)로 json-render 조립이 오프라인에서 끝까지 돈다.
46
+ - 평가 오류 코드 7종의 `diagnostic`(원인·해결·과금 여부)과 `docs/errors.md` 표. 평가 타입을 루트에서도 export한다.
47
+
48
+ ### Fixed
49
+
50
+ - AI provider가 503 `EVALUATIONS_UNAVAILABLE`을 재시도 가능으로 표시하던 것 — 다시 보내도 같은 답이라 AI SDK의 자동
51
+ 재시도가 헛돈다.
52
+
53
+ ### Docs
54
+
55
+ - `/ai-provider` 진입점 주석이 도구 호출·구조화 출력을 "미지원"으로 적고 있었다(실제로는 4.7부터 지원) —
56
+ 지원 범위를 구현과 맞추고, 예시를 기계 자격(`authorization: machine.headers`) 기준으로 바꿨다.
57
+ - `docs/api-reference.md`에 json-render(Standalone·Inline) 연결 예시를 더했다.
58
+
59
+ ## [4.7.0-rc.8] — 2026-10-29
60
+
61
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — 도구 루프 정산·경고·끊김 처리.
62
+
63
+ ### Added
64
+
65
+ - `usage.creditCostMilli`·`providerMetadata.brandapp.creditCostMilli` — 실제 사용량(1/1000 크레딧).
66
+ `creditCost`는 올림한 정수 표시값이라 1크레딧 미만 단계도 1로 보인다. 도구 루프처럼 한 턴에 여러 단계를
67
+ 부르는 앱은 milli를 더한 뒤 한 번만 올림한다. 옛 서버 응답에는 없으므로 선택 필드다.
68
+ - 서버·모델 경고가 AI SDK의 `warnings`로 온다 — 모델이 무시한 설정, 도구 강제로 꺼진 thinking 등. 비스트리밍은
69
+ 응답 `warnings`, 스트리밍은 첫 `warnings` SSE 이벤트(SDK가 `stream-start`에 합친다). `sdk.ai` 타입에
70
+ `CompletionWarning`을 더했다.
71
+ - 403 `CLIENT_TOOLS_DISABLED`·`CLIENT_TOOLS_PLAN_REQUIRED`의 `diagnostic`이 고칠 자리(AI 설정의 도구 호출
72
+ 허용 · Business 플랜)를 가리킨다.
73
+
74
+ ### Changed
75
+
76
+ - 비스트리밍(`generateText`)의 기본 한도를 응답 전체 300초로 늘렸다 — 예전에는 스트리밍 유휴 한도와 같은
77
+ 60초가 응답 본문까지 덮어 추론·긴 JSON 응답이 끊겼다. 스트리밍은 그대로 청크 사이 60초다. `timeout`을
78
+ 지정하면 둘 다 그 값이다.
79
+ - 서버: 호출 앱이 연결을 끊으면(`abortSignal`, 탭 닫기) 모델 호출도 멈춘다 — 예전에는 끝까지 생성하고 전액
80
+ 과금했다. 끊긴 단계는 읽은 입력 + 이미 보낸 출력으로 과금한다.
81
+ - 서버: `maxTokens`(AI SDK `maxOutputTokens`)를 주지 않으면 4096이 아니라 앱 AI 설정의 최대 출력 토큰
82
+ (기본 8192)까지 쓴다 — 추론 모델과 큰 JSON 응답이 잘렸다.
83
+ - 서버: `-thinking` Anthropic 모델에 사고 요약(`display: "summarized"`)을 요청한다 — Claude 5 계열 기본값
84
+ (`omitted`)에서는 추론 파트가 텍스트 없이 서명만 왔다.
85
+
86
+ ## [4.7.0-rc.7] — 2026-10-28
87
+
88
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — AI SDK provider의 도구 호출·구조화 출력·추론 파트 왕복.
89
+
90
+ ### Added
91
+
92
+ - `createBrandappProvider` — **도구 호출·구조화 출력·추론 파트 왕복**. `tools`·`toolChoice`(auto·none·required·
93
+ 특정 도구), `responseFormat: json`을 더 이상 `UnsupportedFunctionalityError`로 거절하지 않는다. 도구는 앱이
94
+ 실행하고 서버는 호출만 돌려준다 — `ToolLoopAgent`·`streamText` + `stopWhen` 루프가 그대로 동작하고, 단계마다
95
+ `providerMetadata.brandapp.creditCost`가 실린다. 스트림은 `reasoning-start/delta/end`·`tool-input-start/delta/end`·
96
+ `tool-call`(한 단계에 여럿 가능) 파트를 내고, 추론 파트의 `providerMetadata`(Anthropic 서명 등)를 다음 요청으로
97
+ 되돌린다. 도구 결과는 `execution-denied`·`content`(텍스트)까지 손실 없이 옮긴다(예전에는 텍스트로 뭉갰다).
98
+ `usage`에 캐시 읽기·쓰기·추론 토큰이 채워진다. 추론 강도는 `providerOptions.brandapp.reasoningEffort`
99
+ (또는 `anthropic.effort`·`openai.reasoningEffort`). 그 밖의 요청 단위 `providerOptions`는 무시한다.
100
+ **서버 쪽 전제**: 브랜드앱 AI 설정의 "도구 호출·구조화 출력 허용" + Business 플랜 — 아니면
101
+ `403 CLIENT_TOOLS_DISABLED` / `CLIENT_TOOLS_PLAN_REQUIRED`.
102
+ - `/ai` 타입 — `CompletionResult.content`(응답 파트), `CompletionUsage`(캐시·추론 토큰), `CompletionContentPart`,
103
+ `PartProviderMetadata`.
104
+
105
+ ### Changed
106
+
107
+ - provider 실행 도구(`type: "provider"`)는 요청 전에 `UnsupportedFunctionalityError`로 거절한다. 비전·파일 입력은
108
+ 여전히 거절한다.
109
+
110
+ - `@reopt-ai/brandapp-sdk/social` — 소셜 운영 플랫폼 API(RFC-0037 §7) 클라이언트 `createSocialClient`(scope
111
+ `social:read`·`social:write`): `accounts.list`, `contents.list/convert`, `posts.list/get/transition/propose`,
112
+ `reviews.run`. 모든 채널은 직접 게시라 플랫폼에 올리는 호출은 없고, 승인·게시 기록·취소는 승인함 **제안**이다.
113
+ - `/social` 계정 `profile.reviewChecklist`(RFC-0038) — 계정별 검수 기준 항목 `{text, severity}`. 응답·저장 스키마 둘 다 선택 칸.
114
+ `/workspace`와 요청기를 공유한다(`createPlatformRequester`). 문서 `docs/social.md`.
115
+ - `/social` — 글(`SocialPost`)에 `links`(변환이 본문 URL을 바꿔 넣은 추적 링크: `originalUrl`·`shortUrl`·`clicks`).
116
+ `clicks`는 리옵트 링크 원장의 누적 클릭이지 플랫폼 반응이 아니다.
117
+
118
+ ### Fixed
119
+
120
+ - 기계 자격(`authorization: machine.headers`, RFC-0034)이 **손으로 짠 요청 경로**에도 실린다 —
121
+ `ai.stream()`·`ai.streamWithMetadata()`(SSE), `files.upload()`, `files.readContent()`,
122
+ `createBrandappProvider`(언어·이미지 모델). 지금까지 이 경로들은 정적 `Basic base64("<clientId>:")`를
123
+ 보내 `401 Missing clientId or clientSecret`로 실패했다(`http.fetch`를 타는 `models`·`complete` 등은 정상).
124
+ DPoP 증명은 요청마다, 스트림 연결 재시도마다 새로 받는다. `createBrandappProvider`가 `authorization`을 받는다.
125
+ 손으로 요청을 짜는 코드는 `http.authorizationHeader` 대신 `http.requestAuthHeaders({ method, url })`를 쓴다.
126
+
127
+ - 서버 — `changePlan`으로 바꾼 플랜의 `paymentEnvironment`가 `null`로 오던 것. 바뀐 플랜에는 자기 체크아웃이 없어
128
+ "모름"이 됐고, 그 값으로 실 결제·테스트 결제만 인정하는 앱은 올린 고객의 이용권을 거뒀다. 이제 그 구독을 시작한
129
+ 체크아웃의 환경을 말한다(SDK 코드 변경 없음, 문서만).
130
+
131
+ ## [4.7.0-rc.6] — 2026-10-15
132
+
133
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — 해지 예약 구독 재개(`plans.resume`)와 해지 기간 중 새 결제 차단.
134
+
135
+ ### Added
136
+
137
+ - `plans.resume(accessToken)` — 결제한 기간이 남은 해지 예약 구독을 되살린다(`POST /me/subscription/resume`, Lemon
138
+ Squeezy). 같은 구독이 갱신일 그대로 이어지고 바뀐 플랜(`getMyPlan`과 같은 모양)을 돌려준다. 거절은
139
+ `NO_RESUMABLE_SUBSCRIPTION`(409), 결제사 실패는 `PROVIDER_ERROR`(502, 재시도).
140
+
141
+ ### Changed
142
+
143
+ - `plans.createCheckout` — 해지 예약 구독이 결제한 기간을 남기고 있으면 `SUBSCRIPTION_CANCEL_PENDING`(409)으로
144
+ 거절한다. 새 구독을 열면 옛 구독과 겹친 기간을 두 번 내기 때문이다 — `resume` 뒤 다른 플랜이면 `changePlan`.
145
+
146
+ ## [4.7.0-rc.5] — 2026-10-14
147
+
148
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — 구독 중 플랜 변경(`plans.changePlan`)과 Lemon Squeezy 해지 계약, 5xx 오류 코드 보존.
149
+
150
+ ### Added
151
+
152
+ - `plans.changePlan(planId, accessToken)` — 구독 중인 플랜을 바꾼다(`POST /me/subscription/change`).
153
+ 새 체크아웃 없이 결제사 구독의 가격을 그 자리에서 바꾸므로 구독은 하나이고 갱신일이 이어진다.
154
+ 즉시 적용되고 바뀐 플랜(`getMyPlan`과 같은 모양)을 돌려준다. 올리면 차액을 지금 청구하고 내리면
155
+ 다음 청구서에서 차감한다. Lemon Squeezy 구독만 지원한다.
156
+
157
+ ### Changed
158
+
159
+ - 5xx 오류가 서버가 준 코드와 실제 상태를 담는다 — 상류(결제사) 실패는 `ServerError`이면서 `code`가
160
+ `PROVIDER_ERROR`·`PROVIDER_CANCEL_FAILED`, `status`가 502다. 코드 없는 5xx는 예전처럼 `SERVER_ERROR`이고
161
+ `status`는 실제 응답 상태다(전에는 항상 500).
162
+ - `plans.cancel` — Lemon Squeezy 구독은 결제사 해지가 먼저다. 결제사 해지가 실패하면 아무것도 바뀌지
163
+ 않고 `PROVIDER_CANCEL_FAILED`(HTTP 502)로 실패한다 — 다시 시도하면 된다. 성공하면 `accessUntil`이
164
+ 결제사의 결제 기간 끝이다.
165
+
166
+ ## [4.7.0-rc.4] — 2026-10-14
167
+
168
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — EAV `listAll()` 커서 훑기와 설치 back-channel 재생 거절 보강.
169
+
170
+ ### Changed
171
+
172
+ - **`eav.records.listAll()`이 커서로 훑는다.** 번호 페이지로 훑으면 필터가 있을 때 서버가 페이지마다 조건에 맞는 행
173
+ 전체를 다시 읽어 그 페이지만 잘랐다 — 훑는 비용이 행 수의 제곱이었다. 이제 `GET …/records?cursor=`로 앞 페이지의
174
+ 마지막 자리 다음부터 그 페이지 분량만 읽는다. 호출부는 바꿀 것이 없다(`backfill()`·typed `entity().listAll()` 포함).
175
+ - 정렬이 `createdAt`(기본)·`updatedAt`일 때만 커서를 쓴다. 커스텀 속성 정렬은 종전대로 번호 페이지다.
176
+ - 커서를 모르는 서버(이전 버전의 reopt, 로컬 dev 서버)는 `cursor`를 무시하고 1페이지를 주므로, 그때는 2페이지부터
177
+ 번호로 이어 간다 — 결과는 같다.
178
+ - 같은 정렬 키를 가진 행들의 순서는 커서 방식에서 id가 정한다(번호 페이지는 createdAt → id). `updatedAt` 정렬로
179
+ 훑는 도중 갱신된 행은 자리를 옮기므로, 전 행을 정확히 한 번씩 읽어야 하면 기본값인 `createdAt`을 쓴다.
180
+ - SQL로 좁혀지지 않는 필터(`neq`·`not_in`·`after`·`before`)로 큰 엔티티를 훑어도 `QUERY_TOO_BROAD`(422)가 나지
181
+ 않는다 — 서버가 요청 한 건이 읽는 행 수를 묶고 커서로 이어 준다.
182
+ - 새 에러 코드 `CURSOR_SCAN_INTERRUPTED`(훑는 도중 커서를 모르는 인스턴스가 응답 — 처음부터 다시),
183
+ `CURSOR_SCAN_STALLED`(서버가 커서를 전진시키지 않음).
184
+
185
+ ### Fixed
186
+
187
+ - **`createInstallationBackchannelHandler`의 재생 거절에 빈틈이 있었다.** 통지의 jti를 `exp`까지만 기억했는데 검증은
188
+ `clockToleranceSeconds`(기본 60초)만큼 더 받아 주므로, `exp` 직후 그 시간 동안은 같은 통지가 다시 통과했다. 이제
189
+ 받아 줄 수 있는 마지막 순간(`exp + clockTolerance`)까지 기억한다.
190
+ - `createMemoryBackchannelReplayStore(now?)` — 시계를 받는다. 핸들러의 `now` 옵션이 기본 메모리 저장소에도 적용돼
191
+ 만료 판정과 기억을 지우는 시점이 같은 시계를 본다(예전에는 저장소만 실제 시계를 봤다).
192
+
193
+ ## [4.7.0-rc.3] — 2026-10-11
194
+
195
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — RFC-0034 2·3단계: 리소스 서버 검증기와 운영자 가드.
196
+
197
+ ### Added
198
+
199
+ - **`@reopt-ai/brandapp-sdk/resource`** (RFC-0034 §4.3) — 서브 제품 API가 리옵트 id의 기계 토큰(`at+jwt` + DPoP)을 받는
200
+ 검증기 **한 벌**. `createResourceVerifier({ issuer, audience, jwks?, dpop: { required, replayStore }, allowUserTokens?, publicUrl? })`
201
+ → `verify(request, { scope })`는 `MachinePrincipal`을 주거나 `ResourceAuthError`(`code` 12종, `status` 401|403,
202
+ `wwwAuthenticate()`)를 던진다. `verify.safe()`·`verify.looksLikeAccessToken()`. 저수준 `verifyMachineToken(input)`(결과 유니언),
203
+ `createRedisDpopReplayStore(redis, { keyPrefix, onFallback })`(`SET NX PX`, fail-closed)·`createMemoryDpopReplayStore()`,
204
+ `resolvePublicRequestUrl()`(proxy 뒤 `x-forwarded-*` → DPoP `htu`). 리옵트 본체의 플랫폼·브랜드앱 미들웨어도 같은 구현을 쓴다.
205
+ - **`@reopt-ai/brandapp-sdk/superadmin`** (RFC-0034 §5.2) — 운영자 가드. 리옵트가 id token·userinfo·access token에
206
+ `reopt_operator`·`reopt_mfa`·`auth_time`을 싣고, `evaluateOperator(claims, { maxAuthAgeSeconds })`/`requireOperator()`가
207
+ ① claim ② 운영자 ③ 2단계 인증 **수행** ④ 로그인 나이 순으로 판정한다(`OperatorAccessError`: `no_claims`·`not_operator`·
208
+ `mfa_not_performed`·`reauth_required`, 403). `decodeIdTokenClaims()`(백채널 id token 전용, 서명 미검증), `latestReoptAccount()`,
209
+ `stepUpAuthorizationParams()`, `OPERATOR_ACCESS_MESSAGES`. 서브 제품은 자기 allowlist를 지운다.
210
+ - **`@reopt-ai/brandapp-sdk/installation`** (RFC-0034 §6–§8) — 설치(리옵트 연결). `installationManifestSchema`·`manifestHash`·
211
+ `signManifest`/`verifyManifestJws`(본문의 `jwksUri`에서 키를 받아 검증, `ManifestVerifyError`), `deriveInstallationManifest`
212
+ (RFC-0030 선언 파일 → 매니페스트, 웹훅 `secret` 필수), `signInstallationAssertion`(`reopt-installation-assertion+jwt`),
213
+ `createInstallationClient`(`request`·`get`·`reinstall`·`revoke`·`refreshJwks`·`health` — 승인 전엔 단언, 활성 뒤엔 설치의
214
+ machine 토큰), `createInstallationBackchannelHandler`(`reopt-installation-event+jwt`, id JWKS·iss·aud·재생 검사),
215
+ `createReoptConnection`(§7.6 headless 상태 `unconnected|pending|connected|suspended|rejected|revoked` + `describe()` 문구),
216
+ `selfCheckJwks`, `planKeyRotation`/`confirmKeyRecognized`(회전 ②, 최대 5분 재시도). 서버 전용, `zod` 필요.
217
+ - `createMachineClient`: `scopes: []`면 토큰 요청에 `scope`를 **보내지 않는다** — id가 클라이언트 행에 등록된 scope 전부를 발급한다
218
+ (설치 클라이언트의 최소 권한). 예전엔 빈 문자열을 보냈다.
219
+ - `createReoptOAuth({ stepUp: true | seconds })` — step-up 재로그인 제공자 `reopt-step-up`(`prompt=login&max_age`)을 함께 등록한다.
220
+ `signInWithReopt(client, { stepUp: true })`가 그 제공자로 authorize를 다시 탄다. `REOPT_PROVIDER_IDS`를
221
+ `account.accountLinking.trustedProviders`에 넣고, 콜백 `/api/auth/callback/reopt-step-up`을 리옵트 클라이언트에 등록한다.
222
+
223
+ ### Changed
224
+
225
+ - 문서·예제를 서버 자격 기준으로 바꿨다 — README Quick Start·`createReoptSDK` JSDoc·`createReoptAdapter` JSDoc·설정 표·env 표가
226
+ `createMachineClient({ keyRing })` + `authorization: machine.headers`를 먼저 보여 주고, `clientSecret`은 로그인 클라이언트의
227
+ code 교환(과도기 Basic)으로만 남긴다. `validateConfig`의 자격 누락 메시지도 `authorization`을 첫 선택지로 안내한다(동작 변화 없음).
228
+
229
+ ## [4.7.0-rc.2] — 2026-10-10
230
+
231
+ ### Changed
232
+
233
+ - peer `better-auth` `^1.7.4` → `^1.7.7`. `/machine`이 쓰는 `@better-auth/core/oauth2`의 DPoP·private_key_jwt 자재는
234
+ 1.7.7부터라, 1.7.4~1.7.6 앱은 core peer가 unmet으로 떴다(핸드북 실측). 두 peer가 같은 버전을 가리킨다.
235
+
236
+ ## [4.7.0-rc.1] — 2026-10-10
237
+
238
+ Pre-release (`npm i @reopt-ai/brandapp-sdk@next`) — RFC-0034 machine credentials. Everything below ships here.
239
+
240
+ ### Added
241
+
242
+ - **`@reopt-ai/brandapp-sdk/machine`** (RFC-0034) — 서버 간 호출용 기계 자격. 공유 시크릿 대신 **`private_key_jwt`**(RFC 7523)
243
+ 단언과 **DPoP**(RFC 9449) 증명으로 id.reopt.ai에서 토큰을 받는다. `generateClientKeyPair()`(EdDSA, `kid`=JWK 지문),
244
+ `readClientKeyRing()`(env `REOPT_CLIENT_PRIVATE_KEY_JWK`, 회전 중 `_NEXT`), `buildClientJwks()`·`CLIENT_JWKS_PATH`
245
+ (`/.well-known/reopt-client-jwks.json`에 공개키 게시), `createMachineClient({ clientId, keyRing|privateKeyJwk, resource, scopes })`
246
+ — `getToken()`·`headers({ method, url })`·`fetch()`(401 시 한 번 재발급)·`invalidateToken()`. 토큰은 resource(audience) 하나에
247
+ 묶이고 만료 60초 전 재발급된다. 실패는 `MachineTokenError`(`code`·`status`). **서버 전용**(브라우저에서 호출하면 throw).
248
+ - bin **`reopt-keygen`** — 개인키 env 한 줄과 JWKS 라우트 안내를 출력한다(키는 그 줄에만 찍힌다).
249
+ - `createReoptSDK({ authorization })` — 요청마다 인증 헤더를 만드는 훅. `authorization: machine.headers`로 어댑터·EAV 호출을
250
+ 기계 토큰(DPoP)으로 보낸다. `clientSecret` 없이 만들 수 있다.
251
+ - `createReoptOAuth({ tokenEndpointAuthMethod: "private_key_jwt", privateKeyJwk? })` — 로그인 클라이언트의 토큰 엔드포인트
252
+ 인증을 비대칭으로. 키는 인자 또는 env 키 링에서 읽고, 없으면 즉시 throw.
253
+ - `createPlatformClient({ privateKeyJwk | keyRing })` — 플랫폼 API 클라이언트도 시크릿 없이 private_key_jwt + DPoP로 간다
254
+ (`clientSecret`은 이제 선택). 요청마다 메서드·URL에 묶인 DPoP 증명이 붙는다.
255
+ - 플랫폼 OAuth 클라이언트 리소스에 **`purpose`**(`web`·`adapter`·`machine`·`connect`, `PLATFORM_OAUTH_CLIENT_PURPOSES`)·
256
+ `jwksUri`·`dpopBoundAccessTokens` 필드와 `tokenEndpointAuthMethod: "private_key_jwt"`가 생겼다. `purpose`를 생략하면
257
+ 그랜트에서 추정한다(`client_credentials`만 → `machine`, 그 밖엔 `web`).
258
+
259
+ - `plans.getCustomerPlan(authUserId)` — 고객의 토큰 없이 **앱 자격 증명으로** 고객 한 명의 현재 플랜을
260
+ 읽는다(`GET /plans/customers/{authUserId}/plan`). 백그라운드 작업, 자체 기기·API 토큰으로 들어온 요청,
261
+ 토큰이 만료된 고객의 엔타이틀먼트 확인용이다. `authUserId`는 Better Auth `session.user.id`,
262
+ 응답은 `getMyPlan`과 같은 모양이다. 서버 전용 — 고객 토큰으로 부르면 403 `APP_CREDENTIAL_REQUIRED`.
263
+
264
+ - `CurrentPlan.paymentEnvironment`(`"live" | "test" | "simulation" | null`) — 지금 플랜을 만든 체크아웃의
265
+ 결제 환경. `paymentProvider`와 달리 해지 뒤 남은 이용 기간에도 유지되므로 "실 결제로 얻은 플랜만 인정"의
266
+ 근거로 쓸 수 있다. `null`은 모름(체크아웃을 거치지 않은 플랜)이다. 타입 `PlanPaymentEnvironment` export.
267
+ - `getCustomerPlan`의 404가 탈퇴를 구분한다 — 연결된 적 없으면 `NOT_FOUND`, 탈퇴했으면 `CUSTOMER_WITHDRAWN`.
268
+
269
+ ### Changed
270
+
271
+ - 파일·폴더 라우트(`sdk.files`·폴더)는 **앱 자격 증명 전용**이다 — 고객 액세스 토큰을 거절한다
272
+ (403 `APP_CREDENTIAL_REQUIRED`). SDK는 이 라우트에 고객 토큰을 보낸 적이 없어 SDK 사용처는 영향이 없다.
273
+ - AI 라우트를 고객 액세스 토큰으로 부르면 사용량과 고객별 호출 제한이 **토큰 주인으로 고정**된다.
274
+ 본문의 `customerId`가 토큰 주인과 다르면 403이다. 앱 자격으로 부르는 호출은 그대로 본문 값을 쓴다.
275
+ - CMS 미발행 글은 앱의 관리 자격에만 보인다 — `brandapp:write`가 실린 고객 토큰에는 발행된 글만 나간다.
276
+ - `PUT /plans/external-subscription`(스토어 구독 미러)은 **앱 자격 증명 전용**이다 — 플랫폼이 고객 액세스
277
+ 토큰을 scope와 무관하게 거절한다(403 `APP_CREDENTIAL_REQUIRED`). Basic 자격이나 서비스 토큰으로
278
+ 부르는 서버 호출은 그대로다.
279
+
280
+ - 개발 기본 호스트에서 포트를 뗐다. `REOPT_BASE_URLS`·`REOPT_ID_BASE_URLS`·`REOPT_PLATFORM_URLS`·
281
+ `REOPT_PLATFORM_ID_URLS`의 `development` 값이 `https://{brand,id,platform}.local.reopt.io`다(이전 `:3443`) —
282
+ dev-proxy가 표준 HTTPS 포트(443)에서 듣는다. `REOPT_BASE_URL`·`config.baseUrl` 등으로 직접 준 값은 그대로 쓴다.
283
+
10
284
  ## [4.6.0] — 2026-09-22
11
285
 
12
286
  ### Added
@@ -724,7 +998,7 @@ reopt 플랫폼의 brandapp API host가 `brand.reopt.ai`로 분리됐다. Better
724
998
  ### Added
725
999
 
726
1000
  - **`ReoptSDKConfig.idBaseUrl`** — id (auth) 서버 URL을 명시 override. 미설정 시 `baseUrl` / `isProduction` / `NODE_ENV`로부터 derive.
727
- - **`REOPT_ID_BASE_URLS`** export — `production: https://id.reopt.ai`, `development: https://id.reopt.de:3443`.
1001
+ - **`REOPT_ID_BASE_URLS`** export — `production: https://id.reopt.ai`, `development: https://id.local.reopt.io:3443`.
728
1002
  - **`resolveIdBaseUrl(config)`** / **`deriveIdFromBaseUrl(baseUrl)`** export — id URL 해석 헬퍼.
729
1003
  - **`BaseHttpClient(config, pathPrefix, { useIdServer: true })`** — 옵션 인자로 id 서버 라우팅 활성화.
730
1004