@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dba79a3

package/dist/types/data.d.ts

@@ -1,18 +1,15 @@
-import { Address, Hash } from 'viem';
-
+import type { Address, Hash } from "viem";
 /**
- * Represents a registered data file in the Vana network with complete blockchain metadata.
+ * Represents a file registered on the Vana blockchain.
  *
  * @remarks
- * This interface describes files that have been uploaded to storage and registered
- * on the Vana blockchain, including their storage location, ownership, and blockchain
- * tracking information. Each file receives a unique ID and is linked to the owner's
- * address for permission management. Used throughout the SDK for file operations
- * and access control workflows.
+ * Contains complete metadata for files uploaded to storage and registered
+ * on-chain. Each file has a unique ID, owner address, and storage URL.
+ * Used throughout SDK for file operations and permission management.
  *
  * @category Data Management
  */
-interface UserFile {
+export interface UserFile {
     /** Unique identifier assigned by the Data Registry contract. */
     id: number;
     /** Storage URL where the encrypted file content is hosted. */
@@ -48,7 +45,7 @@ interface UserFile {
  * organization, validation, and display purposes.
  * @category Data Management
  */
-interface FileMetadata {
+export interface FileMetadata {
     /** Original filename as provided by the user or application. */
     name?: string;
     /** Total file size in bytes for storage tracking. */
@@ -113,7 +110,7 @@ interface FileMetadata {
  * ```
  * @category Data Management
  */
-interface UploadParams {
+export interface UploadParams {
     /** Raw file data as string, Blob, or Buffer. */
     content: string | Blob | Buffer;
     /** Optional filename for the uploaded file. */
@@ -128,6 +125,13 @@ interface UploadParams {
     providerName?: string;
     /** Optional owner address (defaults to current wallet address). */
     owner?: Address;
+    /**
+     * Schema validation mode when schemaId is provided:
+     * - 'strict': Throw error on validation failure (default)
+     * - 'warn': Log warning and continue on validation failure
+     * - 'skip': Skip validation entirely
+     */
+    schemaValidation?: "strict" | "warn" | "skip";
 }
 /**
  * Upload parameters with encryption enabled.
@@ -137,7 +141,7 @@ interface UploadParams {
  * When encrypt is true, any permissions must include public keys for encryption.
  * @category Data Management
  */
-interface EncryptedUploadParams extends Omit<UploadParams, "permissions" | "encrypt"> {
+export interface EncryptedUploadParams extends Omit<UploadParams, "permissions" | "encrypt"> {
     /** File permissions with required public keys for encrypted data sharing. */
     permissions?: FilePermissionParams[];
     /** Encryption is enabled. */
@@ -150,7 +154,7 @@ interface EncryptedUploadParams extends Omit<UploadParams, "permissions" | "encr
  * This interface is used when uploading unencrypted data.
  * @category Data Management
  */
-interface UnencryptedUploadParams extends Omit<UploadParams, "encrypt"> {
+export interface UnencryptedUploadParams extends Omit<UploadParams, "encrypt"> {
     /** Encryption is disabled. */
     encrypt: false;
 }
@@ -177,7 +181,7 @@ interface UnencryptedUploadParams extends Omit<UploadParams, "encrypt"> {
  * ```
  * @category Data Management
  */
-interface FilePermissionParams {
+export interface FilePermissionParams {
     /** The account address that will be able to decrypt this file. */
     account: Address;
     /** The public key to encrypt the file's encryption key with. */
@@ -192,7 +196,7 @@ interface FilePermissionParams {
  *
  * @category Data Management
  */
-interface PermissionParams {
+export interface PermissionParams {
     /** The address of the application to grant permission to. */
     grantee: Address;
     /** The operation type (e.g., "llm_inference", "data_analysis", "compute_task"). */
@@ -223,7 +227,7 @@ interface PermissionParams {
  * @deprecated Removed in v2.0.0. Use FilePermissionParams for uploads.
  * @category Data Management
  */
-interface LegacyPermissionParams {
+export interface LegacyPermissionParams {
     grantee: Address;
     operation: string;
     parameters: Record<string, unknown>;
@@ -238,7 +242,7 @@ interface LegacyPermissionParams {
  * Returned by the `vana.data.upload()` method after successful upload and blockchain registration.
  * @category Data Management
  */
-interface UploadResult {
+export interface UploadResult {
     /** The file ID assigned by the DataRegistry contract. */
     fileId: number;
     /** The storage URL where the file is hosted. */
@@ -279,7 +283,7 @@ interface UploadResult {
  * ```
  * @category Data Management
  */
-interface UploadFileParams {
+export interface UploadFileParams {
     /** Raw file data in bytes, buffer, or string format. */
     content: Uint8Array | Buffer | string;
     /** Descriptive metadata for file organization and tracking. */
@@ -300,7 +304,7 @@ interface UploadFileParams {
  * and encryption details when applicable.
  * @category Data Management
  */
-interface UploadFileResult {
+export interface UploadFileResult {
     /** Public URL where the uploaded file can be accessed. */
     url: string;
     /** Actual file size in bytes after upload processing. */
@@ -315,7 +319,7 @@ interface UploadFileResult {
  *
  * @category Data Management
  */
-interface UploadEncryptedFileResult extends UploadFileResult {
+export interface UploadEncryptedFileResult extends UploadFileResult {
     /** The new file ID assigned by the DataRegistry */
     fileId: number;
     /** Transaction hash of the file registration */
@@ -326,7 +330,7 @@ interface UploadEncryptedFileResult extends UploadFileResult {
  *
  * @category Data Management
  */
-interface EncryptionInfo {
+export interface EncryptionInfo {
     /** Encryption algorithm used */
     algorithm: string;
     /** Key derivation function */
@@ -343,7 +347,7 @@ interface EncryptionInfo {
  *
  * @category Data Management
  */
-interface GetUserFilesParams {
+export interface GetUserFilesParams {
     /** Owner address to filter by */
     owner?: Address;
     /** Starting block number for filtering */
@@ -360,7 +364,7 @@ interface GetUserFilesParams {
  *
  * @category Data Management
  */
-interface GetFileParams {
+export interface GetFileParams {
     /** File ID to retrieve */
     fileId: number;
     /** Whether to include metadata */
@@ -371,7 +375,7 @@ interface GetFileParams {
  *
  * @category Data Management
  */
-interface DownloadFileParams {
+export interface DownloadFileParams {
     /** File URL or ID to download */
     file: string | number;
     /** Storage provider to use */
@@ -384,7 +388,7 @@ interface DownloadFileParams {
  *
  * @category Data Management
  */
-interface DownloadFileResult {
+export interface DownloadFileResult {
     /** File content */
     content: Uint8Array;
     /** File metadata */
@@ -397,7 +401,7 @@ interface DownloadFileResult {
  *
  * @category Data Management
  */
-interface DeleteFileParams {
+export interface DeleteFileParams {
     /** File ID to delete */
     fileId: number;
     /** Whether to also delete from storage */
@@ -410,7 +414,7 @@ interface DeleteFileParams {
  *
  * @category Data Management
  */
-interface DeleteFileResult {
+export interface DeleteFileResult {
     /** Whether the file was successfully deleted from the registry */
     registryDeleted: boolean;
     /** Whether the file was successfully deleted from storage */
@@ -418,12 +422,83 @@ interface DeleteFileResult {
     /** Transaction hash of the deletion */
     transactionHash?: Hash;
 }
+/**
+ * Options for encrypting a file
+ *
+ * @category Data Management
+ */
+export interface EncryptFileOptions {
+    /** Encryption seed for key derivation. Defaults to DEFAULT_ENCRYPTION_SEED */
+    seed?: string;
+    /** MIME type for the encrypted blob if input is not already a Blob */
+    mimeType?: string;
+}
+/**
+ * Result of encrypting a file
+ *
+ * @category Data Management
+ */
+export interface EncryptFileResult {
+    /** The encrypted data as a Blob */
+    encryptedData: Blob;
+    /** The encryption key used (derived from wallet) */
+    encryptionKey: string;
+}
+/**
+ * Options for decrypting a file
+ *
+ * @category Data Management
+ */
+export interface DecryptFileOptions {
+    /** Encryption seed for key derivation. Defaults to DEFAULT_ENCRYPTION_SEED */
+    seed?: string;
+}
+/**
+ * Parameters for uploading a file with permissions
+ *
+ * @category Data Management
+ */
+export interface UploadFileWithPermissionsParams {
+    /** The file data to encrypt and upload */
+    data: Blob;
+    /** Array of permissions to grant, each with account address and public key */
+    permissions: Array<{
+        account: Address;
+        publicKey: string;
+    }>;
+    /** Optional filename for the upload */
+    filename?: string;
+    /** Optional storage provider to use */
+    providerName?: string;
+}
+/**
+ * Parameters for adding permission to a file
+ *
+ * @category Data Management
+ */
+export interface AddFilePermissionParams {
+    /** The file ID to grant permission for */
+    fileId: number;
+    /** The account to grant permission to */
+    account: Address;
+    /** The public key of the account for encryption */
+    publicKey: string;
+}
+/**
+ * Options for decrypting a file with permission
+ *
+ * @category Data Management
+ */
+export interface DecryptFileWithPermissionOptions {
+    /** Optional account address to verify permission against */
+    account?: Address;
+}
 /**
  * File access permissions
  *
  * @category Data Management
  */
-interface FileAccessPermissions {
+export interface FileAccessPermissions {
     /** Whether the file can be read */
     read: boolean;
     /** Whether the file can be written */
@@ -438,7 +513,7 @@ interface FileAccessPermissions {
  *
  * @category Data Management
  */
-interface FileSharingConfig {
+export interface FileSharingConfig {
     /** Addresses that can access the file */
     allowedAddresses?: Address[];
     /** Expiration time for shared access */
@@ -451,7 +526,7 @@ interface FileSharingConfig {
  *
  * @category Data Management
  */
-interface BatchUploadParams {
+export interface BatchUploadParams {
     /** Array of files to upload */
     files: UploadFileParams[];
     /** Storage provider to use for all files */
@@ -466,7 +541,7 @@ interface BatchUploadParams {
  *
  * @category Data Management
  */
-interface BatchUploadResult {
+export interface BatchUploadResult {
     /** Results for each uploaded file */
     results: UploadEncryptedFileResult[];
     /** Overall success status */
@@ -482,7 +557,7 @@ interface BatchUploadResult {
  *
  * @category Data Management
  */
-interface SchemaMetadata {
+export interface SchemaMetadata {
     /** Schema ID */
     id: number;
     /** Schema name */
@@ -496,7 +571,7 @@ interface SchemaMetadata {
  * Complete schema with all definition fields populated.
  * This is what schemas.get() returns - a schema with the definition fetched.
  */
-interface CompleteSchema extends SchemaMetadata {
+export interface CompleteSchema extends SchemaMetadata {
     /** Version of the schema */
     version: string;
     /** Optional description of the schema */
@@ -544,7 +619,7 @@ interface CompleteSchema extends SchemaMetadata {
  * };
  * ```
  */
-interface Schema extends SchemaMetadata {
+export interface Schema extends SchemaMetadata {
     /** Version of the schema (present when definition is fetched) */
     version?: string;
     /** Optional description of the schema */
@@ -559,7 +634,7 @@ interface Schema extends SchemaMetadata {
  *
  * @category Data Management
  */
-interface Refiner {
+export interface Refiner {
     /** Refiner ID */
     id: number;
     /** DLP ID this refiner belongs to */
@@ -578,7 +653,7 @@ interface Refiner {
  *
  * @category Data Management
  */
-interface AddSchemaParams {
+export interface AddSchemaParams {
     /** Schema name */
     name: string;
     /** Schema dialect */
@@ -591,7 +666,7 @@ interface AddSchemaParams {
  *
  * @category Data Management
  */
-interface AddSchemaResult {
+export interface AddSchemaResult {
     /** The new schema ID assigned by the contract */
     schemaId: number;
     /** Transaction hash of the schema registration */
@@ -615,7 +690,7 @@ interface AddSchemaResult {
  * };
  * ```
  */
-interface AddRefinerParams {
+export interface AddRefinerParams {
     /** DLP ID this refiner belongs to */
     dlpId: number;
     /** Refiner name */
@@ -630,7 +705,7 @@ interface AddRefinerParams {
  *
  * @category Data Management
  */
-interface AddRefinerResult {
+export interface AddRefinerResult {
     /** The new refiner ID assigned by the contract */
     refinerId: number;
     /** Transaction hash of the refiner registration */
@@ -641,7 +716,7 @@ interface AddRefinerResult {
  *
  * @category Data Management
  */
-interface UpdateSchemaIdParams {
+export interface UpdateSchemaIdParams {
     /** Refiner ID to update */
     refinerId: number;
     /** New schema ID to associate with the refiner */
@@ -652,7 +727,7 @@ interface UpdateSchemaIdParams {
  *
  * @category Data Management
  */
-interface UpdateSchemaIdResult {
+export interface UpdateSchemaIdResult {
     /** Transaction hash of the update */
     transactionHash: Hash;
 }
@@ -661,7 +736,7 @@ interface UpdateSchemaIdResult {
  *
  * @category Data Management
  */
-interface TrustedServer {
+export interface TrustedServer {
     /** Unique identifier for the trusted server relationship */
     id: string;
     /** Server address (EVM address) */
@@ -680,15 +755,9 @@ interface TrustedServer {
  *
  * @category Data Management
  */
-interface GetUserTrustedServersParams {
+export interface GetUserTrustedServersParams {
     /** User address to query trusted servers for */
     user: Address;
     /** Optional subgraph URL to override default */
     subgraphUrl?: string;
-    /** Maximum number of results */
-    limit?: number;
-    /** Number of results to skip */
-    offset?: number;
 }
-
-export type { AddRefinerParams, AddRefinerResult, AddSchemaParams, AddSchemaResult, BatchUploadParams, BatchUploadResult, CompleteSchema, DeleteFileParams, DeleteFileResult, DownloadFileParams, DownloadFileResult, EncryptedUploadParams, EncryptionInfo, FileAccessPermissions, FileMetadata, FilePermissionParams, FileSharingConfig, GetFileParams, GetUserFilesParams, GetUserTrustedServersParams, LegacyPermissionParams, PermissionParams, Refiner, Schema, SchemaMetadata, TrustedServer, UnencryptedUploadParams, UpdateSchemaIdParams, UpdateSchemaIdResult, UploadEncryptedFileResult, UploadFileParams, UploadFileResult, UploadParams, UploadResult, UserFile };

package/dist/types/external-apis.d.ts

@@ -7,9 +7,9 @@
  * Documentation: https://replicate.com/docs/reference/http
  */
 /** Status values for Replicate predictions */
-type ReplicateStatus = "starting" | "processing" | "succeeded" | "failed" | "canceled";
+export type ReplicateStatus = "starting" | "processing" | "succeeded" | "failed" | "canceled";
 /** Base Replicate API prediction response */
-interface ReplicateAPIResponse {
+export interface ReplicateAPIResponse {
     /** Unique identifier for the prediction */
     id: string;
     /** Model version identifier */
@@ -53,7 +53,7 @@ interface ReplicateAPIResponse {
  * Storage Provider API Types
  */
 /** Pinata IPFS upload response */
-interface PinataUploadResponse {
+export interface PinataUploadResponse {
     /** IPFS hash of the uploaded content */
     IpfsHash: string;
     /** Size of the pinned content in bytes */
@@ -64,7 +64,7 @@ interface PinataUploadResponse {
     isDuplicate?: boolean;
 }
 /** Pinata pin information */
-interface PinataPin {
+export interface PinataPin {
     /** IPFS hash */
     ipfs_pin_hash: string;
     /** Pin size in bytes */
@@ -82,7 +82,7 @@ interface PinataPin {
     };
 }
 /** Pinata list response */
-interface PinataListResponse {
+export interface PinataListResponse {
     /** Total count of pins */
     count: number;
     /** Array of pin information */
@@ -93,7 +93,7 @@ interface PinataListResponse {
  * Used for internal API routes in the demo application
  */
 /** Standard API response wrapper */
-interface APIResponse<T = unknown> {
+export interface APIResponse<T = unknown> {
     /** Whether the request was successful */
     success: boolean;
     /** Response data (if successful) */
@@ -120,7 +120,7 @@ interface APIResponse<T = unknown> {
  * }
  * ```
  */
-declare function isReplicateAPIResponse(value: unknown): value is ReplicateAPIResponse;
+export declare function isReplicateAPIResponse(value: unknown): value is ReplicateAPIResponse;
 /**
  * Validates whether a value is a valid APIResponse.
  *
@@ -140,7 +140,7 @@ declare function isReplicateAPIResponse(value: unknown): value is ReplicateAPIRe
  * }
  * ```
  */
-declare function isAPIResponse<T>(value: unknown): value is APIResponse<T>;
+export declare function isAPIResponse<T>(value: unknown): value is APIResponse<T>;
 /**
  * Utility Functions for Safe JSON Parsing
  */
@@ -162,7 +162,7 @@ declare function isAPIResponse<T>(value: unknown): value is APIResponse<T>;
  * }
  * ```
  */
-declare function safeParseJSON<T>(jsonString: string, typeGuard: (value: unknown) => value is T): T | null;
+export declare function safeParseJSON<T>(jsonString: string, typeGuard: (value: unknown) => value is T): T | null;
 /**
  * Parses Replicate API response output with type safety.
  *
@@ -181,6 +181,4 @@ declare function safeParseJSON<T>(jsonString: string, typeGuard: (value: unknown
  * }
  * ```
  */
-declare function parseReplicateOutput<T>(response: ReplicateAPIResponse, typeGuard: (value: unknown) => value is T): T | null;
-
-export { type APIResponse, type PinataListResponse, type PinataPin, type PinataUploadResponse, type ReplicateAPIResponse, type ReplicateStatus, isAPIResponse, isReplicateAPIResponse, parseReplicateOutput, safeParseJSON };
+export declare function parseReplicateOutput<T>(response: ReplicateAPIResponse, typeGuard: (value: unknown) => value is T): T | null;

package/dist/types/generics.cjs.map

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