Types

interface Passport {
  format_version?: number;          // Frozen canonical field order (always 1 for v1 passports; optional for legacy compat)
  agent_hash: string;
  agent_public_key: string | null;  // Wallet address (key-binding)
  authority_key_id?: string;        // Authority key identifier (optional for legacy passport compat)
  identity_class: IdentityClass | null;  // null for SIGIL-less descendants
  registered_at_beat: number;
  sigil_issued_at_beat: number | null;
  last_heartbeat_beat: number;
  lineage_chain_hash: string;
  issued_at: number;       // Unix timestamp (ms)
  valid_until: number;     // Unix timestamp (ms), issued_at + 24h
  provenonce_signature: string;  // Hex-encoded Ed25519 signature
}

interface SigilResult {
  ok: boolean;
  sigil?: {
    sigil: string;                 // Full SIGIL string e.g. "name*principal*tier"
    sigil_name: string;            // Name portion of SIGIL
    principal: string;             // Principal portion
    tier: SigilTier;               // Tier ('sov' | 'org' | 'ind' | 'eph' | 'sbx')
    identity_class: IdentityClass;
    issued_at_beat: number;
    birth_tx: string | null;       // Solana memo tx signature
    explorer_url: string | null;
  };
  passport?: Passport;
  /** @deprecated Use `passport`. Sunset 2026-09-01. */
  lineage_proof?: Passport;
  fee?: { amount_sol: number; amount_lamports: number; payment_tx: string | null };
  error?: string;
}

interface HeartbeatResult {
  ok: boolean;
  passport?: Passport;
  heartbeat_count_epoch?: number;
  billing_epoch?: number;
  current_beat?: number;
  fee?: { amount_sol: number; amount_lamports: number; tier: number; payment_tx: string | null };
  sponsor?: { parent_hash: string };  // Present if heartbeat was sponsor-paid
  sigil_required?: boolean;
  /** @deprecated Use `passport`. Sunset 2026-09-01. */
  lineage_proof?: Passport;
  error?: string;
}

type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';

interface RegistrationResult {
  hash: string;
  api_key: string;
  secret: string;
  type: 'root' | 'agent';
  parent: string | null;
  depth: number;
  name: string;
  wallet_chain?: string | null;
  birth_tx?: string;             // Present in wire response (not in SDK TypeScript type)
  beat?: { genesis_hash: string; difficulty: number; status: string };
  wallet?: WalletInfo;
}

interface WalletInfo {
  address: string;           // chain-native address (base58 or hex)
  chain: string;             // "solana" or "ethereum"
  solana_address?: string;   // base58 Solana address (Solana only)
}

interface Beat {
  index: number;
  hash: string;
  prev: string;
  timestamp: number;
  nonce?: string;
  anchor_hash?: string;
}

interface SpawnResult {
  ok: boolean;
  eligible: boolean;
  child_hash?: string;              // Present after finalize (Step 2)
  spawn_authorization?: string;     // Present after preflight (Step 1)
  receipt_based?: boolean;          // true if authorized via Beats work-proof
  required_beats?: number;          // Beats needed (if not yet eligible)
  accumulated_beats?: number;       // Current beat balance
  progress_pct?: number;            // Gestation progress percentage
  deficit?: number;                 // Beats still needed
  error?: string;
}

interface BeatAgentConfig {
  apiKey: string;
  registryUrl: string;
  heartbeatIntervalSec?: number;
  onHeartbeat?: (result: HeartbeatResult) => void;
  onError?: (error: Error, context: string) => void;
  onStatusChange?: (status: string, details: Record<string, unknown>) => void;
  verbose?: boolean;
  verifyAnchors?: boolean;         // Verify anchor hashes against Beats service
  beatsUrl?: string;               // Beats service URL (for anchor verification)
}

interface CheckinResult {
  ok: boolean;
  total_beats: number;
  beats_accepted: number;
  global_beat: number;
  status?: string;
  beats_behind?: number;
}