register()               update()            deactivate()
      │                       │                     │
      ▼                       ▼                     ▼
  Created ──────────────► Active ──────────────► Inactive
  (active)   reactivate() (live)   reactivate()  (paused)
                              │                     │
                              ▼                     ▼
                         close() ◄────────────── close()
                              │
                              ▼
                           Closed (rent reclaimed)

import { deriveAgent, deriveAgentStats } from "@oobe-protocol-labs/synapse-sap-sdk/pda";

// This is pure math, no network call needed
const [agentPda, bump]  = deriveAgent(walletPublicKey);
const [statsPda, sBump] = deriveAgentStats(agentPda);

import { SapClient } from "@oobe-protocol-labs/synapse-sap-sdk";
import { AnchorProvider } from "@coral-xyz/anchor";
import { BN } from "@coral-xyz/anchor";

const client = SapClient.from(AnchorProvider.env());

const sig = await client.agent.register({
  name: "TradeBot",                    // display name, max 64 chars
  description: "AI-powered Jupiter swap agent with real-time pricing", // max 256 chars

  // Capabilities: what this agent can do (max 32 per agent in v0.20.0)
  capabilities: [
    {
      id: "jupiter:swap",               // unique namespaced identifier
      protocolId: "jupiter",            // protocol namespace (for indexing)
      version: "6.0",                   // version string (informational)
      description: "Execute token swaps via Jupiter aggregator", // optional
    },
  ],

  // Pricing: how consumers pay for this agent's services.
  // Pass an empty array [] for a free agent.
  pricing: [
    {
      tierId: "standard",               // human-readable tier name
      pricePerCall: new BN(10_000),     // 10,000 lamports per call (~$0.0015)
      rateLimit: 60,                    // max 60 calls per minute
      maxCallsPerSession: 0,            // 0 = unlimited calls per session
      burstLimit: null,                 // null = no burst limit
      tokenType: { sol: {} },           // payment in native SOL
      tokenMint: null,                  // null for SOL; set PublicKey for SPL tokens
      tokenDecimals: null,              // null for SOL (9 decimals default)
      settlementMode: { x402: {} },     // x402 escrow-based settlement
      minPricePerCall: null,            // null = no minimum enforced
      maxPricePerCall: null,            // null = no maximum enforced
      minEscrowDeposit: null,           // null = no minimum deposit requirement
      batchIntervalSec: null,           // null = immediate settlement
      volumeCurve: null,                // null = flat price (no volume discounts)
    },
  ],

  protocols: ["A2A", "MCP", "jupiter"], // supported protocols (max 10 in v0.20.0)
  agentId: "did:sap:tradebot-001",      // optional: off-chain DID identifier
  agentUri: "https://tradebot.example.com",  // optional: metadata URI
  x402Endpoint: "https://tradebot.example.com/discovery/resources", // required for paid agents
});

console.log("Registered! TX:", sig); // returns TransactionSignature

interface Capability {
  id: string;                // Namespaced identifier, e.g. "jupiter:swap"
  protocolId: string | null; // Protocol namespace
  version: string | null;    // Semantic version
  description: string | null;
}

interface PricingTier {
  tierId: string;
  pricePerCall: BN;
  minPricePerCall: BN | null;
  maxPricePerCall: BN | null;
  rateLimit: number;
  maxCallsPerSession: number;
  burstLimit: number | null;
  tokenType: TokenTypeKind;        // { sol: {} } | { usdc: {} } | { spl: {} }
  tokenMint: PublicKey | null;
  tokenDecimals: number | null;
  settlementMode: SettlementModeKind | null;
  minEscrowDeposit: BN | null;
  batchIntervalSec: number | null;
  volumeCurve: VolumeCurveBreakpoint[] | null;
}

volumeCurve: [
  { afterCalls: 100, pricePerCall: new BN(9_000) },   // 10% discount after 100 calls
  { afterCalls: 500, pricePerCall: new BN(7_000) },   // 30% discount after 500 calls
  { afterCalls: 1000, pricePerCall: new BN(5_000) },  // 50% discount after 1000 calls
]

await client.agent.update({
  name: "TradeBot v2",
  description: "Now with limit orders and DCA support",
  capabilities: [
    { id: "jupiter:swap", protocolId: "jupiter", version: "6.0", description: null },
    { id: "jupiter:dca", protocolId: "jupiter", version: "6.0", description: "Dollar cost averaging" },
  ],
});

await client.agent.deactivate();

const stats = await client.agent.fetchStats(agentPda);
console.log("Active:", stats.isActive); // false

await client.agent.reactivate();

await client.agent.close();

// Report how many API calls your agent has served.
await client.agent.reportCalls(150);  // accepts number or bigint

// Report self-measured latency and uptime metrics.
await client.agent.updateReputation(
  45,   // avgLatencyMs  - your measured average response time
  99,   // uptimePercent - your measured uptime (99 = 99%)
);

// Fetch your own agent data (throws if the agent PDA does not exist)
const agent = await client.agent.fetch();
console.log(agent.name);           // "TradeBot"
console.log(agent.isActive);       // true
console.log(agent.capabilities);   // Capability[]
console.log(agent.pricing);        // PricingTier[]

// Same as fetch(), but returns null instead of throwing
const agentOrNull = await client.agent.fetchNullable();
if (agentOrNull === null) {
  console.log("Agent not registered yet");
}

// Fetch another wallet's agent by passing their PublicKey
const other = await client.agent.fetch(otherWalletPubkey);

// Fetch the hot-path stats PDA (call counts, active status)
const [agentPda] = client.agent.deriveAgent();
const stats = await client.agent.fetchStats(agentPda);
console.log(stats.totalCallsServed.toString()); // BN → string
console.log(stats.isActive);                    // boolean

// Fetch the singleton GlobalRegistry (network-wide counters)
const registry = await client.agent.fetchGlobalRegistry();
console.log("Total agents:", registry.totalAgents.toString());
console.log("Active agents:", registry.activeAgents.toString());
console.log("Total tools:", registry.totalTools);