@downcity/city 0.2.200 → 0.2.211

package/README.md

@@ -6,7 +6,7 @@
 
 - 挂载 `Service` / `AIService`
 - 初始化内置 `cities` / `env` 表
-- 校验 `user_token` 和 `admin_secret_key`
+- 校验 `user_token`、`bureau_token` 和控制面凭证
 - 暴露统一的 `/v1/*` HTTP 路由
 - 提供 env、数据库、hook 和鉴权上下文
 
@@ -114,7 +114,7 @@ console.log(text);
 GET /v1/federation/instruction
 ```
 
-这个接口只允许 `admin_secret_key` 访问，返回 `text/plain`。
+这个接口只允许携带 Federation `admin_secret_key` 的控制面请求访问，返回 `text/plain`。
 
 ## Service
 
@@ -149,19 +149,37 @@ City 会自动映射为：
 `AIService` 负责模型目录和模态路由：
 
 ```ts
-import { AIService, Provider } from "@downcity/city";
+import {
+  AIChannel,
+  AIService,
+  type AIChannelStreamInput,
+  type LanguageModelV3StreamResult,
+} from "@downcity/city";
+
+class DeepSeekChannel extends AIChannel {
+  constructor() {
+    super({
+      id: "deepseek",
+      base_url: "https://api.deepseek.com/v1",
+      env_key: "DEEPSEEK_API_KEY",
+      ai_sdk_provider_id: "deepseek",
+    });
+  }
 
-const deepseek = new Provider("deepseek", {
-  baseURL: "https://api.deepseek.com/v1",
-  envKey: "DEEPSEEK_API_KEY",
-  text: myTextAction,
-  stream: myStreamAction,
-});
+  protected stream(
+    input: AIChannelStreamInput,
+  ): Promise<LanguageModelV3StreamResult> {
+    return myStreamAction(input);
+  }
+}
+
+const deepseek = new DeepSeekChannel();
 
 const ai = new AIService();
 ai.use(
   deepseek.model({
     id: "deepseek-v4-flash",
+    upstream_model: "deepseek-chat",
     name: "DeepSeek V4 Flash",
     context_window: 128_000,
   }),
@@ -190,10 +208,67 @@ base.use(usageService());
 ## 鉴权语义
 
 - 默认 action 需要 `user_token`
-- `auth: ["admin"]` 只允许 `admin_secret_key`
+- `auth: ["admin"]` 只允许携带 Federation `admin_secret_key` 的控制面请求
 - `auth: []` 表示免登录
 
-对于用户侧请求，`user_token` 绑定 city 身份。如果请求体或 query 中传了 `city_id`，它必须与 token 里的 city 一致。
+Federation 首次启动会自动生成并持久化 Ed25519 Key Ring。私钥只用于 Federation
+签发 `user_token`，公开公钥通过以下接口发布：
+
+```text
+GET /.well-known/downcity.json
+GET /.well-known/jwks.json
+```
+
+用户侧 `City` 只需要 Federation 地址和登录后获得的 token：
+
+```ts
+const city = new City({
+  federation_url: "https://fed.example.com",
+  user_token,
+});
+
+const profile = await city.user().profile();
+```
+
+`city_id` 由 Federation 验签后从 token 中读取，客户端不再重复传入。
+
+City 直接访问 Federation，不依赖 Bureau。只有产品需要自己的后端能力时，才通过
+`fed bureau token` 登记并部署 Bureau：
+
+```bash
+fed bureau token --city city_product
+```
+
+命令生成的高熵 `bureau_token` 只显示一次，Federation 数据库只保存 hash。将明文
+配置到 Bureau 所在服务器：
+
+```env
+DOWNCITY_FEDERATION_URL=https://fed.example.com
+DOWNCITY_BUREAU_TOKEN=fb_br_xxx.secret
+```
+
+Bureau 获取绑定的 City 上下文与 JWKS，并在本地识别请求身份：
+
+```ts
+const bureau = new Bureau({
+  federation_url: "https://fed.example.com",
+  bureau_token,
+});
+
+const identity = await bureau.identify(request);
+const profile = await (await bureau.user(request)).profile();
+```
+
+Federation 管理控制面使用独立的 `FederationAdmin`：
+
+```ts
+const admin = new FederationAdmin({
+  federation_url: "https://fed.example.com",
+  admin_secret_key,
+});
+
+await admin.bureaus.list();
+```
 
 ## 主要导出
 
@@ -202,10 +277,11 @@ base.use(usageService());
 - `Service`
 - `ServiceDefinition`
 - `AIService`
-- `Provider`
+- `AIChannel`
 - `CityModel`
 - `CityModelDescriptor`
-- `TokenSigner`
+- `Bureau`
+- `FederationAdmin`
 - `EnvService`
 - `CitiesService`
 

package/bin/client/bureau.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bureau 产品后端客户端。
+ *
+ * Bureau 是某个 City 的可选后端入口：启动时使用 Bureau Token 获取自身
+ * City 上下文，运行时使用 Federation 公钥在本地验证 user_token。它不承载
+ * Federation 管理能力，也不会把 user_token 发送到在线 identify 接口。
+ */
+import type { BureauContext, BureauFetch, BureauIdentity, BureauOptions } from "../types/Bureau.js";
+import type { UserProfile } from "../types/User.js";
+/** 已通过本地验签的用户后端会话。 */
+export declare class BureauUser {
+    private readonly federation_url;
+    private readonly user_token;
+    private readonly fetcher;
+    /** 当前用户身份。 */
+    readonly identity: BureauIdentity;
+    constructor(identity: BureauIdentity, federation_url: string, user_token: string, fetcher: BureauFetch);
+    /** 在线读取 Federation 当前用户 Profile。 */
+    profile(): Promise<UserProfile | null>;
+}
+/** Bureau 产品后端客户端。 */
+export declare class Bureau {
+    /** 当前 Bureau 绑定的 City ID；首次读取上下文后可用。 */
+    get city_id(): string | undefined;
+    private readonly federation_url;
+    private readonly bureau_token;
+    private readonly fetcher;
+    private readonly cache_ttl;
+    private cache?;
+    private refresh_promise?;
+    constructor(options: BureauOptions);
+    /** 获取当前 Bureau 在 Federation 中注册的可信 City 上下文。 */
+    context(): Promise<BureauContext>;
+    /** 从 HTTP Request 或 user_token 中本地识别 Federation 用户。 */
+    identify(input: Request | string): Promise<BureauIdentity>;
+    /** 验证请求并创建一个可读取 Federation 用户数据的会话。 */
+    user(input: Request | string): Promise<BureauUser>;
+    private get_cache;
+    private refresh_cache;
+}
+//# sourceMappingURL=bureau.d.ts.map

package/bin/client/bureau.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bureau.d.ts","sourceRoot":"","sources":["../../src/client/bureau.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAsBpD,sBAAsB;AACtB,qBAAa,UAAU;IAMnB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,cAAc;IACd,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;gBAGhC,QAAQ,EAAE,cAAc,EACP,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW;IAKvC,oCAAoC;IAC9B,OAAO,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAW7C;AAED,sBAAsB;AACtB,qBAAa,MAAM;IACjB,wCAAwC;IACxC,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,KAAK,CAAC,CAAc;IAC5B,OAAO,CAAC,eAAe,CAAC,CAAuB;gBAEnC,OAAO,EAAE,aAAa;IAUlC,gDAAgD;IAC1C,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IAKvC,uDAAuD;IACjD,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAmChE,uCAAuC;IACjC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;YAM1C,SAAS;YAUT,aAAa;CAgC5B"}

package/bin/client/bureau.js

@@ -0,0 +1,240 @@
+/**
+ * Bureau 产品后端客户端。
+ *
+ * Bureau 是某个 City 的可选后端入口：启动时使用 Bureau Token 获取自身
+ * City 上下文，运行时使用 Federation 公钥在本地验证 user_token。它不承载
+ * Federation 管理能力，也不会把 user_token 发送到在线 identify 接口。
+ */
+import { decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { httpError } from "../utils/helpers.js";
+import { USER_TOKEN_ALGORITHM } from "../federation/auth/federation-key-store.js";
+import { normalize_user_token, read_user_token_payload } from "../federation/auth/user-token-authority.js";
+const DEFAULT_CACHE_TTL = 5 * 60 * 1000;
+/** 已通过本地验签的用户后端会话。 */
+export class BureauUser {
+    federation_url;
+    user_token;
+    fetcher;
+    /** 当前用户身份。 */
+    identity;
+    constructor(identity, federation_url, user_token, fetcher) {
+        this.federation_url = federation_url;
+        this.user_token = user_token;
+        this.fetcher = fetcher;
+        this.identity = identity;
+    }
+    /** 在线读取 Federation 当前用户 Profile。 */
+    async profile() {
+        const response = await this.fetcher(`${this.federation_url}/v1/accounts/me`, {
+            method: "GET",
+            headers: { authorization: `Bearer ${this.user_token}` },
+        });
+        if (!response.ok) {
+            throw httpError(response.status, "Federation user profile unavailable");
+        }
+        const body = await response.json();
+        return body.profile ?? null;
+    }
+}
+/** Bureau 产品后端客户端。 */
+export class Bureau {
+    /** 当前 Bureau 绑定的 City ID；首次读取上下文后可用。 */
+    get city_id() {
+        return this.cache?.context.city_id;
+    }
+    federation_url;
+    bureau_token;
+    fetcher;
+    cache_ttl;
+    cache;
+    refresh_promise;
+    constructor(options) {
+        if (!options || typeof options !== "object") {
+            throw new TypeError("Bureau options are required");
+        }
+        this.federation_url = normalize_federation_url(options.federation_url);
+        this.bureau_token = read_required_string(options.bureau_token, "bureau_token");
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.cache_ttl = read_cache_ttl(options.jwks_cache_ttl);
+    }
+    /** 获取当前 Bureau 在 Federation 中注册的可信 City 上下文。 */
+    async context() {
+        const context = (await this.get_cache(false)).context;
+        return { ...context, capabilities: [...context.capabilities] };
+    }
+    /** 从 HTTP Request 或 user_token 中本地识别 Federation 用户。 */
+    async identify(input) {
+        const user_token = typeof input === "string" ? read_token_string(input) : read_request_token(input);
+        const normalized_token = normalize_user_token(user_token);
+        let cache = await this.get_cache(false);
+        let key = find_jwk(cache.jwks, normalized_token);
+        if (!key) {
+            cache = await this.get_cache(true);
+            key = find_jwk(cache.jwks, normalized_token);
+        }
+        if (!key)
+            throw httpError(401, "Unknown token signing key");
+        try {
+            const public_key = await importJWK(key, USER_TOKEN_ALGORITHM);
+            const result = await jwtVerify(normalized_token, public_key, {
+                algorithms: [USER_TOKEN_ALGORITHM],
+                audience: cache.discovery.user_token_audience,
+                issuer: cache.discovery.issuer,
+            });
+            const payload = read_user_token_payload(result.payload);
+            if (payload.city_id !== cache.context.city_id) {
+                throw httpError(403, "Token does not belong to this City");
+            }
+            return {
+                user_id: payload.user_id,
+                city_id: payload.city_id,
+                metadata: payload.metadata ?? {},
+                token_id: payload.jti,
+                expires_at: payload.exp,
+            };
+        }
+        catch (error) {
+            if (is_http_error(error))
+                throw error;
+            throw map_identify_error(error);
+        }
+    }
+    /** 验证请求并创建一个可读取 Federation 用户数据的会话。 */
+    async user(input) {
+        const user_token = typeof input === "string" ? read_token_string(input) : read_request_token(input);
+        const identity = await this.identify(user_token);
+        return new BureauUser(identity, this.federation_url, user_token, this.fetcher);
+    }
+    async get_cache(force_refresh) {
+        if (!force_refresh && this.cache && this.cache.expires_at > Date.now())
+            return this.cache;
+        if (!this.refresh_promise) {
+            this.refresh_promise = this.refresh_cache().finally(() => {
+                this.refresh_promise = undefined;
+            });
+        }
+        return this.refresh_promise;
+    }
+    async refresh_cache() {
+        const discovery = await read_json(this.fetcher, `${this.federation_url}/.well-known/downcity.json`, "Federation discovery unavailable");
+        validate_discovery(discovery, this.federation_url);
+        const [jwks, context] = await Promise.all([
+            read_json(this.fetcher, discovery.jwks_uri, "Federation signing keys unavailable"),
+            read_json(this.fetcher, `${this.federation_url}/v1/bureaus/context`, "Bureau context unavailable", { authorization: `Bearer ${this.bureau_token}` }),
+        ]);
+        validate_jwks(jwks);
+        validate_context(context);
+        const cache = {
+            discovery,
+            jwks,
+            context,
+            expires_at: Date.now() + this.cache_ttl,
+        };
+        this.cache = cache;
+        return cache;
+    }
+}
+function find_jwk(jwks, jwt) {
+    const header = decodeProtectedHeader(jwt);
+    if (header.alg !== USER_TOKEN_ALGORITHM)
+        throw httpError(401, "Invalid user token algorithm");
+    const key_id = typeof header.kid === "string" ? header.kid : "";
+    if (!key_id)
+        throw httpError(401, "Unknown token signing key");
+    return jwks.keys.find((key) => key.kid === key_id);
+}
+function read_request_token(request) {
+    const authorization = request.headers.get("authorization") ?? "";
+    if (!authorization.startsWith("Bearer "))
+        throw httpError(401, "Authentication required");
+    return read_required_string(authorization.slice("Bearer ".length), "user_token");
+}
+function read_token_string(value) {
+    const token = value.trim();
+    return read_required_string(token.startsWith("Bearer ") ? token.slice("Bearer ".length) : token, "user_token");
+}
+function normalize_federation_url(value) {
+    const input = read_required_string(value, "federation_url").replace(/\/+$/, "");
+    const url = new URL(input);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new TypeError("federation_url must use http or https");
+    }
+    if (url.username || url.password)
+        throw new TypeError("federation_url must not contain credentials");
+    return input;
+}
+function validate_discovery(discovery, federation_url) {
+    if (!discovery || typeof discovery !== "object")
+        throw httpError(503, "Federation discovery unavailable");
+    read_required_string(discovery.issuer, "Federation issuer");
+    if (discovery.user_token_audience !== "downcity:user")
+        throw httpError(503, "Invalid Federation user token audience");
+    const expected = new URL(`${federation_url}/.well-known/jwks.json`);
+    const actual = new URL(discovery.jwks_uri);
+    if (actual.origin !== expected.origin || actual.pathname !== expected.pathname) {
+        throw httpError(503, "Invalid Federation JWKS location");
+    }
+}
+function validate_jwks(jwks) {
+    if (!jwks || !Array.isArray(jwks.keys))
+        throw httpError(503, "Federation signing keys unavailable");
+    for (const key of jwks.keys) {
+        if (key.kty !== "OKP" || key.crv !== "Ed25519" || key.alg !== USER_TOKEN_ALGORITHM
+            || key.use !== "sig" || typeof key.kid !== "string" || typeof key.x !== "string") {
+            throw httpError(503, "Invalid Federation signing key");
+        }
+        if ("d" in key)
+            throw httpError(503, "Federation JWKS exposed a private key");
+    }
+}
+function validate_context(context) {
+    if (!context || typeof context !== "object")
+        throw httpError(503, "Bureau context unavailable");
+    read_required_string(context.token_id, "Bureau token_id");
+    read_required_string(context.city_id, "Bureau city_id");
+    if (!Array.isArray(context.capabilities))
+        throw httpError(503, "Invalid Bureau capabilities");
+}
+async function read_json(fetcher, url, error_message, extra_headers = {}) {
+    let response;
+    try {
+        response = await fetcher(url, { headers: { accept: "application/json", ...extra_headers } });
+    }
+    catch {
+        throw httpError(503, error_message);
+    }
+    if (!response.ok)
+        throw httpError(response.status === 401 ? 401 : 503, error_message);
+    try {
+        return await response.json();
+    }
+    catch {
+        throw httpError(503, error_message);
+    }
+}
+function read_required_string(value, name) {
+    if (typeof value !== "string" || !value.trim())
+        throw new TypeError(`${name} must be a non-empty string`);
+    return value.trim();
+}
+function read_cache_ttl(value) {
+    if (value === undefined)
+        return DEFAULT_CACHE_TTL;
+    if (!Number.isFinite(value) || value <= 0)
+        throw new TypeError("jwks_cache_ttl must be a positive number");
+    return value;
+}
+function is_http_error(error) {
+    return error instanceof Error && typeof error.statusCode === "number";
+}
+function map_identify_error(error) {
+    const code = error && typeof error === "object" ? String(error.code ?? "") : "";
+    if (code === "ERR_JWT_EXPIRED")
+        return httpError(401, "User token expired");
+    if (code === "ERR_JWS_SIGNATURE_VERIFICATION_FAILED")
+        return httpError(401, "Invalid user token signature");
+    if (code === "ERR_JWT_CLAIM_VALIDATION_FAILED")
+        return httpError(401, "Invalid user token claims");
+    return httpError(401, "Invalid user token");
+}
+//# sourceMappingURL=bureau.js.map

package/bin/client/bureau.js.map

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

package/bin/client/city.d.ts

@@ -1,90 +1,26 @@
 /**
- * City 客户端统一访问入口。
+ * City 终端用户客户端。
  *
- * City 面向开发者表达“我以某种角色进入 Federation”，内部再委托给
- * admin / user 协议访问层（`pact/`），让用户在第一层概念上无需关心 client 拆分。
+ * City 只持有 Federation 地址与可选 user_token。city_id 由 Federation 在服务端
+ * 验签后从 token 中读取，客户端不能重复声明或覆盖。
  */
-import { AdminPactAccess } from "../pact/admin/index.js";
 import { UserPactAccess } from "../pact/user/index.js";
 import type { ServiceClient } from "../pact/invoker/invoker.js";
-import type { CityOptionsForRole, CityRole } from "./types.js";
-import type { AdminModelRecord, AdminServiceSummary } from "../pact/admin/types.js";
+import type { CityOptions } from "./types.js";
 import type { UserServiceSummary } from "../pact/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 角色的 AI 调用入口。
-     */
+/** Downcity City 用户客户端。 */
+export declare class City {
+    private readonly user_access;
+    constructor(options: CityOptions);
+    /** 用户侧 AI 调用入口。 */
     get ai(): UserPactAccess["ai"];
-    /**
-     * User 角色的支付入口。
-     */
+    /** 用户侧支付入口。 */
     get payment(): UserPactAccess["payment"];
-    /**
-     * Admin 角色的余额服务入口。
-     */
-    get balance(): AdminPactAccess["balance"];
-    /**
-     * Admin 角色的 City 管理入口。
-     */
-    get cities(): AdminPactAccess["cities"];
-    /**
-     * Admin 角色的环境变量服务入口。
-     */
-    get env(): AdminPactAccess["env"];
-    /**
-     * Token 管理入口。
-     *
-     * 不需要传 city_id，构造时传入的 city_id 会自动注入。
-     */
-    get tokens(): {
-        apply: (input: {
-            user_id: string;
-            metadata?: Record<string, unknown>;
-            ttl?: string | number;
-        }) => Promise<{
-            user_token: string;
-            city_id: string;
-            user_id: string;
-            expires_at?: string;
-        }>;
-    };
-    /**
-     * 获取普通 service 调用器。
-     */
+    /** Federation 当前用户数据入口。 */
+    user(): UserPactAccess["user"];
+    /** 获取普通 Service 调用器。 */
     service(name: string): ServiceClient;
-    /**
-     * 列出当前 Federation 暴露的 service。
-     */
-    listServices(): Promise<AdminServiceSummary[] | UserServiceSummary[]>;
-    /**
-     * 列出 Federation 模型目录。
-     */
-    listModels(): Promise<AdminModelRecord[]>;
-    /**
-     * 读取 Federation 聚合说明文档。
-     */
-    instruction(): Promise<string>;
-    private require_admin;
-    private require_user;
+    /** 列出 Federation 暴露的 Service。 */
+    listServices(): Promise<UserServiceSummary[]>;
 }
 //# sourceMappingURL=city.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"city.d.ts","sourceRoot":"","sources":["../../src/client/city.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;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;IAyB9C;;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,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAEtC;IAED;;OAEG;IACH,IAAI,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAEhC;IAED;;;;OAIG;IACH,IAAI,MAAM,IAAI;QAAE,KAAK,EAAE,CAAC,KAAK,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAGzM;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"}
+{"version":3,"file":"city.d.ts","sourceRoot":"","sources":["../../src/client/city.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,2BAA2B;AAC3B,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;gBAEjC,OAAO,EAAE,WAAW;IAWhC,mBAAmB;IACnB,IAAI,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,CAE7B;IAED,eAAe;IACf,IAAI,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAEvC;IAED,2BAA2B;IAC3B,IAAI,IAAI,cAAc,CAAC,MAAM,CAAC;IAI9B,wBAAwB;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAIpC,iCAAiC;IACjC,YAAY,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAG9C"}