@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.15.0

package/src/types/common.ts

@@ -1,187 +0,0 @@
-/**
- * @module types/common
- * @description Shared helper structs used across accounts and instructions.
- *
- * These types appear as nested fields in both on-chain account data
- * and instruction argument DTOs.
- *
- * @category Types
- * @since v0.1.0
- */
-
-import type { PublicKey } from "@solana/web3.js";
-import type BN from "bn.js";
-import type { PluginTypeKind, SettlementModeKind, TokenTypeKind } from "./enums";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Agent Capability
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface Capability
- * @description Agent capability descriptor declaring what the agent can do.
- *
- * Capabilities use a namespaced identifier format (e.g. `"jupiter:swap"`).
- * They are indexed on-chain via the `CapabilityIndex` PDA for scalable discovery.
- *
- * @category Types
- * @since v0.1.0
- *
- * @example
- * ```ts
- * const cap: Capability = {
- *   id: "jupiter:swap",
- *   description: "Token swap via Jupiter aggregator",
- *   protocolId: "jupiter",
- *   version: "1.0",
- * };
- * ```
- */
-export interface Capability {
-  /** Unique identifier (e.g. `"jupiter:swap"`). */
-  readonly id: string;
-  /** Human-readable description of the capability. */
-  readonly description: string | null;
-  /** Protocol namespace this capability belongs to. */
-  readonly protocolId: string | null;
-  /** Semantic version of the capability. */
-  readonly version: string | null;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Pricing
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface VolumeCurveBreakpoint
- * @description A single breakpoint in a volume-based pricing curve.
- *
- * After a consumer exceeds `afterCalls` total invocations, the effective
- * price drops to `pricePerCall`. Multiple breakpoints form a tiered
- * discount schedule (ERC-8004–style).
- *
- * @category Types
- * @since v0.1.0
- *
- * @example
- * ```ts
- * const curve: VolumeCurveBreakpoint[] = [
- *   { afterCalls: 100, pricePerCall: new BN(90_000) },
- *   { afterCalls: 500, pricePerCall: new BN(70_000) },
- * ];
- * ```
- */
-export interface VolumeCurveBreakpoint {
-  /** Number of cumulative calls after which this price tier activates. */
-  readonly afterCalls: number;
-  /** Price per call (in token base units) once `afterCalls` is exceeded. */
-  readonly pricePerCall: BN;
-}
-
-/**
- * @interface PricingTier
- * @description Full pricing tier for agent services, including rate limits,
- *   supported token, settlement mode, and optional volume discounts.
- *
- * Agents can expose multiple tiers (e.g. free, pro) each with independent
- * rate-limiting and pricing parameters.
- *
- * @category Types
- * @since v0.1.0
- * @see {@link SettlementMode} for settlement strategies.
- * @see {@link VolumeCurveBreakpoint} for volume-based discounts.
- *
- * @example
- * ```ts
- * import { TokenType, SettlementMode } from "@synapse-sap/sdk";
- *
- * const tier: PricingTier = {
- *   tierId: "pro",
- *   pricePerCall: new BN(100_000),
- *   minPricePerCall: null,
- *   maxPricePerCall: null,
- *   rateLimit: 60,
- *   maxCallsPerSession: 1000,
- *   burstLimit: 10,
- *   tokenType: TokenType.Usdc,
- *   tokenMint: USDC_MINT,
- *   tokenDecimals: 6,
- *   settlementMode: SettlementMode.Escrow,
- *   minEscrowDeposit: new BN(1_000_000),
- *   batchIntervalSec: null,
- *   volumeCurve: null,
- * };
- * ```
- */
-export interface PricingTier {
-  /** Unique identifier for this tier (e.g. `"free"`, `"pro"`). */
-  readonly tierId: string;
-  /** Default price per call in token base units. */
-  readonly pricePerCall: BN;
-  /** Floor price guard (optional). */
-  readonly minPricePerCall: BN | null;
-  /** Ceiling price guard (optional). */
-  readonly maxPricePerCall: BN | null;
-  /** Maximum calls per second allowed. */
-  readonly rateLimit: number;
-  /** Maximum calls allowed within a single session. */
-  readonly maxCallsPerSession: number;
-  /** Burst capacity above steady-state rate limit. */
-  readonly burstLimit: number | null;
-  /** Token type accepted for payment. */
-  readonly tokenType: TokenTypeKind;
-  /** SPL token mint address (required when `tokenType` is `Spl`). */
-  readonly tokenMint: PublicKey | null;
-  /** Decimal places for the token. */
-  readonly tokenDecimals: number | null;
-  /** Settlement strategy for this tier. */
-  readonly settlementMode: SettlementModeKind | null;
-  /** Minimum escrow deposit required (for escrow settlement). */
-  readonly minEscrowDeposit: BN | null;
-  /** Batch settlement interval in seconds (for batched settlement). */
-  readonly batchIntervalSec: number | null;
-  /** Optional volume discount breakpoints. */
-  readonly volumeCurve: VolumeCurveBreakpoint[] | null;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Plugin Reference
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface PluginRef
- * @description Reference to an active plugin PDA attached to an agent.
- *
- * Stored in the agent's `activePlugins` array to track which extensions
- * are currently enabled.
- *
- * @category Types
- * @since v0.1.0
- */
-export interface PluginRef {
-  /** Discriminant identifying the plugin extension type. */
-  readonly pluginType: PluginTypeKind;
-  /** PDA address of the plugin account. */
-  readonly pda: PublicKey;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Settlement
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface Settlement
- * @description Individual settlement entry used in batch settlement instructions.
- *
- * Each entry describes how many calls to settle for a given service, identified
- * by its 32-byte hash.
- *
- * @category Types
- * @since v0.1.0
- */
-export interface Settlement {
-  /** Number of calls to settle in this batch entry. */
-  readonly callsToSettle: BN;
-  /** SHA-256 hash identifying the service being settled. */
-  readonly serviceHash: number[]; // [u8; 32]
-}

package/src/types/endpoint.ts

@@ -1,181 +0,0 @@
-/**
- * @module types/endpoint
- * @description Typed endpoint metadata for SAP agent discovery.
- *
- * Provides machine-verifiable descriptions of an agent's HTTP endpoints,
- * authentication requirements, health-check expectations, and CORS/CSRF
- * needs. These types solve the "guess the endpoint" interoperability
- * problem highlighted by Kamiyo and AceDataCloud integrations.
- *
- * @category Types
- * @since v0.6.0
- */
-
-// ═══════════════════════════════════════════════════════════════════
-//  Endpoint Descriptor
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface EndpointDescriptor
- * @description Machine-readable description of an agent's HTTP endpoint.
- *
- * Designed so that clients never have to "guess" the method, auth
- * requirements, or content type of an agent's API.
- *
- * @category Types
- * @since v0.6.0
- */
-export interface EndpointDescriptor {
-  /** Full URL of the endpoint (e.g. `https://api.example.com/x402`). */
-  readonly url: string;
-  /** HTTP method (uppercase). Defaults to `"POST"`. */
-  readonly method: "GET" | "POST" | "PUT" | "DELETE";
-  /** Expected `Content-Type` of the response (defaults to `"application/json"`). */
-  readonly contentType: string;
-  /** Whether the endpoint requires an `Authorization` header. */
-  readonly requiresAuth: boolean;
-  /** Type of auth if `requiresAuth` is true: bearer, api-key, x402, etc. */
-  readonly authType?: "bearer" | "api-key" | "x402" | "none";
-  /** Whether the endpoint requires CSRF tokens / cookies. */
-  readonly requiresCSRF: boolean;
-  /** Whether the endpoint requires browser cookies. */
-  readonly requiresCookies: boolean;
-  /** Expected CORS headers (if any specific origins are required). */
-  readonly corsOrigins?: string[];
-  /** Additional custom headers that the endpoint requires. */
-  readonly requiredHeaders?: Record<string, string>;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Health Check
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface HealthCheckDescriptor
- * @description Health-check endpoint configuration for an agent.
- *
- * Clients and the CLI can use this to verify that an agent's
- * endpoint is reachable and SAP-capable before attempting x402 calls.
- *
- * @category Types
- * @since v0.6.0
- */
-export interface HealthCheckDescriptor {
-  /** Health-check URL (e.g. `https://api.example.com/health`). */
-  readonly url: string;
-  /** Expected HTTP status code (defaults to `200`). */
-  readonly expectedStatus: number;
-  /** Timeout in milliseconds for the check (defaults to `5000`). */
-  readonly timeoutMs: number;
-  /** HTTP method to use (defaults to `"GET"`). */
-  readonly method?: "GET" | "HEAD";
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Agent Manifest (typed capability manifest)
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface ToolManifestEntry
- * @description Typed descriptor for a single tool in an agent's manifest.
- *
- * Provides enough metadata so clients can statically validate arguments,
- * know the payment mode, and understand prerequisites before calling.
- *
- * @category Types
- * @since v0.6.0
- */
-export interface ToolManifestEntry {
-  /** Tool name (e.g. `"serp:search"`, `"jupiter:swap"`). */
-  readonly name: string;
-  /** Human-readable description. */
-  readonly description: string;
-  /** Protocol namespace (e.g. `"kamiyo"`, `"ace_data_cloud"`). */
-  readonly protocol: string;
-  /** Tool category. */
-  readonly category: string;
-  /** JSON Schema (draft-07) for input arguments. */
-  readonly inputSchema: Record<string, unknown>;
-  /** JSON Schema (draft-07) for output shape. */
-  readonly outputSchema: Record<string, unknown>;
-  /** HTTP method used to invoke this tool. */
-  readonly httpMethod: "GET" | "POST" | "PUT" | "DELETE" | "COMPOUND";
-  /** Payment mode: `"x402"`, `"free"`, `"prepaid"`, etc. */
-  readonly paymentMode: "x402" | "free" | "prepaid" | "subscription";
-  /** Price per call (in smallest token unit; 0 for free). */
-  readonly pricePerCall: number;
-  /** Required arguments (subset of inputSchema.required). */
-  readonly requiredArgs: string[];
-  /** Prerequisites or preconditions (e.g. "requires escrow"). */
-  readonly prerequisites: string[];
-  /** Endpoint override for this specific tool (if different from agent default). */
-  readonly endpointOverride?: EndpointDescriptor;
-}
-
-/**
- * @interface AgentManifest
- * @description Complete typed manifest for an agent, including
- * endpoints, health checks, tools, and discovery metadata.
- *
- * Replaces the "stringly typed" approach to agent metadata with
- * machine-verifiable schemas. Generated by the CLI or published
- * to the on-chain registry.
- *
- * @category Types
- * @since v0.6.0
- */
-export interface AgentManifest {
-  /** Manifest schema version. */
-  readonly version: "1.0.0";
-  /** Agent's wallet address (base58). */
-  readonly wallet: string;
-  /** Agent name. */
-  readonly name: string;
-  /** Agent description. */
-  readonly description: string;
-  /** Primary x402 endpoint descriptor. */
-  readonly endpoint: EndpointDescriptor;
-  /** Health-check configuration. */
-  readonly healthCheck?: HealthCheckDescriptor;
-  /** All available tools with typed schemas. */
-  readonly tools: ToolManifestEntry[];
-  /** Supported network identifiers for x402 headers. */
-  readonly supportedNetworks: string[];
-  /** Timestamp of manifest generation (ISO 8601). */
-  readonly generatedAt: string;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Endpoint Validation Result
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface EndpointValidationResult
- * @description Result of validating an agent's endpoint reachability and capabilities.
- *
- * Returned by the SDK's validation utilities and the CLI's
- * `discovery validate` command.
- *
- * @category Types
- * @since v0.6.0
- */
-export interface EndpointValidationResult {
-  /** The URL that was tested. */
-  readonly url: string;
-  /** Whether the endpoint is reachable. */
-  readonly reachable: boolean;
-  /** HTTP status code received (or 0 if unreachable). */
-  readonly statusCode: number;
-  /** Response time in milliseconds. */
-  readonly latencyMs: number;
-  /** Whether the response Content-Type is JSON. */
-  readonly isJson: boolean;
-  /** Whether CORS headers are present. */
-  readonly hasCors: boolean;
-  /** Whether the endpoint returned SAP-compatible headers. */
-  readonly isSapCapable: boolean;
-  /** Error message if validation failed. */
-  readonly error?: string;
-  /** Warnings (e.g. "requires CSRF", "returns HTML"). */
-  readonly warnings: string[];
-}