SDK Architecture

The Quicksilver SDK is fundamentally designed to abstract the complexities of programmable money, transforming a generic REST API interaction into a fluent, type-safe Domain-Specific Language (DSL). This architectural shift enables developers to express intricate financial logic with clarity and precision, aligning closely with the vision outlined in the [Quicksilver SDK Overview].

Core Philosophy: From API Wrapper to Fluent DSL

The architectural foundation of the Quicksilver SDK rests on several key principles that empower its fluent, expressive interface:

1. Builder Pattern:

   • Explanation: Complex operations, particularly in defining conditional logic and programmable products, leverage the Builder Pattern. This allows for step-by-step construction of sophisticated configurations through method chaining. Instead of constructing large, complex JSON objects manually, developers use human-readable methods that guide them through the configuration process.
   • Implementation Example: The ConditionBuilder (see src/builders/condition.ts) and ProductBuilder (see src/builders/product.ts) are prime examples. For instance, client.condition().when(...).then(...).otherwise(...) fluently builds a set of rules.

2. Active Records:

   • Explanation: Core domain entities like Account and Transaction are implemented as "Active Records." This means they are not merely data transfer objects but possess methods that encapsulate behavior and directly interact with the API to perform operations related to that entity. This brings a more object-oriented and intuitive feel to financial operations.
   • Implementation Example: The Account model (src/models/account.ts) has methods like delegate(), transaction(), purchase(), and refresh(). Similarly, the Transaction model (src/models/transaction.ts) offers execute(), cancel(), triggerEvent(), and getCost().

3. First-Class Primitives:

   • Explanation: Key concepts in programmable money, such as Condition and Product, are elevated to first-class citizens within the SDK. This means they are not hidden away as properties of other objects but have their own dedicated structures and fluent builders, making them central to the SDK's expressive power.
   • Implementation Example: The ConditionBuilder and ProductBuilder are directly accessible from the QuicksilverClient and are designed to define these primitives comprehensively. This allows for precise type definitions and specialized methods for QuickSilverEvent triggers and Action responses.

4. Type Safety:

   • Explanation: Built entirely in TypeScript, the SDK emphasizes strong type safety. This ensures that developers benefit from rich autocompletion, compile-time error checking, and a clear understanding of expected inputs and outputs. Invalid states are often caught before runtime, leading to more robust and maintainable code.
   • Implementation Example: Every method, parameter, and return value is typed, from QuickSilverClient initialization to the complex Condition and Action payloads. This is evident across all .ts files, particularly in src/types.ts which defines the core interfaces.

5. Hide Complexity:

   • Explanation: A core design goal is to abstract away the underlying API complexity. While the builders allow for intricate logic, the developer primarily interacts with the fluent DSL, and the SDK handles the transformation of these high-level expressions into the detailed JSON payloads required by the Quicksilver Engine API.
   • Implementation Example: The toJSON() methods within builders (e.g., ConditionBuilder.toJSON(), ProductBuilder.toJSON()) are responsible for converting the fluent expressions into the wire format, effectively hiding the API's low-level details.

New File Structure

The codebase is organized to reflect this architectural philosophy, clearly separating concerns and making the fluent DSL a central part of the developer experience:

src/
├── client.ts              # Factory for builders
├── builders/              # Fluent builders
│   ├── action.ts         # Action definitions
│   ├── condition.ts      # Conditional logic
│   └── product.ts        # Programmable products
├── models/               # Active models
│   ├── account.ts        # Account with methods
│   └── transaction.ts    # Transaction with methods
└── resources/            # Legacy REST wrapper
    ├── accounts.ts
    └── transactions.ts
    ... (other resources like streams, admin, kyc, gateways)

Logical Organization:

• client.ts: This file acts as the primary entry point and factory for the SDK. It initializes the HttpClient and exposes instances of all resource wrappers (accounts, transactions, streams, etc.). Crucially, it also provides the factory methods for the fluent DSL builders (client.condition(), client.product()), making them easily accessible and central to the SDK's usage.

• builders/: This directory contains the implementation of the fluent DSL.

  • action.ts: Defines Action and ActionBuilder classes, allowing developers to fluently construct payment, notification, or custom actions that are executed when conditions are met.
  • condition.ts: Implements the ConditionBuilder, providing a chainable interface to define "when-then-otherwise" logic for transactions and products. This is where complex conditional logic is made elegant and readable.
  • product.ts: Houses the ProductBuilder, enabling the definition of programmable products and services with pricing, guarantees, and multi-agent workflows.

• models/: This directory contains the "Active Record" implementations for the core entities.

  • account.ts: The Account class wraps raw account data, augmenting it with methods like delegate(), transaction(), purchase(), refresh(), getBalance(), and KYC-related operations, transforming a data object into a behavioral entity.
  • transaction.ts: The Transaction class similarly wraps transaction data, providing methods for execute(), cancel(), triggerEvent(), getCost(), and methods to interact with its conditions and streams.

• resources/: This directory contains the more traditional, lower-level REST API wrappers. These resources (accounts.ts, transactions.ts, streams.ts, admin.ts, gateways.ts, kyc.ts, health.ts) encapsulate direct HTTP requests (GET, POST, PUT, DELETE) to specific API endpoints. While they provide direct access to API operations, the SDK's higher-level models/ and builders/ are designed to be the preferred interface for most use cases, often using these underlying resources internally.

This layered architecture ensures that the SDK is both powerful and approachable, offering a fluid developer experience while maintaining access to granular API control when necessary.