@paybond/kit 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -95,6 +95,553 @@ export declare class SignalHttpError extends Error {
         bodyText: string;
     });
 }
+export type SignalMetrics = {
+    terminal_intents: number;
+    released: number;
+    refunded: number;
+    disputed: number;
+    success_rate_bps: number;
+    dispute_rate_bps: number;
+    refund_rate_bps: number;
+    mean_latency_nanos: number;
+    latency_sample_count: number;
+    receipted_volume_cents: number;
+};
+export type SignalConfidence = {
+    band: string;
+    support_score: number;
+    summary: string;
+};
+export type SignalSupportDepth = {
+    band: string;
+    terminal_intents: number;
+    receipted_volume_cents: number;
+    history_depth: number;
+    latency_sample_count: number;
+};
+export type SignalExplanationMetricDelta = {
+    metric: string;
+    previous: number;
+    current: number;
+    delta: number;
+};
+export type SignalExplanationDelta = {
+    basis: string;
+    previous_score: number;
+    score_delta: number;
+    previous_ledger_watermark_seq: number;
+    changed_metrics: SignalExplanationMetricDelta[];
+    reason_codes_added: string[];
+    reason_codes_removed: string[];
+    summary: string;
+};
+export type SignalSignedReceipt = {
+    schema_version: number;
+    receipt_version: string;
+    tenant_id: string;
+    operator_did: string;
+    score_version: string;
+    scoring_model: string;
+    scoring_narrative: string;
+    explanation_summary: string;
+    ledger_watermark_seq: number;
+    reason_codes: string[];
+    confidence?: SignalConfidence;
+    support_depth?: SignalSupportDepth;
+    review_state?: string;
+    explanation_delta?: SignalExplanationDelta;
+    metrics: SignalMetrics;
+    score: number;
+    signing_algorithm: string;
+    message_digest_hex: string;
+    signing_public_key_hex: string;
+    signature_hex: string;
+};
+export type SignalReceiptEnvelope = {
+    schema_version: number;
+    updated_at: string;
+    receipt: SignalSignedReceipt;
+};
+export type SignalPortfolioOperator = {
+    operator_did: string;
+    receipt_version?: string;
+    score: number;
+    ledger_watermark_seq: number;
+    receipt_message_digest_hex: string;
+    confidence?: SignalConfidence;
+    support_depth?: SignalSupportDepth;
+    review_state?: string;
+    explanation_delta?: SignalExplanationDelta;
+};
+export type SignalSignedPortfolioArtifact = {
+    schema_version: number;
+    artifact_version: string;
+    kind: string;
+    tenant_id: string;
+    score_model_version: string;
+    scoring_model: string;
+    checkpoint_last_ledger_seq: number;
+    operators: SignalPortfolioOperator[];
+    signing_algorithm: string;
+    message_digest_hex: string;
+    signing_public_key_hex: string;
+    signature_hex: string;
+};
+export type SignalPortfolioSummary = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    scoring_model: string;
+    checkpoint_last_ledger_seq: number;
+    operator_count: number;
+    average_score: number;
+    total_terminal_intents: number;
+    total_receipted_volume_cents: number;
+    operators_under_review: number;
+};
+export type SignalFraudSeverity = "elevated" | "high" | "critical";
+export type SignalReviewState = "none" | "open" | "in_review" | "closed" | "all";
+export type SignalFraudSignal = {
+    code: string;
+    severity: SignalFraudSeverity | string;
+    category: string;
+    window: string;
+    evidence_count: number;
+    summary: string;
+    affects_score: false;
+    signal_source?: string;
+    first_seen_at?: string;
+    last_seen_at?: string;
+    evidence_binding_strength?: string;
+    provider_event_refs?: string[];
+    intent_refs?: string[];
+};
+export type SignalFraudAssessment = {
+    fraud_signal_version: string;
+    level: "none" | SignalFraudSeverity | string;
+    highest_severity: "none" | SignalFraudSeverity | string;
+    review_priority: "normal" | "elevated" | "high" | "urgent" | string;
+    signal_count: number;
+    severe_signal_count: number;
+    summary: string;
+};
+export type SignalFraudReleaseGateMode = "review_only" | "critical_hold";
+export type SignalFraudReleaseGateConfig = {
+    mode: SignalFraudReleaseGateMode | string;
+};
+export type SignalFraudSignalFamilyReliability = {
+    signal_family: string;
+    reliable: boolean;
+    stale: boolean;
+    sparse: boolean;
+    reviewed_count: number;
+    labeled_outcome_count: number;
+    review_precision_bps: number;
+    min_signal_family_labeled_outcome_count: number;
+    last_labeled_at?: string;
+    reasons: string[];
+    summary: string;
+};
+export type SignalFraudReleaseGateMetricsReliability = {
+    reliable: boolean;
+    stale: boolean;
+    sparse: boolean;
+    reviewed_count: number;
+    labeled_outcome_count: number;
+    review_precision_bps: number;
+    min_reviewed_count: number;
+    min_labeled_outcome_count: number;
+    min_signal_family_labeled_outcome_count: number;
+    min_review_precision_bps: number;
+    last_labeled_at?: string;
+    signal_families?: SignalFraudSignalFamilyReliability[];
+    reasons: string[];
+    summary: string;
+};
+export type SignalFraudReleaseGateDecision = {
+    mode: SignalFraudReleaseGateMode | string;
+    enforcement_enabled: boolean;
+    metrics_reliable: boolean;
+    release_allowed: boolean;
+    hold_required: boolean;
+    critical_signal_count: number;
+    critical_signal_codes: string[];
+    blocking_signal_codes?: string[];
+    blocking_evidence_refs?: string[];
+    reliability_reasons?: string[];
+    reasons: string[];
+    summary: string;
+};
+export type SignalFraudAssessmentResponse = {
+    schema_version: number;
+    tenant_id: string;
+    operator_did: string;
+    score_model_version: string;
+    review_state: string;
+    review_outcome: string;
+    review_reasons: string[];
+    fraud_signals: SignalFraudSignal[];
+    fraud_assessment: SignalFraudAssessment;
+    release_gate?: SignalFraudReleaseGateDecision;
+    [key: string]: unknown;
+};
+export type SignalFraudReviewQueueItem = {
+    operator_did: string;
+    review_state: string;
+    review_outcome: string;
+    review_reasons: string[];
+    anomaly_flagged: boolean;
+    opened_at: string;
+    reviewed_at: string;
+    updated_at: string;
+    last_receipt_message_digest_hex: string;
+    fraud_signals: SignalFraudSignal[];
+    fraud_assessment: SignalFraudAssessment;
+    release_gate?: SignalFraudReleaseGateDecision;
+    [key: string]: unknown;
+};
+export type SignalFraudReviewQueueResponse = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    items: SignalFraudReviewQueueItem[];
+};
+export type SignalFraudMetricsWindow = "24h" | "7d" | "30d";
+export type SignalFraudMetricsResponse = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    fraud_signal_version: string;
+    window: SignalFraudMetricsWindow | string;
+    window_started_at: string;
+    window_ended_at: string;
+    generated_at: string;
+    flagged_operator_count: number;
+    critical_signal_count: number;
+    high_signal_count: number;
+    elevated_signal_count: number;
+    review_open_count: number;
+    review_load_count: number;
+    reviewed_count: number;
+    labeled_outcome_count: number;
+    confirmed_risk_count: number;
+    false_positive_count: number;
+    needs_more_evidence_count: number;
+    review_precision_bps: number;
+    false_positive_rate_bps: number;
+    confirmed_risk_rate_bps: number;
+    labeled_coverage_bps: number;
+    median_time_to_review_seconds: number;
+    refund_burst_count: number;
+    dispute_cluster_count: number;
+    replay_appeal_abuse_count: number;
+    critical_signal_hold_candidate_count: number;
+    provider_signal_count: number;
+    stale_label_gap_seconds: number;
+    stale_signal_family_label_gap_count: number;
+    backtest_summary: string;
+    release_gate_config?: SignalFraudReleaseGateConfig;
+    release_gate_metrics_reliability?: SignalFraudReleaseGateMetricsReliability;
+};
+export type SignalFraudReleaseGateConfigResponse = {
+    schema_version: number;
+    tenant_id: string;
+    score_model_version: string;
+    fraud_signal_version: string;
+    generated_at: string;
+    config: SignalFraudReleaseGateConfig;
+    metrics_reliability: SignalFraudReleaseGateMetricsReliability;
+};
+export type SignalFraudReviewEventType = "review_open_requested" | "appeal_requested" | "replay_requested" | "review_outcome_recorded" | SignalFraudReviewOutcome;
+export type SignalFraudReviewOutcome = "confirmed_risk" | "false_positive" | "needs_more_evidence";
+export type SignalFraudReviewEventInput = {
+    eventType: SignalFraudReviewEventType | string;
+    reviewOutcome?: SignalFraudReviewOutcome | string;
+    review_outcome?: SignalFraudReviewOutcome | string;
+    signalCode?: string;
+    signal_code?: string;
+    intentId?: string;
+    intent_id?: string;
+    providerEventId?: string;
+    provider_event_id?: string;
+    summary: string;
+};
+export type SignalFraudReviewEventResponse = {
+    schema_version: number;
+    tenant_id: string;
+    operator_did: string;
+    score_model_version: string;
+    requested_event_type: string;
+    recorded_event_type: string;
+    review_outcome?: string;
+    signal_code?: string;
+    intent_id?: string;
+    provider_event_id?: string;
+    accepted: boolean;
+    next_eligible_at?: string;
+    [key: string]: unknown;
+};
+export type ListFraudReviewQueueOptions = {
+    state?: SignalReviewState | string;
+    severity?: SignalFraudSeverity | string;
+    limit?: number;
+    scoreVersion?: string;
+};
+export type GetFraudMetricsOptions = {
+    window?: SignalFraudMetricsWindow | string;
+    scoreVersion?: string;
+};
+export type A2AAgentCard = {
+    name: string;
+    description: string;
+    supportedInterfaces: Array<{
+        url: string;
+        protocolBinding: string;
+        protocolVersion: string;
+        tenant?: string;
+    }>;
+    provider?: {
+        url: string;
+        organization: string;
+    };
+    version: string;
+    documentationUrl?: string;
+    capabilities: {
+        streaming?: boolean;
+        pushNotifications?: boolean;
+        extendedAgentCard?: boolean;
+        extensions?: Array<{
+            uri?: string;
+            description?: string;
+            required?: boolean;
+            params?: Record<string, unknown>;
+        }>;
+    };
+    securitySchemes?: Record<string, unknown>;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: Array<{
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+        examples?: string[];
+        inputModes?: string[];
+        outputModes?: string[];
+        securityRequirements?: Array<Record<string, string[]>>;
+    }>;
+};
+export type A2ATaskField = {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+};
+export type A2ATaskParticipant = {
+    role: string;
+    required: boolean;
+    description: string;
+};
+export type A2ATaskExample = {
+    name: string;
+    description: string;
+    sampleInput?: Record<string, unknown>;
+    sampleResponse?: Record<string, unknown>;
+};
+export type A2ASettlementTaskContractV1 = {
+    schemaVersion: number;
+    kind: string;
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    routeBindings: string[];
+    requiredTrustArtifacts: string[];
+    settlementPhases: string[];
+    participants: A2ATaskParticipant[];
+    inputModes: string[];
+    outputModes: string[];
+    taskMetadataFields?: A2ATaskField[];
+    inputFields: A2ATaskField[];
+    resultFields: A2ATaskField[];
+    examples?: A2ATaskExample[];
+};
+export type A2ATaskContractCatalogV1 = {
+    schemaVersion: number;
+    kind: string;
+    agentCardUrl: string;
+    documentationUrl?: string;
+    contracts: A2ASettlementTaskContractV1[];
+};
+export type AgentMandateAuthorization = {
+    kind: string;
+    tenant_id: string;
+    principal_subject?: string;
+    principal_type?: string;
+};
+export type AgentMandateAgentIdentity = {
+    subject: string;
+    issuer?: string;
+    key_id?: string;
+    display_name?: string;
+};
+export type AgentMandateSpendCeiling = {
+    amount_minor: number;
+    currency: string;
+};
+export type AgentMandateSettlementRailPolicy = {
+    default_rail: string;
+    allowed_rails: string[];
+};
+export type AgentMandateConstraintReference = {
+    kind: string;
+    id?: string;
+    version?: string;
+    digest_sha256_hex?: string;
+    uri?: string;
+};
+export type AgentMandateV1 = {
+    schema_version: number;
+    kind: string;
+    authorization: AgentMandateAuthorization;
+    agent: AgentMandateAgentIdentity;
+    allowed_actions: string[];
+    allowed_tools: string[];
+    spend_ceiling: AgentMandateSpendCeiling;
+    settlement: AgentMandateSettlementRailPolicy;
+    constraint: AgentMandateConstraintReference;
+    expires_at: string;
+    nonce: string;
+    human_presence_mode: string;
+};
+export type SignedAgentMandateV1 = AgentMandateV1 & {
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type AgentRecognitionVerifierContext = {
+    tenant_id: string;
+    verifier_id: string;
+};
+export type AgentRecognitionRequestEnvelope = {
+    method: string;
+    path: string;
+    body_digest_sha256_hex: string;
+};
+export type AgentRecognitionProofV1 = {
+    schema_version?: number;
+    kind?: string;
+    key_id: string;
+    signature_algorithm?: string;
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+    purpose: string;
+    verifier_context: AgentRecognitionVerifierContext;
+    request_envelope: AgentRecognitionRequestEnvelope;
+    message_digest_sha256_hex?: string;
+    signing_public_key_ed25519_hex?: string;
+    ed25519_signature_hex?: string;
+};
+export type ProtocolTransportBindingV1 = {
+    source_protocol?: string;
+    partner_platform?: string;
+    external_authorization_id?: string;
+    request_id?: string;
+};
+export type ProtocolAuthorizationReceiptV1 = {
+    schema_version: number;
+    kind: string;
+    receipt_version: string;
+    receipt_id: string;
+    issued_at: string;
+    status: string;
+    intent_id: string;
+    tenant_id: string;
+    verifier_id: string;
+    transport_binding: ProtocolTransportBindingV1;
+    mandate_digest_sha256_hex: string;
+    imported_mandate_signing_public_key_ed25519_hex: string;
+    authorization: AgentMandateAuthorization;
+    agent: AgentMandateAgentIdentity;
+    allowed_actions: string[];
+    allowed_tools: string[];
+    spend_ceiling: AgentMandateSpendCeiling;
+    settlement: AgentMandateSettlementRailPolicy;
+    constraint: AgentMandateConstraintReference;
+    expires_at: string;
+    nonce: string;
+    human_presence_mode: string;
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type ProtocolSettlementReceiptV1 = {
+    schema_version: number;
+    kind: string;
+    receipt_version: string;
+    receipt_id: string;
+    issued_at: string;
+    intent_id: string;
+    tenant_id: string;
+    verifier_id: string;
+    transport_binding: ProtocolTransportBindingV1;
+    authorization_receipt_id: string;
+    mandate_digest_sha256_hex: string;
+    harbor_state: string;
+    predicate_passed?: boolean;
+    settlement_rail: string;
+    settlement_mode: string;
+    principal_did: string;
+    payee_did: string;
+    currency: string;
+    amount_cents: number;
+    terminal_observed_at: string;
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type ImportAgentMandateV1Result = {
+    valid: boolean;
+    intent_id: string;
+    mandate_digest_sha256_hex: string;
+    mandate: AgentMandateV1;
+    authorization_receipt: ProtocolAuthorizationReceiptV1;
+};
+export type VerifyProtocolReceiptV1Result = {
+    valid: boolean;
+    kind: string;
+    receipt_id: string;
+    tenant_id: string;
+    receipt: ProtocolAuthorizationReceiptV1 | ProtocolSettlementReceiptV1 | Record<string, unknown>;
+};
+export declare class A2AHttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    readonly bodyText: string;
+    constructor(message: string, init: {
+        statusCode: number;
+        url: string;
+        bodyText: string;
+    });
+}
+export declare class ProtocolHttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    readonly bodyText: string;
+    readonly errorCode?: string;
+    readonly errorMessage?: string;
+    constructor(message: string, init: {
+        statusCode: number;
+        url: string;
+        bodyText: string;
+        errorCode?: string;
+        errorMessage?: string;
+    });
+}
 /**
  * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
  * gateway response (no separate tenant env var for the default path).
@@ -261,6 +808,10 @@ type GatewaySignalClientOptions = {
     staticGatewayBearerToken: string;
     maxRetries?: number;
 };
+type GatewayFraudClientOptions = {
+    staticGatewayBearerToken: string;
+    maxRetries?: number;
+};
 /**
  * Tenant-bound reader for gateway Signal routes.
  */
@@ -273,17 +824,108 @@ export declare class GatewaySignalClient {
     private fetchGetWithRetries;
     private assertTenant;
     private scoreQuery;
-    getReputationReceipt(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
-    getPortfolioSummary(scoreVersion?: string): Promise<Record<string, unknown>>;
+    getReputationReceipt(operatorDid: string, scoreVersion?: string): Promise<SignalReceiptEnvelope | null>;
+    getPortfolioSummary(scoreVersion?: string): Promise<SignalPortfolioSummary>;
+    getSignedPortfolioArtifact(scoreVersion?: string): Promise<SignalSignedPortfolioArtifact>;
     getOperatorExplanation(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
     getOperatorReviewStatus(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
 }
+/**
+ * Tenant-bound client for gateway fraud review and metrics routes.
+ */
+export declare class GatewayFraudClient {
+    private readonly base;
+    readonly tenantId: string;
+    private readonly bearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, options: GatewayFraudClientOptions);
+    private fetchGetWithRetries;
+    private fetchPostJSON;
+    private fetchPutJSON;
+    private assertTenant;
+    private assertOperator;
+    private query;
+    private normalizedSeverity;
+    private normalizedWindow;
+    private normalizedReleaseGateMode;
+    private normalizedReviewEventType;
+    private normalizedReviewOutcome;
+    private optionalReviewContext;
+    getFraudAssessment(operatorDid: string, scoreVersion?: string): Promise<SignalFraudAssessmentResponse | null>;
+    listFraudReviewQueue(options?: ListFraudReviewQueueOptions): Promise<SignalFraudReviewQueueResponse>;
+    getFraudMetrics(options?: GetFraudMetricsOptions): Promise<SignalFraudMetricsResponse>;
+    getFraudReleaseGateConfig(scoreVersion?: string): Promise<SignalFraudReleaseGateConfigResponse>;
+    setFraudReleaseGateMode(mode: SignalFraudReleaseGateMode | string): Promise<SignalFraudReleaseGateConfigResponse>;
+    recordFraudReviewEvent(operatorDid: string, event: SignalFraudReviewEventInput, scoreVersion?: string): Promise<SignalFraudReviewEventResponse>;
+}
+type GatewayA2AClientOptions = {
+    staticGatewayBearerToken?: string;
+    maxRetries?: number;
+};
+/**
+ * Public or optionally authenticated reader for the gateway's A2A discovery surface.
+ */
+export declare class GatewayA2AClient {
+    private readonly base;
+    private readonly bearerToken?;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, options?: GatewayA2AClientOptions);
+    private fetchGetWithRetries;
+    getAgentCard(): Promise<A2AAgentCard>;
+    getTaskContracts(): Promise<A2ATaskContractCatalogV1>;
+    getTaskContract(contractId: string): Promise<A2ASettlementTaskContractV1>;
+}
+export declare class GatewayProtocolClient {
+    readonly tenantId: string;
+    private readonly base;
+    private readonly staticGatewayBearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, init?: {
+        staticGatewayBearerToken?: string;
+        maxRetries?: number;
+    });
+    private fetchWithRetries;
+    private headers;
+    private postJSON;
+    importAgentMandateV1(init: {
+        signedMandate: SignedAgentMandateV1;
+        intentId: string;
+        transportBinding?: ProtocolTransportBindingV1;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+    }): Promise<ImportAgentMandateV1Result>;
+    getSettlementReceiptV1(receiptId: string): Promise<ProtocolSettlementReceiptV1>;
+    verifyProtocolReceiptV1(receipt: ProtocolAuthorizationReceiptV1 | ProtocolSettlementReceiptV1 | Record<string, unknown>): Promise<VerifyProtocolReceiptV1Result>;
+    createHarborIntent(init: {
+        body: Record<string, unknown>;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    fundHarborIntent(init: {
+        intentId: string;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        paymentSignature?: string;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    submitHarborEvidence(init: {
+        intentId: string;
+        body: Record<string, unknown>;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+    confirmHarborSettlement(init: {
+        intentId: string;
+        body: Record<string, unknown>;
+        recognitionProof: AgentRecognitionProofV1 | Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<Record<string, unknown>>;
+}
 export type ServiceAccountSignalSessionInit = {
     gatewayBaseUrl: string;
     apiKey: string;
     principalPath?: string;
     maxRetries?: number;
 };
+export type ServiceAccountFraudSessionInit = ServiceAccountSignalSessionInit;
 /**
  * Read-only tenant-bound Signal session for one service-account API key.
  */
@@ -293,6 +935,15 @@ export declare class ServiceAccountSignalSession {
     static open(init: ServiceAccountSignalSessionInit): Promise<ServiceAccountSignalSession>;
     aclose(): Promise<void>;
 }
+/**
+ * Tenant-bound fraud review and metrics session for one service-account API key.
+ */
+export declare class ServiceAccountFraudSession {
+    readonly fraud: GatewayFraudClient;
+    private constructor();
+    static open(init: ServiceAccountFraudSessionInit): Promise<ServiceAccountFraudSession>;
+    aclose(): Promise<void>;
+}
 /**
  * Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client).
  * `settlementRail`, when set, requests one allowed rail; Harbor still resolves the destination
@@ -337,6 +988,9 @@ export declare class PaybondIntents {
 export declare class Paybond {
     readonly harbor: HarborClient;
     readonly signal: GatewaySignalClient;
+    readonly fraud: GatewayFraudClient;
+    readonly a2a: GatewayA2AClient;
+    readonly protocol: GatewayProtocolClient;
     readonly intents: PaybondIntents;
     private readonly session;
     private constructor();