@harrylabsj/kiwi 0.8.0 → 0.10.0

package/dist/discovery/catalog-source/connector-identity.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.
+ */
+/** 授权请求（入口持有；login_url 是给商家浏览器打开的地址）。 */
+export interface ConnectorIdentityRequest {
+    readonly requestId: string;
+    readonly loginUrl: string;
+    readonly expiresAt: string;
+}
+/**
+ * 身份兑换时同时签发的商家作用域凭据（目录侧 schema v32）。
+ *
+ * 入口用它代表**该商家**调用目录的商家接口（公开资料草稿/状态/撤回）；发布
+ * 仍须商家在目录门户确认页批准，凭据本身不能把 draft 变成 published。
+ */
+export interface ConnectorMerchantCredential {
+    readonly accessToken: string;
+    readonly scope: string;
+    readonly expiresAt: string;
+}
+/** 兑换结果：已验证的商家身份（唯一可信来源）+ 该商家的作用域凭据。 */
+export interface ConnectorIdentity {
+    readonly merchantId: string;
+    readonly merchantName: string;
+    readonly credential: ConnectorMerchantCredential;
+}
+/**
+ * 入口需要的身份能力。测试与部署可注入不同实现；生产实现是本文件的
+ * HTTP 客户端。
+ */
+export interface CatalogIdentityProvider {
+    createRequest(input: {
+        returnUrl: string;
+        clientLabel?: string;
+    }): Promise<ConnectorIdentityRequest>;
+    exchange(input: {
+        requestId: string;
+        code: string;
+    }): Promise<ConnectorIdentity>;
+}
+export interface CatalogConnectorIdentityDeps {
+    /** Catalog 服务根 URL（http/https）。 */
+    baseUrl: string;
+    /** 连接器机器凭据（catalog 侧 KIWI_CATALOG_CONNECTOR_TOKEN）。 */
+    connectorToken: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare class CatalogConnectorIdentityClient implements CatalogIdentityProvider {
+    private readonly baseUrl;
+    private readonly connectorToken;
+    private readonly deps;
+    constructor(deps: CatalogConnectorIdentityDeps);
+    createRequest(input: {
+        returnUrl: string;
+        clientLabel?: string;
+    }): Promise<ConnectorIdentityRequest>;
+    exchange(input: {
+        requestId: string;
+        code: string;
+    }): Promise<ConnectorIdentity>;
+    private postJson;
+}

package/dist/discovery/catalog-source/connector-identity.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.
+ */
+/**
+ * CatalogConnectorIdentityClient —— kiwi-catalog 一次性身份授权（连接器侧）。
+ *
+ *   POST {baseUrl}/v1/connector-identity/requests
+ *        {return_url, client_label?} → {ok, request:{request_id, expires_at}, login_url}
+ *   POST {baseUrl}/v1/connector-identity/exchange
+ *        {request_id, code}         → {ok, identity:{merchant_id, merchant_name}}
+ *
+ * 契约来源：kiwi-catalog 仓 kiwi_catalog/api/handlers/connector_identity.py
+ * （schema v31；merchant-buddy 第 1 版设计 §3.2 / 商家连接器发布计划 §3.1）。
+ * 调用方是**商家连接器**的远程入口——买方连接器（`kiwi-sourcing`，本地
+ * stdio）不使用本接口。
+ *
+ * 硬边界（fail-closed，调用方不得吞掉错误）：
+ *   - merchant_id 只能来自 exchange 的返回值——绝不从工具参数、URL 或
+ *     客户端自述值推断（商家连接器入口的租户判定唯一来源）；
+ *   - 出站加固与既有 catalog 客户端一致：不跟随重定向（3xx 可能转发凭据）、
+ *     超时、响应大小上限、响应结构逐字段校验。
+ *
+ * connector token（`KIWI_CATALOG_CONNECTOR_TOKEN`）是入口与目录之间的机器
+ * 凭据：它只够创建/兑换一次性授权请求，不能读写任何商家数据（目录侧在
+ * 商家确认前不会为该请求绑定 merchant_id）。
+ */
+import { PRODUCT_VERSION } from "../../product-cli.js";
+import { isRedirectResponse, readJsonBody } from "../../net/safe-http.js";
+import { CatalogSourceError } from "./errors.js";
+import { validateBaseUrl } from "./source.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+function nonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new CatalogSourceError("response_invalid", `connector-identity response is missing non-empty string field "${field}"`);
+    }
+    return value;
+}
+export class CatalogConnectorIdentityClient {
+    baseUrl;
+    connectorToken;
+    deps;
+    constructor(deps) {
+        this.baseUrl = validateBaseUrl(deps.baseUrl);
+        if (typeof deps.connectorToken !== "string" || deps.connectorToken.trim() === "") {
+            throw new CatalogSourceError("invalid_input", "connector-identity client requires a non-empty connector token");
+        }
+        this.connectorToken = deps.connectorToken;
+        this.deps = deps;
+    }
+    async createRequest(input) {
+        const body = await this.postJson("/v1/connector-identity/requests", {
+            return_url: input.returnUrl,
+            ...(input.clientLabel !== undefined ? { client_label: input.clientLabel } : {}),
+        });
+        const request = body.request;
+        if (request === null || typeof request !== "object" || Array.isArray(request)) {
+            throw new CatalogSourceError("response_invalid", 'connector-identity response is missing object field "request"');
+        }
+        const record = request;
+        const loginUrl = nonEmptyString(body.login_url, "login_url");
+        let parsedLoginUrl;
+        try {
+            parsedLoginUrl = new URL(loginUrl);
+        }
+        catch {
+            throw new CatalogSourceError("response_invalid", "connector-identity login_url is not an absolute URL");
+        }
+        if (parsedLoginUrl.protocol !== "https:" && parsedLoginUrl.protocol !== "http:") {
+            throw new CatalogSourceError("response_invalid", `connector-identity login_url must use http or https (got ${parsedLoginUrl.protocol})`);
+        }
+        return {
+            requestId: nonEmptyString(record.request_id, "request.request_id"),
+            loginUrl,
+            expiresAt: nonEmptyString(record.expires_at, "request.expires_at"),
+        };
+    }
+    async exchange(input) {
+        const body = await this.postJson("/v1/connector-identity/exchange", {
+            request_id: input.requestId,
+            code: input.code,
+        });
+        const identity = body.identity;
+        if (identity === null || typeof identity !== "object" || Array.isArray(identity)) {
+            throw new CatalogSourceError("response_invalid", 'connector-identity response is missing object field "identity"');
+        }
+        const record = identity;
+        const credential = body.credential;
+        if (credential === null || typeof credential !== "object" || Array.isArray(credential)) {
+            throw new CatalogSourceError("response_invalid", 'connector-identity response is missing object field "credential"');
+        }
+        const credentialRecord = credential;
+        return {
+            merchantId: nonEmptyString(record.merchant_id, "identity.merchant_id"),
+            // 商家名允许为空字符串（未填名称的账号），不做非空校验。
+            merchantName: typeof record.merchant_name === "string" ? record.merchant_name : "",
+            credential: {
+                accessToken: nonEmptyString(credentialRecord.access_token, "credential.access_token"),
+                scope: typeof credentialRecord.scope === "string" ? credentialRecord.scope : "",
+                expiresAt: nonEmptyString(credentialRecord.expires_at, "credential.expires_at"),
+            },
+        };
+    }
+    async postJson(requestPath, body) {
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${requestPath}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        let raw;
+        try {
+            try {
+                response = await fetchImpl(url, {
+                    method: "POST",
+                    // 出站加固：绝不跟随重定向（3xx 目标不经过校验，且可能转发凭据）。
+                    redirect: "manual",
+                    signal: controller.signal,
+                    headers: {
+                        accept: "application/json",
+                        "content-type": "application/json",
+                        authorization: `Bearer ${this.connectorToken}`,
+                        "user-agent": `kiwi-connector/${PRODUCT_VERSION}`,
+                    },
+                    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 connector request timed out after ${timeoutMs}ms: ${url}`
+                    : `kiwi-catalog connector request failed: ${url} (${detail})`);
+            }
+            if (isRedirectResponse(response)) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog connector 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 connector credential (HTTP ${response.status} from ${url})`);
+            }
+            if (!response.ok) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog connector request returned HTTP ${response.status} from ${url}`);
+            }
+            try {
+                raw = await readJsonBody(response, { signal: controller.signal });
+            }
+            catch {
+                throw new CatalogSourceError("response_invalid", `kiwi-catalog connector response from ${url} is not valid JSON`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new CatalogSourceError("response_invalid", "connector-identity response must be a JSON object");
+        }
+        const envelope = raw;
+        if (envelope.ok !== true) {
+            throw new CatalogSourceError("response_invalid", `connector-identity response is not ok: ${typeof envelope.error === "string" ? envelope.error : "unknown error"}`);
+        }
+        return envelope;
+    }
+}
+//# sourceMappingURL=connector-identity.js.map

package/dist/discovery/catalog-source/connector-identity.js.map

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

package/dist/discovery/catalog-source/errors.d.ts

@@ -23,7 +23,7 @@
  *   - contract_violation 候选元素未通过 CandidateAgent DTO schema 校验，或 contract
  *                        注解非 candidate-agent / 非 1.x（视为协议级违规）。
  */
-export declare const CATALOG_SOURCE_ERROR_CODES: readonly ["invalid_input", "request_failed", "response_invalid", "contract_violation"];
+export declare const CATALOG_SOURCE_ERROR_CODES: readonly ["invalid_input", "request_failed", "response_invalid", "contract_violation", "session_rejected"];
 export type CatalogSourceErrorCode = (typeof CATALOG_SOURCE_ERROR_CODES)[number];
 /** Catalog 读取失败。带错误码；fail-closed，调用方不得吞掉。 */
 export declare class CatalogSourceError extends Error {

package/dist/discovery/catalog-source/errors.js

@@ -28,6 +28,8 @@ export const CATALOG_SOURCE_ERROR_CODES = [
     "request_failed",
     "response_invalid",
     "contract_violation",
+    /** 会话认证端点拒绝了买家会话（HTTP 401/403）：登录态缺失或已过期。 */
+    "session_rejected",
 ];
 /** Catalog 读取失败。带错误码；fail-closed，调用方不得吞掉。 */
 export class CatalogSourceError extends Error {

package/dist/discovery/catalog-source/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/discovery/catalog-source/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,eAAe;IACf,gBAAgB;IAChB,kBAAkB;IAClB,oBAAoB;CACZ,CAAC;AAIX,6CAA6C;AAC7C,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAEtC,YAAY,IAA4B,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/discovery/catalog-source/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,eAAe;IACf,gBAAgB;IAChB,kBAAkB;IAClB,oBAAoB;IACpB,6CAA6C;IAC7C,kBAAkB;CACV,CAAC;AAIX,6CAA6C;AAC7C,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAEtC,YAAY,IAA4B,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/discovery/catalog-source/merchant-publications.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 type { CatalogSourceDeps } from "./source.js";
+/**
+ * kiwi-catalog 商家公开资料（M0）wire 投影。仅收纳买方发现需要的公开字段；
+ * faq/summary 等大字段不进搜索投影（工具返回大小控制）。
+ */
+export interface MerchantPublicationRecord {
+    readonly publication_id: string;
+    readonly merchant_id: string;
+    readonly merchant_display_name: string;
+    /** 命中查询的商品名（商家声明）。 */
+    readonly title: string;
+    readonly category?: string;
+    readonly shop_platform?: string;
+    readonly shop_url?: string;
+    readonly source_kind: "merchant_declared";
+    readonly status: "draft" | "published" | "withdrawn";
+    readonly published_at?: string;
+    readonly updated_at: string;
+    /** M0 恒 false（schema 层不变量）；为 true 的响应视为协议级违规。 */
+    readonly inquiry_available: false;
+}
+/** 公开资料搜索查询（上游键集：q/category/merchant_id/limit/cursor）。 */
+export interface MerchantPublicationSearchQuery {
+    q?: string;
+    category?: string;
+    /** 精确限定商家（RFQ 硬门按 merchant_id 解析用）。 */
+    merchant_id?: string;
+    limit?: number;
+    /** 分页游标（searchPublications 内部翻页用；调用方无需直接设置）。 */
+    cursor?: string;
+}
+/**
+ * 手写校验（上游无 vendored schema 时的 fail-closed 兜底）：必需公开字段 +
+ * 两个 M0 不变量。失败抛 contract_violation，绝不把未校验对象当合法结果。
+ */
+export declare function validateMerchantPublication(value: unknown): MerchantPublicationRecord;
+export declare class MerchantPublicationsSource {
+    private readonly baseUrl;
+    private readonly deps;
+    constructor(deps: CatalogSourceDeps);
+    /** 核心请求：超时 / HTTP / 网络失败统一映射为 CatalogSourceError。 */
+    private getJson;
+    /**
+     * 公开检索商家公开资料（仅 published 未过期由上游保证）。分页完整拉取，
+     * 跨页按 publication_id 去重；limit 是总返回上限而非页大小（同 searchRecords
+     * 的历史教训）。旧 catalog 无此端点时抛 request_failed（HTTP 404），由
+     * 调用方（KiwiCatalogMerchantIndex）按单侧失败容忍处理。
+     */
+    searchPublications(query?: MerchantPublicationSearchQuery): Promise<MerchantPublicationRecord[]>;
+}

package/dist/discovery/catalog-source/merchant-publications.js

@@ -0,0 +1,207 @@
+/**
+ * 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.
+ */
+/**
+ * MerchantPublicationsSource —— kiwi-catalog 商家公开资料（M0）只读客户端。
+ *
+ *   GET {baseUrl}/v1/merchant-publications/search → {ok, results: […], next_cursor}
+ *
+ * 契约来源：kiwi-catalog 仓 kiwi_catalog/services/merchant_publications.py 的
+ * public_projection（schema v29，merchant-buddy 第 0 版设计 §4 M0 表）。上游暂无
+ * vendored JSON schema，本文件用手写校验锁定关键不变量（fail-closed）：
+ *   - source_kind 恒为 merchant_declared（商家声明，不是 Kiwi 背书）；
+ *   - inquiry_available 恒为 false（M0 不产生 Agent Card / A2A 端点 / 实时报价）。
+ *
+ * 与 KiwiCatalogSource 的关系：同一 catalog 服务的第三个搜索面；出站加固
+ * （不跟随重定向、超时、响应大小上限）与错误语义（CatalogSourceError）保持一致。
+ */
+import { CatalogSourceError } from "./errors.js";
+import { PRODUCT_VERSION } from "../../product-cli.js";
+import { isRedirectResponse, readJsonBody, SafeHttpError } from "../../net/safe-http.js";
+import { validateBaseUrl } from "./source.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** 分页拉取上限（与 KiwiCatalogSource 同一防御：游标不前进/循环保护）。 */
+const MAX_SEARCH_PAGES = 100;
+const PUBLICATION_SEARCH_QUERY_KEYS = [
+    "q",
+    "category",
+    "merchant_id",
+    "limit",
+    "cursor",
+];
+/**
+ * 手写校验（上游无 vendored schema 时的 fail-closed 兜底）：必需公开字段 +
+ * 两个 M0 不变量。失败抛 contract_violation，绝不把未校验对象当合法结果。
+ */
+export function validateMerchantPublication(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new CatalogSourceError("contract_violation", "MerchantPublication must be a JSON object");
+    }
+    const record = value;
+    for (const field of [
+        "publication_id",
+        "merchant_id",
+        "merchant_display_name",
+        "title",
+        "updated_at",
+    ]) {
+        if (typeof record[field] !== "string" || record[field] === "") {
+            throw new CatalogSourceError("contract_violation", `MerchantPublication missing non-empty string field "${field}"`);
+        }
+    }
+    if (record.source_kind !== "merchant_declared") {
+        throw new CatalogSourceError("contract_violation", `MerchantPublication source_kind must be "merchant_declared" (got ${String(record.source_kind)})`);
+    }
+    if (record.inquiry_available !== false) {
+        // M0 不变量：公开资料绝不声称可实时询价（不产生虚假 Agent/实时报价标记）。
+        throw new CatalogSourceError("contract_violation", "MerchantPublication inquiry_available must be false (M0 invariant)");
+    }
+    for (const field of ["category", "shop_platform", "shop_url", "published_at"]) {
+        const v = record[field];
+        if (v !== undefined && v !== null && typeof v !== "string") {
+            throw new CatalogSourceError("contract_violation", `MerchantPublication field "${field}" must be a string when present`);
+        }
+    }
+    return record;
+}
+/** 序列化公开资料搜索查询。未知键 → invalid_input（fail-closed）。 */
+function buildPublicationSearchQuery(query) {
+    for (const key of Object.keys(query)) {
+        if (!PUBLICATION_SEARCH_QUERY_KEYS.includes(key)) {
+            throw new CatalogSourceError("invalid_input", `unknown merchant-publications search query key: "${key}"`);
+        }
+    }
+    if (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit <= 0)) {
+        throw new CatalogSourceError("invalid_input", `merchant-publications search limit must be a positive integer (got ${query.limit})`);
+    }
+    const entries = [];
+    const push = (key, value) => {
+        if (value !== undefined)
+            entries.push([key, value]);
+    };
+    push("q", query.q);
+    push("category", query.category);
+    push("merchant_id", query.merchant_id);
+    if (query.limit !== undefined)
+        push("limit", String(query.limit));
+    push("cursor", query.cursor);
+    return new URLSearchParams(entries).toString();
+}
+export class MerchantPublicationsSource {
+    baseUrl;
+    deps;
+    constructor(deps) {
+        this.baseUrl = validateBaseUrl(deps.baseUrl);
+        this.deps = deps;
+    }
+    /** 核心请求：超时 / HTTP / 网络失败统一映射为 CatalogSourceError。 */
+    async getJson(requestPath) {
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${requestPath}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        let raw;
+        try {
+            try {
+                response = await fetchImpl(url, {
+                    // 出站加固：绝不跟随重定向（3xx 目标不经过校验，且可能转发 Bearer 头）。
+                    redirect: "manual",
+                    signal: controller.signal,
+                    headers: {
+                        accept: "application/json",
+                        "user-agent": `kiwi-buyer/${PRODUCT_VERSION}`,
+                        ...(this.deps.authToken !== undefined
+                            ? { authorization: `Bearer ${this.deps.authToken}` }
+                            : {}),
+                        ...(this.deps.buyerId !== undefined ? { "x-buyer-id": this.deps.buyerId } : {}),
+                    },
+                });
+            }
+            catch (err) {
+                const name = err?.name;
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new CatalogSourceError("request_failed", name === "AbortError"
+                    ? `kiwi-catalog request timed out after ${timeoutMs}ms: ${url}`
+                    : `kiwi-catalog request failed: ${url} (${detail})`);
+            }
+            if (isRedirectResponse(response)) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog request must not follow redirects (HTTP ${response.status} from ${url})`);
+            }
+            if (!response.ok) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog request returned HTTP ${response.status} from ${url}`);
+            }
+            try {
+                raw = await readJsonBody(response, { signal: controller.signal });
+            }
+            catch (err) {
+                if (controller.signal.aborted) {
+                    throw new CatalogSourceError("request_failed", `kiwi-catalog request timed out after ${timeoutMs}ms while reading response: ${url}`);
+                }
+                throw new CatalogSourceError("response_invalid", err instanceof SafeHttpError && err.code === "response_too_large"
+                    ? `kiwi-catalog response from ${url}: ${err.message}`
+                    : `kiwi-catalog response from ${url} is not valid JSON`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return raw;
+    }
+    /**
+     * 公开检索商家公开资料（仅 published 未过期由上游保证）。分页完整拉取，
+     * 跨页按 publication_id 去重；limit 是总返回上限而非页大小（同 searchRecords
+     * 的历史教训）。旧 catalog 无此端点时抛 request_failed（HTTP 404），由
+     * 调用方（KiwiCatalogMerchantIndex）按单侧失败容忍处理。
+     */
+    async searchPublications(query = {}) {
+        const records = [];
+        const seen = new Set();
+        const limit = query.limit;
+        let cursor;
+        for (let page = 0; page < MAX_SEARCH_PAGES; page++) {
+            const qs = buildPublicationSearchQuery({
+                ...query,
+                ...(cursor !== undefined ? { cursor } : {}),
+            });
+            if (limit !== undefined && records.length >= limit)
+                break;
+            const raw = await this.getJson(`/v1/merchant-publications/search${qs.length > 0 ? `?${qs}` : ""}`);
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                throw new CatalogSourceError("response_invalid", "merchant-publications search response must be a JSON object");
+            }
+            const body = raw;
+            if (!Array.isArray(body.results)) {
+                throw new CatalogSourceError("response_invalid", 'merchant-publications search response is missing array field "results"');
+            }
+            for (const element of body.results) {
+                if (limit !== undefined && records.length >= limit)
+                    break;
+                const record = validateMerchantPublication(element);
+                if (seen.has(record.publication_id))
+                    continue;
+                seen.add(record.publication_id);
+                records.push(record);
+            }
+            const next = body.next_cursor;
+            if (typeof next !== "string" || next === "")
+                break;
+            cursor = next;
+        }
+        return limit !== undefined ? records.slice(0, limit) : records;
+    }
+}
+//# sourceMappingURL=merchant-publications.js.map

package/dist/discovery/catalog-source/merchant-publications.js.map

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

package/dist/discovery/catalog-source/register.d.ts

@@ -56,3 +56,27 @@ export declare function normalizeCatalogBaseUrl(url: string): string;
  * 幂等：同 domain + agent_card_url 重复注册由 catalog 侧幂等处理，安全可重试。
  */
 export declare function registerCatalogAgent(input: CatalogRegisterInput): Promise<CatalogRegisterResult>;
+/** 心跳结果（catalog 侧 last_seen_at 与生效 TTL）。 */
+export interface CatalogHeartbeatResult {
+    ok: true;
+    lastSeenAt: string;
+    freshTtlSeconds: number;
+}
+export interface CatalogHeartbeatInput {
+    catalogBaseUrl: string;
+    catalogAgentId: string;
+    /** owner 凭据：随机 token（优先）或 HMAC 派生 secret（legacy）。 */
+    ownerToken?: string;
+    ownerTokenSecret?: string;
+    merchantId?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Agent 心跳（WP6 / 发布计划 §3.6）：只刷新 last_seen_at，不重新抓取资料。
+ *
+ * 商家 A2A 节点周期性调用；catalog 读侧按 last_seen_at + TTL 派生 freshness，
+ * 离线商家因此不再被采购专家标成"可实时询价"（公开资料仍可查）。
+ * 心跳间隔应显著小于 catalog 的 TTL（缺省 900s）。
+ */
+export declare function sendCatalogAgentHeartbeat(input: CatalogHeartbeatInput): Promise<CatalogHeartbeatResult>;

package/dist/discovery/catalog-source/register.js

@@ -110,4 +110,50 @@ export async function registerCatalogAgent(input) {
         verificationEnqueued: payload.verification_enqueued === true,
     };
 }
+/**
+ * Agent 心跳（WP6 / 发布计划 §3.6）：只刷新 last_seen_at，不重新抓取资料。
+ *
+ * 商家 A2A 节点周期性调用；catalog 读侧按 last_seen_at + TTL 派生 freshness，
+ * 离线商家因此不再被采购专家标成"可实时询价"（公开资料仍可查）。
+ * 心跳间隔应显著小于 catalog 的 TTL（缺省 900s）。
+ */
+export async function sendCatalogAgentHeartbeat(input) {
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const base = normalizeCatalogBaseUrl(input.catalogBaseUrl);
+    const body = {};
+    if (input.ownerToken !== undefined && input.ownerToken !== "") {
+        body.owner_token = input.ownerToken;
+    }
+    else if (input.ownerTokenSecret !== undefined && input.merchantId !== undefined) {
+        body.owner_token = createHmac("sha256", input.ownerTokenSecret)
+            .update(`kiwi-catalog-owner:${input.merchantId}`)
+            .digest("hex");
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), input.timeoutMs ?? 15_000);
+    try {
+        const res = await fetchImpl(`${base}/v1/agent-catalog/agents/${encodeURIComponent(input.catalogAgentId)}/heartbeat`, {
+            method: "POST",
+            // 出站纪律同 register：不跟随重定向（体里带 owner 凭据）。
+            redirect: "manual",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        const payload = text === "" ? {} : JSON.parse(text);
+        if (!res.ok || payload.ok === false) {
+            const detail = typeof payload.error === "string" ? payload.error : `HTTP ${res.status}`;
+            throw new CatalogSourceError("request_failed", `catalog heartbeat failed: ${detail}`);
+        }
+        return {
+            ok: true,
+            lastSeenAt: typeof payload.last_seen_at === "string" ? payload.last_seen_at : "",
+            freshTtlSeconds: typeof payload.fresh_ttl_seconds === "number" ? payload.fresh_ttl_seconds : 0,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 //# sourceMappingURL=register.js.map