# API Reference - Core Models The Quicksilver SDK provides powerful, fluent interfaces through its "active record" models: `Account` and `Transaction`. These objects not only hold data but also encapsulate behavior, allowing developers to interact with the Quicksilver Engine in an intuitive, object-oriented manner. ## Data Interfaces These interfaces define the raw data structures returned by the Quicksilver API that the `Account` and `Transaction` models wrap. ### AccountData Interface Represents the raw data structure for an account in the Quicksilver Engine. ```typescript interface AccountData { id: string; name: string; account_type: AccountType; parent_id?: string | null; public_key?: string | null; meta: Record; limits: { daily?: number | null; per_transaction?: number | null; total?: number | null; }; verification: { status: 'unverified' | 'pending' | 'verified' | 'rejected'; verified_at?: string | null; kyc_data?: { document_type?: string; document_number?: string; verified_by?: string; } | null; }; created_at: string; // ISO 8601 DateTime string updated_at: string; // ISO 8601 DateTime string children: string[]; } ``` ### TransactionData Interface Represents the raw data structure for a transaction in the Quicksilver Engine. ```typescript interface TransactionData { id: string; transaction_type: TransactionType; amount: number; currency: Currency; from: string; to?: string | null; parent_id?: string | null; children: string[]; state: TransactionState; // Also referred to as 'status' in some contexts conditions?: Condition[] | null; meta: Record; created_at: string; updated_at: string; executed_at?: string | null; } ``` --- ## Account Model The `Account` class represents an active account in the Quicksilver Engine. It provides methods for account management, delegation, and initiating transactions or product purchases. ```typescript class Account { constructor(data: AccountData, http: HttpClient); readonly id: string; /** The name of the account. */ get name(): string; /** The type of the account (e.g., "Human", "AgentMain", "AgentDelegated"). */ get accountType(): string; /** The ID of the parent account, if delegated. */ get parentId(): string | null; /** Custom metadata associated with the account. */ get meta(): Record; /** Spending limits configured for the account. */ get limits(): { daily?: number | null; per_transaction?: number | null; total?: number | null }; /** ISO 8601 timestamp when the account was created. */ get createdAt(): string; /** ISO 8601 timestamp when the account was last updated. */ get updatedAt(): string; /** List of IDs of directly delegated child accounts. */ get children(): string[]; /** * Delegates a new sub-agent account from this account. * @param options - Configuration for the new sub-agent. * @returns A Promise resolving to the newly created Account object. */ delegate(options: { name: string, limits: { daily: number } }): Promise; /** * Creates a new fluent transaction builder originating from this account. * The transaction is initially in 'Draft' state. * @param details - The core details of the transaction. * @returns A new Transaction object, pre-filled with this account as the sender. */ transaction(details: Omit): Transaction; /** * Purchases a programmable product using funds from this account. * @param product - The Product builder instance defining the product. * @param options - Additional options specific to the product purchase. * @returns A Promise resolving to the resulting Transaction object. */ purchase(product: Product, options: { [key: string]: any }): Promise; /** * Refreshes the account's data from the server, updating the current instance. * @returns A Promise resolving to the updated Account object. */ refresh(): Promise; /** * Fetches the directly delegated child accounts for this account. * @returns A Promise resolving to an array of Account objects. */ getChildren(): Promise; /** * Updates the spending limits for this account. * @param limits - New limits to apply (e.g., daily, per_transaction, total). * @returns A Promise resolving to the updated Account object. */ updateLimits(limits: { daily?: number; per_transaction?: number; total?: number }): Promise; /** * Fetches the current balance of this account. * @returns A Promise resolving to an object containing the amount and currency. */ getBalance(): Promise<{ amount: number; currency: string }>; /** * Checks if the account has been verified (e.g., via KYC). * @returns A boolean indicating verification status. */ isVerified(): boolean; /** * Checks if this account is a root account (i.e., has no parent). * @returns A boolean indicating if it's a root account. */ isRootAccount(): boolean; /** * Submits KYC (Know Your Customer) verification documents for the account. * @param kycData - Details of the documents to submit. * @returns A Promise resolving to the updated Account object. */ submitKYC(kycData: { document_type: string; document_number: string; document_file?: File | Blob; }): Promise; /** * Verifies the account (administrative function requiring special permissions). * @param verifiedBy - Identifier of the user or system performing the verification. * @returns A Promise resolving to the updated Account object. */ verify(verifiedBy: string): Promise; /** * Rejects the verification for the account (administrative function requiring special permissions). * @param reason - The reason for rejecting the verification. * @returns A Promise resolving to the updated Account object. */ rejectVerification(reason: string): Promise; /** * Retrieves the current KYC verification status and details for the account. * @returns An object containing the verification status and related data. */ getVerificationStatus(): { status: 'unverified' | 'pending' | 'verified' | 'rejected'; verified_at?: string | null; kyc_data?: { document_type?: string; document_number?: string; verified_by?: string; } | null; }; /** * Checks if the account is authorized to perform transactions. * @returns A boolean indicating transaction capability. */ canTransact(): boolean; /** * Checks if the account is authorized to delegate sub-accounts. * @returns A boolean indicating delegation capability. */ canDelegate(): boolean; } ``` --- ## Transaction Model The `Transaction` class represents an active transaction in the Quicksilver Engine. It provides methods for managing the transaction lifecycle, interacting with conditional logic, and handling real-time events. ```typescript class Transaction { constructor(data: TransactionData, http: HttpClient); readonly id: string; /** The type of transaction (e.g., "Payment", "Escrow", "Stream"). */ get transactionType(): string; /** The monetary amount of the transaction. */ get amount(): number; /** The currency of the transaction. */ get currency(): string; /** The ID of the sender account. */ get from(): string; /** The ID of the recipient account. */ get to(): string | null; /** The current state of the transaction (e.g., "Draft", "Pending", "Completed"). */ get state(): string; /** The current status of the transaction (alias for `state`). */ get status(): string; /** The ID of the parent transaction, if this is a sub-transaction. */ get parentId(): string | null; /** Custom metadata associated with the transaction. */ get meta(): Record; /** ISO 8601 timestamp when the transaction was created. */ get createdAt(): string; /** ISO 8601 timestamp when the transaction was last updated. */ get updatedAt(): string; /** ISO 8601 timestamp when the transaction was executed. */ get executedAt(): string | null; /** List of IDs of directly related child transactions. */ get children(): string[]; /** * Executes the transaction, moving it from 'Draft' or 'Pending' to an active state. * @param gatewayId - Optional ID of a specific payment gateway to use. * @returns A Promise resolving to the updated Transaction object. */ execute(gatewayId?: string): Promise; /** * Cancels the transaction. Cannot cancel transactions that are already 'Completed' or 'Failed'. * @returns A Promise resolving to the updated Transaction object. */ cancel(): Promise; /** * Triggers a specific event on this transaction, useful for conditional logic evaluation. * @param event - The name of the event to trigger. * @param context - Optional context data for the event. * @returns A Promise resolving to the updated Transaction object. */ triggerEvent(event: string, context?: any): Promise; /** * Retrieves the current cost or accumulated value of the transaction. * For streaming transactions, this represents the accumulated amount. * @returns A Promise resolving to the numerical cost. */ getCost(): Promise; /** * Refreshes the transaction's data from the server, updating the current instance. * @returns A Promise resolving to the updated Transaction object. */ refresh(): Promise; /** * Checks if the transaction is in a final, irreversible state (Completed, Failed, Cancelled). * @returns A boolean indicating if the transaction is final. */ isFinal(): boolean; /** * Checks if the transaction is currently pending execution or in draft status. * @returns A boolean indicating if the transaction is pending. */ isPending(): boolean; /** * Fetches directly related child transactions. * @returns A Promise resolving to an array of Transaction objects. */ getChildren(): Promise; /** * Attaches conditional logic to the transaction. * @param conditionBuilder - An instance of `ConditionBuilder` defining the logic. * @returns The current Transaction object for chaining. */ withConditions(conditionBuilder: ConditionBuilder): this; /** * Retrieves the metadata associated with the transaction. * @returns A record of string keys to any values. */ getMeta(): Record; /** * Updates the metadata for the transaction. * @param meta - An object containing the metadata to merge or set. * @returns A Promise resolving to the updated Transaction object. */ updateMeta(meta: Record): Promise; /** * Subscribes to real-time events for this specific transaction via Server-Sent Events (SSE). * @returns A `StreamConnection` object to listen for events. */ subscribe(): StreamConnection; /** * Retrieves the status of the transaction (alias for `state` or `status` getter). * @returns The current status string. */ getStatus(): string; /** * Retrieves the metadata associated with the transaction (alias for `getMeta`). * @returns A record of string keys to any values. */ getMetadata(): Record; /** * Fluent method to add or update metadata for the transaction. * @param metadata - An object containing the metadata to merge. * @returns The current Transaction object for chaining. */ withMetadata(metadata: Record): this; /** * Fluent method to add conditional logic to the transaction (alias for `withConditions`). * @param condition - An instance of `ConditionBuilder` defining the logic. * @returns The current Transaction object for chaining. */ withCondition(condition: ConditionBuilder): this; /** * Converts this base transaction into a streaming transaction. * @param options - Configuration options for the streaming behavior. * @returns A Promise resolving to the streaming transaction details. */ toStream(options: { rate: number; rate_unit: string }): Promise; /** * Starts streaming this transaction with the specified rate and unit (alias for `toStream`). * @param rate - The numerical rate for the stream. * @param unit - The unit of the rate (e.g., 'per_second', 'per_word'). * @returns A Promise resolving to the streaming transaction details. */ startStreaming(rate: number, unit: string): Promise; /** * Updates the transaction with partial new data. * @param updates - An object containing fields to update. * @returns A Promise resolving to the updated Transaction object. */ update(updates: Partial): Promise; /** * Deletes the transaction. * @returns A Promise that resolves when the deletion is complete. */ delete(): Promise; /** * Executes the transaction through a specific payment gateway. * @param gatewayId - The ID of the gateway to use. * @returns A Promise resolving to the updated Transaction object. */ executeGateway(gatewayId: string): Promise; /** * General method to manage streaming aspects of the transaction. * @param options - Options for creating or updating a stream. * @returns A Promise resolving to streaming transaction details. */ stream(options: { rate?: number; rateUnit?: string; rate_unit?: string; endTime?: string }): Promise; /** * Refunds the transaction, either fully or partially. * @param amount - Optional amount to refund. If not provided, the full transaction amount is refunded. * @returns A Promise resolving to the updated Transaction object. */ refund(amount?: number): Promise; /** * Retrieves all streaming operations associated with this transaction. * @returns A Promise resolving to an array of stream details. */ getStreams(): Promise; /** * Checks if the transaction has been successfully completed. * @returns A boolean indicating if the transaction is completed. */ isCompleted(): boolean; /** * Checks if the transaction has failed. * @returns A boolean indicating if the transaction is failed. */ isFailed(): boolean; /** * Retrieves the conditional logic currently applied to this transaction. * @returns An array of condition objects. */ getConditions(): any; /** * Returns a string representation of the transaction. * @returns A string summary of the transaction. */ toString(): string; /** * Returns the raw transaction data object. * @returns The underlying `TransactionData` object. */ toJSON(): TransactionData; } ```

API Reference - Core Models

Page Viewers

Guest Views