@downcity/city 0.2.17 → 0.2.25

package/README.md

@@ -5,7 +5,7 @@
 它负责这些共用能力：
 
 - 挂载 `Service` / `AIService`
-- 初始化内置 `studios` / `env` 表
+- 初始化内置 `towns` / `env` 表
 - 校验 `user_token` 和 `admin_secret_key`
 - 暴露统一的 `/v1/*` HTTP 路由
 - 提供 env、数据库、hook 和鉴权上下文
@@ -19,7 +19,7 @@ pnpm add @downcity/city
 ## 最小示例
 
 ```ts
-import { City, AIService } from "@downcity/city";
+import { CityBase, AIService } from "@downcity/city";
 import Database from "better-sqlite3";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 
@@ -30,7 +30,7 @@ const db = Object.assign(drizzle(sqlite), {
   $client: { exec: (sql: string) => sqlite.exec(sql) },
 });
 
-const city = new City({ db, dialect: "sqlite", raw: sqlite });
+const base = new CityBase({ db, dialect: "sqlite", raw: sqlite });
 
 const ai = new AIService();
 ai.use({
@@ -52,7 +52,7 @@ ai.use({
   },
 });
 
-city.use(ai);
+base.use(ai);
 ```
 
 启动 HTTP 服务：
@@ -60,21 +60,21 @@ city.use(ai);
 ```ts
 import { serve } from "@hono/node-server";
 
-await city.health();
-serve({ fetch: city.router().fetch, port: 43127, hostname: "127.0.0.1" });
+await base.health();
+serve({ fetch: base.router().fetch, port: 43127, hostname: "127.0.0.1" });
 ```
 
 ## City 说明文档
 
-`city.instruction()` 会返回当前 City 实例的聚合说明文档字符串，内容包含：
+`base.instruction()` 会返回当前 CityBase 实例的聚合说明文档字符串，内容包含：
 
-- City 的基本使用方式
+- CityBase 的基本使用方式
 - 当前已挂载的 service
 - 每个模块需要的 env 配置
 - 每个模块补充的使用说明
 
 ```ts
-const text = await city.instruction();
+const text = await base.instruction();
 console.log(text);
 ```
 
@@ -106,7 +106,7 @@ notes.action("list", async () => {
   return { items: [] };
 }, { method: "GET", auth: ["admin"] });
 
-city.use(notes);
+base.use(notes);
 ```
 
 City 会自动映射为：
@@ -137,19 +137,19 @@ ai.use(
   }),
 );
 
-city.use(ai);
+base.use(ai);
 ```
 
 ## 官方服务
 
-官方服务用于封装多 studio 复用能力：
+官方服务用于封装多 town 复用能力：
 
 ```ts
 import { accountsService } from "@downcity/services";
 import { usageService } from "@downcity/services";
 
-city.use(accountsService());
-city.use(usageService());
+base.use(accountsService());
+base.use(usageService());
 ```
 
 服务路由当前只支持：
@@ -163,18 +163,35 @@ city.use(usageService());
 - `auth: ["admin"]` 只允许 `admin_secret_key`
 - `auth: []` 表示免登录
 
-对于用户侧请求，`user_token` 绑定 studio 身份。如果请求体或 query 中传了 `studio_id`，它必须与 token 里的 studio 一致。
+对于用户侧请求，`user_token` 绑定 town 身份。如果请求体或 query 中传了 `town_id`，它必须与 token 里的 town 一致。
 
 ## 主要导出
 
 - `City`
+- `CityBase`
 - `Service`
 - `ServiceDefinition`
 - `AIService`
 - `Provider`
+- `CityModel`
+- `CityModelDescriptor`
 - `TokenSigner`
 - `EnvService`
-- `StudiosService`
+- `TownsService`
+
+## City 模型目录
+
+`User City` 的 `client.ai.listModels()` 返回 `ModelCatalog`。目录中的模型是 `CityModel`，可以直接用于 City 的 AI 调用，也可以传给支持 CityModel 的 Agent SDK：
+
+```ts
+const catalog = await client.ai.listModels();
+const model = catalog.default();
+
+await client.ai.text({
+  model,
+  prompt: "hello",
+});
+```
 
 ## 文档
 

package/bin/city/admin/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 管理端 SDK。
+ */
+import { ServiceClient } from "../invoker/invoker.js";
+import { BalanceInvoker } from "../invoker/balance/index.js";
+import { EnvInvoker } from "../invoker/env/index.js";
+import { TownsInvoker } from "../invoker/towns/index.js";
+import type { AdminCityAccessOptions, AdminModelRecord, AdminServiceSummary } from "./types.js";
+export declare class AdminCityAccess {
+    readonly balance: BalanceInvoker;
+    readonly env: EnvInvoker;
+    readonly towns: TownsInvoker;
+    private readonly base_url;
+    private readonly secret;
+    private readonly fetchImpl;
+    constructor(options: AdminCityAccessOptions);
+    /** 获取 Service 调用器（与 User City 共用同一路由） */
+    service(name: string): ServiceClient;
+    /** 列出当前 City 暴露的 service 摘要。 */
+    listServices(): Promise<AdminServiceSummary[]>;
+    /** 列出当前 City 注册的模型目录（admin 身份可见额外状态字段）。 */
+    listModels(): Promise<AdminModelRecord[]>;
+    /** 读取 City 聚合后的说明文档。 */
+    instruction(): Promise<string>;
+    private json;
+    private text;
+    /**
+     * 为管理端请求统一补齐鉴权头。
+     *
+     * 关键说明（中文）
+     * - 所有管理端请求都必须带上 admin bearer token
+     * - 默认仍然补 `content-type: application/json`，便于 POST action 统一行为
+     */
+    private withAuth;
+}
+//# sourceMappingURL=index.d.ts.map

package/bin/city/admin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/city/admin/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAUzD,OAAO,KAAK,EACV,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,OAAO,EAAE,sBAAsB;IAkB3C,yCAAyC;IACzC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAUpC,gCAAgC;IAC1B,YAAY,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAOpD,2CAA2C;IACrC,UAAU,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAO/C,wBAAwB;IAClB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAIpC,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,IAAI;IAQZ;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;CAUjB"}

package/bin/city/admin/index.js

@@ -0,0 +1,85 @@
+/**
+ * 管理端 SDK。
+ */
+import { ServiceClient } from "../invoker/invoker.js";
+import { BalanceInvoker } from "../invoker/balance/index.js";
+import { EnvInvoker } from "../invoker/env/index.js";
+import { TownsInvoker } from "../invoker/towns/index.js";
+import { defaultFetch, normalizeBaseURL, requestJSON, requestText, requiredString, } from "../http.js";
+export class AdminCityAccess {
+    balance;
+    env;
+    towns;
+    base_url;
+    secret;
+    fetchImpl;
+    constructor(options) {
+        if (!options || typeof options !== "object") {
+            throw new TypeError("Admin City options are required");
+        }
+        this.base_url = normalizeBaseURL(options.base_url, "base_url");
+        this.secret = requiredString(options.admin_secret_key ?? process.env.DOWNCITY_CITY_ADMIN_SECRET_KEY, "admin_secret_key");
+        this.fetchImpl = options.fetch ?? defaultFetch();
+        const req = (path, init) => this.json(path, init);
+        this.balance = new BalanceInvoker({ requestJSON: req });
+        this.env = new EnvInvoker({ requestJSON: req });
+        this.towns = new TownsInvoker({ requestJSON: req });
+    }
+    /** 获取 Service 调用器（与 User City 共用同一路由） */
+    service(name) {
+        const id = String(name ?? "").trim();
+        if (!id)
+            throw new TypeError("service name is required");
+        return new ServiceClient((path, init) => this.json(path, init), "/v1", id);
+    }
+    /** 列出当前 City 暴露的 service 摘要。 */
+    async listServices() {
+        const body = await this.json("/v1/services", {
+            method: "GET",
+        });
+        return body.items;
+    }
+    /** 列出当前 City 注册的模型目录（admin 身份可见额外状态字段）。 */
+    async listModels() {
+        const body = await this.json("/v1/ai/models", {
+            method: "GET",
+        });
+        return body.items;
+    }
+    /** 读取 City 聚合后的说明文档。 */
+    async instruction() {
+        return this.text("/v1/city/instruction", { method: "GET" });
+    }
+    json(path, init) {
+        return requestJSON({
+            fetch: this.fetchImpl,
+            url: `${this.base_url}${path}`,
+            init: this.withAuth(init),
+        });
+    }
+    text(path, init) {
+        return requestText({
+            fetch: this.fetchImpl,
+            url: `${this.base_url}${path}`,
+            init: this.withAuth(init),
+        });
+    }
+    /**
+     * 为管理端请求统一补齐鉴权头。
+     *
+     * 关键说明（中文）
+     * - 所有管理端请求都必须带上 admin bearer token
+     * - 默认仍然补 `content-type: application/json`，便于 POST action 统一行为
+     */
+    withAuth(init) {
+        return {
+            ...init,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.secret}`,
+                ...init.headers,
+            },
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/bin/city/admin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/city/admin/index.ts"],"names":[],"mappings":"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"}

package/bin/city/admin/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 管理端类型。
+ */
+import type { FetchLike } from "../http.js";
+import type { CityModelDescriptor } from "@downcity/type";
+import type { UserServiceSummary } from "../user/types.js";
+/** Admin City 内部访问层构造参数 */
+export interface AdminCityAccessOptions {
+    /** City 管理端 server URL */
+    base_url: string;
+    /** 管理密钥 */
+    admin_secret_key?: string;
+    /** 自定义 fetch 实现 */
+    fetch?: FetchLike;
+}
+/**
+ * 管理端可见的 Service 摘要。
+ *
+ * 复用统一 Service 目录结构：
+ * - `id` / `name` 用于展示可调用模块
+ * - `env` 用于提示当前模块依赖的配置项
+ */
+export type AdminServiceSummary = UserServiceSummary;
+/**
+ * 管理端可见的模型目录记录。
+ *
+ * 复用统一模型目录结构；admin 身份下会额外看到：
+ * - `env_requirements`
+ * - `default_modes`
+ */
+export type AdminModelRecord = CityModelDescriptor;
+/**
+ * City 聚合说明文档结果。
+ */
+export interface AdminInstructionResult {
+    /**
+     * 供管理端直接阅读的纯文本说明。
+     */
+    text: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/bin/city/admin/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/city/admin/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,2BAA2B;AAC3B,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd"}

package/bin/city/admin/types.js

@@ -0,0 +1,5 @@
+/**
+ * 管理端类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/bin/city/admin/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/city/admin/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/bin/city/city.d.ts

@@ -0,0 +1,73 @@
+/**
+ * City 统一访问入口。
+ *
+ * City 面向开发者表达“我以某种角色进入 City”，内部再委托给
+ * admin / user 访问层，避免用户在第一层概念上关心 client 拆分。
+ */
+import { AdminCityAccess } from "./admin/index.js";
+import { UserCityAccess } from "./user/index.js";
+import type { ServiceClient } from "./invoker/invoker.js";
+import type { CityOptionsForRole, CityRole } from "./types/city.js";
+import type { AdminModelRecord, AdminServiceSummary } from "./admin/types.js";
+import type { UserServiceSummary } from "./user/types.js";
+/**
+ * Downcity City。
+ */
+export declare class City<TRole extends CityRole = CityRole> {
+    /**
+     * 当前 City 访问角色。
+     */
+    readonly role: TRole;
+    /**
+     * Admin 能力面。
+     *
+     * 仅 `role: "admin"` 时可用。
+     */
+    private readonly admin_access?;
+    /**
+     * User 能力面。
+     *
+     * 仅 `role: "user"` 时可用。
+     */
+    private readonly user_access?;
+    constructor(options: CityOptionsForRole<TRole>);
+    /**
+     * User City 的 AI 调用入口。
+     */
+    get ai(): UserCityAccess["ai"];
+    /**
+     * User City 的支付入口。
+     */
+    get payment(): UserCityAccess["payment"];
+    /**
+     * Admin City 的余额服务入口。
+     */
+    get balance(): AdminCityAccess["balance"];
+    /**
+     * Admin City 的环境变量服务入口。
+     */
+    get env(): AdminCityAccess["env"];
+    /**
+     * Admin City 的 Town 管理入口。
+     */
+    get towns(): AdminCityAccess["towns"];
+    /**
+     * 获取普通 service 调用器。
+     */
+    service(name: string): ServiceClient;
+    /**
+     * 列出当前 City 暴露的 service。
+     */
+    listServices(): Promise<AdminServiceSummary[] | UserServiceSummary[]>;
+    /**
+     * 列出 City 模型目录。
+     */
+    listModels(): Promise<AdminModelRecord[]>;
+    /**
+     * 读取 City 聚合说明文档。
+     */
+    instruction(): Promise<string>;
+    private require_admin;
+    private require_user;
+}
+//# sourceMappingURL=city.d.ts.map

package/bin/city/city.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"city.d.ts","sourceRoot":"","sources":["../../src/city/city.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;GAEG;AACH,qBAAa,IAAI,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACjD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAkB;IAEhD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAiB;gBAElC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC;IAwB9C;;OAEG;IACH,IAAI,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,CAE7B;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAEvC;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,eAAe,CAAC,SAAS,CAAC,CAExC;IAED;;OAEG;IACH,IAAI,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAEhC;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,CAEpC;IAED;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAIpC;;OAEG;IACH,YAAY,IAAI,OAAO,CAAC,mBAAmB,EAAE,GAAG,kBAAkB,EAAE,CAAC;IAIrE;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIzC;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAI9B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;CAMrB"}

package/bin/city/city.js

@@ -0,0 +1,116 @@
+/**
+ * City 统一访问入口。
+ *
+ * City 面向开发者表达“我以某种角色进入 City”，内部再委托给
+ * admin / user 访问层，避免用户在第一层概念上关心 client 拆分。
+ */
+import { AdminCityAccess } from "./admin/index.js";
+import { UserCityAccess } from "./user/index.js";
+/**
+ * Downcity City。
+ */
+export class City {
+    /**
+     * 当前 City 访问角色。
+     */
+    role;
+    /**
+     * Admin 能力面。
+     *
+     * 仅 `role: "admin"` 时可用。
+     */
+    admin_access;
+    /**
+     * User 能力面。
+     *
+     * 仅 `role: "user"` 时可用。
+     */
+    user_access;
+    constructor(options) {
+        if (!options || typeof options !== "object") {
+            throw new TypeError("City options are required");
+        }
+        this.role = options.role;
+        if (options.role === "admin") {
+            this.admin_access = new AdminCityAccess({
+                base_url: options.city_url,
+                admin_secret_key: options.admin_secret_key,
+                fetch: options.fetch,
+            });
+            return;
+        }
+        this.user_access = new UserCityAccess({
+            base_url: options.city_url,
+            town_id: options.town_id,
+            user_token: options.user_token,
+            fetch: options.fetch,
+        });
+    }
+    /**
+     * User City 的 AI 调用入口。
+     */
+    get ai() {
+        return this.require_user().ai;
+    }
+    /**
+     * User City 的支付入口。
+     */
+    get payment() {
+        return this.require_user().payment;
+    }
+    /**
+     * Admin City 的余额服务入口。
+     */
+    get balance() {
+        return this.require_admin().balance;
+    }
+    /**
+     * Admin City 的环境变量服务入口。
+     */
+    get env() {
+        return this.require_admin().env;
+    }
+    /**
+     * Admin City 的 Town 管理入口。
+     */
+    get towns() {
+        return this.require_admin().towns;
+    }
+    /**
+     * 获取普通 service 调用器。
+     */
+    service(name) {
+        return this.admin_access?.service(name) ?? this.require_user().service(name);
+    }
+    /**
+     * 列出当前 City 暴露的 service。
+     */
+    listServices() {
+        return this.admin_access?.listServices() ?? this.require_user().listServices();
+    }
+    /**
+     * 列出 City 模型目录。
+     */
+    listModels() {
+        return this.require_admin().listModels();
+    }
+    /**
+     * 读取 City 聚合说明文档。
+     */
+    instruction() {
+        return this.require_admin().instruction();
+    }
+    require_admin() {
+        if (!this.admin_access) {
+            throw new TypeError("City role admin is required for this operation");
+        }
+        return this.admin_access;
+    }
+    require_user() {
+        if (!this.user_access) {
+            throw new TypeError("City role user is required for this operation");
+        }
+        return this.user_access;
+    }
+}
+//# sourceMappingURL=city.js.map

package/bin/city/city.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"city.js","sourceRoot":"","sources":["../../src/city/city.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMjD;;GAEG;AACH,MAAM,OAAO,IAAI;IACf;;OAEG;IACM,IAAI,CAAQ;IAErB;;;;OAIG;IACc,YAAY,CAAmB;IAEhD;;;;OAIG;IACc,WAAW,CAAkB;IAE9C,YAAY,OAAkC;QAC5C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,SAAS,CAAC,2BAA2B,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAa,CAAC;QAElC,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,eAAe,CAAC;gBACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;gBAC1C,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,cAAc,CAAC;YACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,OAAO,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,YAAY,EAAE,CAAC;IACjF,CAAC;IAED;;OAEG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,UAAU,EAAE,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/bin/city/http.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Client 包 HTTP 基础设施。
+ *
+ * 集中处理 fetch 封装、URL 规范化、服务路径等共享工具。
+ * 同时包含 HTTP 层的公共类型。
+ */
+/** fetch 层收到的原始字节流 body */
+export type RawStreamBody = ReadableStream<Uint8Array> | null;
+/** SDK 内部传给 fetch 的请求配置 */
+export interface RequestInitLike {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** fetch 返回对象的最小接口 */
+export interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    body: RawStreamBody;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** SDK 使用的 fetch 函数签名 */
+export interface FetchLike {
+    (url: string, init: RequestInitLike): Promise<FetchResponseLike>;
+}
+/** 去掉 server URL 末尾多余斜杠 */
+export declare function normalizeBaseURL(value: unknown, label: string): string;
+/** 校验必填字符串 */
+export declare function requiredString(value: unknown, label: string): string;
+/** 读取全局 fetch */
+export declare function defaultFetch(): FetchLike;
+/** 发送 JSON 请求并解析响应 */
+export declare function requestJSON<T>(params: {
+    fetch: FetchLike;
+    url: string;
+    init: RequestInitLike;
+}): Promise<T>;
+/** 发送请求并返回原始响应 */
+export declare function requestRaw(params: {
+    fetch: FetchLike;
+    url: string;
+    init: RequestInitLike;
+}): Promise<FetchResponseLike>;
+/** 发送请求并解析文本响应 */
+export declare function requestText(params: {
+    fetch: FetchLike;
+    url: string;
+    init: RequestInitLike;
+}): Promise<string>;
+/** 标准化服务 ID */
+export declare function normalizeServiceId(value: string): string;
+/** 拼接服务请求路径 */
+export declare function servicePath(prefix: string, serviceId: string, path: string): string;
+//# sourceMappingURL=http.d.ts.map

package/bin/city/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/city/http.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,2BAA2B;AAC3B,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;AAE9D,2BAA2B;AAC3B,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,sBAAsB;AACtB,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,yBAAyB;AACzB,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAClE;AAMD,2BAA2B;AAC3B,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,cAAc;AACd,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpE;AAMD,iBAAiB;AACjB,wBAAgB,YAAY,IAAI,SAAS,CAKxC;AAED,sBAAsB;AACtB,wBAAsB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE;IAC3C,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,eAAe,CAAC;CACvB,GAAG,OAAO,CAAC,CAAC,CAAC,CAIb;AAED,kBAAkB;AAClB,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,eAAe,CAAC;CACvB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAI7B;AAED,kBAAkB;AAClB,wBAAsB,WAAW,CAAC,MAAM,EAAE;IACxC,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,eAAe,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIlB;AAMD,eAAe;AACf,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,eAAe;AACf,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnF"}

package/bin/city/http.js

@@ -0,0 +1,78 @@
+/**
+ * Client 包 HTTP 基础设施。
+ *
+ * 集中处理 fetch 封装、URL 规范化、服务路径等共享工具。
+ * 同时包含 HTTP 层的公共类型。
+ */
+// ===========================================================================
+// URL 与校验
+// ===========================================================================
+/** 去掉 server URL 末尾多余斜杠 */
+export function normalizeBaseURL(value, label) {
+    const url = requiredString(value, label);
+    return url.replace(/\/+$/, "");
+}
+/** 校验必填字符串 */
+export function requiredString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+// ===========================================================================
+// fetch 封装
+// ===========================================================================
+/** 读取全局 fetch */
+export function defaultFetch() {
+    if (typeof globalThis.fetch !== "function") {
+        throw new Error("fetch is required");
+    }
+    return async (url, init) => globalThis.fetch(url, init);
+}
+/** 发送 JSON 请求并解析响应 */
+export async function requestJSON(params) {
+    const response = await params.fetch(params.url, params.init);
+    if (!response.ok)
+        throw await httpError(response);
+    return response.json();
+}
+/** 发送请求并返回原始响应 */
+export async function requestRaw(params) {
+    const response = await params.fetch(params.url, params.init);
+    if (!response.ok)
+        throw await httpError(response);
+    return response;
+}
+/** 发送请求并解析文本响应 */
+export async function requestText(params) {
+    const response = await params.fetch(params.url, params.init);
+    if (!response.ok)
+        throw await httpError(response);
+    return response.text();
+}
+// ===========================================================================
+// 服务路径工具
+// ===========================================================================
+/** 标准化服务 ID */
+export function normalizeServiceId(value) {
+    const normalized = String(value ?? "").trim();
+    if (!normalized)
+        throw new TypeError("service id is required");
+    return normalized;
+}
+/** 拼接服务请求路径 */
+export function servicePath(prefix, serviceId, path) {
+    const suffix = String(path ?? "").trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    return suffix ? `${prefix}/${serviceId}/${suffix}` : `${prefix}/${serviceId}`;
+}
+// ===========================================================================
+// 内部
+// ===========================================================================
+async function httpError(response) {
+    const body = await response.text();
+    const error = new Error(`Downcity request failed with ${response.status}: ${body}`);
+    error.status = response.status;
+    error.body = body;
+    return error;
+}
+//# sourceMappingURL=http.js.map

package/bin/city/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/city/http.ts"],"names":[],"mappings":"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"}