Quicksilver SDK Architecture

The Quicksilver SDK is fundamentally designed to elevate the developer experience from interacting with a generic REST API to leveraging a powerful, fluent Domain-Specific Language (DSL) for Agent Commerce. This architectural shift, detailed in the Quicksilver SDK Overview, underpins the SDK's ability to express complex financial interactions with elegance and type safety.

Core Architectural Philosophy: From API Wrapper to Fluent DSL

The primary objective of the SDK's architecture is to abstract away the boilerplate and complexity of raw API calls, providing an intuitive, expressive interface. This is achieved by moving beyond simple API wrappers to a design where core financial concepts are treated as first-class citizens, allowing developers to "program money" rather than merely send data.

This philosophy is built on several core principles:

1. Builder Pattern: Complex operations, particularly those involving conditional logic and product definitions, are constructed using fluent, chainable methods. This pattern allows for step-by-step object construction, improving readability and ensuring valid configurations at each stage. Instead of crafting intricate JSON payloads manually, developers build logic through method calls.
2. Active Records: Core entities like Account and Transaction are implemented as "active models." This means they are not just passive data containers but possess methods that encapsulate their behaviors and direct interactions with the Quicksilver Engine API. For example, an Account object can directly initiate a transaction() or delegate() a sub-agent, and a Transaction object can execute() or cancel() itself.
3. First-Class Primitives: Concepts central to programmable money, such as Condition (for conditional logic) and Product (for defining programmable services), are elevated to core, first-class primitives within the SDK. This emphasizes their importance and provides dedicated, rich interfaces for their manipulation.
4. Type Safety: Leveraging TypeScript, the SDK ensures robust type checking throughout. This provides rich autocompletion in IDEs, prevents common data-related errors at compile time, and guides developers toward creating valid states and interactions, significantly reducing runtime bugs.
5. Hide Complexity: The sophisticated architecture deliberately abstracts away the underlying HTTP requests, JSON serialization, and API endpoint details. Developers interact with high-level, business-logic-oriented methods and objects, allowing them to focus on the "what" of programmable money rather than the "how" of API communication.

src/ Directory Structure

The SDK's codebase is organized to reflect this architectural philosophy, clearly separating concerns and reinforcing the fluent DSL design:

src/
├── client.ts              # Factory for builders and entry point to legacy resources
├── builders/              # Fluent builders for complex objects
│   ├── action.ts         # Defines actions within conditions
│   ├── condition.ts      # Constructs conditional logic
│   └── product.ts        # Defines programmable products/services
├── models/               # Active models representing core entities
│   ├── account.ts        # Active Account model with methods
│   └── transaction.ts    # Active Transaction model with methods
├── resources/            # Legacy REST wrapper for direct API interaction
│   ├── accounts.ts
│   ├── transactions.ts
│   └── (other API resources like streams, admin, gateways, kyc)
├── realtime/              # Real-time event handling
│   └── sse.ts            # Server-Sent Events (SSE) connection management
├── http.ts                # Low-level HTTP client
├── errors.ts              # Custom error classes
├── types.ts               # Shared TypeScript type definitions and enums
└── index.ts               # Main SDK export file

Purpose of Top-Level Directories:

• client.ts: This is the central entry point for the SDK. The QuicksilverClient class serves as a factory, providing access to instances of the fluent builders (condition(), product()) and the resources/ wrappers. It initializes the HttpClient and orchestrates access to various SDK functionalities.
• builders/: This directory is home to the fluent builders (Action, ConditionBuilder, ProductBuilder) that are key to the DSL.
  • action.ts: Defines atomic actions (e.g., release, notify, hold) that can be chained within conditional logic. ActionBuilder extends this to add more fluency for specific action types.
  • condition.ts: The ConditionBuilder allows developers to construct complex conditional logic using when(), then(), and otherwise() clauses, abstracting the underlying JSON structure that the API expects.
  • product.ts: The ProductBuilder facilitates the definition of programmable products or services, allowing developers to specify pricing, guarantees, and multi-agent workflows through a fluent interface.
• models/: This directory contains the "active record" models (Account, Transaction).
  • account.ts: The Account model represents an account entity with methods like delegate(), transaction(), purchase(), refresh(), and getBalance(). These methods encapsulate business logic and interact with the API, making account management intuitive.
  • transaction.ts: The Transaction model similarly provides methods for managing a transaction's lifecycle, such as execute(), cancel(), triggerEvent(), getCost(), and refresh(). It allows direct manipulation and querying of transaction state.
• resources/: This directory holds the traditional, more direct REST API wrappers (e.g., AccountsResource, TransactionsResource, StreamsResource, KycResource). While less "fluent" on their own, these resources are crucial. They are often utilized internally by the active models (Account, Transaction) to perform the actual HTTP requests to the Quicksilver Engine API. They can also be used directly by advanced developers needing lower-level API control.
• realtime/: This directory focuses on real-time capabilities.
  • sse.ts: The StreamConnection class provides functionality for connecting to Server-Sent Events (SSE) endpoints, enabling real-time updates for streaming transactions and other system events.
• http.ts: Contains the HttpClient class, a low-level utility responsible for abstracting the underlying HTTP request mechanism (using fetch). It handles request headers (e.g., API key, content-type), timeouts, and basic error parsing, forming the bedrock of all API communication.
• errors.ts: Defines custom error classes (e.g., APIErrorResponse, NetworkError, AuthenticationError) for standardized and more descriptive error handling within the SDK.
• types.ts: Houses shared TypeScript interfaces, enums, and type aliases that define the data structures for API payloads, responses, and internal SDK objects, ensuring strong type safety across the entire codebase.

How Components Work Together to Form the Fluent DSL

The QuicksilverClient acts as the central orchestrator. When a developer needs to define complex logic, they start with client.condition() or client.product(), which return instances of the respective builders. These builders, residing in src/builders/, expose methods that allow developers to construct sophisticated objects in a readable, chainable manner.

For managing core entities, the SDK returns active models (Account, Transaction) from src/models/. These models are initialized with data and an instance of the HttpClient. When a method like account.delegate() or transaction.execute() is called, the active model internally utilizes the appropriate, lower-level resource wrapper (from src/resources/) to send an HTTP request via the HttpClient.

The HttpClient (from src/http.ts) handles the actual network communication, adding authentication headers (API key), managing timeouts, and parsing responses. If an error occurs, it maps raw HTTP errors to the SDK's custom error types (from src/errors.ts).

Throughout this entire process, the src/types.ts file ensures consistent data structures and strong type checking, preventing mismatches and guiding developers with rich autocompletion, thus realizing the vision of a type-safe, expressive DSL for programmable money. The combination of builders for complex definitions and active models for core entity management allows developers to fluidly describe their desired financial behaviors, abstracting away the underlying API mechanics.