SapError (base)
├── SapValidationError      — invalid inputs, length limits, type mismatches
├── SapRpcError             — network timeouts, 429 rate limits, node failures
├── SapAccountNotFoundError — PDA doesn't exist, account not initialized
├── SapTimeoutError         — operation exceeded timeout threshold
├── SapPermissionError      — wrong signer, delegate lacks permission
├── SapInstructionError     — on-chain instruction failed (v0.20.0)
└── SapDisputeError         — dispute-related errors (v0.20.0)

import {
  SapError,
  SapValidationError,
  SapRpcError,
  SapAccountNotFoundError,
  SapTimeoutError,
  SapPermissionError,
  SapInstructionError,
} from "@oobe-protocol-labs/synapse-sap-sdk";

try {
  await client.builder
    .agent("MyAgent")
    .description("Service agent")
    .register();
} catch (error: unknown) {
  if (error instanceof SapAccountNotFoundError) {
    // PDA doesn't exist yet - expected on first run
    console.log("Agent not found - needs registration");
  } else if (error instanceof SapValidationError) {
    // Bad inputs - fix calling code
    console.error("Validation:", error.message);
  } else if (error instanceof SapRpcError) {
    // Network issue - retry with backoff
    console.error("RPC:", error.message);
  } else if (error instanceof SapTimeoutError) {
    // Timed out - retry or increase timeout
    console.error("Timeout:", error.message);
  } else if (error instanceof SapPermissionError) {
    // Wrong signer or delegate lacks permission
    console.error("Permission:", error.message);
  } else if (error instanceof SapInstructionError) {
    // On-chain instruction failed - check program logs
    console.error("Instruction:", error.code, error.logs);
  } else if (error instanceof SapError) {
    // Other SDK error
    console.error("SAP:", error.message);
  } else {
    console.error("Unexpected:", error);
  }
}

import {
  classifyAnchorError,
  extractAnchorErrorCode,
} from "@oobe-protocol-labs/synapse-sap-sdk";

try {
  await client.agent.register(/* ... */);
} catch (error: unknown) {
  if (error instanceof Error) {
    // Extract the numeric error code from the message
    const code = extractAnchorErrorCode(error);
    // code → 6000 (number) or null if not an Anchor error

    // Classify into a structured object
    const classified = classifyAnchorError(error);
    // classified → { code: 6000, name: "AgentAlreadyRegistered", ... }
    // or null if the error isn't from Anchor

    if (code === 6000) {
      console.log("Agent already registered - skipping.");
    }
  }
}

// src/app/api/sap/agent/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  try {
    const agent = await client.agent.fetch();
    return NextResponse.json({ data: agent });
  } catch (error: unknown) {
    const message =
      error instanceof Error ? error.message : "Unknown error";

    // Classify the error for the client
    if (message.includes("Account does not exist")) {
      return NextResponse.json(
        { error: "Agent not found", code: "NOT_FOUND" },
        { status: 404 }
      );
    }

    if (message.includes("429")) {
      return NextResponse.json(
        { error: "Rate limited", code: "RATE_LIMITED" },
        { status: 429 }
      );
    }

    if (message.includes("Simulation failed")) {
      return NextResponse.json(
        { error: "Transaction simulation failed", code: "SIMULATION_FAILED" },
        { status: 400 }
      );
    }

    console.error("[API] Agent fetch failed:", message);
    return NextResponse.json(
      { error: "Internal error", code: "INTERNAL" },
      { status: 500 }
    );
  }
}

export function useAgent() {
  const [data, setData] = useState<Agent | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch("/api/sap/agent")
      .then(async (res) => {
        if (!res.ok) {
          const body = await res.json();
          throw new Error(body.error || `HTTP ${res.status}`);
        }
        return res.json();
      })
      .then((json) => setData(json.data))
      .catch((err) => setError(err.message))
      .finally(() => setLoading(false));
  }, []);

  return { data, error, loading };
}

try {
  const result = await client.agent.register(params);
} catch (error: unknown) {
  if (
    error instanceof Error &&
    error.message.includes("Simulation failed")
  ) {
    // Extract program logs from the error
    const logs = (error as any).logs as string[] | undefined;
    if (logs) {
      console.error("Program logs:");
      for (const log of logs) {
        console.error("  ", log);
      }
    }
  }
}

// Safe: start() checks if session exists before creating
await client.session.start("session-id");

// Safe: fetch returns null if not initialized
const agent = await client.agent.fetchNullable();

const cached = sessionStorage.getItem("agent-data");

try {
  const fresh = await fetch("/api/sap/agent").then((r) => r.json());
  sessionStorage.setItem("agent-data", JSON.stringify(fresh));
  return fresh;
} catch {
  return cached ? JSON.parse(cached) : null;
}

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 500,
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: unknown) {
      if (attempt === maxRetries) throw error;
      
      const isRateLimit = 
        error instanceof Error && error.message.includes("429");
      const delay = isRateLimit 
        ? baseDelay * Math.pow(2, attempt) 
        : baseDelay;
      
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

// src/lib/error-monitoring.ts
import { SapError } from "@oobe-protocol-labs/synapse-sap-sdk";

export function reportError(error: unknown, context: string) {
  if (error instanceof SapError) {
    // Send to monitoring service
    console.error(`[SAP:${context}]`, {
      type: error.constructor.name,
      code: (error as any).code,
      message: error.message,
      timestamp: Date.now(),
    });
  } else {
    console.error(`[Unknown:${context}]`, error);
  }
}

// Usage
try {
  await client.agent.register(params);
} catch (error: unknown) {
  reportError(error, "agent.register");
  throw error; // Re-throw for caller to handle
}