@harrylabsj/kiwi 0.8.0 → 0.9.0

package/dist/merchant-gateway/catalog-publications.js

@@ -0,0 +1,175 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 商家连接器入口 → kiwi-catalog 商家公开资料客户端（写侧，凭据为 `cmt_…`）。
+ *
+ *   POST {base}/v1/merchant-publications                （action=draft|publish）
+ *   GET  {base}/v1/merchant-publications/{id}
+ *   POST {base}/v1/merchant-publications/{id}/withdraw
+ *
+ * 契约来源：kiwi-catalog 仓 kiwi_catalog/services/merchant_publications.py 的
+ * validate_payload / public_projection（schema v29+，M0 工作包 A）。
+ *
+ * 硬边界：
+ *   - merchant_id 由目录按凭据绑定决定，**客户端永远不传**；
+ *   - 本客户端只把 `action=draft` 用于常规保存；`publish` 只应由商家在门户
+ *     确认页触发（入口不替商家确认，见第 1 版设计 §3.3 / §4 执行控制）；
+ *   - 出站加固与既有 catalog 客户端一致：不跟随重定向、超时、响应字段校验。
+ */
+import { PRODUCT_VERSION } from "../product-cli.js";
+import { isRedirectResponse, readJsonBody } from "../net/safe-http.js";
+import { CatalogSourceError } from "../discovery/catalog-source/errors.js";
+import { validateBaseUrl } from "../discovery/catalog-source/source.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+function asRecord(value, field) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new CatalogSourceError("response_invalid", `merchant-publications response is missing object field "${field}"`);
+    }
+    return value;
+}
+function asString(record, field) {
+    return typeof record[field] === "string" ? record[field] : "";
+}
+function toPublication(value) {
+    const record = asRecord(value, "publication");
+    const faq = Array.isArray(record.faq)
+        ? record.faq.map((item) => {
+            const entry = asRecord(item, "publication.faq[]");
+            return { question: asString(entry, "question"), answer: asString(entry, "answer") };
+        })
+        : [];
+    const publicationId = asString(record, "publication_id");
+    const merchantId = asString(record, "merchant_id");
+    if (publicationId === "" || merchantId === "") {
+        throw new CatalogSourceError("response_invalid", "merchant-publications response is missing publication_id or merchant_id");
+    }
+    if (record.inquiry_available !== false) {
+        // 第 0 版公开资料恒不可实时询价；为 true 视为协议级违规（不得向上传播）。
+        throw new CatalogSourceError("contract_violation", "merchant-publications projected inquiry_available must be false");
+    }
+    return {
+        publication_id: publicationId,
+        merchant_id: merchantId,
+        merchant_display_name: asString(record, "merchant_display_name"),
+        title: asString(record, "title"),
+        category: asString(record, "category"),
+        summary: asString(record, "summary"),
+        shop_platform: asString(record, "shop_platform"),
+        shop_url: asString(record, "shop_url"),
+        faq,
+        source_kind: asString(record, "source_kind"),
+        status: asString(record, "status"),
+        version: typeof record.version === "number" ? record.version : 0,
+        published_at: asString(record, "published_at"),
+        expires_at: asString(record, "expires_at"),
+        updated_at: asString(record, "updated_at"),
+        inquiry_available: false,
+    };
+}
+export class MerchantPublicationClient {
+    baseUrl;
+    deps;
+    constructor(deps) {
+        this.baseUrl = validateBaseUrl(deps.baseUrl);
+        this.deps = deps;
+    }
+    /** 保存草稿（action=draft；发布不由入口执行）。 */
+    async saveDraft(token, input) {
+        const body = await this.request(token, "POST", "/v1/merchant-publications", {
+            action: "draft",
+            merchant_display_name: input.merchantDisplayName,
+            title: input.title,
+            ...(input.category !== undefined ? { category: input.category } : {}),
+            ...(input.summary !== undefined ? { summary: input.summary } : {}),
+            ...(input.shopPlatform !== undefined ? { shop_platform: input.shopPlatform } : {}),
+            ...(input.shopUrl !== undefined ? { shop_url: input.shopUrl } : {}),
+            ...(input.faq !== undefined ? { faq: input.faq } : {}),
+            ...(input.expiresAt !== undefined ? { expires_at: input.expiresAt } : {}),
+        });
+        return {
+            publication: toPublication(body.publication),
+            created: body.created === true,
+            idempotent: body.idempotent === true,
+        };
+    }
+    async getPublication(token, publicationId) {
+        const body = await this.request(token, "GET", `/v1/merchant-publications/${encodeURIComponent(publicationId)}`);
+        return toPublication(body.publication);
+    }
+    async withdraw(token, publicationId) {
+        const body = await this.request(token, "POST", `/v1/merchant-publications/${encodeURIComponent(publicationId)}/withdraw`, {});
+        return toPublication(body.publication);
+    }
+    async request(token, method, path, body) {
+        if (typeof token !== "string" || token.trim() === "") {
+            throw new CatalogSourceError("invalid_input", "merchant publication request requires a merchant credential");
+        }
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        let raw;
+        try {
+            try {
+                response = await fetchImpl(url, {
+                    method,
+                    redirect: "manual",
+                    signal: controller.signal,
+                    headers: {
+                        accept: "application/json",
+                        ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                        authorization: `Bearer ${token}`,
+                        "user-agent": `kiwi-merchant-entry/${PRODUCT_VERSION}`,
+                    },
+                    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                });
+            }
+            catch (err) {
+                const name = err?.name;
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new CatalogSourceError("request_failed", name === "AbortError"
+                    ? `kiwi-catalog merchant request timed out after ${timeoutMs}ms: ${url}`
+                    : `kiwi-catalog merchant request failed: ${url} (${detail})`);
+            }
+            if (isRedirectResponse(response)) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog merchant request must not follow redirects (HTTP ${response.status} from ${url})`);
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new CatalogSourceError("session_rejected", `kiwi-catalog rejected the merchant credential (HTTP ${response.status} from ${url})`);
+            }
+            if (!response.ok) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog merchant request returned HTTP ${response.status} from ${url}`);
+            }
+            try {
+                raw = await readJsonBody(response, { signal: controller.signal });
+            }
+            catch {
+                throw new CatalogSourceError("response_invalid", `kiwi-catalog merchant response from ${url} is not valid JSON`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const envelope = asRecord(raw, "envelope");
+        if (envelope.ok !== true) {
+            throw new CatalogSourceError("response_invalid", `merchant-publications response is not ok: ${typeof envelope.error === "string" ? envelope.error : "unknown error"}`);
+        }
+        return envelope;
+    }
+}
+//# sourceMappingURL=catalog-publications.js.map

package/dist/merchant-gateway/catalog-publications.js.map

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

package/dist/merchant-gateway/catalog-tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 商家连接器第 0 版目录工具（`kiwi_catalog_*`）。
+ *
+ * merchant-buddy 第 1 版设计 §3.3 / §4 执行控制与商家连接器发布计划 §3.2：
+ * - 商家身份来自**已验证的 OAuth 主体**（`merchantId` 由入口从访问令牌解析，
+ *   绝不来自工具参数）；目录凭据按该 merchant_id 从保管库取；
+ * - 草稿是私有状态；`request_publish` **不写入 published**，只保存草稿并给出
+ *   目录门户的确认入口——发布必须由商家本人在门户确认页批准；
+ * - 无凭据/凭据失效时工具明确报「需要重新连接」，不返回过期数据。
+ */
+import type { ScopedMcpTools } from "../mcp/merchant-server.js";
+import type { MerchantPublicationClient } from "./catalog-publications.js";
+import type { MerchantCredentialStore } from "./credential-vault.js";
+/** 工具所需 scope（读/写两类；与目录凭据 scope 同名）。 */
+export declare function catalogToolScope(name: string): "catalog:read" | "catalog:write";
+export interface CatalogToolDeps {
+    client: MerchantPublicationClient;
+    credentials: MerchantCredentialStore;
+    /** 目录门户地址（发布确认入口）。 */
+    portalBaseUrl: string;
+    toolOptions?: {
+        maxChars?: number;
+    };
+}
+/**
+ * 构建绑定到某个已验证商家的目录工具束。
+ *
+ * `merchantId` 必须来自 OAuth 访问令牌（入口解析），不能来自工具入参——
+ * 这是第 0 版商家之间隔离的唯一依据。
+ */
+export declare function buildCatalogTools(merchantId: string, deps: CatalogToolDeps): ScopedMcpTools;

package/dist/merchant-gateway/catalog-tools.js

@@ -0,0 +1,277 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { CatalogSourceError } from "../discovery/catalog-source/errors.js";
+import { trimTrailingSlashes } from "../net/url.js";
+const READ_TOOLS = new Set([
+    "kiwi_catalog_get_merchant_profile",
+    "kiwi_catalog_get_publication_status",
+]);
+const WRITE_TOOLS = new Set([
+    "kiwi_catalog_save_publication_draft",
+    "kiwi_catalog_request_publish",
+    "kiwi_catalog_withdraw_publication",
+]);
+/** 工具所需 scope（读/写两类；与目录凭据 scope 同名）。 */
+export function catalogToolScope(name) {
+    return WRITE_TOOLS.has(name) ? "catalog:write" : "catalog:read";
+}
+const DISPLAY_NAME_PARAM = { type: "string", description: "公开商家名称（买家可见）" };
+const TITLE_PARAM = { type: "string", description: "商品名（买家通过它搜索到你）" };
+const PUBLICATION_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        merchant_display_name: DISPLAY_NAME_PARAM,
+        title: TITLE_PARAM,
+        category: { type: "string", description: "类目（选填）" },
+        summary: { type: "string", description: "公开简介（选填，买家可见）" },
+        shop_platform: { type: "string", description: "店铺平台（选填，如 淘宝/京东）" },
+        shop_url: { type: "string", description: "公开店铺链接（选填，http/https）" },
+        faq: {
+            type: "array",
+            description: "公开 FAQ（选填；每项 question/answer，不得含电话或邮箱）",
+            items: {
+                type: "object",
+                properties: {
+                    question: { type: "string" },
+                    answer: { type: "string" },
+                },
+                required: ["question", "answer"],
+                additionalProperties: false,
+            },
+        },
+        expires_at: {
+            type: "string",
+            description: "资料有效期（选填，ISO 时间；到期后不再出现在搜索中）",
+        },
+    },
+    required: ["merchant_display_name", "title"],
+    additionalProperties: false,
+};
+const PUBLICATION_ID_SCHEMA = {
+    type: "object",
+    properties: {
+        publication_id: { type: "string", description: "公开资料 id（发布回执中的 publication_id）" },
+    },
+    required: ["publication_id"],
+    additionalProperties: false,
+};
+const DEFAULT_MAX_CHARS = 8_000;
+function ok(payload, maxChars) {
+    const text = JSON.stringify(payload);
+    return {
+        content: [
+            {
+                type: "text",
+                text: text.length > maxChars ? `${text.slice(0, maxChars)}…（结果已截断）` : text,
+            },
+        ],
+    };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function readString(args, field) {
+    const value = args[field];
+    return typeof value === "string" ? value.trim() : "";
+}
+function readFaq(args) {
+    const raw = args.faq;
+    if (!Array.isArray(raw))
+        return [];
+    const items = [];
+    for (const element of raw) {
+        if (element === null || typeof element !== "object")
+            continue;
+        const question = readString(element, "question");
+        const answer = readString(element, "answer");
+        if (question !== "" && answer !== "")
+            items.push({ question, answer });
+    }
+    return items;
+}
+/**
+ * 构建绑定到某个已验证商家的目录工具束。
+ *
+ * `merchantId` 必须来自 OAuth 访问令牌（入口解析），不能来自工具入参——
+ * 这是第 0 版商家之间隔离的唯一依据。
+ */
+export function buildCatalogTools(merchantId, deps) {
+    const maxChars = deps.toolOptions?.maxChars ?? DEFAULT_MAX_CHARS;
+    const portalUrl = `${trimTrailingSlashes(deps.portalBaseUrl)}/portal/publications`;
+    const credential = () => {
+        const stored = deps.credentials.get(merchantId);
+        if (stored === undefined) {
+            throw new CatalogSourceError("session_rejected", "目录凭据不可用（未连接或已过期）：请重新连接「Kiwi 商家运营」，然后在 Buddy 中重试");
+        }
+        return stored.token;
+    };
+    const credentialExpiry = () => {
+        const stored = deps.credentials.get(merchantId);
+        return stored?.expiresAt ?? "";
+    };
+    const draftInput = (args) => {
+        const merchantDisplayName = readString(args, "merchant_display_name");
+        const title = readString(args, "title");
+        const category = readString(args, "category");
+        const summary = readString(args, "summary");
+        const shopPlatform = readString(args, "shop_platform");
+        const shopUrl = readString(args, "shop_url");
+        const expiresAt = readString(args, "expires_at");
+        const faq = readFaq(args);
+        return {
+            merchantDisplayName,
+            title,
+            ...(category !== "" ? { category } : {}),
+            ...(summary !== "" ? { summary } : {}),
+            ...(shopPlatform !== "" ? { shopPlatform } : {}),
+            ...(shopUrl !== "" ? { shopUrl } : {}),
+            ...(faq.length > 0 ? { faq } : {}),
+            ...(expiresAt !== "" ? { expiresAt } : {}),
+        };
+    };
+    const handlers = {
+        kiwi_catalog_get_merchant_profile: async () => {
+            const stored = deps.credentials.get(merchantId);
+            return ok({
+                merchant_id: merchantId,
+                connected: stored !== undefined,
+                credential_expires_at: credentialExpiry(),
+                portal_url: portalUrl,
+                note: stored === undefined
+                    ? "尚未连接或凭据已过期：请重新连接「Kiwi 商家运营」后再管理公开资料。"
+                    : "公开资料为商家声明快照（买家看到「资料可查」，不可实时询价）；发布须在目录门户确认页批准。",
+            }, maxChars);
+        },
+        kiwi_catalog_save_publication_draft: async (args) => {
+            const input = draftInput(args);
+            if (input.merchantDisplayName === "" || input.title === "") {
+                return fail("缺少必填字段：merchant_display_name 与 title 都是必填");
+            }
+            const result = await deps.client.saveDraft(credential(), input);
+            return ok({
+                publication_id: result.publication.publication_id,
+                merchant_id: result.publication.merchant_id,
+                title: result.publication.title,
+                status: result.publication.status,
+                version: result.publication.version,
+                created: result.created,
+                updated: result.idempotent,
+                confirm_url: portalUrl,
+                note: "已保存为私有草稿（未公开，采购专家搜索不到）。发布需你在目录门户的公开资料页确认。",
+            }, maxChars);
+        },
+        kiwi_catalog_request_publish: async (args) => {
+            const input = draftInput(args);
+            if (input.merchantDisplayName === "" || input.title === "") {
+                return fail("缺少必填字段：merchant_display_name 与 title 都是必填");
+            }
+            const result = await deps.client.saveDraft(credential(), input);
+            return ok({
+                publication_id: result.publication.publication_id,
+                status: result.publication.status,
+                version: result.publication.version,
+                confirm_url: portalUrl,
+                note: "草稿已保存，但**尚未发布**：请在目录门户的公开资料页核对公开预览并点击确认发布。" +
+                    "确认前采购专家搜索不到该商品。",
+            }, maxChars);
+        },
+        kiwi_catalog_get_publication_status: async (args) => {
+            const publicationId = readString(args, "publication_id");
+            if (publicationId === "")
+                return fail("缺少 publication_id");
+            const publication = await deps.client.getPublication(credential(), publicationId);
+            return ok({
+                publication_id: publication.publication_id,
+                merchant_id: publication.merchant_id,
+                title: publication.title,
+                status: publication.status,
+                version: publication.version,
+                published_at: publication.published_at,
+                updated_at: publication.updated_at,
+                expires_at: publication.expires_at,
+                inquiry_available: publication.inquiry_available,
+            }, maxChars);
+        },
+        kiwi_catalog_withdraw_publication: async (args) => {
+            const publicationId = readString(args, "publication_id");
+            if (publicationId === "")
+                return fail("缺少 publication_id");
+            const publication = await deps.client.withdraw(credential(), publicationId);
+            return ok({
+                publication_id: publication.publication_id,
+                status: publication.status,
+                version: publication.version,
+                note: "已撤回：该资料不再出现在采购专家的正常搜索中。",
+            }, maxChars);
+        },
+    };
+    const tools = [
+        {
+            name: "kiwi_catalog_get_merchant_profile",
+            description: "读取当前已连接商家的目录身份与连接状态（只读）。返回 merchant_id、目录凭据是否可用，以及公开资料管理入口地址。",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        },
+        {
+            name: "kiwi_catalog_save_publication_draft",
+            description: "保存商家公开资料草稿（私有，不公开）。必填 merchant_display_name 与 title；类目/简介/店铺链接/FAQ/有效期选填。" +
+                "草稿不会出现在采购专家搜索结果中；公开前置请用 kiwi_catalog_request_publish。不得填写电话、邮箱等联系方式（会被目录拒绝）。",
+            inputSchema: PUBLICATION_INPUT_SCHEMA,
+        },
+        {
+            name: "kiwi_catalog_request_publish",
+            description: "准备发布公开资料：保存草稿并返回目录门户的确认入口。**本工具不会把资料变成已发布**——必须由商家本人在门户核对公开预览并确认发布后才生效。",
+            inputSchema: PUBLICATION_INPUT_SCHEMA,
+        },
+        {
+            name: "kiwi_catalog_get_publication_status",
+            description: "按 publication_id 查询公开资料状态（draft/published/withdrawn）、版本与更新时间。第 0 版资料恒为不可实时询价（inquiry_available=false）。",
+            inputSchema: PUBLICATION_ID_SCHEMA,
+        },
+        {
+            name: "kiwi_catalog_withdraw_publication",
+            description: "撤回已发布的公开资料（终态）：撤回后不再出现在采购专家搜索结果中。撤回不会删除账号或历史版本。",
+            inputSchema: PUBLICATION_ID_SCHEMA,
+        },
+    ];
+    return {
+        listTools: (scopes) => tools.filter((tool) => {
+            if (scopes === undefined)
+                return true;
+            return scopes.includes(catalogToolScope(tool.name));
+        }),
+        call: async (name, args, scopes) => {
+            const handler = handlers[name];
+            if (handler === undefined) {
+                return fail(`未知工具：${name}`);
+            }
+            const required = catalogToolScope(name);
+            if (scopes !== undefined && !scopes.includes(required)) {
+                return fail(`scope 不足：${name} 需要 ${required}，请重新连接并授予该权限`);
+            }
+            if (!READ_TOOLS.has(name) && !WRITE_TOOLS.has(name)) {
+                return fail(`工具未注册：${name}`);
+            }
+            try {
+                return await handler(args);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return fail(`目录操作失败：${message}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=catalog-tools.js.map

package/dist/merchant-gateway/catalog-tools.js.map

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

package/dist/merchant-gateway/cli.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** 默认商家连接器 source（平台唯一性待核验；核验后按此处替换即可）。 */
+export declare const DEFAULT_MERCHANT_CONNECTOR_SOURCE = "kiwi-merchant";
+export interface GatewayServeOptions {
+    publicUrl?: string;
+    catalogUrl: string;
+    source: string;
+    host: string;
+    port: number;
+    mcpPath: string;
+    dataDir: string;
+    connectorTokenEnv: string;
+    credentialKeyEnv: string;
+    tlsCertPath?: string;
+    tlsKeyPath?: string;
+    trustedProxy: boolean;
+    allowLoopbackCallback: boolean;
+    callbackUri?: string;
+    checkOnly: boolean;
+    portalBaseUrl?: string;
+    /** 运维提供的租户（实例）配置 JSON 文件；缺省表示尚无商家配对实例。 */
+    tenantConfigPath?: string;
+}
+export declare function defaultGatewayDataDir(cwd?: string): string;
+/** 解析 `kiwi merchant gateway serve` 的原始 flag（含 `--check`）。 */
+export declare function parseGatewayServeArgs(args: string[], env?: Record<string, string | undefined>): GatewayServeOptions;
+export interface GatewayServeReadiness {
+    /** 公网入口（OAuth issuer / 连接回跳基准）。 */
+    publicUrl: string;
+    /** 生效的 OAuth 回调地址（source 派生或显式配置）。 */
+    callbackUri: string;
+    /** 由本进程终止 TLS。 */
+    directTls: boolean;
+    /** 监听非 loopback（依赖直接 TLS 或受信反向代理）。 */
+    nonLoopback: boolean;
+    /** 依赖加密存储的功能是否启用（缺密钥即 false）。 */
+    encryptedFeaturesEnabled: boolean;
+    /** 已注册（已配对）的商家实例数量；0 表示第 1 版路由未启用。 */
+    registeredInstances: number;
+    connectorTokenConfigured: boolean;
+    warnings: string[];
+}
+export type GatewayServeValidation = {
+    ok: true;
+    readiness: GatewayServeReadiness;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 启动前校验（fail-closed）。纯函数，便于测试与 `--check` 复用。
+ *
+ * 规则：
+ *   - `--public-url` 必填，且 https（loopback http 仅限本地开发）；
+ *   - 监听非 loopback 必须给出 TLS 材料，或显式 `--trusted-proxy`；
+ *   - TLS 证书与私钥必须成对；
+ *   - connector token 必须已配置（缺少则入口无法建立商家身份，直接拒绝启动）；
+ *   - 凭据加密密钥缺失**不**拒绝启动，但关闭依赖加密存储的功能并给出警告。
+ */
+export declare function validateGatewayServeOptions(opts: GatewayServeOptions, env?: Record<string, string | undefined>): GatewayServeValidation;
+export declare function runGatewayServe(args: string[], env?: Record<string, string | undefined>): Promise<number>;