@agentgo-tw/app-sdk 0.0.0-stage → 1.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/README.md CHANGED
@@ -1,3 +1,262 @@
1
- # Temporary Holding Version
1
+ # @agentgo-tw/app-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ AI 研究所(agentgo.tw)上架 App 的平台 SDK。在 App 裡取得會員身分,使用平台 AI、房市資料、工作憑證和點數查詢;費用從會員的月點數扣,你不必自備 AI 金鑰。
4
+
5
+ - 伺服器端:`@agentgo-tw/app-sdk`(Node ≥ 20;Express、Next.js、任何以 fetch `Request` 為主的框架)
6
+ - 瀏覽器端:`@agentgo-tw/app-sdk/browser`(純前端 App 不必自己寫後端)
7
+ - 沒有執行期依賴;ESM 與 CommonJS 都可以用
8
+
9
+ ```bash
10
+ npm install @agentgo-tw/app-sdk
11
+ ```
12
+
13
+ > 平台規格:AI 研究所 spec 16〈AI 小工具上架與訂閱〉。協定版本 `CONTRACT_VERSION = 1`,SDK 主版號跟著協定走。
14
+
15
+ ---
16
+
17
+ ## 1. 環境變數
18
+
19
+ **平台會自動注入**(教官不用設,也不能自己設任何 `ACADEMY_` 開頭的變數):
20
+
21
+ | 變數 | 內容 |
22
+ |---|---|
23
+ | `ACADEMY_APP_UUID` | 這個 App 的編號 |
24
+ | `ACADEMY_APP_TOKEN` | App 呼叫平台用的金鑰(在上架頁換發後要重啟才生效) |
25
+ | `ACADEMY_BASE_URL` | 平台網址,例如 `https://agentgo.tw` |
26
+ | `ACADEMY_ENV` | `test`(測試環境)或 `production`(正式環境) |
27
+
28
+ **只在你自己的電腦上設**(本機開發模式,見第 8 節):`ACADEMY_DEV_MODE=1`、`ACADEMY_DEV_KEY`(在上架頁產生的個人開發金鑰)、`ACADEMY_DEV_USER`(假身分,可省略)、`ACADEMY_BASE_URL=https://agentgo.tw`。
29
+
30
+ ## 2. 伺服器端:取得會員身分
31
+
32
+ ### Express
33
+
34
+ ```js
35
+ import express from 'express';
36
+ import { createAcademy } from '@agentgo-tw/app-sdk';
37
+
38
+ const academy = createAcademy(); // 讀平台注入的環境變數
39
+ const app = express();
40
+ app.use(express.json());
41
+ app.use(academy.express()); // 驗身分掛到 req.academy;自動回應上架自檢 /__academy/selfcheck
42
+
43
+ app.get('/api/me', (req, res) => {
44
+ if (!req.academy) return res.status(401).json({ message: '請從 AI 研究所開啟' });
45
+ const { user, entitlement, env } = req.academy;
46
+ res.json({ user, entitlement, env }); // user: { uuid, name, email }
47
+ });
48
+ ```
49
+
50
+ `req.academy` 是 `null` 的情況:公開路徑(上架時設定、不經入口關卡的路徑),以及**尚未按「啟用」的正式環境**。
51
+
52
+ ### Next.js(App Router)與其他 fetch 框架
53
+
54
+ ```ts
55
+ // app/api/chat/route.ts
56
+ import { createAcademy } from '@agentgo-tw/app-sdk';
57
+ const academy = createAcademy();
58
+
59
+ export async function POST(request: Request) {
60
+ const ctx = await academy.fromRequest(request); // 沒有身分回 null
61
+ if (!ctx) return Response.json({ message: '請從 AI 研究所開啟' }, { status: 401 });
62
+ const r = await academy.ai(ctx).chat.completions.create({ model: 'smart', messages: await request.json() });
63
+ return Response.json(r);
64
+ }
65
+ ```
66
+
67
+ 上架自檢要放在 `middleware.ts`(`app/` 底下以底線開頭的資料夾不會成為路由,`/__academy/selfcheck` 沒辦法寫成 Route Handler):
68
+
69
+ ```ts
70
+ // middleware.ts
71
+ import { createAcademy } from '@agentgo-tw/app-sdk';
72
+ const academy = createAcademy();
73
+ export async function middleware(request: Request) {
74
+ return (await academy.handleSelfcheck(request)) ?? undefined;
75
+ }
76
+ export const config = { matcher: '/__academy/selfcheck' };
77
+ ```
78
+
79
+ ### 身分 `entitlement.kind`
80
+
81
+ | 值 | 意思 |
82
+ |---|---|
83
+ | `SUBSCRIBED` | 訂閱制工具的有效訂閱者 |
84
+ | `OPEN` | 免費工具的會員 |
85
+ | `OWNER` | 你自己(正式環境) |
86
+ | `OWNER_TEST` | 測試環境(你自己、指定測試帳號、管理員) |
87
+ | `STAFF` | 平台管理員 |
88
+
89
+ 日後可能新增其他值,**不認得的值請當成「可以使用」**。`entitlement.tier`(會員等級)只供顯示,不要用來擋人。
90
+
91
+ ## 3. 平台 AI
92
+
93
+ ```js
94
+ const ai = academy.ai(req); // 綁定這次請求的會員;瀏覽器端用 academyBrowser.ai()
95
+
96
+ const r = await ai.chat.completions.create({ model: 'smart', messages: [{ role: 'user', content: '你好' }], max_tokens: 400 });
97
+ console.log(r.choices[0].message.content);
98
+
99
+ // 串流
100
+ for await (const chunk of await ai.chat.completions.create({ model: 'fast', stream: true, messages })) {
101
+ process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
102
+ }
103
+
104
+ const img = await ai.images.generate({ model: 'image', prompt: '簡約房子圖示', n: 1 }); // data[0].b64_json
105
+ const tts = await ai.audio.speech.create({ model: 'tts', input: '歡迎光臨', voice: 'female-shaonv' }); // audio_url(限時網址,要保存請自行下載)
106
+ ```
107
+
108
+ - **`model` 填平台別名,不是模型名**:`fast`(快速對話)、`smart`(進階對話)、`image`(圖片生成)、`tts`(語音合成)。填錯會收到 `MODEL_NOT_ALLOWED`,`err.details.allowed` 列出可用的別名。別名背後的模型由平台維護、有多段備援,模型退場時你不用改程式。
109
+ - 請求與回應形狀與 OpenAI 相容(對話、圖片);SDK 不改寫內容,只補認證、改打平台、把錯誤轉成 `AcademyError`。
110
+ - `max_tokens` 沒帶時平台以 4,096 計算預佔;**帶上合理的上限可以少佔點數**。單次呼叫上限 200 點。
111
+ - 圖片只提供生成(一次最多 4 張),不提供修改。語音 `input` 最多 5,000 字,`voice` 不帶用平台預設的中文女聲;瀏覽器端不提供語音。
112
+ - 固定格式輸出(`response_format`)不保證可用;請在提示詞要求 JSON 並自行解析。
113
+ - 扣點:依實際成本換算(`點數 = ceil(美元成本 × 匯率 × 1.3)`,最少 1 點)。被內容審查擋下、上游失敗都不扣點。
114
+
115
+ ## 4. 房市資料
116
+
117
+ ```js
118
+ const od = academy.od(req);
119
+ await od.lvr.deals({ city: '臺北市', district: '大安區', limit: 10 }); // 實價登錄逐筆成交
120
+ await od.lvr.marketContext({ city: '臺北市', district: '大安區' }); // 區域行情:中位數、p25/p75、逐月趨勢
121
+ await od.nearby.deals({ address: '臺北市大安區敦化南路二段 1 號' }); // 周邊近期成交
122
+ await od.nearby.amenities({ lat: 25.0263, lng: 121.5434 }); // 生活機能(含公車路線)與嫌惡設施
123
+ await od.address.convert({ address: '…' }); // 地址正規化、地址與座標互轉
124
+ await od.area.profile({ city: '臺北市', district: '大安區' }); // 人口、所得、房貸利率
125
+ await od.hazards({ lat: 25.0263, lng: 121.5434 }); // 五類災害潛勢(查無不等於無風險)
126
+ await od.marketBriefs({ period_type: 'weekly' }); // 市場快訊
127
+ ```
128
+
129
+ - 參數與 AI 研究所 MCP 的開放資料工具相同:**中文縣市名**、價格用**萬元/坪**、面積用**坪**。單價一律是車位拆算後的值(推估的會註記)。
130
+ - 每次查詢扣 1 點(翻頁每頁各算一次),失敗不扣。
131
+ - 每位會員每分鐘最多 10 次(跨 App 合計)、每個 App 每分鐘最多 60 次;超過回 `DATA_UNAVAILABLE`,`err.retryAfterSeconds` 是建議等待秒數。
132
+ - 上架時要勾選「使用平台房市資料」才能用。
133
+
134
+ ## 5. 工作憑證(背景工作)
135
+
136
+ 會員離開頁面後還要繼續跑的工作(產生報告、批次處理),在會員在場時先開一個工作,預佔點數換一張憑證;背景工作憑它在預佔額度內使用平台 AI 與房市資料。
137
+
138
+ ```js
139
+ // 會員在場時(有 req.academy)
140
+ const job = await academy.jobs.open(req, { maxPoints: 80, ttlSeconds: 1200, purpose: '月報生成' });
141
+ await db.save({ jobToken: job.token }); // 憑證可以存進資料庫
142
+
143
+ // 背景工作
144
+ const j = academy.jobs.resume(token);
145
+ const r = await academy.ai(j).chat.completions.create({ model: 'smart', messages });
146
+ await academy.od(j).lvr.marketContext({ city: '臺北市' });
147
+ await j.close(); // 實扣用掉的、釋放其餘;沒關也會在到期時自動結清
148
+ ```
149
+
150
+ - `maxPoints` 上限 500、`ttlSeconds` 上限 1,800;每位會員在同一個 App 同時最多 2 個進行中的工作(超過回 `JOB_LIMIT_EXCEEDED`)。
151
+ - 預佔期間這些點數不能做別的用途,會員在「我的點數」看得到「處理中預佔:工具名:用途」。
152
+ - 用完預佔額度回 `JOB_BUDGET_EXCEEDED`;過期或已結束回 `JOB_EXPIRED`。
153
+ - 沒有會員在場啟動的排程工作(例如每天自動產生內容)**不能**用平台 AI,只能用你自備的金鑰。
154
+
155
+ ## 6. 點數與網址
156
+
157
+ ```js
158
+ await academy.getQuota(req);
159
+ // { tier, points_remaining, points_held, reset_at, dev_quota_remaining? } dev_quota_remaining 只在測試環境與開發模式回傳
160
+
161
+ academy.urls.upgrade // 方案頁(點數不足時帶會員去這裡)
162
+ academy.urls.points // 我的點數
163
+ academy.urls.subscribe // 我的訂閱
164
+ academy.urls.logout // 登出這個 App(同網域相對路徑)
165
+ ```
166
+
167
+ ## 7. 瀏覽器端(純前端 App)
168
+
169
+ ```js
170
+ import { academyBrowser, AcademyError } from '@agentgo-tw/app-sdk/browser';
171
+
172
+ const me = await academyBrowser.me(); // 打同網域 /__academy/me,同時向平台握手(純前端 App 的上架自檢以此為準)
173
+ if (me === null) {
174
+ // 尚未啟用入口關卡(例如還沒按「啟用」的正式環境):維持原本的行為
175
+ }
176
+
177
+ const ai = academyBrowser.ai(); // 對話(含串流)、圖片
178
+ const od = academyBrowser.od(); // 房市資料
179
+
180
+ try {
181
+ await ai.chat.completions.create({ model: 'fast', messages });
182
+ } catch (e) {
183
+ if (!academyBrowser.redirectFor(e)) alert(e.message); // 未登入、沒有訂閱、點數不足 → 導到平台頁面
184
+ }
185
+ ```
186
+
187
+ 瀏覽器端以 App cookie 驗身分,請求一律同網域;平台另做來源檢查,別的網站拿不到會員的點數。
188
+
189
+ ## 8. 本機開發模式
190
+
191
+ 在自己電腦上設:
192
+
193
+ ```bash
194
+ ACADEMY_DEV_MODE=1
195
+ ACADEMY_DEV_KEY=adk_… # 在上架頁「個人開發金鑰」產生
196
+ ACADEMY_BASE_URL=https://agentgo.tw
197
+ ACADEMY_DEV_USER=me@example.com # 可省略
198
+ ```
199
+
200
+ - SDK 不驗章,`req.academy` 一律是假身分(`env: 'test'`、`entitlement.kind: 'OWNER_TEST'`)。
201
+ - 平台 AI、房市資料與工作憑證改帶開發金鑰,先扣你的**開發額度**(每月 200 點),用完扣你本人的月點數。
202
+ - **防呆**:跑在平台上(有 `ACADEMY_ENV`)時,SDK 一律忽略 `ACADEMY_DEV_MODE` 並在啟動時印出警告;不會因為你把開發設定一起部署上去就繞過驗證。
203
+
204
+ ## 9. 錯誤
205
+
206
+ 所有平台錯誤都是 `AcademyError`:`code`、`status`、`message`、`details`(附帶欄位),另有捷徑 `loginUrl`、`subscribeUrl`、`upgradeUrl`、`retryAfterSeconds`、`reason`。**請看 `code`,不要只看 HTTP 狀態**(暫停、下架與沒有訂閱都是 403)。
207
+
208
+ | `code` | HTTP | 情況 | 附帶欄位 |
209
+ |---|---|---|---|
210
+ | `LOGIN_REQUIRED` | 401 | 未登入或 App 登入失效 | `login_url` |
211
+ | `SUBSCRIPTION_REQUIRED` | 403 | 訂閱制工具沒有有效訂閱 | `subscribe_url` |
212
+ | `APP_UNAVAILABLE` | 403 | 工具暫停、已下架,或非放行帳號進測試環境 | `status`:`SUSPENDED`/`DELISTED`/`TEST_ONLY` |
213
+ | `ORIGIN_NOT_ALLOWED` | 403 | 瀏覽器端來源檢查不通過 | — |
214
+ | `IDENTITY_EXPIRED` | 401 | 沒有會員身分或身分已過期 | — |
215
+ | `INSUFFICIENT_POINTS` | 402 | 點數不足 | `upgrade_url`、`reset_at` |
216
+ | `MODEL_NOT_ALLOWED` | 400 | `model` 不是可用的平台別名 | `allowed` |
217
+ | `AI_LIMIT_EXCEEDED` | 429 | 超過上限 | `reason`:`PER_CALL`/`USER_RATE`(附 `retry_after_seconds`)/`APP_DAILY_COST` |
218
+ | `AI_UNAVAILABLE` | 503 | 上游失敗或平台 AI 暫停 | — |
219
+ | `CONTENT_FLAGGED` | 400 | 內容審查擋下(不扣點) | — |
220
+ | `INVALID_REQUEST` | 400 | 請求格式不正確(不扣點) | `message` 說明哪個欄位 |
221
+ | `DATA_UNAVAILABLE` | 429/503 | 房市資料暫時無法提供(不扣點) | `reason`、`retry_after_seconds` |
222
+ | `JOB_EXPIRED` | 401 | 工作憑證過期或已結束 | — |
223
+ | `JOB_BUDGET_EXCEEDED` | 402 | 工作憑證的預佔額度用完 | `max_points`、`used_points` |
224
+ | `JOB_LIMIT_EXCEEDED` | 409 | 進行中的工作已達上限 | `max_concurrent` |
225
+
226
+ 日後可能新增錯誤碼;不認得的 `code` 也會包成 `AcademyError`,不會讓你的程式崩潰。
227
+
228
+ ## 10. 從 Google AI Studio 匯出的專案改寫
229
+
230
+ SDK **不提供** `@google/genai` 相容層,也不會自動對照 Gemini 模型名。請把呼叫改成下面的形狀:
231
+
232
+ | 原本(`@google/genai`) | 改成(本 SDK) |
233
+ |---|---|
234
+ | `new GoogleGenAI({ apiKey })` | 伺服器端 `createAcademy()`;瀏覽器端 `academyBrowser.ai()` |
235
+ | `ai.models.generateContent({ model: 'gemini-2.5-flash', contents })` | `ai.chat.completions.create({ model: 'fast', messages: [{ role: 'user', content }] })` |
236
+ | `response.text` | `response.choices[0].message.content` |
237
+ | `config.systemInstruction` | `messages` 第一則 `{ role: 'system', content }` |
238
+ | `generateContentStream(...)`、`chunk.text` | `create({ ..., stream: true })`、`chunk.choices[0].delta.content` |
239
+ | `ai.models.generateImages({ model: 'imagen-…', prompt })` | `ai.images.generate({ model: 'image', prompt })`,結果在 `data[0].b64_json` |
240
+ | 多輪對話 `ai.chats.create()` | 自己保存 `messages` 陣列,每次整串送出 |
241
+ | `config.responseMimeType: 'application/json'` | 在提示詞要求 JSON 並自行 `JSON.parse` |
242
+
243
+ 不改寫的部分可以繼續用你自備的金鑰直連,只是那部分的 AI 費用不能用會員點數支付。function calling、檔案上傳、Live API 目前不支援。
244
+
245
+ ## 11. 過渡期:保留原本的登入
246
+
247
+ 上架前或還沒按「啟用」時,正式環境沒有入口關卡,`req.academy` 是 `null`。App 可以這樣同時支援兩種登入:
248
+
249
+ ```js
250
+ app.use(academy.express());
251
+ app.use((req, res, next) => {
252
+ if (req.academy) { req.currentUser = { id: req.academy.user.uuid, name: req.academy.user.name }; return next(); }
253
+ return yourOwnLogin(req, res, next); // 原本的登入
254
+ });
255
+ ```
256
+
257
+ 同一位會員在每個 App 的 `user.uuid` 都相同,可以用 email 對應到你原本的使用者資料。
258
+
259
+ ## 12. 範例
260
+
261
+ - [`examples/express-subscription`](examples/express-subscription):有伺服器端的訂閱制 App(身分、對話、房市資料、點數、工作憑證背景報告)
262
+ - [`examples/frontend-free`](examples/frontend-free):純前端免費 App(AI Studio 匯出的 Vite 專案改寫:串流文案、圖片、災害潛勢)
@@ -0,0 +1,233 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/browser.ts
21
+ var browser_exports = {};
22
+ __export(browser_exports, {
23
+ AcademyError: () => AcademyError,
24
+ CONTRACT_VERSION: () => CONTRACT_VERSION,
25
+ SDK_VERSION: () => SDK_VERSION,
26
+ academyBrowser: () => academyBrowser
27
+ });
28
+ module.exports = __toCommonJS(browser_exports);
29
+
30
+ // src/errors.ts
31
+ var AcademyError = class extends Error {
32
+ code;
33
+ status;
34
+ details;
35
+ constructor(code, message, status = 0, details = {}) {
36
+ super(message);
37
+ this.name = "AcademyError";
38
+ this.code = code;
39
+ this.status = status;
40
+ this.details = details;
41
+ }
42
+ /** `LOGIN_REQUIRED` 的重新登入網址 */
43
+ get loginUrl() {
44
+ return str(this.details.login_url);
45
+ }
46
+ /** `SUBSCRIPTION_REQUIRED` 的訂閱網址 */
47
+ get subscribeUrl() {
48
+ return str(this.details.subscribe_url);
49
+ }
50
+ /** `INSUFFICIENT_POINTS` 的升級網址 */
51
+ get upgradeUrl() {
52
+ return str(this.details.upgrade_url);
53
+ }
54
+ /** 429 類錯誤建議等待的秒數 */
55
+ get retryAfterSeconds() {
56
+ const v = this.details.retry_after_seconds;
57
+ return typeof v === "number" ? v : void 0;
58
+ }
59
+ /** `AI_LIMIT_EXCEEDED`/`DATA_UNAVAILABLE` 的原因 */
60
+ get reason() {
61
+ return str(this.details.reason);
62
+ }
63
+ };
64
+ var str = (v) => typeof v === "string" ? v : void 0;
65
+ async function errorFromResponse(res) {
66
+ let body = {};
67
+ try {
68
+ body = await res.json();
69
+ } catch {
70
+ }
71
+ const { code, message, ...rest } = body;
72
+ const fallback = res.status === 401 ? "IDENTITY_EXPIRED" : res.status === 402 ? "INSUFFICIENT_POINTS" : res.status >= 500 ? "AI_UNAVAILABLE" : "INVALID_REQUEST";
73
+ return new AcademyError(
74
+ typeof code === "string" && code ? code : fallback,
75
+ typeof message === "string" && message ? message : `\u5E73\u53F0\u56DE\u61C9 HTTP ${res.status}`,
76
+ res.status,
77
+ rest
78
+ );
79
+ }
80
+
81
+ // src/sse.ts
82
+ async function* parseSse(body, onError) {
83
+ const reader = body.getReader();
84
+ const decoder = new TextDecoder();
85
+ let buf = "";
86
+ try {
87
+ for (; ; ) {
88
+ const { done, value } = await reader.read();
89
+ if (done) break;
90
+ buf += decoder.decode(value, { stream: true });
91
+ let idx;
92
+ while ((idx = buf.search(/\r?\n\r?\n/)) >= 0) {
93
+ const event = buf.slice(0, idx);
94
+ buf = buf.slice(idx).replace(/^\r?\n\r?\n/, "");
95
+ const data = event.split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trimStart()).join("\n");
96
+ if (!data) continue;
97
+ if (data === "[DONE]") return;
98
+ let obj;
99
+ try {
100
+ obj = JSON.parse(data);
101
+ } catch {
102
+ continue;
103
+ }
104
+ if (obj.error && typeof obj.error === "object") throw onError(obj.error);
105
+ yield obj;
106
+ }
107
+ }
108
+ } finally {
109
+ reader.releaseLock();
110
+ }
111
+ }
112
+
113
+ // src/transport.ts
114
+ function toQuery(q) {
115
+ if (!q) return "";
116
+ const sp = new URLSearchParams();
117
+ for (const [k, v] of Object.entries(q)) {
118
+ if (v === void 0 || v === null || v === "") continue;
119
+ sp.set(k, Array.isArray(v) ? v.join(",") : String(v));
120
+ }
121
+ const s = sp.toString();
122
+ return s ? `?${s}` : "";
123
+ }
124
+ async function json(t, method, path, init) {
125
+ const res = await t.send(method, path, init);
126
+ if (res.ok) return await res.json();
127
+ throw await toError(t, res);
128
+ }
129
+ async function toError(t, res) {
130
+ if (t.browser && res.status === 404 && !(res.headers.get("content-type") ?? "").includes("json")) {
131
+ return new AcademyError("IDENTITY_EXPIRED", "\u9019\u500B\u7DB2\u5740\u6C92\u6709\u5E73\u53F0\u4FDD\u7559\u8DEF\u5F91\uFF08\u5C1A\u672A\u555F\u7528\u5165\u53E3\u95DC\u5361\uFF09\uFF0C\u7121\u6CD5\u4F7F\u7528\u5E73\u53F0\u8CC7\u6E90", 404);
132
+ }
133
+ return await errorFromResponse(res);
134
+ }
135
+
136
+ // src/ai.ts
137
+ function createAiClient(t, base, opts) {
138
+ async function create(body) {
139
+ if (!body.stream) return await json(t, "POST", `${base}/chat/completions`, { body });
140
+ const res = await t.send("POST", `${base}/chat/completions`, { body });
141
+ if (!res.ok || !res.body) throw await toError(t, res);
142
+ const stream = res.body;
143
+ return {
144
+ [Symbol.asyncIterator]: () => parseSse(stream, (e) => new AcademyError(typeof e.code === "string" ? e.code : "AI_UNAVAILABLE", typeof e.message === "string" ? e.message : "\u4E32\u6D41\u4E2D\u65B7", 0, e))
145
+ };
146
+ }
147
+ return {
148
+ chat: { completions: { create } },
149
+ images: { generate: (body) => json(t, "POST", `${base}/images/generations`, { body }) },
150
+ audio: {
151
+ speech: {
152
+ create: (body) => {
153
+ if (!opts.speech) return Promise.reject(new AcademyError("INVALID_REQUEST", "\u700F\u89BD\u5668\u7AEF\u4E0D\u63D0\u4F9B\u8A9E\u97F3\uFF0C\u8ACB\u7531 App \u5F8C\u7AEF\u547C\u53EB", 0));
154
+ return json(t, "POST", `${base}/audio/speech`, { body });
155
+ }
156
+ }
157
+ }
158
+ };
159
+ }
160
+
161
+ // src/od.ts
162
+ function createOdClient(t, base) {
163
+ const get = (resource, q) => json(t, "GET", `${base}/${resource.replace(/^\/+/, "")}`, { query: q ?? {} });
164
+ return {
165
+ lvr: { deals: (q) => get("lvr/deals", q), marketContext: (q) => get("lvr/market-context", q) },
166
+ nearby: { deals: (q) => get("nearby/deals", q), amenities: (q) => get("nearby/amenities", q) },
167
+ address: { convert: (q) => get("address/convert", q) },
168
+ area: { profile: (q) => get("area/profile", q) },
169
+ hazards: (q) => get("hazards", q),
170
+ marketBriefs: (q) => get("market-briefs", q),
171
+ get
172
+ };
173
+ }
174
+
175
+ // src/version.ts
176
+ var SDK_VERSION = "1.0.0";
177
+ var CONTRACT_VERSION = 1;
178
+
179
+ // src/browser.ts
180
+ var transport = {
181
+ browser: true,
182
+ send: (method, path, init) => fetch(`${path}${toQuery(init?.query)}`, {
183
+ method,
184
+ credentials: "same-origin",
185
+ headers: { "X-Academy-SDK": SDK_VERSION, ...init?.body !== void 0 ? { "Content-Type": "application/json" } : {} },
186
+ body: init?.body !== void 0 ? JSON.stringify(init.body) : void 0
187
+ })
188
+ };
189
+ var academyBrowser = {
190
+ /**
191
+ * 目前的身分、訂閱狀態與點數;同時向平台握手(純前端 App 的上架自檢以此為準)。
192
+ * 保留路徑不存在(尚未啟用入口關卡)時回 null;未登入、沒有訂閱、工具暫停等丟 AcademyError(看 `code`)。
193
+ */
194
+ async me() {
195
+ let res;
196
+ try {
197
+ res = await transport.send("GET", "/__academy/me");
198
+ } catch {
199
+ return null;
200
+ }
201
+ if (res.ok) return await res.json();
202
+ const err = await toError(transport, res);
203
+ if (err.code === "IDENTITY_EXPIRED" && res.status === 404) return null;
204
+ throw err;
205
+ },
206
+ /** 平台 AI:對話(含串流)與圖片生成;語音請由 App 後端呼叫 */
207
+ ai() {
208
+ return createAiClient(transport, "/__academy/ai", { speech: false });
209
+ },
210
+ /** 房市資料 */
211
+ od() {
212
+ return createOdClient(transport, "/__academy/od");
213
+ },
214
+ /** 登出這個 App(清除 App cookie 後回到研究所首頁) */
215
+ logout() {
216
+ window.location.href = "/__academy/logout";
217
+ },
218
+ /** 依錯誤碼導到平台頁面(登入、訂閱、升級);處理了回 true */
219
+ redirectFor(err) {
220
+ if (!(err instanceof AcademyError)) return false;
221
+ const url = err.loginUrl ?? err.subscribeUrl ?? err.upgradeUrl;
222
+ if (!url) return false;
223
+ window.location.href = url;
224
+ return true;
225
+ }
226
+ };
227
+ // Annotate the CommonJS export names for ESM import in node:
228
+ 0 && (module.exports = {
229
+ AcademyError,
230
+ CONTRACT_VERSION,
231
+ SDK_VERSION,
232
+ academyBrowser
233
+ });
@@ -0,0 +1,20 @@
1
+ import { A as AcademyMe, a as AcademyAI, b as AcademyOD } from './version-CAQs9BfE.cjs';
2
+ export { c as AcademyContext, d as AcademyEntitlement, e as AcademyError, f as AcademyErrorCode, g as AcademyJobInfo, h as AcademyQuota, i as AcademyUser, j as AppEntitlementKind, k as AppIdentityEnv, l as AppJobStatus, C as CONTRACT_VERSION, m as ChatCompletion, n as ChatCompletionChunk, o as ChatCompletionRequest, p as ChatMessage, q as ChatRole, I as ImageGenerateRequest, r as ImageGenerateResponse, M as MembershipTier, O as OdQuery, s as OdResult, S as SDK_VERSION, t as SpeechRequest, u as SpeechResponse } from './version-CAQs9BfE.cjs';
3
+
4
+ declare const academyBrowser: {
5
+ /**
6
+ * 目前的身分、訂閱狀態與點數;同時向平台握手(純前端 App 的上架自檢以此為準)。
7
+ * 保留路徑不存在(尚未啟用入口關卡)時回 null;未登入、沒有訂閱、工具暫停等丟 AcademyError(看 `code`)。
8
+ */
9
+ me(): Promise<AcademyMe | null>;
10
+ /** 平台 AI:對話(含串流)與圖片生成;語音請由 App 後端呼叫 */
11
+ ai(): AcademyAI;
12
+ /** 房市資料 */
13
+ od(): AcademyOD;
14
+ /** 登出這個 App(清除 App cookie 後回到研究所首頁) */
15
+ logout(): void;
16
+ /** 依錯誤碼導到平台頁面(登入、訂閱、升級);處理了回 true */
17
+ redirectFor(err: unknown): boolean;
18
+ };
19
+
20
+ export { AcademyAI, AcademyMe, AcademyOD, academyBrowser };
@@ -0,0 +1,20 @@
1
+ import { A as AcademyMe, a as AcademyAI, b as AcademyOD } from './version-CAQs9BfE.js';
2
+ export { c as AcademyContext, d as AcademyEntitlement, e as AcademyError, f as AcademyErrorCode, g as AcademyJobInfo, h as AcademyQuota, i as AcademyUser, j as AppEntitlementKind, k as AppIdentityEnv, l as AppJobStatus, C as CONTRACT_VERSION, m as ChatCompletion, n as ChatCompletionChunk, o as ChatCompletionRequest, p as ChatMessage, q as ChatRole, I as ImageGenerateRequest, r as ImageGenerateResponse, M as MembershipTier, O as OdQuery, s as OdResult, S as SDK_VERSION, t as SpeechRequest, u as SpeechResponse } from './version-CAQs9BfE.js';
3
+
4
+ declare const academyBrowser: {
5
+ /**
6
+ * 目前的身分、訂閱狀態與點數;同時向平台握手(純前端 App 的上架自檢以此為準)。
7
+ * 保留路徑不存在(尚未啟用入口關卡)時回 null;未登入、沒有訂閱、工具暫停等丟 AcademyError(看 `code`)。
8
+ */
9
+ me(): Promise<AcademyMe | null>;
10
+ /** 平台 AI:對話(含串流)與圖片生成;語音請由 App 後端呼叫 */
11
+ ai(): AcademyAI;
12
+ /** 房市資料 */
13
+ od(): AcademyOD;
14
+ /** 登出這個 App(清除 App cookie 後回到研究所首頁) */
15
+ logout(): void;
16
+ /** 依錯誤碼導到平台頁面(登入、訂閱、升級);處理了回 true */
17
+ redirectFor(err: unknown): boolean;
18
+ };
19
+
20
+ export { AcademyAI, AcademyMe, AcademyOD, academyBrowser };
@@ -0,0 +1,64 @@
1
+ import {
2
+ AcademyError,
3
+ CONTRACT_VERSION,
4
+ SDK_VERSION,
5
+ createAiClient,
6
+ createOdClient,
7
+ toError,
8
+ toQuery
9
+ } from "./chunk-6QX4VARC.js";
10
+
11
+ // src/browser.ts
12
+ var transport = {
13
+ browser: true,
14
+ send: (method, path, init) => fetch(`${path}${toQuery(init?.query)}`, {
15
+ method,
16
+ credentials: "same-origin",
17
+ headers: { "X-Academy-SDK": SDK_VERSION, ...init?.body !== void 0 ? { "Content-Type": "application/json" } : {} },
18
+ body: init?.body !== void 0 ? JSON.stringify(init.body) : void 0
19
+ })
20
+ };
21
+ var academyBrowser = {
22
+ /**
23
+ * 目前的身分、訂閱狀態與點數;同時向平台握手(純前端 App 的上架自檢以此為準)。
24
+ * 保留路徑不存在(尚未啟用入口關卡)時回 null;未登入、沒有訂閱、工具暫停等丟 AcademyError(看 `code`)。
25
+ */
26
+ async me() {
27
+ let res;
28
+ try {
29
+ res = await transport.send("GET", "/__academy/me");
30
+ } catch {
31
+ return null;
32
+ }
33
+ if (res.ok) return await res.json();
34
+ const err = await toError(transport, res);
35
+ if (err.code === "IDENTITY_EXPIRED" && res.status === 404) return null;
36
+ throw err;
37
+ },
38
+ /** 平台 AI:對話(含串流)與圖片生成;語音請由 App 後端呼叫 */
39
+ ai() {
40
+ return createAiClient(transport, "/__academy/ai", { speech: false });
41
+ },
42
+ /** 房市資料 */
43
+ od() {
44
+ return createOdClient(transport, "/__academy/od");
45
+ },
46
+ /** 登出這個 App(清除 App cookie 後回到研究所首頁) */
47
+ logout() {
48
+ window.location.href = "/__academy/logout";
49
+ },
50
+ /** 依錯誤碼導到平台頁面(登入、訂閱、升級);處理了回 true */
51
+ redirectFor(err) {
52
+ if (!(err instanceof AcademyError)) return false;
53
+ const url = err.loginUrl ?? err.subscribeUrl ?? err.upgradeUrl;
54
+ if (!url) return false;
55
+ window.location.href = url;
56
+ return true;
57
+ }
58
+ };
59
+ export {
60
+ AcademyError,
61
+ CONTRACT_VERSION,
62
+ SDK_VERSION,
63
+ academyBrowser
64
+ };