@opendatalabs/vana-sdk 2.3.0 → 3.0.0

package/dist/types/generics.d.ts

@@ -1,518 +0,0 @@
-/**
- * Defines generic types and interfaces for SDK infrastructure.
- *
- * @remarks
- * This module provides reusable type definitions and interfaces that form
- * the foundation of the SDK's architecture. It includes patterns for requests,
- * responses, caching, middleware, repositories, and other common software
- * engineering abstractions.
- *
- * @category Types
- * @module types/generics
- */
-import type { Address, Hash } from "viem";
-/**
- * Represents a standardized request structure for SDK operations.
- *
- * @remarks
- * Provides consistent request handling across all SDK methods with
- * typed parameters and optional configuration.
- *
- * @typeParam TParams - Type of request parameters
- * @typeParam TOptions - Type of optional configuration
- *
- * @category Reference
- */
-export interface GenericRequest<TParams = unknown, TOptions = unknown> {
-    /** Request parameters */
-    params: TParams;
-    /** Additional request options */
-    options?: TOptions;
-}
-/**
- * Represents a standardized response structure for SDK operations.
- *
- * @remarks
- * Provides consistent response handling with success/error states
- * and optional metadata for additional context.
- *
- * @typeParam TData - Type of response data
- * @typeParam TMeta - Type of response metadata
- *
- * @category Reference
- */
-export interface GenericResponse<TData = unknown, TMeta = unknown> {
-    /** Response data */
-    data: TData;
-    /** Response metadata */
-    meta?: TMeta;
-    /** Success status */
-    success: boolean;
-    /** Error information if not successful */
-    error?: {
-        code: string;
-        message: string;
-        details?: unknown;
-    };
-}
-/**
- * Represents the result of an asynchronous blockchain operation.
- *
- * @remarks
- * Includes transaction details when the operation involves
- * blockchain state changes.
- *
- * @typeParam T - Type of the operation result
- *
- * @category Reference
- */
-export interface AsyncResult<T> {
-    /** Operation result */
-    result: T;
-    /** Transaction hash if applicable */
-    transactionHash?: Hash;
-    /** Block number if applicable */
-    blockNumber?: bigint;
-    /** Gas used if applicable */
-    gasUsed?: bigint;
-}
-/**
- * Generic contract interaction parameters
- *
- * @category Reference
- */
-export interface ContractCall<TArgs extends readonly unknown[] = readonly unknown[]> {
-    /** Contract method name */
-    method: string;
-    /** Method arguments */
-    args: TArgs;
-    /** Call options */
-    options?: {
-        /** Gas limit */
-        gas?: bigint;
-        /** Gas price */
-        gasPrice?: bigint;
-        /** Value to send */
-        value?: bigint;
-    };
-}
-/**
- * Generic contract event filter
- *
- * @category Reference
- */
-export interface EventFilter<TEventArgs = unknown> {
-    /** Event name */
-    event: string;
-    /** Event arguments filter */
-    args?: TEventArgs;
-    /** From block */
-    fromBlock?: bigint;
-    /** To block */
-    toBlock?: bigint;
-    /** Address filter */
-    address?: Address | Address[];
-}
-/**
- * Generic event log
- *
- * @category Reference
- */
-export interface EventLog<TArgs = unknown> {
-    /** Event name */
-    event: string;
-    /** Event arguments */
-    args: TArgs;
-    /** Block number */
-    blockNumber: bigint;
-    /** Transaction hash */
-    transactionHash: Hash;
-    /** Log index */
-    logIndex: number;
-    /** Transaction index */
-    transactionIndex: number;
-    /** Contract address */
-    address: Address;
-}
-/**
- * Generic controller context for dependency injection
- *
- * @category Reference
- */
-export interface ControllerContext<TClient = unknown, TConfig = unknown> {
-    /** Client instance */
-    client: TClient;
-    /** Configuration */
-    config?: TConfig;
-    /** Additional context */
-    [key: string]: unknown;
-}
-/**
- * Generic controller interface
- *
- * @category Reference
- */
-export interface Controller<TContext = unknown> {
-    /** Controller context */
-    readonly context: TContext;
-}
-/**
- * Generic storage provider interface
- *
- * @category Reference
- */
-export interface StorageProvider<TConfig = unknown, TOptions = unknown> {
-    /** Provider name */
-    readonly name: string;
-    /** Provider configuration */
-    readonly config: TConfig;
-    /** Upload data */
-    upload(data: Uint8Array, options?: TOptions): Promise<{
-        url: string;
-        size: number;
-        checksum?: string;
-    }>;
-    /** Download data */
-    download(url: string, options?: TOptions): Promise<{
-        data: Uint8Array;
-        size: number;
-        checksum?: string;
-    }>;
-    /** Delete data */
-    delete?(url: string, options?: TOptions): Promise<boolean>;
-    /** Check if data exists */
-    exists?(url: string, options?: TOptions): Promise<boolean>;
-}
-/**
- * Defines a generic caching interface with TTL support.
- *
- * @remarks
- * Provides standard cache operations for performance optimization
- * and reducing redundant computations or network requests.
- *
- * @typeParam TKey - Type of cache keys
- * @typeParam TValue - Type of cached values
- *
- * @category Reference
- */
-export interface Cache<TKey = string, TValue = unknown> {
-    /** Get value from cache */
-    get(key: TKey): Promise<TValue | undefined>;
-    /** Set value in cache */
-    set(key: TKey, value: TValue, ttl?: number): Promise<void>;
-    /** Delete value from cache */
-    delete(key: TKey): Promise<boolean>;
-    /** Clear all cache */
-    clear(): Promise<void>;
-    /** Check if key exists */
-    has(key: TKey): Promise<boolean>;
-}
-/**
- * Configures retry behavior for resilient operations.
- *
- * @remarks
- * Supports exponential backoff, jitter, and custom retry conditions
- * for handling transient failures gracefully.
- *
- * @typeParam TError - Type of errors to handle
- *
- * @category Reference
- */
-export interface RetryConfig<TError = Error> {
-    /** Maximum retry attempts */
-    maxAttempts: number;
-    /** Base delay in milliseconds */
-    baseDelay: number;
-    /** Backoff multiplier */
-    backoffMultiplier?: number;
-    /** Maximum delay */
-    maxDelay?: number;
-    /** Jitter factor */
-    jitter?: number;
-    /** Retry condition */
-    shouldRetry?: (error: TError, attempt: number) => boolean;
-}
-/**
- * Generic rate limiter configuration
- *
- * @category Reference
- */
-export interface RateLimiterConfig {
-    /** Requests per time window */
-    requestsPerWindow: number;
-    /** Time window in milliseconds */
-    windowMs: number;
-    /** Burst allowance */
-    burstLimit?: number;
-}
-/**
- * Defines middleware for request/response processing pipelines.
- *
- * @remarks
- * Middleware can transform requests, responses, and handle errors
- * in a composable chain of responsibility pattern.
- *
- * @typeParam TRequest - Type of requests to process
- * @typeParam TResponse - Type of responses to process
- *
- * @category Reference
- */
-export interface Middleware<TRequest = unknown, TResponse = unknown> {
-    /** Middleware name */
-    readonly name: string;
-    /** Process request */
-    request?(req: TRequest): Promise<TRequest>;
-    /** Process response */
-    response?(res: TResponse): Promise<TResponse>;
-    /** Handle errors */
-    error?(error: Error, req: TRequest): Promise<TResponse | void>;
-}
-/**
- * Generic plugin interface
- *
- * @category Reference
- */
-export interface Plugin<TConfig = unknown> {
-    /** Plugin name */
-    readonly name: string;
-    /** Plugin version */
-    readonly version: string;
-    /** Plugin configuration */
-    readonly config: TConfig;
-    /** Initialize plugin */
-    init?(): Promise<void>;
-    /** Cleanup plugin */
-    cleanup?(): Promise<void>;
-}
-/**
- * Generic factory interface
- *
- * @category Reference
- */
-export interface Factory<T, TParams = unknown> {
-    /** Create instance */
-    create(params: TParams): T;
-    /** Create multiple instances */
-    createMany?(params: TParams[]): T[];
-    /** Validate parameters */
-    validate?(params: TParams): boolean;
-}
-/**
- * Defines a repository pattern for data access abstraction.
- *
- * @remarks
- * Provides CRUD operations with filtering, sorting, and pagination
- * for consistent data access across different storage backends.
- *
- * @typeParam TEntity - Type of entities managed by the repository
- * @typeParam TKey - Type of entity identifiers
- *
- * @category Reference
- */
-export interface Repository<TEntity, TKey = string | number> {
-    /** Find by ID */
-    findById(id: TKey): Promise<TEntity | undefined>;
-    /** Find all entities */
-    findAll(options?: {
-        limit?: number;
-        offset?: number;
-        filter?: Partial<TEntity>;
-        sort?: Array<{
-            field: keyof TEntity;
-            direction: "asc" | "desc";
-        }>;
-    }): Promise<{
-        entities: TEntity[];
-        total: number;
-        hasMore: boolean;
-    }>;
-    /** Create entity */
-    create(entity: Omit<TEntity, "id">): Promise<TEntity>;
-    /** Update entity */
-    update(id: TKey, updates: Partial<TEntity>): Promise<TEntity>;
-    /** Delete entity */
-    delete(id: TKey): Promise<boolean>;
-    /** Check if entity exists */
-    exists(id: TKey): Promise<boolean>;
-}
-/**
- * Generic validator interface
- *
- * @category Reference
- */
-export interface Validator<T> {
-    /** Validate value */
-    validate(value: unknown): value is T;
-    /** Get validation errors */
-    getErrors?(value: unknown): string[];
-    /** Get validation schema */
-    getSchema?(): unknown;
-}
-/**
- * Generic transformer interface
- *
- * @category Reference
- */
-export interface Transformer<TInput, TOutput> {
-    /** Transform input to output */
-    transform(input: TInput): TOutput | Promise<TOutput>;
-    /** Reverse transform output to input */
-    reverse?(output: TOutput): TInput | Promise<TInput>;
-}
-/**
- * Generic service interface
- *
- * @category Reference
- */
-export interface Service<TConfig = unknown> {
-    /** Service name */
-    readonly name: string;
-    /** Service configuration */
-    readonly config: TConfig;
-    /** Service status */
-    readonly status: "idle" | "starting" | "running" | "stopping" | "stopped" | "error";
-    /** Start service */
-    start(): Promise<void>;
-    /** Stop service */
-    stop(): Promise<void>;
-    /** Restart service */
-    restart?(): Promise<void>;
-    /** Get health status */
-    getHealth?(): Promise<{
-        healthy: boolean;
-        details?: Record<string, unknown>;
-    }>;
-}
-/**
- * Implements the observer in the observer pattern.
- *
- * @remarks
- * Receives notifications about events from observable subjects
- * for decoupled event handling.
- *
- * @typeParam TEvent - Type of events to observe
- *
- * @category Reference
- */
-export interface Observer<TEvent = unknown> {
-    /** Handle event */
-    notify(event: TEvent): void | Promise<void>;
-}
-/**
- * Implements the subject in the observer pattern.
- *
- * @remarks
- * Manages observers and emits events to all subscribed observers
- * for event-driven architectures.
- *
- * @typeParam TEvent - Type of events to emit
- *
- * @category Reference
- */
-export interface Observable<TEvent = unknown> {
-    /** Subscribe to events */
-    subscribe(observer: Observer<TEvent>): () => void;
-    /** Unsubscribe from events */
-    unsubscribe(observer: Observer<TEvent>): void;
-    /** Emit event */
-    emit(event: TEvent): void;
-}
-/**
- * Generic state machine interface
- *
- * @category Reference
- */
-export interface StateMachine<TState, TEvent> {
-    /** Current state */
-    readonly currentState: TState;
-    /** Transition to new state */
-    transition(event: TEvent): TState;
-    /** Check if transition is valid */
-    canTransition(event: TEvent): boolean;
-    /** Get available transitions */
-    getAvailableTransitions(): TEvent[];
-}
-/**
- * Helper type to make properties optional conditionally
- *
- * @category Reference
- */
-export type ConditionalOptional<T, K extends keyof T, Condition extends boolean> = Condition extends true ? Omit<T, K> & Partial<Pick<T, K>> : T;
-/**
- * Helper type to extract promise result type
- *
- * @category Reference
- */
-export type PromiseResult<T> = T extends Promise<infer U> ? U : T;
-/**
- * Helper type to create a union of all possible keys
- *
- * @category Reference
- */
-export type AllKeys<T> = T extends unknown ? keyof T : never;
-/**
- * Helper type to create a deep partial type
- *
- * @category Reference
- */
-export type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-/**
- * Helper type to create a deep readonly type
- *
- * @category Reference
- */
-export type DeepReadonly<T> = {
-    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
-};
-/**
- * Helper type to create a required type with specific keys
- *
- * @category Reference
- */
-export type RequireKeys<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
-/**
- * Helper type to create an optional type with specific keys
- *
- * @category Reference
- */
-export type OptionalKeys<T, K extends keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
-/**
- * Helper type to exclude null and undefined
- *
- * @category Reference
- */
-export type NonNullable<T> = T extends null | undefined ? never : T;
-/**
- * Helper type to create a type with only specific keys
- *
- * @category Reference
- */
-export type PickByType<T, U> = {
-    [K in keyof T as T[K] extends U ? K : never]: T[K];
-};
-/**
- * Helper type to omit keys by type
- *
- * @category Reference
- */
-export type OmitByType<T, U> = {
-    [K in keyof T as T[K] extends U ? never : K]: T[K];
-};
-/**
- * Helper type for branded types
- *
- * @category Reference
- */
-export type Brand<T, B> = T & {
-    readonly __brand: B;
-};
-/**
- * Helper type for nominal types
- *
- * @category Reference
- */
-export type Nominal<T, N extends string> = T & {
-    readonly __nominal: N;
-};

package/dist/types/generics.js

@@ -1 +0,0 @@
-//# sourceMappingURL=generics.js.map

package/dist/types/generics.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/operationStore.cjs

@@ -1,17 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var operationStore_exports = {};
-module.exports = __toCommonJS(operationStore_exports);
-//# sourceMappingURL=operationStore.cjs.map

package/dist/types/operationStore.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/types/operationStore.ts"],"sourcesContent":["/**\n * Operation storage interfaces for queuing and managing asynchronous operations.\n *\n * @module\n */\n\nimport type { Hash, TransactionReceipt } from \"viem\";\nimport type { UnifiedRelayerRequest } from \"./relayer\";\n\n/**\n * The state of an asynchronous, relayed operation.\n *\n * @remarks\n * This is the data the application backend is responsible for persisting.\n * It serves as a complete recovery log for a given operation.\n *\n * @category Operations\n */\nexport interface OperationState {\n  status: \"pending\" | \"confirmed\" | \"failed\";\n  transactionHash: Hash;\n  originalRequest: UnifiedRelayerRequest;\n  nonce?: number;\n  retryCount: number;\n  lastAttemptedGas: { maxFeePerGas?: string; maxPriorityFeePerGas?: string };\n  submittedAt: number; // Unix timestamp (ms)\n  finalReceipt?: TransactionReceipt;\n  error?: string;\n}\n\n/**\n * Simple storage interface for operation state tracking.\n *\n * @remarks\n * This interface is used by the relayer handler to track operation state\n * in a stateful mode. Implementations can use any backend storage system.\n *\n * @category Operations\n */\nexport interface IRelayerStateStore {\n  /**\n   * Gets the state of an operation.\n   *\n   * @param operationId - The operation ID\n   * @returns The operation state or null if not found\n   */\n  get(operationId: string): Promise<OperationState | null>;\n\n  /**\n   * Sets the state of an operation.\n   *\n   * @param operationId - The operation ID\n   * @param state - The operation state to store\n   */\n  set(operationId: string, state: OperationState): Promise<void>;\n}\n\n/**\n * Represents a stored operation in the queue.\n */\nexport interface StoredOperation {\n  /** Unique identifier for the operation */\n  id: string;\n  /** Current status of the operation */\n  status: \"queued\" | \"processing\" | \"submitted\" | \"completed\" | \"failed\";\n  /** Serialized transaction or operation data */\n  data: string;\n  /** Number of retry attempts */\n  retryCount?: number;\n  /** Timestamp when the operation was created */\n  createdAt?: number;\n  /** Additional metadata */\n  metadata?: any;\n}\n\n/**\n * Interface for operation storage backends.\n *\n * @remarks\n * Implementations of this interface provide persistent storage for queued\n * operations in a distributed relayer system. This allows operations to\n * be processed asynchronously and recovered after failures.\n *\n * Common implementations include:\n * - PostgreSQL for production environments\n * - MongoDB for document-based storage\n * - DynamoDB for serverless deployments\n * - In-memory storage for testing\n *\n * @example\n * ```typescript\n * class PostgresOperationStore implements IOperationStore {\n *   async storeOperation(operation) {\n *     await this.db.query(\n *       'INSERT INTO operations (id, status, data) VALUES ($1, $2, $3)',\n *       [operation.id, 'queued', operation.data]\n *     );\n *   }\n *\n *   async getQueuedOperations(options) {\n *     const result = await this.db.query(\n *       'SELECT * FROM operations WHERE status = $1 LIMIT $2',\n *       ['queued', options.limit || 100]\n *     );\n *     return result.rows;\n *   }\n * }\n * ```\n *\n * @category Storage\n */\nexport interface IOperationStore {\n  /**\n   * Stores a new operation in the queue.\n   *\n   * @param operation - The operation to store\n   * @returns Promise that resolves when the operation is stored\n   */\n  storeOperation(operation: {\n    id: string;\n    data: any;\n    metadata?: any;\n  }): Promise<void>;\n\n  /**\n   * Retrieves queued operations for processing.\n   *\n   * @param options - Query options\n   * @returns Promise resolving to an array of queued operations\n   */\n  getQueuedOperations(options?: { limit?: number }): Promise<StoredOperation[]>;\n\n  /**\n   * Updates the status of an operation.\n   *\n   * @param operationId - The ID of the operation to update\n   * @param status - The new status\n   * @param metadata - Optional metadata to store with the update\n   * @returns Promise that resolves when the status is updated\n   */\n  updateStatus(\n    operationId: string,\n    status: string,\n    metadata?: any,\n  ): Promise<void>;\n\n  /**\n   * Gets operations currently being processed.\n   *\n   * @param options - Query options\n   * @returns Promise resolving to an array of processing operations\n   */\n  getProcessingOperations?(options?: {\n    limit?: number;\n  }): Promise<StoredOperation[]>;\n\n  /**\n   * Gets failed operations.\n   *\n   * @param options - Query options\n   * @returns Promise resolving to an array of failed operations\n   */\n  getFailedOperations?(options?: {\n    limit?: number;\n  }): Promise<StoredOperation[]>;\n\n  /**\n   * Gets the status of a specific operation.\n   *\n   * @param operationId - The ID of the operation to check\n   * @returns Promise resolving to the operation or null if not found\n   */\n  getOperation?(operationId: string): Promise<StoredOperation | null>;\n\n  /**\n   * Deletes an operation from storage.\n   *\n   * @param operationId - The ID of the operation to delete\n   * @returns Promise that resolves when the operation is deleted\n   */\n  deleteOperation?(operationId: string): Promise<void>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}