@umpledger/sdk 2.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,839 @@
+type AgentType = 'HUMAN' | 'ORGANIZATION' | 'AI_AGENT' | 'SERVICE' | 'COMPOSITE';
+type AgentStatus = 'ACTIVE' | 'SUSPENDED' | 'REVOKED' | 'EXPIRED';
+interface AuthorityScope {
+    maxPerTransaction: number;
+    maxPerDay: number;
+    maxPerMonth: number;
+    allowedServices?: string[];
+    allowedCounterparties?: string[];
+    requiresApprovalAbove?: number;
+    autoRevokeAfter?: number;
+}
+interface VerificationProof {
+    publicKey: string;
+    issuingAuthority: string;
+    expiresAt: Date;
+    revocationEndpoint?: string;
+}
+interface AgentIdentity {
+    agentId: string;
+    agentType: AgentType;
+    parentId: string | null;
+    displayName: string;
+    capabilities: string[];
+    authorityScope: AuthorityScope;
+    verification: VerificationProof;
+    metadata: Record<string, unknown>;
+    status: AgentStatus;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreateAgentOptions {
+    name: string;
+    type: AgentType;
+    parentId?: string;
+    capabilities?: string[];
+    authority: Partial<AuthorityScope> & {
+        maxPerTransaction: number | string;
+        maxPerDay: number | string;
+    };
+    metadata?: Record<string, unknown>;
+}
+type ValueUnitType = 'FIAT' | 'AI_TOKEN' | 'COMPUTE_CREDIT' | 'OUTCOME_SCORE' | 'PLATFORM_CREDIT' | 'ENVIRONMENTAL';
+interface Balance {
+    valueUnitType: ValueUnitType;
+    currency?: string;
+    amount: number;
+    reserved: number;
+    available: number;
+}
+interface FundingConfig {
+    type: 'LINKED_BANK' | 'PARENT_DRAWDOWN' | 'PREPAID';
+    sourceId: string;
+    autoTopup?: AutoTopupRule;
+}
+interface AutoTopupRule {
+    threshold: number;
+    amount: number;
+    maxPerDay: number;
+}
+interface LedgerEntry {
+    entryId: string;
+    timestamp: Date;
+    type: 'DEBIT' | 'CREDIT' | 'RESERVE' | 'RELEASE' | 'TOPUP';
+    amount: number;
+    valueUnitType: ValueUnitType;
+    currency?: string;
+    counterpartyAgentId?: string;
+    transactionId?: string;
+    description: string;
+    balanceAfter: number;
+}
+interface Wallet {
+    walletId: string;
+    ownerAgentId: string;
+    balances: Balance[];
+    fundingSource?: FundingConfig;
+    frozen: boolean;
+    createdAt: Date;
+}
+interface FundWalletOptions {
+    amount: number | string;
+    source?: string;
+    valueUnitType?: ValueUnitType;
+    currency?: string;
+}
+type PricingPrimitive = 'FIXED' | 'UNIT_RATE' | 'TIERED' | 'PERCENTAGE' | 'THRESHOLD' | 'TIME_WINDOW' | 'CONDITIONAL' | 'COMPOSITE';
+type CompositeOperator = 'ADD' | 'MAX' | 'MIN' | 'FIRST_MATCH';
+interface PricingRuleBase {
+    ruleId: string;
+    name: string;
+    description?: string;
+    primitive: PricingPrimitive;
+}
+interface FixedRule extends PricingRuleBase {
+    primitive: 'FIXED';
+    amount: number;
+    period?: 'PER_EVENT' | 'HOURLY' | 'DAILY' | 'MONTHLY' | 'YEARLY';
+}
+interface UnitRateRule extends PricingRuleBase {
+    primitive: 'UNIT_RATE';
+    rate: number;
+    unit: string;
+}
+interface TierBand {
+    from: number;
+    to: number | null;
+    rate: number;
+}
+interface TieredRule extends PricingRuleBase {
+    primitive: 'TIERED';
+    tiers: TierBand[];
+    mode: 'GRADUATED' | 'VOLUME';
+}
+interface PercentageRule extends PricingRuleBase {
+    primitive: 'PERCENTAGE';
+    percentage: number;
+    referenceField: string;
+    min?: number;
+    max?: number;
+}
+interface ThresholdRule extends PricingRuleBase {
+    primitive: 'THRESHOLD';
+    threshold: number;
+    belowRate: number;
+    aboveRate: number;
+}
+interface TimeWindowBand {
+    dayOfWeek?: number[];
+    startHour: number;
+    endHour: number;
+    rate: number;
+    label?: string;
+}
+interface TimeWindowRule extends PricingRuleBase {
+    primitive: 'TIME_WINDOW';
+    windows: TimeWindowBand[];
+    defaultRate: number;
+    timezone: string;
+}
+interface ConditionalBranch {
+    condition: string;
+    rule: PricingRule;
+}
+interface ConditionalRule extends PricingRuleBase {
+    primitive: 'CONDITIONAL';
+    field: string;
+    branches: ConditionalBranch[];
+    fallback?: PricingRule;
+}
+interface CompositeRule extends PricingRuleBase {
+    primitive: 'COMPOSITE';
+    operator: CompositeOperator;
+    rules: PricingRule[];
+}
+type PricingRule = FixedRule | UnitRateRule | TieredRule | PercentageRule | ThresholdRule | TimeWindowRule | ConditionalRule | CompositeRule;
+type ContractMode = 'PRE_NEGOTIATED' | 'TEMPLATE' | 'DYNAMIC';
+type ContractStatus = 'DRAFT' | 'PROPOSED' | 'ACTIVE' | 'EXPIRED' | 'TERMINATED';
+interface Contract {
+    contractId: string;
+    mode: ContractMode;
+    status: ContractStatus;
+    parties: {
+        sourceAgentId: string;
+        targetAgentId: string;
+    };
+    pricingRules: PricingRule[];
+    effectiveFrom: Date;
+    effectiveUntil?: Date;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+}
+interface CreateContractOptions {
+    mode?: ContractMode;
+    targetAgentId: string;
+    pricingRules: Omit<PricingRule, 'ruleId'>[];
+    effectiveFrom?: Date;
+    effectiveUntil?: Date;
+    metadata?: Record<string, unknown>;
+}
+interface UsageEvent {
+    eventId: string;
+    sourceAgentId: string;
+    targetAgentId: string;
+    contractId: string;
+    serviceId: string;
+    timestamp: Date;
+    quantity: number;
+    unit: string;
+    dimensions: Record<string, string | number>;
+    outcome?: OutcomeAttestation;
+    signature?: string;
+}
+type OutcomeType = 'TASK_COMPLETION' | 'METRIC_IMPROVEMENT' | 'REVENUE_GENERATED' | 'COST_SAVED' | 'CUSTOM';
+type VerificationMethod = 'SELF_REPORTED' | 'BILATERAL_AGREEMENT' | 'THIRD_PARTY_ORACLE' | 'AUTOMATED_TEST';
+type AttestationStatus = 'CLAIMED' | 'VERIFIED' | 'DISPUTED' | 'EXPIRED';
+interface OutcomeAttestation {
+    outcomeId: string;
+    outcomeType: OutcomeType;
+    claimedBy: string;
+    evidence: Evidence[];
+    verificationMethod: VerificationMethod;
+    verifiedBy?: string;
+    confidenceScore: number;
+    attestationStatus: AttestationStatus;
+    disputeWindow: number;
+}
+interface Evidence {
+    type: 'LOG' | 'METRIC' | 'SCREENSHOT' | 'THIRD_PARTY' | 'TEST_RESULT';
+    uri: string;
+    hash: string;
+    description?: string;
+}
+type SettlementPattern = 'INSTANT_DRAWDOWN' | 'ESCROW_RELEASE' | 'WATERFALL_SPLIT' | 'NET_SETTLEMENT' | 'CONDITIONAL_RELEASE' | 'CROSS_CURRENCY_ATOMIC';
+type SettlementStatus = 'PENDING' | 'PROCESSING' | 'SETTLED' | 'FAILED' | 'REVERSED';
+interface RatedRecord {
+    ratedRecordId: string;
+    usageEventId: string;
+    contractId: string;
+    pricingRuleId: string;
+    quantity: number;
+    rate: number;
+    amount: number;
+    currency: string;
+    ratedAt: Date;
+}
+interface Settlement {
+    settlementId: string;
+    pattern: SettlementPattern;
+    status: SettlementStatus;
+    sourceAgentId: string;
+    targetAgentId: string;
+    ratedRecords: RatedRecord[];
+    totalAmount: number;
+    currency: string;
+    settledAt?: Date;
+    auditId: string;
+}
+interface TransactOptions {
+    from: string;
+    to: string;
+    service: string;
+    payload?: Record<string, unknown>;
+    maxCost?: number | string;
+}
+interface TransactionResult {
+    transactionId: string;
+    cost: number;
+    currency: string;
+    outcome?: OutcomeAttestation;
+    auditId: string;
+    settledAt: Date;
+    duration: number;
+}
+interface AuditRecord {
+    auditId: string;
+    what: {
+        operation: string;
+        entityType: string;
+        entityId: string;
+        amount?: number;
+    };
+    who: {
+        sourceAgentId: string;
+        targetAgentId: string;
+        humanOwnerId?: string;
+    };
+    when: Date;
+    why: {
+        contractId?: string;
+        pricingRuleId?: string;
+        justification?: string;
+    };
+    how: {
+        policiesEvaluated: string[];
+        policiesPassed: string[];
+        overrides?: string[];
+    };
+    result: {
+        balanceBefore?: number;
+        balanceAfter?: number;
+        settlementAmount?: number;
+        status: string;
+    };
+}
+type DisputeStage = 'AUTOMATED_RECONCILIATION' | 'AGENT_NEGOTIATION' | 'ARBITRATION_ORACLE' | 'HUMAN_ESCALATION';
+type DisputeStatus = 'OPEN' | 'IN_PROGRESS' | 'RESOLVED' | 'ESCALATED' | 'CLOSED';
+interface Dispute {
+    disputeId: string;
+    transactionId: string;
+    openedBy: string;
+    respondent: string;
+    stage: DisputeStage;
+    status: DisputeStatus;
+    reason: string;
+    evidence: Evidence[];
+    amount: number;
+    resolution?: {
+        outcome: 'UPHELD' | 'REJECTED' | 'PARTIAL';
+        adjustedAmount: number;
+    };
+    openedAt: Date;
+    resolvedAt?: Date;
+}
+type PolicyType = 'SPENDING_LIMIT' | 'COUNTERPARTY_ALLOWLIST' | 'SERVICE_ALLOWLIST' | 'RATE_REASONABLENESS' | 'OUTCOME_VERIFICATION' | 'COMPLIANCE' | 'ANOMALY_DETECTION' | 'BUDGET_ALLOCATION';
+type ViolationAction = 'HARD_BLOCK' | 'SOFT_BLOCK' | 'ALERT' | 'LOG';
+interface Policy {
+    policyId: string;
+    type: PolicyType;
+    agentId: string;
+    config: Record<string, unknown>;
+    violationAction: ViolationAction;
+    enabled: boolean;
+}
+interface UMPConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    onAudit?: (record: AuditRecord) => void;
+}
+
+/**
+ * AgentManager — Layer 1 primitive
+ *
+ * Manages Agent Identity lifecycle: creation, verification,
+ * authority scope enforcement, hierarchical revocation.
+ */
+declare class AgentManager {
+    private agents;
+    /**
+     * Register a new Agent Identity with authority scope.
+     */
+    create(options: CreateAgentOptions): AgentIdentity;
+    /**
+     * Retrieve an agent by ID.
+     */
+    get(agentId: string): AgentIdentity;
+    /**
+     * Update authority scope (tightening is always allowed; loosening requires parent).
+     */
+    updateAuthority(agentId: string, newScope: Partial<AuthorityScope>): AgentIdentity;
+    /**
+     * Revoke an agent and cascade to all children.
+     */
+    revoke(agentId: string): string[];
+    /**
+     * Verify that an agent's identity is valid and active.
+     */
+    verify(agentId: string): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Check if a transaction amount is within the agent's authority scope.
+     */
+    checkAuthority(agentId: string, amount: number, counterpartyId?: string, serviceId?: string): {
+        allowed: boolean;
+        reason?: string;
+        requiresApproval?: boolean;
+    };
+    /**
+     * List all agents, optionally filtered.
+     */
+    list(filter?: {
+        parentId?: string;
+        type?: AgentType;
+        status?: AgentStatus;
+    }): AgentIdentity[];
+}
+
+/**
+ * WalletManager — Layer 1 primitive
+ *
+ * Manages wallets, balances, reserves, and the immutable spending ledger.
+ * Every financial operation is recorded as a LedgerEntry.
+ */
+declare class WalletManager {
+    private wallets;
+    private ledgers;
+    /**
+     * Create a wallet for an agent.
+     */
+    create(ownerAgentId: string): Wallet;
+    /**
+     * Get wallet by ID.
+     */
+    get(walletId: string): Wallet;
+    /**
+     * Get wallet by owner agent ID.
+     */
+    getByAgent(agentId: string): Wallet;
+    /**
+     * Fund a wallet (add money).
+     */
+    fund(walletId: string, options: FundWalletOptions): LedgerEntry;
+    /**
+     * Reserve funds for a pending transaction (escrow pattern).
+     */
+    reserve(walletId: string, amount: number, counterpartyAgentId: string, transactionId: string): LedgerEntry;
+    /**
+     * Debit wallet (immediate drawdown).
+     */
+    debit(walletId: string, amount: number, counterpartyAgentId: string, transactionId: string): LedgerEntry;
+    /**
+     * Credit wallet (receive payment).
+     */
+    credit(walletId: string, amount: number, counterpartyAgentId: string, transactionId: string): LedgerEntry;
+    /**
+     * Release reserved funds (escrow release after outcome).
+     */
+    releaseReservation(walletId: string, amount: number, transactionId: string): LedgerEntry;
+    /**
+     * Emergency freeze — blocks all transactions.
+     */
+    freeze(walletId: string): void;
+    /**
+     * Unfreeze wallet.
+     */
+    unfreeze(walletId: string): void;
+    /**
+     * Get immutable ledger entries for a wallet.
+     */
+    getLedger(walletId: string, limit?: number, offset?: number): LedgerEntry[];
+    /**
+     * Get real-time balance summary.
+     */
+    getBalance(walletId: string): Balance[];
+    private getPrimaryBalance;
+    private getOrCreateBalance;
+    private appendLedger;
+}
+
+/**
+ * AuditTrail — Layer 3 primitive
+ *
+ * Immutable append-only log of every UMP operation.
+ * Captures 6 dimensions: WHAT, WHO, WHEN, WHY, HOW, RESULT.
+ */
+declare class AuditTrail {
+    private records;
+    private onAudit?;
+    constructor(onAudit?: (record: AuditRecord) => void);
+    /**
+     * Record an audit entry. Returns the audit ID.
+     */
+    record(data: Omit<AuditRecord, 'auditId' | 'when'>): string;
+    /**
+     * Query audit records with filters.
+     */
+    query(filters?: {
+        agentId?: string;
+        operation?: string;
+        fromDate?: Date;
+        toDate?: Date;
+        minAmount?: number;
+        contractId?: string;
+    }, limit?: number, offset?: number): AuditRecord[];
+    /**
+     * Get a specific audit record by ID.
+     */
+    get(auditId: string): AuditRecord | undefined;
+    /**
+     * Get total count of records.
+     */
+    count(): number;
+}
+
+/**
+ * Context passed into the rating engine for each usage event.
+ * Contains the event data plus any external dimensions needed
+ * for conditional evaluation.
+ */
+interface RatingContext {
+    event: UsageEvent;
+    cumulativeQuantity?: number;
+    referenceAmount?: number;
+    currentTime?: Date;
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * PricingEngine — Layer 2 primitive
+ *
+ * Evaluates the 8 atomic pricing primitives and their compositions.
+ * Takes usage events + pricing rules → rated records (billable amounts).
+ */
+declare class PricingEngine {
+    /**
+     * Rate a single usage event against a pricing rule.
+     * Returns the calculated amount.
+     */
+    rate(rule: PricingRule, context: RatingContext): RatedRecord;
+    /**
+     * Rate multiple usage events against a pricing rule.
+     */
+    rateBatch(rule: PricingRule, events: UsageEvent[]): RatedRecord[];
+    /**
+     * Simulate: calculate projected cost without creating rated records.
+     */
+    simulate(rule: PricingRule, quantity: number, dimensions?: Record<string, string | number>): number;
+    /**
+     * Human-readable breakdown of how a price was calculated.
+     */
+    explain(rule: PricingRule, context: RatingContext): string;
+    private evaluate;
+    /**
+     * FIXED: flat amount per event or period.
+     */
+    private evalFixed;
+    /**
+     * UNIT_RATE: rate × quantity.
+     */
+    private evalUnitRate;
+    /**
+     * TIERED: different rates at different consumption levels.
+     * Supports GRADUATED (each unit at its tier's rate) and VOLUME (all units at qualifying tier).
+     */
+    private evalTiered;
+    /**
+     * PERCENTAGE: fraction of a reference amount.
+     */
+    private evalPercentage;
+    /**
+     * THRESHOLD: binary trigger — different rates above/below threshold.
+     */
+    private evalThreshold;
+    /**
+     * TIME_WINDOW: rate varies by when consumption occurs.
+     */
+    private evalTimeWindow;
+    /**
+     * CONDITIONAL: price depends on an attribute or outcome.
+     */
+    private evalConditional;
+    /**
+     * COMPOSITE: combines multiple rules with an operator.
+     */
+    private evalComposite;
+    private evaluateCondition;
+    private buildExplanation;
+}
+
+/**
+ * ContractManager — Layer 1/2 bridge
+ *
+ * Manages commercial agreements between agents.
+ * Supports pre-negotiated, template-based, and dynamic negotiation.
+ */
+declare class ContractManager {
+    private contracts;
+    /**
+     * Create a new contract between two agents.
+     */
+    create(sourceAgentId: string, options: CreateContractOptions): Contract;
+    /**
+     * Get contract by ID.
+     */
+    get(contractId: string): Contract;
+    /**
+     * Find active contract between two agents.
+     */
+    findActive(sourceAgentId: string, targetAgentId: string): Contract | undefined;
+    /**
+     * Dynamic negotiation: propose terms.
+     * Returns a DRAFT contract that the counterparty can accept or counter.
+     */
+    propose(sourceAgentId: string, options: CreateContractOptions): Contract;
+    /**
+     * Accept a proposed contract — transitions to ACTIVE.
+     */
+    accept(contractId: string): Contract;
+    /**
+     * Counter-propose: create a new proposal based on an existing one with modified terms.
+     */
+    counter(contractId: string, counterAgentId: string, modifiedRules: Omit<PricingRule, 'ruleId'>[]): Contract;
+    /**
+     * Terminate a contract.
+     */
+    terminate(contractId: string): Contract;
+    /**
+     * List contracts for an agent.
+     */
+    listByAgent(agentId: string, status?: ContractStatus): Contract[];
+}
+
+/**
+ * MeteringEngine — Layer 2 primitive
+ *
+ * Captures usage events with cryptographic integrity.
+ * Supports idempotent event submission, deduplication, and
+ * outcome attestation for result-based billing.
+ */
+declare class MeteringEngine {
+    private events;
+    private seenIds;
+    /**
+     * Record a usage event.
+     * Idempotent: resubmitting the same eventId is a no-op.
+     */
+    record(event: Omit<UsageEvent, 'eventId' | 'timestamp'> & {
+        eventId?: string;
+    }): UsageEvent;
+    /**
+     * Record a batch of usage events.
+     */
+    recordBatch(events: Array<Omit<UsageEvent, 'eventId' | 'timestamp'>>): UsageEvent[];
+    /**
+     * Create an outcome attestation for result-based billing.
+     */
+    attestOutcome(data: {
+        outcomeType: OutcomeAttestation['outcomeType'];
+        claimedBy: string;
+        evidence: OutcomeAttestation['evidence'];
+        verificationMethod: OutcomeAttestation['verificationMethod'];
+        confidenceScore: number;
+        disputeWindow?: number;
+    }): OutcomeAttestation;
+    /**
+     * Get events for a contract within a time range.
+     */
+    getByContract(contractId: string, from?: Date, to?: Date): UsageEvent[];
+    /**
+     * Get events for a specific agent (as source or target).
+     */
+    getByAgent(agentId: string, limit?: number): UsageEvent[];
+    /**
+     * Get a specific event by ID.
+     */
+    get(eventId: string): UsageEvent | undefined;
+    /**
+     * Get total metered quantity for a contract.
+     */
+    totalQuantity(contractId: string): number;
+}
+
+interface SettlementResult {
+    settlement: Settlement;
+    auditId: string;
+}
+/**
+ * SettlementBus — Layer 3 primitive
+ *
+ * Executes real-time settlement between agent wallets.
+ * Supports 6 patterns: instant drawdown, escrow, waterfall,
+ * net settlement, conditional release, cross-currency atomic.
+ */
+declare class SettlementBus {
+    private wallets;
+    private audit;
+    private pricingEngine;
+    private settlements;
+    private escrows;
+    constructor(wallets: WalletManager, audit: AuditTrail, pricingEngine: PricingEngine);
+    /**
+     * Execute a full transaction: meter → rate → settle in one call.
+     * This is the high-level "transact" method from the Quick Start.
+     */
+    transact(sourceAgentId: string, targetAgentId: string, event: UsageEvent, rule: PricingRule): Promise<SettlementResult>;
+    /**
+     * INSTANT_DRAWDOWN: Debit source, credit target atomically.
+     * Used for per-token, per-inference micro-transactions.
+     */
+    settleInstant(sourceAgentId: string, targetAgentId: string, ratedRecords: RatedRecord[], _startTime?: number): SettlementResult;
+    /**
+     * ESCROW_RELEASE: Reserve funds, release upon outcome attestation.
+     * Used for outcome-based pricing and milestone payments.
+     */
+    createEscrow(sourceAgentId: string, targetAgentId: string, amount: number, transactionId: string): string;
+    /**
+     * Release escrowed funds to the target (full or partial).
+     */
+    releaseEscrow(escrowId: string, releaseAmount?: number): SettlementResult;
+    /**
+     * WATERFALL_SPLIT: Distribute payment across multiple parties.
+     * Used for marketplace commissions and multi-party revenue share.
+     */
+    settleWaterfall(sourceAgentId: string, splits: Array<{
+        agentId: string;
+        amount: number;
+    }>, ratedRecords: RatedRecord[]): SettlementResult[];
+    /**
+     * Get settlement by ID.
+     */
+    get(settlementId: string): Settlement | undefined;
+    /**
+     * List settlements for an agent.
+     */
+    listByAgent(agentId: string, limit?: number): Settlement[];
+}
+
+/**
+ * Pre-built pricing rule templates for common AI-era models.
+ * These are convenience factories — all decompose into the 8 atomic primitives.
+ */
+declare const PricingTemplates: {
+    /**
+     * Per-Token LLM pricing (separate input/output rates).
+     * Example: GPT-4 at $30/M input, $60/M output tokens.
+     */
+    perToken(inputRatePerMillion: number, outputRatePerMillion: number): PricingRule;
+    /**
+     * Per-Inference pricing with volume tiers.
+     * Example: $0.01/call for first 10K, $0.005/call after.
+     */
+    perInference(tiers: Array<{
+        upTo: number | null;
+        rate: number;
+    }>): PricingRule;
+    /**
+     * Per-Resolution / outcome-based pricing.
+     * Charges only on successful outcome + percentage of value.
+     */
+    perResolution(successFee: number, valuePct: number): PricingRule;
+    /**
+     * Subscription + Usage hybrid.
+     * Base monthly fee + per-unit overage above included units.
+     */
+    subscriptionPlusUsage(monthlyBase: number, includedUnits: number, overageRate: number): PricingRule;
+    /**
+     * Credit pool with per-unit drawdown.
+     */
+    creditPool(creditCost: number): PricingRule;
+    /**
+     * Spot compute pricing with peak/off-peak rates.
+     */
+    computeSpot(peakRate: number, offPeakRate: number, peakHours?: [number, number]): PricingRule;
+    /**
+     * Marketplace commission (percentage take rate with floor and cap).
+     */
+    marketplaceCommission(takeRate: number, minFee: number, maxFee: number): PricingRule;
+    /**
+     * Agent-to-agent task pricing (fixed per-task + outcome bonus).
+     */
+    agentTask(basePerTask: number, bonusOnSuccess: number): PricingRule;
+};
+
+/**
+ * UMP Error Hierarchy
+ * All SDK errors extend UMPError for easy catch-all handling.
+ */
+declare class UMPError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare class AuthorityExceededError extends UMPError {
+    readonly limit: number;
+    readonly attempted: number;
+    constructor(limitType: string, limit: number, attempted: number);
+}
+declare class InsufficientFundsError extends UMPError {
+    readonly available: number;
+    readonly required: number;
+    constructor(available: number, required: number);
+}
+declare class WalletFrozenError extends UMPError {
+    constructor(walletId: string);
+}
+declare class AgentNotFoundError extends UMPError {
+    constructor(agentId: string);
+}
+declare class AgentRevokedError extends UMPError {
+    constructor(agentId: string);
+}
+declare class ContractNotFoundError extends UMPError {
+    constructor(contractId: string);
+}
+declare class PolicyViolationError extends UMPError {
+    readonly policyType: string;
+    readonly action: string;
+    constructor(policyType: string, action: string, details: string);
+}
+declare class DisputeError extends UMPError {
+    constructor(message: string);
+}
+
+/**
+ * ═══════════════════════════════════════════════════════════════
+ * @ump/sdk — Universal Monetization Protocol v2.0
+ *
+ * The payment rail for the autonomous economy.
+ * When AI agents transact with AI agents, UMP governs
+ * how value flows between them.
+ *
+ * Quick Start:
+ *   const ump = new UMP({ apiKey: "ump_sk_..." });
+ *   const agent = ump.agents.create({ name: "my-agent", type: "AI_AGENT", authority: { maxPerTransaction: "$50", maxPerDay: "$500" } });
+ *   await ump.transact({ from: agent.agentId, to: "agent_target", service: "code_review" });
+ *
+ * Architecture: 3 layers
+ *   L1: Identity & Value  (AgentManager, WalletManager)
+ *   L2: Terms & Metering  (ContractManager, MeteringEngine, PricingEngine)
+ *   L3: Settlement & Gov  (SettlementBus, AuditTrail)
+ *
+ * © 2026 UMPLedger — Apache 2.0 License
+ * ═══════════════════════════════════════════════════════════════
+ */
+
+/**
+ * Convenience wrapper: an agent + its wallet in one object.
+ */
+interface AgentHandle {
+    id: string;
+    agent: AgentIdentity;
+    wallet: {
+        fund: (options: FundWalletOptions) => void;
+        balance: () => number;
+        freeze: () => void;
+        unfreeze: () => void;
+    };
+}
+/**
+ * UMP — Main SDK Entry Point
+ *
+ * Orchestrates all three protocol layers through a clean API.
+ */
+declare class UMP {
+    readonly agents: AgentManager;
+    readonly wallets: WalletManager;
+    readonly contracts: ContractManager;
+    readonly metering: MeteringEngine;
+    readonly pricing: PricingEngine;
+    readonly settlement: SettlementBus;
+    readonly audit: AuditTrail;
+    constructor(config: UMPConfig);
+    /**
+     * High-level: Register an agent and create its wallet.
+     * Returns an AgentHandle with convenience methods.
+     */
+    registerAgent(options: CreateAgentOptions): AgentHandle;
+    /**
+     * High-level: Execute a priced transaction between two agents.
+     *
+     * This is the "10 lines of code" Quick Start method.
+     * It finds or creates a contract, meters the event, rates it,
+     * settles payment, and returns the result — all in one call.
+     */
+    transact(options: TransactOptions): Promise<TransactionResult>;
+}
+
+export { type AgentHandle, type AgentIdentity, AgentManager, AgentNotFoundError, AgentRevokedError, type AgentStatus, type AgentType, type AttestationStatus, type AuditRecord, AuditTrail, AuthorityExceededError, type AuthorityScope, type AutoTopupRule, type Balance, type CompositeOperator, type CompositeRule, type ConditionalBranch, type ConditionalRule, type Contract, ContractManager, type ContractMode, ContractNotFoundError, type ContractStatus, type CreateAgentOptions, type CreateContractOptions, type Dispute, DisputeError, type DisputeStage, type DisputeStatus, type Evidence, type FixedRule, type FundWalletOptions, type FundingConfig, InsufficientFundsError, type LedgerEntry, MeteringEngine, type OutcomeAttestation, type OutcomeType, type PercentageRule, type Policy, type PolicyType, PolicyViolationError, PricingEngine, type PricingPrimitive, type PricingRule, type PricingRuleBase, PricingTemplates, type RatedRecord, type RatingContext, type Settlement, SettlementBus, type SettlementPattern, type SettlementResult, type SettlementStatus, type ThresholdRule, type TierBand, type TieredRule, type TimeWindowBand, type TimeWindowRule, type TransactOptions, type TransactionResult, UMP, type UMPConfig, UMPError, type UnitRateRule, type UsageEvent, type ValueUnitType, type VerificationMethod, type VerificationProof, type ViolationAction, type Wallet, WalletFrozenError, WalletManager };