@harrylabsj/kiwi 0.7.8 → 0.7.10

package/dist/buyer-core/quote-fetcher.js

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+/**
+ * MarketplaceQuoteFetcher —— 真实 RFQ fan-out（战略 v2.5 Phase 2 Supply 轨）。
+ *
+ * 对每个目标 Merchant，经 shopping-cli marketplace 创建定向会话（真实商品/
+ * 库存/交付数据 + resident merchant agent 确定性回复），轮询拿真实回复，映射为
+ * QuoteCandidateInput（含 provenance：merchant_reply_id / conversation_id）。
+ *
+ * 拒绝编造：Merchant 不可达 / 超时 / 协议错误 → failed + 可解释 failure
+ * classification；绝不返回虚构报价。
+ */
+import { uuidv7 } from "@earendil-works/pi-ai";
+const DEFAULT_POLL_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 20_000;
+export class MarketplaceQuoteFetcher {
+    baseUrl;
+    buyerBootstrapToken;
+    pollIntervalMs;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.buyerBootstrapToken = options.buyerBootstrapToken;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_MS;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    }
+    /** 对每个 Merchant 独立发起真实 RFQ 并收集回复（部分失败语义）。 */
+    async requestQuotes(intent, merchants) {
+        const buyerId = `buyer-${uuidv7()}`;
+        const results = await Promise.all(merchants.map((merchant) => this.requestQuote(buyerId, intent, merchant)));
+        return results;
+    }
+    async requestQuote(buyerId, intent, merchant) {
+        const { sku, text } = this.buildRfq(intent, merchant);
+        try {
+            const conversation = await this.createConversation(buyerId, merchant.merchant_id, sku, text);
+            if (conversation.conversation?.id === undefined || conversation.buyer_token === undefined) {
+                throw new Error(`marketplace did not return conversation/buyer_token for ${merchant.merchant_id}`);
+            }
+            const convId = conversation.conversation.id;
+            const reply = await this.pollMerchantReply(convId, conversation.buyer_token);
+            if (reply === undefined) {
+                return {
+                    merchant_id: merchant.merchant_id,
+                    status: "failed",
+                    failure: { classification: "timeout", retryable: true, detail: `no merchant reply within ${this.timeoutMs}ms` },
+                };
+            }
+            return {
+                merchant_id: merchant.merchant_id,
+                status: "succeeded",
+                provenance: {
+                    merchant_reply_id: String(reply.messageId),
+                    negotiation_id: convId,
+                    source: "marketplace",
+                    reply_text: reply.text,
+                    // 会话 buyer_token：供后续磋商（claim→counter→complete）复用。
+                    // 作用域仅限该会话，属最小披露。
+                    buyer_token: conversation.buyer_token,
+                    // 该商家实际报价的 SKU（RFQ 用商家自有 SKU），磋商 proposal 复用。
+                    sku,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                merchant_id: merchant.merchant_id,
+                status: "failed",
+                failure: {
+                    classification: "protocol_error",
+                    retryable: true,
+                    detail: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+    }
+    /**
+     * 从 CommerceIntent 提取 sku 与 RFQ 文本（真实商品语义，不做虚构）。
+     * 商家有 matching_skus（marketplace 商品 FTS 路由）时优先用商家自有 SKU——
+     * 否则商家 agent 无法按文本匹配到自己的商品（SKU 是会话匹配键）。
+     */
+    buildRfq(intent, merchant) {
+        const items = Array.isArray(intent.items) ? intent.items : [];
+        const first = items[0] ?? {};
+        const query = typeof first.query === "string" ? first.query : "";
+        const itemSku = typeof first.sku === "string" ? first.sku : "";
+        const sku = merchant.matching_skus?.[0] ?? itemSku;
+        const quantity = typeof first.quantity === "object" && first.quantity !== null
+            ? String(first.quantity.value ?? "")
+            : "";
+        const itemText = query !== "" ? query : sku;
+        const text = `采购 ${quantity} 个 ${itemText}（sku=${sku || "?"}），请报价与交期。`.trim();
+        return { sku, text };
+    }
+    async createConversation(buyerId, merchantId, sku, text) {
+        const res = await this.fetchImpl(`${this.baseUrl}/conversations`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.buyerBootstrapToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                buyer_id: buyerId,
+                merchant_id: merchantId,
+                sku,
+                text,
+                intent: "ask_price",
+            }),
+            // 连接挂起不阻塞 worker：单次请求硬超时（fail-closed，同仓库 safe-http）。
+            signal: AbortSignal.timeout(this.pollIntervalMs + 8000),
+        });
+        if (!res.ok) {
+            throw new Error(`marketplace /conversations ${res.status}`);
+        }
+        const data = (await res.json());
+        if (data.ok !== true) {
+            throw new Error(`marketplace rejected conversation: ${JSON.stringify(data)}`);
+        }
+        return data;
+    }
+    /** 轮询会话直到 merchant_agent 回复出现或超时。 */
+    async pollMerchantReply(conversationId, buyerToken) {
+        const deadline = Date.now() + this.timeoutMs;
+        for (;;) {
+            const reply = await this.readConversation(conversationId, buyerToken);
+            if (reply !== undefined)
+                return reply;
+            if (Date.now() >= deadline)
+                return undefined;
+            await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
+        }
+    }
+    async readConversation(conversationId, buyerToken) {
+        const res = await this.fetchImpl(`${this.baseUrl}/conversations/${conversationId}`, {
+            headers: { authorization: `Bearer ${buyerToken}` },
+            signal: AbortSignal.timeout(this.pollIntervalMs + 8000),
+        });
+        if (!res.ok) {
+            throw new Error(`marketplace /conversations/${conversationId} ${res.status}`);
+        }
+        const data = (await res.json());
+        const messages = data.conversation?.messages ?? [];
+        const reply = [...messages]
+            .reverse()
+            .find((m) => m.sender === "merchant_agent" && typeof m.id === "number");
+        if (reply === undefined)
+            return undefined;
+        return { messageId: reply.id, text: reply.text ?? "" };
+    }
+}
+//# sourceMappingURL=quote-fetcher.js.map

package/dist/buyer-core/quote-fetcher.js.map

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

package/dist/buyer-core/service.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 { TaskApprovalStore } from "./store.js";
+export type BuyerAction = "discover" | "inquiry_rfq" | "compare_offers" | "counter_offer" | "accept_nonbinding" | "handoff" | "payment";
+export interface MerchantRecord {
+    merchant_id: string;
+    name: string;
+    verified: boolean;
+    category?: string;
+    region?: string;
+    ucp_profile_url?: string;
+    agent_card_url?: string;
+    capabilities: string[];
+    /** 该商家匹配查询的商品 SKU（marketplace 商品 FTS 路由），供 RFQ 用商家自有 SKU。 */
+    matching_skus?: string[];
+}
+export interface MerchantIndex {
+    search(query: string, opts?: {
+        category?: string;
+        region?: string;
+    }): Promise<MerchantRecord[]>;
+}
+export interface QuoteCandidateInput {
+    merchant_id: string;
+    status: "succeeded" | "failed";
+    provenance?: {
+        merchant_reply_id?: string;
+        negotiation_id?: string;
+        offer_id?: string;
+        source?: string;
+        /** 商家原回复文本（真实报价/库存/交付事实），用于 kiwi_get_task 展示。 */
+        reply_text?: string;
+        /** 会话 buyer_token（作用域限该会话），供磋商复用；最小披露。 */
+        buyer_token?: string;
+        /** 该商家实际报价的 SKU（磋商 proposal 复用）。 */
+        sku?: string;
+    };
+    failure?: {
+        classification: string;
+        retryable: boolean;
+        detail?: string;
+    };
+}
+export interface QuoteFetcher {
+    requestQuotes(intent: Record<string, unknown>, merchants: MerchantRecord[]): Promise<QuoteCandidateInput[]>;
+}
+export interface NegotiationStep {
+    round: number;
+    action: "counter_offer" | "clarification";
+    summary: string;
+    /** 商家对本次还价的回复（真实文本），供 kiwi_get_task 展示。 */
+    reply?: string;
+}
+export interface Negotiator {
+    negotiate(taskId: string, intent: Record<string, unknown>, current: NegotiationStep, candidates: Array<Record<string, unknown>>): Promise<NegotiationStep>;
+}
+export interface KiwiBuyerServiceOptions {
+    store: TaskApprovalStore;
+    principal: string;
+    buyerAgentId: string;
+    sessionId: string;
+    /** 冻结的 DelegationPolicy（已通过 schema 校验）。 */
+    delegationPolicy: Record<string, unknown>;
+    merchantIndex?: MerchantIndex;
+    quoteFetcher?: QuoteFetcher;
+    negotiator?: Negotiator;
+    now?: () => string;
+}
+export interface AuthorizationRecord {
+    authorization_id: string;
+    action: BuyerAction;
+    subject: {
+        buyer_agent_id: string;
+        session_id: string;
+        delegation_id: string;
+        expires_at: string;
+    };
+    layers: Record<string, {
+        status: "allowed" | "denied";
+        reason?: string;
+    }>;
+    effective_decision: "granted" | "denied";
+    approval_id?: string;
+    expires_at: string;
+    decided_at: string;
+}
+export declare class KiwiBuyerService {
+    private readonly store;
+    private readonly principal;
+    private readonly buyerAgentId;
+    private readonly sessionId;
+    private readonly policy;
+    private readonly merchantIndex?;
+    private readonly quoteFetcher?;
+    private readonly negotiator?;
+    private readonly now;
+    constructor(options: KiwiBuyerServiceOptions);
+    search(input: {
+        query: string;
+        category?: string;
+        region?: string;
+    }): Promise<{
+        merchants: MerchantRecord[];
+        note?: string;
+    }>;
+    requestQuotes(input: {
+        intent: Record<string, unknown>;
+        idempotency_key?: string;
+        merchant_ids?: string[];
+    }): Promise<{
+        task: Record<string, unknown>;
+        created: boolean;
+    }>;
+    getTask(taskId: string): {
+        task: Record<string, unknown>;
+    };
+    negotiate(input: {
+        task_id: string;
+        action: "counter_offer" | "clarification";
+        summary: string;
+    }): Promise<{
+        task: Record<string, unknown>;
+        step: NegotiationStep;
+    }>;
+    acceptAgreement(input: {
+        task_id: string;
+        candidate_id: string;
+        approval_id?: string;
+    }): Promise<{
+        task: Record<string, unknown>;
+        agreement: Record<string, unknown>;
+        authorization: AuthorizationRecord;
+    }>;
+    getAgreement(agreementId: string): {
+        agreement: Record<string, unknown>;
+    };
+    handoff(input: {
+        agreement_id: string;
+        approval_id: string;
+        destination_type: string;
+        url?: string;
+    }): Promise<{
+        handoff_ref: {
+            handoff_id: string;
+            destination_type: string;
+            url?: string;
+        };
+        authorization: AuthorizationRecord;
+    }>;
+    /** 创建 pending 审批记录（ASK 动作触发）。返回持久 approval_id。 */
+    requestApproval(input: {
+        task_id: string;
+        action: "accept_nonbinding" | "handoff" | "sensitive_disclosure";
+        candidate_digest?: string;
+    }): {
+        approval_id: string;
+    };
+    /** 批准一个 pending 审批（绑定授权记录）。 */
+    approveApproval(input: {
+        approval_id: string;
+        authorization: AuthorizationRecord;
+    }): void;
+    /** 拒绝一个 pending 审批（deny 路径；deny 优先，§5.5）。 */
+    rejectApproval(input: {
+        approval_id: string;
+        reason?: string;
+    }): void;
+    evaluateAuthorization(action: BuyerAction, opts: {
+        taskId: string;
+        candidateId?: string;
+        candidateDigest?: string;
+        approvalId?: string;
+    }): Promise<AuthorizationRecord>;
+    private limitViolation;
+    private firstQuery;
+    private currentRounds;
+    private decodeTask;
+    private parsePayload;
+}