@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/src/errors/index.ts

@@ -0,0 +1,346 @@
+/**
+ * @module errors
+ * @description Typed error classes for the SAP v2 SDK.
+ *
+ * All SDK errors extend {@link SapError} to allow catch-all handling,
+ * while concrete subclasses enable fine-grained error matching.
+ *
+ * @category Errors
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapError, SapRpcError, SapAccountNotFoundError } from "@synapse-sap/sdk/errors";
+ *
+ * try {
+ *   const agent = await client.agent.fetch();
+ * } catch (err) {
+ *   if (err instanceof SapAccountNotFoundError) {
+ *     console.log("Agent not registered yet");
+ *   } else if (err instanceof SapRpcError) {
+ *     console.error("RPC failure:", err.rpcCode);
+ *   } else if (err instanceof SapError) {
+ *     console.error("SAP error:", err.message);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ * @see {@link SapValidationError}
+ * @see {@link SapRpcError}
+ * @see {@link SapAccountNotFoundError}
+ * @see {@link SapTimeoutError}
+ * @see {@link SapPermissionError}
+ */
+
+// ═══════════════════════════════════════════════════════════════════
+//  Base Error
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapError
+ * @description Base class for all SAP SDK errors.
+ *
+ * Extends `Error` and sets `name` automatically so `instanceof`
+ * checks work correctly in both CJS and ESM environments.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {Error}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.fetch();
+ * } catch (err) {
+ *   if (err instanceof SapError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapValidationError}
+ * @see {@link SapRpcError}
+ * @see {@link SapAccountNotFoundError}
+ * @see {@link SapTimeoutError}
+ * @see {@link SapPermissionError}
+ */
+export class SapError extends Error {
+  /**
+   * @description Machine-readable error code for programmatic handling.
+   * @readonly
+   */
+  readonly code: string;
+
+  /**
+   * @param message - A human-readable description of the error.
+   * @param code    - Machine-readable error code (defaults to `"SAP_ERROR"`).
+   */
+  constructor(message: string, code = "SAP_ERROR") {
+    super(message);
+    this.name = "SapError";
+    this.code = code;
+    // Fix prototype chain for instanceof checks
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Validation Error
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapValidationError
+ * @description Thrown when SDK-side input validation fails before sending a
+ * transaction or making an RPC call.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.register({ name: "" });
+ * } catch (err) {
+ *   if (err instanceof SapValidationError) {
+ *     console.error(`Validation failed on field "${err.field}": ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+export class SapValidationError extends SapError {
+  /**
+   * @description Field or parameter that failed validation (if applicable).
+   * @readonly
+   */
+  readonly field?: string;
+
+  /**
+   * @param message - A human-readable description of the validation failure.
+   * @param field   - The name of the field or parameter that failed validation.
+   */
+  constructor(message: string, field?: string) {
+    super(message, "SAP_VALIDATION_ERROR");
+    this.name = "SapValidationError";
+    this.field = field;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  RPC / Transaction Error
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapRpcError
+ * @description Wraps Solana RPC or Anchor transaction errors with additional
+ * context (error code, logs).
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.register(params);
+ * } catch (err) {
+ *   if (err instanceof SapRpcError) {
+ *     console.error(`RPC error ${err.rpcCode}: ${err.message}`);
+ *     err.logs?.forEach((log) => console.debug(log));
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapRpcError.fromAnchor}
+ * @see {@link SapError}
+ */
+export class SapRpcError extends SapError {
+  /**
+   * @description Anchor / program error code, if available.
+   * @readonly
+   */
+  readonly rpcCode?: number;
+  /**
+   * @description Transaction logs returned by the RPC node.
+   * @readonly
+   */
+  readonly logs?: readonly string[];
+
+  /**
+   * @param message - A human-readable description of the RPC or transaction error.
+   * @param opts    - Optional additional context.
+   * @param opts.rpcCode - Anchor or Solana program error code.
+   * @param opts.logs    - Raw transaction logs from the RPC node.
+   */
+  constructor(
+    message: string,
+    opts?: { rpcCode?: number; logs?: readonly string[] },
+  ) {
+    super(message, "SAP_RPC_ERROR");
+    this.name = "SapRpcError";
+    this.rpcCode = opts?.rpcCode;
+    this.logs = opts?.logs;
+  }
+
+  /**
+   * @static
+   * @description Create a {@link SapRpcError} from an Anchor-style error object.
+   * Extracts `code` and `logs` automatically from the Anchor error shape.
+   *
+   * @param err - The raw Anchor or Solana error object.
+   * @returns A new {@link SapRpcError} populated with extracted code, logs, and message.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await program.methods.registerAgent(args).rpc();
+   * } catch (raw) {
+   *   throw SapRpcError.fromAnchor(raw);
+   * }
+   * ```
+   *
+   * @see {@link SapRpcError}
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static fromAnchor(err: any): SapRpcError {
+    const code = err?.error?.errorCode?.number ?? err?.code;
+    const logs: string[] = err?.logs ?? err?.error?.logs ?? [];
+    const msg =
+      err?.error?.errorMessage ?? err?.message ?? "Unknown RPC error";
+    return new SapRpcError(msg, { rpcCode: code, logs });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Account Not Found
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapAccountNotFoundError
+ * @description Thrown when an expected on-chain account does not exist or has
+ * been closed.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const agent = await client.agent.fetch(agentPda);
+ * } catch (err) {
+ *   if (err instanceof SapAccountNotFoundError) {
+ *     console.warn(`Missing ${err.accountType ?? "account"}: ${err.address}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+export class SapAccountNotFoundError extends SapError {
+  /**
+   * @description The base-58 encoded account address that was not found.
+   * @readonly
+   */
+  readonly address: string;
+  /**
+   * @description The expected account type (e.g. `"AgentRecord"`, `"VaultAccount"`).
+   * @readonly
+   */
+  readonly accountType?: string;
+
+  /**
+   * @param address     - The base-58 encoded address of the missing account.
+   * @param accountType - Optional label for the expected account type.
+   */
+  constructor(address: string, accountType?: string) {
+    const label = accountType ? `${accountType} account` : "Account";
+    super(`${label} not found: ${address}`, "SAP_ACCOUNT_NOT_FOUND");
+    this.name = "SapAccountNotFoundError";
+    this.address = address;
+    this.accountType = accountType;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Timeout Error
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapTimeoutError
+ * @description Thrown when an operation (e.g., transaction confirmation) exceeds
+ * the configured timeout.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.register(params, { timeoutMs: 30_000 });
+ * } catch (err) {
+ *   if (err instanceof SapTimeoutError) {
+ *     console.error(`Timed out after ${err.timeoutMs}ms: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+export class SapTimeoutError extends SapError {
+  /**
+   * @description Timeout duration in milliseconds that was exceeded.
+   * @readonly
+   */
+  readonly timeoutMs: number;
+
+  /**
+   * @param message   - A human-readable description of the timeout.
+   * @param timeoutMs - The timeout threshold in milliseconds.
+   */
+  constructor(message: string, timeoutMs: number) {
+    super(message, "SAP_TIMEOUT");
+    this.name = "SapTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Permission Error
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name SapPermissionError
+ * @description Thrown when the current wallet lacks the required permission
+ * (authority, delegate, etc.) for an operation.
+ *
+ * @category Errors
+ * @since v0.1.0
+ * @extends {SapError}
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.agent.update(agentPda, updates);
+ * } catch (err) {
+ *   if (err instanceof SapPermissionError) {
+ *     console.error(`Permission denied: ${err.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SapError}
+ */
+export class SapPermissionError extends SapError {
+  /**
+   * @param message - A human-readable description of the permission failure.
+   */
+  constructor(message: string) {
+    super(message, "SAP_PERMISSION_DENIED");
+    this.name = "SapPermissionError";
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,335 @@
+/**
+ * @module events
+ * @description Decode SAP v2 events from transaction logs.
+ *
+ * Uses Anchor's event parser under the hood. Provides a
+ * strongly-typed, filterable event stream.
+ *
+ * @category Events
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { EventParser } from "@synapse-sap/sdk/events";
+ *
+ * const events = client.events.parseLogs(txLogs);
+ * for (const event of events) {
+ *   if (event.name === "PaymentSettledEvent") {
+ *     console.log(event.data);
+ *   }
+ * }
+ * ```
+ */
+
+import { type Program, BN, EventParser as AnchorEventParser } from "@coral-xyz/anchor";
+import type { PublicKey } from "@solana/web3.js";
+
+// ═══════════════════════════════════════════════════════════════════
+//  Event Data Types
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Decoded payload for the `RegisteredEvent` emitted when a new agent is registered.
+ *
+ * @interface RegisteredEventData
+ * @name RegisteredEventData
+ * @description Contains the agent PDA, owner wallet, display name, capabilities list, and timestamp.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEvent}
+ */
+export interface RegisteredEventData {
+  readonly name: "RegisteredEvent";
+  readonly data: {
+    agent: PublicKey;
+    wallet: PublicKey;
+    name: string;
+    capabilities: string[];
+    timestamp: BN;
+  };
+}
+
+/**
+ * Decoded payload for the `UpdatedEvent` emitted when an agent’s profile is modified.
+ *
+ * @interface UpdatedEventData
+ * @name UpdatedEventData
+ * @description Contains the agent PDA, owner wallet, a list of changed field names, and timestamp.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEvent}
+ */
+export interface UpdatedEventData {
+  readonly name: "UpdatedEvent";
+  readonly data: {
+    agent: PublicKey;
+    wallet: PublicKey;
+    updatedFields: string[];
+    timestamp: BN;
+  };
+}
+
+/**
+ * Decoded payload for the `FeedbackEvent` emitted when a reviewer submits feedback.
+ *
+ * @interface FeedbackEventData
+ * @name FeedbackEventData
+ * @description Contains the agent PDA, reviewer wallet, numeric score, tag, and timestamp.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEvent}
+ */
+export interface FeedbackEventData {
+  readonly name: "FeedbackEvent";
+  readonly data: {
+    agent: PublicKey;
+    reviewer: PublicKey;
+    score: number;
+    tag: string;
+    timestamp: BN;
+  };
+}
+
+/**
+ * Decoded payload for the `MemoryInscribedEvent` emitted when data is written to a vault.
+ *
+ * @interface MemoryInscribedEventData
+ * @name MemoryInscribedEventData
+ * @description Contains vault/session PDAs, sequence info, encrypted data, nonce, content hash,
+ *   fragment metadata, compression flag, and timestamp.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEvent}
+ */
+export interface MemoryInscribedEventData {
+  readonly name: "MemoryInscribedEvent";
+  readonly data: {
+    vault: PublicKey;
+    session: PublicKey;
+    sequence: number;
+    epochIndex: number;
+    encryptedData: number[];
+    nonce: number[];
+    contentHash: number[];
+    totalFragments: number;
+    fragmentIndex: number;
+    compression: number;
+    dataLen: number;
+    nonceVersion: number;
+    timestamp: BN;
+  };
+}
+
+/**
+ * Decoded payload for the `PaymentSettledEvent` emitted when an escrow settlement occurs.
+ *
+ * @interface PaymentSettledEventData
+ * @name PaymentSettledEventData
+ * @description Contains escrow/agent/depositor PDAs, settlement counts, amounts, service hash,
+ *   and remaining balance.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEvent}
+ */
+export interface PaymentSettledEventData {
+  readonly name: "PaymentSettledEvent";
+  readonly data: {
+    escrow: PublicKey;
+    agent: PublicKey;
+    depositor: PublicKey;
+    callsSettled: BN;
+    amount: BN;
+    serviceHash: number[];
+    totalCallsSettled: BN;
+    remainingBalance: BN;
+    timestamp: BN;
+  };
+}
+
+/**
+ * Decoded payload for the `LedgerEntryEvent` emitted when data is appended to a ledger.
+ *
+ * @interface LedgerEntryEventData
+ * @name LedgerEntryEventData
+ * @description Contains session/ledger PDAs, entry index, raw data, content hash,
+ *   Merkle root, and timestamp.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEvent}
+ */
+export interface LedgerEntryEventData {
+  readonly name: "LedgerEntryEvent";
+  readonly data: {
+    session: PublicKey;
+    ledger: PublicKey;
+    entryIndex: number;
+    data: number[];
+    contentHash: number[];
+    dataLen: number;
+    merkleRoot: number[];
+    timestamp: BN;
+  };
+}
+
+/**
+ * Discriminated union of all known SAP v2 event types.
+ *
+ * @name SapEvent
+ * @description Use the `name` discriminant to narrow to a specific event payload.
+ * @category Events
+ * @since v0.1.0
+ */
+export type SapEvent =
+  | RegisteredEventData
+  | UpdatedEventData
+  | FeedbackEventData
+  | MemoryInscribedEventData
+  | PaymentSettledEventData
+  | LedgerEntryEventData;
+
+// ═══════════════════════════════════════════════════════════════════
+//  Event Name Literals
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * Exhaustive list of all SAP v2 event name strings.
+ *
+ * @name SAP_EVENT_NAMES
+ * @description Frozen array of every event discriminant emitted by the program.
+ *   Useful for log filtering and exhaustive switch checks.
+ * @category Events
+ * @since v0.1.0
+ * @see {@link SapEventName}
+ */
+export const SAP_EVENT_NAMES = [
+  "RegisteredEvent",
+  "UpdatedEvent",
+  "DeactivatedEvent",
+  "ReactivatedEvent",
+  "ClosedEvent",
+  "FeedbackEvent",
+  "FeedbackUpdatedEvent",
+  "FeedbackRevokedEvent",
+  "ReputationUpdatedEvent",
+  "CallsReportedEvent",
+  "VaultInitializedEvent",
+  "SessionOpenedEvent",
+  "MemoryInscribedEvent",
+  "EpochOpenedEvent",
+  "SessionClosedEvent",
+  "VaultClosedEvent",
+  "SessionPdaClosedEvent",
+  "EpochPageClosedEvent",
+  "VaultNonceRotatedEvent",
+  "DelegateAddedEvent",
+  "DelegateRevokedEvent",
+  "ToolPublishedEvent",
+  "ToolSchemaInscribedEvent",
+  "ToolUpdatedEvent",
+  "ToolDeactivatedEvent",
+  "ToolReactivatedEvent",
+  "ToolClosedEvent",
+  "ToolInvocationReportedEvent",
+  "CheckpointCreatedEvent",
+  "EscrowCreatedEvent",
+  "EscrowDepositedEvent",
+  "PaymentSettledEvent",
+  "EscrowWithdrawnEvent",
+  "BatchSettledEvent",
+  "AttestationCreatedEvent",
+  "AttestationRevokedEvent",
+  "LedgerEntryEvent",
+  "LedgerSealedEvent",
+] as const;
+
+/**
+ * String literal union of all SAP v2 event names.
+ *
+ * @name SapEventName
+ * @description Derived from {@link SAP_EVENT_NAMES} for compile-time exhaustiveness.
+ * @category Events
+ * @since v0.1.0
+ */
+export type SapEventName = (typeof SAP_EVENT_NAMES)[number];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Event Parser
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * A single parsed event extracted from transaction logs.
+ *
+ * @interface ParsedEvent
+ * @name ParsedEvent
+ * @description Lightweight container with a `name` discriminant and untyped `data` record.
+ *   Narrow via {@link SapEventName} for type-safe access.
+ * @category Events
+ * @since v0.1.0
+ */
+export interface ParsedEvent {
+  readonly name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly data: Record<string, any>;
+}
+
+/**
+ * Typed wrapper around Anchor’s `EventParser` for SAP v2 programs.
+ *
+ * Extracts strongly-typed {@link ParsedEvent} objects from raw
+ * transaction log lines.
+ *
+ * @name EventParser
+ * @description Instantiate with an Anchor `Program` and call {@link EventParser.parseLogs}
+ *   to decode events, or {@link EventParser.filterByName} to narrow results.
+ * @category Events
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * const parser = new EventParser(program);
+ * const events = parser.parseLogs(txLogs);
+ * const settled = parser.filterByName(events, "PaymentSettledEvent");
+ * ```
+ */
+export class EventParser {
+  private readonly parser: AnchorEventParser;
+
+  /**
+   * Create a new `EventParser`.
+   *
+   * @param program - An Anchor `Program` instance whose IDL defines the events to decode.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(program: Program<any>) {
+    this.parser = new AnchorEventParser(program.programId, program.coder);
+  }
+
+  /**
+   * Parse raw transaction log lines into typed events.
+   *
+   * @param logs - Array of log strings from a confirmed transaction.
+   * @returns {ParsedEvent[]} Decoded events found in the logs.
+   */
+  parseLogs(logs: string[]): ParsedEvent[] {
+    const events: ParsedEvent[] = [];
+    const generator = this.parser.parseLogs(logs);
+    for (const event of generator) {
+      events.push(event as ParsedEvent);
+    }
+    return events;
+  }
+
+  /**
+   * Filter a list of parsed events by event name.
+   *
+   * @param events - The full array of {@link ParsedEvent} objects to filter.
+   * @param name   - The {@link SapEventName} to match against.
+   * @returns {ParsedEvent[]} Only events whose `name` matches.
+   */
+  filterByName<N extends SapEventName>(
+    events: ParsedEvent[],
+    name: N,
+  ): ParsedEvent[] {
+    return events.filter((e) => e.name === name);
+  }
+}