@harrylabsj/kiwi 0.7.21 → 0.8.0

package/dist/agent/merchant/intelligence/http-analytics-source.js

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+import { readJsonBody, SafeHttpError, isRedirectResponse } from "../../../net/safe-http.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 512 * 1024;
+export class MerchantAnalyticsHttpError extends Error {
+    status;
+    code;
+    constructor(code, message, status) {
+        super(message);
+        this.name = "MerchantAnalyticsHttpError";
+        this.code = code;
+        this.status = status;
+    }
+}
+function assertBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new MerchantAnalyticsHttpError("configuration", "analytics baseUrl must be a valid URL");
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new MerchantAnalyticsHttpError("configuration", "analytics baseUrl must not contain credentials");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new MerchantAnalyticsHttpError("configuration", "analytics baseUrl must use http or https");
+    }
+    if (url.protocol === "http:" && !["localhost", "127.0.0.1", "[::1]", "::1"].includes(url.hostname.toLowerCase())) {
+        throw new MerchantAnalyticsHttpError("configuration", "analytics baseUrl must use HTTPS for remote hosts");
+    }
+    return value.replace(/\/+$/, "");
+}
+function object(value, message) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new MerchantAnalyticsHttpError("protocol", message);
+    }
+    return value;
+}
+function requireMerchant(value, expected) {
+    if (value !== expected) {
+        throw new MerchantAnalyticsHttpError("protocol", "analytics response merchant_id mismatch");
+    }
+}
+function limitations(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new MerchantAnalyticsHttpError("protocol", "analytics limitations must be an array");
+    const result = value.filter((item) => item !== null && typeof item === "object" &&
+        typeof item.source === "string" &&
+        typeof item.note === "string");
+    if (result.length !== value.length)
+        throw new MerchantAnalyticsHttpError("protocol", "analytics limitation item is invalid");
+    return result;
+}
+function metricValues(value) {
+    if (!Array.isArray(value))
+        throw new MerchantAnalyticsHttpError("protocol", "analytics metrics must be an array");
+    if (value.length > 1_000)
+        throw new MerchantAnalyticsHttpError("protocol", "analytics metrics exceed 1000 items");
+    const names = new Set();
+    return value.map((item) => {
+        const metric = object(item, "analytics metric must be an object");
+        if (typeof metric.name !== "string" || metric.name.length === 0 || metric.name.length > 80 ||
+            (metric.value !== null && (typeof metric.value !== "number" || !Number.isFinite(metric.value))) ||
+            (metric.unit !== "count" && metric.unit !== "percent" && metric.unit !== "minor_currency") ||
+            typeof metric.observed_at !== "string" || metric.observed_at.length === 0 ||
+            (metric.currency !== undefined && typeof metric.currency !== "string") ||
+            (metric.note !== undefined && typeof metric.note !== "string"))
+            throw new MerchantAnalyticsHttpError("protocol", `analytics metric ${String(metric.name)} is invalid`);
+        if (names.has(metric.name))
+            throw new MerchantAnalyticsHttpError("protocol", `analytics metric ${metric.name} is duplicated`);
+        names.add(metric.name);
+        return metric;
+    });
+}
+function metricSeries(value, expected) {
+    const series = object(value, "analytics series must be an object");
+    if (series.metric !== expected.metric || series.period !== expected.period || series.granularity !== expected.granularity ||
+        (series.unit !== "count" && series.unit !== "percent" && series.unit !== "minor_currency") ||
+        !Array.isArray(series.points) || series.points.length > 10_000 ||
+        (series.currency !== undefined && typeof series.currency !== "string") ||
+        (series.note !== undefined && typeof series.note !== "string"))
+        throw new MerchantAnalyticsHttpError("protocol", "analytics series metadata is invalid");
+    for (const point of series.points) {
+        const item = object(point, "analytics series point must be an object");
+        if (typeof item.date !== "string" || item.date.length === 0 || item.date.length > 32 ||
+            typeof item.value !== "number" || !Number.isFinite(item.value)) {
+            throw new MerchantAnalyticsHttpError("protocol", "analytics series point is invalid");
+        }
+    }
+    return series;
+}
+/**
+ * Generic server-side adapter for order, sales, campaign or advertising
+ * services. The remote service is never exposed to the model as a tool.
+ *
+ * Contract:
+ *   GET /v1/merchant/analytics/metrics?merchant_id=...&period=7d
+ *     -> { ok: true, merchant_id, metrics, limitations? }
+ *   GET /v1/merchant/analytics/series?merchant_id=...&metric=...&period=7d&granularity=day
+ *     -> { ok: true, merchant_id, series: MetricSeries }
+ * A 404 on the series endpoint means the source does not provide that metric.
+ */
+export class HttpMerchantAnalyticsSource {
+    baseUrl;
+    token;
+    fetchImpl;
+    timeoutMs;
+    maxResponseBytes;
+    constructor(options) {
+        this.baseUrl = assertBaseUrl(options.baseUrl);
+        this.token = options.token;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.timeoutMs = Math.max(100, Math.min(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 120_000));
+        this.maxResponseBytes = Math.max(1_024, Math.min(options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES, 8 * 1024 * 1024));
+    }
+    async request(path, query) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const url = new URL(`${this.baseUrl}${path}`);
+        for (const [key, value] of Object.entries(query))
+            url.searchParams.set(key, value);
+        try {
+            let response;
+            try {
+                response = await this.fetchImpl(url, {
+                    method: "GET",
+                    redirect: "manual",
+                    headers: {
+                        accept: "application/json",
+                        ...(this.token === undefined ? {} : { authorization: `Bearer ${this.token}` }),
+                    },
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                throw new MerchantAnalyticsHttpError("transport", `analytics request failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (isRedirectResponse(response)) {
+                throw new MerchantAnalyticsHttpError("transport", "analytics endpoint must not redirect", response.status);
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new MerchantAnalyticsHttpError("auth", "analytics authorization failed", response.status);
+            }
+            if (response.status === 404)
+                return { status: response.status, payload: {} };
+            let payload;
+            try {
+                payload = await readJsonBody(response, { maxBytes: this.maxResponseBytes, signal: controller.signal });
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    throw new MerchantAnalyticsHttpError("transport", "analytics request timed out while reading response");
+                if (error instanceof SafeHttpError && error.code === "response_too_large") {
+                    throw new MerchantAnalyticsHttpError("protocol", "analytics response exceeds the configured size limit");
+                }
+                throw new MerchantAnalyticsHttpError("protocol", "analytics response is not valid JSON");
+            }
+            const body = object(payload, "analytics response must be an object");
+            if (!response.ok || body.ok === false)
+                throw new MerchantAnalyticsHttpError("unavailable", "analytics service returned an error", response.status);
+            if (body.ok !== true)
+                throw new MerchantAnalyticsHttpError("protocol", "analytics response must set ok=true", response.status);
+            return { status: response.status, payload: body };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async getMetrics(input) {
+        const { payload } = await this.request("/v1/merchant/analytics/metrics", input);
+        requireMerchant(payload.merchant_id, input.merchant_id);
+        return {
+            metrics: metricValues(payload.metrics),
+            ...(payload.limitations === undefined ? {} : { limitations: limitations(payload.limitations) }),
+        };
+    }
+    async queryMetric(input) {
+        const { status, payload } = await this.request("/v1/merchant/analytics/series", input);
+        if (status === 404)
+            return undefined;
+        requireMerchant(payload.merchant_id, input.merchant_id);
+        return metricSeries(payload.series, input);
+    }
+}
+//# sourceMappingURL=http-analytics-source.js.map

package/dist/agent/merchant/intelligence/http-analytics-source.js.map

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

package/dist/agent/merchant/intelligence/types.d.ts

@@ -0,0 +1,109 @@
+export interface DataLimitation {
+    source: string;
+    note: string;
+}
+export type MetricUnit = "count" | "percent" | "minor_currency";
+/** Formal analytics metric names understood by the optional commerce source. */
+export type FormalAnalyticsMetric = "gross_sales" | "orders" | "ad_spend" | "roas" | "campaign_conversions";
+export interface MetricValue {
+    name: string;
+    value: number | null;
+    unit: MetricUnit;
+    currency?: string;
+    observed_at: string;
+    note?: string;
+}
+export interface MetricPoint {
+    date: string;
+    value: number;
+}
+export interface MetricSeries {
+    metric: string;
+    unit: MetricUnit;
+    period: string;
+    /** Points use UTC dates; week = Monday, month = first day of month. */
+    granularity: "day" | "week" | "month";
+    points: MetricPoint[];
+    note?: string;
+}
+/**
+ * Optional authoritative sales/marketing adapter. It is deliberately
+ * separate from MerchantClient and MerchantStatsStore: deployments can wire
+ * an ERP, order service or ad platform without granting the model direct
+ * access to that system.
+ */
+export interface MerchantAnalyticsSource {
+    getMetrics(input: {
+        merchant_id: string;
+        period: string;
+    }): Promise<{
+        metrics: MetricValue[];
+        limitations?: DataLimitation[];
+    }>;
+    queryMetric(input: {
+        merchant_id: string;
+        metric: string;
+        period: string;
+        granularity: "day" | "week" | "month";
+    }): Promise<MetricSeries | undefined>;
+}
+export interface MerchantChangePreview {
+    candidate_id: string;
+    tool: string;
+    status: string;
+    risk: string;
+    expires_at: string;
+    stale_sensitive: true;
+    changes: Array<{
+        field: string;
+        before: unknown;
+        after: unknown;
+    }>;
+}
+export interface CatalogHealth {
+    total: number;
+    active: number;
+    paused: number;
+    out_of_stock: number | null;
+    observed_at: string;
+}
+export interface MerchantBusinessSnapshot {
+    merchant_id: string;
+    period: string;
+    generated_at: string;
+    metrics: MetricValue[];
+    alerts: {
+        active_negotiations: number;
+        human_reviews: number;
+        pending_actions: number;
+        low_stock: number | null;
+    };
+    top_sku_contacts?: Array<{
+        sku: string;
+        contact_events: number;
+        distinct_buyers: number;
+        negotiations: number;
+    }>;
+    limitations: DataLimitation[];
+}
+export interface NegotiationDigestItem {
+    negotiation_id: string;
+    phase: string;
+    buyer_identity: string;
+    skus: string[];
+    quantity?: number;
+    latest_price_minor?: number;
+    currency?: string;
+    needs_human_review: boolean;
+    updated_at: string;
+    agreement_id?: string;
+}
+export interface PendingActionSummary {
+    candidate_id: string;
+    tool: string;
+    risk: string;
+    status: string;
+    expires_at: string;
+    /** Literal invariant: every approval must revalidate current preconditions. */
+    stale_sensitive: true;
+}

package/dist/agent/merchant/intelligence/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agent/merchant/intelligence/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/agent/merchant/intelligence/types.ts"],"names":[],"mappings":""}

package/dist/agent/merchant/merchant-enrichment.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+import type { WriteApprovalCandidateStore } from "./action-candidate.js";
+import type { MerchantChangePreview } from "./intelligence/types.js";
+/** Public, server-enriched projection of an approval candidate. */
+export declare function publicCandidatePreview(candidate: ReturnType<WriteApprovalCandidateStore["get"]>): MerchantChangePreview | undefined;

package/dist/agent/merchant/merchant-enrichment.js

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/** Public, server-enriched projection of an approval candidate. */
+export function publicCandidatePreview(candidate) {
+    if (candidate === undefined)
+        return undefined;
+    const args = candidate.arguments;
+    const before = candidate.preconditions;
+    const changes = [];
+    const patch = args.changes;
+    if (patch !== null && typeof patch === "object" && !Array.isArray(patch)) {
+        for (const [field, after] of Object.entries(patch)) {
+            if (/token|secret|credential|password|floor|cost|vault|private/i.test(field))
+                continue;
+            changes.push({ field, before: before[field], after });
+        }
+    }
+    if (typeof args.stock === "number")
+        changes.push({ field: "stock", before: before.stock, after: args.stock });
+    if (typeof args.paused === "boolean")
+        changes.push({ field: "paused", before: before.paused, after: args.paused });
+    if (changes.length === 0)
+        changes.push({ field: "operation", before: "not_applied", after: candidate.tool });
+    return {
+        candidate_id: candidate.candidate_id,
+        tool: candidate.tool,
+        status: candidate.status,
+        risk: candidate.risk,
+        expires_at: candidate.expires_at,
+        stale_sensitive: true,
+        changes,
+    };
+}
+//# sourceMappingURL=merchant-enrichment.js.map

package/dist/agent/merchant/merchant-enrichment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-enrichment.js","sourceRoot":"","sources":["../../../src/agent/merchant/merchant-enrichment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,mEAAmE;AACnE,MAAM,UAAU,sBAAsB,CACpC,SAAyD;IAEzD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC;IACjC,MAAM,MAAM,GAAG,SAAS,CAAC,aAAa,CAAC;IACvC,MAAM,OAAO,GAA8D,EAAE,CAAC;IAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;IAC3B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC9E,IAAI,4DAA4D,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,SAAS;YACvF,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9G,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACnH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7G,OAAO;QACL,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,eAAe,EAAE,IAAI;QACrB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/agent/merchant/merchant-grounding.d.ts

@@ -0,0 +1,5 @@
+import type { AgentProfile } from "../../config/profile.js";
+import type { GroundingContext, GroundingRule } from "../context/grounding.js";
+/** Rules are intentionally read-only; write tools can never be a grounding target. */
+export declare const MERCHANT_GROUNDING_RULES: readonly GroundingRule[];
+export declare function merchantGroundingContext(profile: AgentProfile, latestUserText: string): GroundingContext;

package/dist/agent/merchant/merchant-grounding.js

@@ -0,0 +1,76 @@
+function has(text, terms) {
+    const lowered = text.toLowerCase();
+    return terms.some((term) => lowered.includes(term));
+}
+function enabled(profile) {
+    return profile.merchant_experience?.enabled !== false &&
+        profile.merchant_experience?.grounding !== false;
+}
+/** Rules are intentionally read-only; write tools can never be a grounding target. */
+export const MERCHANT_GROUNDING_RULES = [
+    {
+        name: "pending-actions",
+        priority: 10,
+        match: ({ latestUserText, sessionState }) => {
+            const profile = sessionState.profile;
+            if (profile !== undefined && !enabled(profile))
+                return undefined;
+            if (!has(latestUserText, ["待审批", "等待批准", "pending", "approve", "批准", "执行"])) {
+                return undefined;
+            }
+            return { tool: "get_pending_actions", arguments: {}, reason: "approval state must be current" };
+        },
+    },
+    {
+        name: "negotiations",
+        priority: 20,
+        match: ({ latestUserText }) => {
+            if (!has(latestUserText, ["磋商", "询价", "报价", "还价", "buyer", "negotiation"])) {
+                return undefined;
+            }
+            return { tool: "get_negotiation_digest", arguments: { status: "active" }, reason: "read current A2A negotiations first" };
+        },
+    },
+    {
+        name: "human-review",
+        priority: 30,
+        match: ({ latestUserText }) => {
+            if (!has(latestUserText, ["人工", "审核", "转人工", "human review"]))
+                return undefined;
+            return { tool: "get_human_review_queue", arguments: {}, reason: "read the current review queue first" };
+        },
+    },
+    {
+        name: "inventory-health",
+        priority: 40,
+        match: ({ latestUserText }) => {
+            if (!has(latestUserText, ["库存", "缺货", "有货", "补货", "stock", "inventory"])) {
+                return undefined;
+            }
+            return { tool: "get_catalog_health", arguments: {}, reason: "inventory answers require current catalog facts" };
+        },
+    },
+    {
+        name: "catalog",
+        priority: 50,
+        match: ({ latestUserText }) => {
+            if (!has(latestUserText, ["商品", "目录", "sku", "listing", "catalog"]))
+                return undefined;
+            return { tool: "list_catalog_products", arguments: {}, reason: "catalog answers require current owned listings" };
+        },
+    },
+    {
+        name: "business-snapshot",
+        priority: 60,
+        match: ({ latestUserText }) => {
+            if (!has(latestUserText, ["经营", "生意", "销售", "业绩", "指标", "收入", "最近怎么样"])) {
+                return undefined;
+            }
+            return { tool: "get_business_snapshot", arguments: {}, reason: "business answers require current metrics" };
+        },
+    },
+];
+export function merchantGroundingContext(profile, latestUserText) {
+    return { latestUserText, sessionState: { profile } };
+}
+//# sourceMappingURL=merchant-grounding.js.map

package/dist/agent/merchant/merchant-grounding.js.map

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

package/dist/agent/merchant/merchant-presentations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+import { PresentationRegistry } from "../presentation/registry.js";
+export declare function createMerchantPresentationRegistry(): PresentationRegistry;