@harrylabsj/kiwi 0.7.21 → 0.8.0

package/dist/agent/supplier/scheduler.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { KiwiCatalogSource } from "../../discovery/catalog-source/kiwi-source.js";
+import type { TrustRecordStore } from "../../trust/records/store.js";
+import type { SupplierObservation, SupplierRelationshipStore } from "./store.js";
+export interface SupplierSchedulerOptions {
+    store: SupplierRelationshipStore;
+    catalogSource?: KiwiCatalogSource;
+    trustStore?: TrustRecordStore;
+    now?: () => string;
+    /** 可注入 fake fetch（测试）；缺省 globalThis.fetch。 */
+    fetchFn?: typeof fetch;
+    /** 本地开发放行字面 loopback（不可信 Card 默认 false）。 */
+    allowLoopback?: boolean;
+    skipDnsCheck?: boolean;
+    resolveIp?: (hostname: string) => Promise<string[]>;
+    /** 退避 jitter 随机源（±10%），可注入固定值做确定性测试。 */
+    random?: () => number;
+    timeoutMs?: number;
+}
+export interface SupplierTickBudget {
+    max_requests?: number;
+    max_relationships?: number;
+}
+export interface SupplierTickNotification {
+    relationship_id: string;
+    merchant_id: string;
+    summary: string;
+}
+export interface SupplierTickResult {
+    checked: number;
+    requests_used: number;
+    observations: SupplierObservation[];
+    notified: SupplierTickNotification[];
+    errors: string[];
+}
+export declare class SupplierScheduler {
+    private readonly store;
+    private readonly catalogSource?;
+    private readonly trustStore?;
+    private readonly now;
+    private readonly fetchFn;
+    private readonly allowLoopback;
+    private readonly skipDnsCheck?;
+    private readonly resolveIp?;
+    private readonly random;
+    private readonly timeoutMs;
+    constructor(options: SupplierSchedulerOptions);
+    tick(budget?: SupplierTickBudget): Promise<SupplierTickResult>;
+    /**
+     * 拉取一个关系的所有配置来源。返回 true 表示预算耗尽应中断整个 tick。
+     * Agent Card 指纹变化 → review_required 并跳过后续来源（§8 第 5 步）。
+     */
+    private checkRelationship;
+    private checkCatalog;
+    private requireReview;
+    private diffCatalogSnapshot;
+    /** 返回 false 表示指纹变化已置 review_required，调用方停止该关系后续拉取。 */
+    private checkAgentCard;
+    private checkUcpProfile;
+    private intervalSeconds;
+    /** 成功后下次检查：连续无变化 interval×1.5 逐步放慢，封顶 24h（§8）。 */
+    private scheduleAfterSuccess;
+    /**
+     * 失败退避（§8 第 9 步）：transient 指数退避 2^min(n-1,5)×interval 封顶
+     * 24h + ±10% jitter；permanent（4xx/SSRF 拒绝/schema 拒绝）直接 24h。
+     * 同时写 unreachable observation（content_digest 去重，持续失败不刷屏）。
+     * 例外：本地安全策略拒绝（SSRF/redirect，observeUnreachable=false）不是
+     * 远程事实，只退避、不写 observation。
+     */
+    private recordFailure;
+    private getJson;
+}