@opendatalabs/vana-sdk 2.3.0 → 3.0.1

package/dist/tests/factories/mockFactory.d.ts

@@ -1,316 +0,0 @@
-/**
- * Provides type-safe mock factories for testing Vana SDK components.
- *
- * @remarks
- * This module contains factory functions that create properly typed mock objects
- * for testing. These factories eliminate the need for `as any` assertions in tests
- * by providing complete implementations with sensible defaults.
- *
- * ## Usage Patterns
- *
- * ### Basic Usage
- * ```typescript
- * const context = createMockControllerContext();
- * const controller = new MyController(context);
- * ```
- *
- * ### Direct Transaction Testing (No Relayer/Storage)
- * ```typescript
- * const context = createMockControllerContextForDirectTransaction();
- * ```
- *
- * ### With Relayer Callbacks
- * ```typescript
- * const context = createMockControllerContextWithRelayer();
- * ```
- *
- * ### Accessing Mock Methods
- * When you need to access mock methods like `mockImplementation`, wrap with `vi.mocked()`:
- * ```typescript
- * vi.mocked(context.walletClient.signTypedData).mockImplementation(...);
- * ```
- *
- * @category Testing
- * @module mockFactory
- * @internal
- */
-import { vi } from "vitest";
-import type { WalletClient, PublicClient, Account, Chain, Hash, Address } from "../../types";
-import type { ControllerContext } from "../../types/controller-context";
-import type { VanaPlatformAdapter } from "../../platform/interface";
-import type { StorageManager } from "../../storage/manager";
-/**
- * Represents a deeply partial version of type T.
- *
- * @remarks
- * This utility type allows for partial overrides at any depth of an object structure,
- * making it easy to specify only the properties you want to customize in mocks.
- */
-export type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-/**
- * Creates a mock Viem account for testing.
- *
- * @param overrides - Optional account properties to override the defaults
- * @returns A complete Account object with mock implementations
- *
- * @example
- * ```typescript
- * const account = createMockAccount({
- *   address: "0xCustomAddress"
- * });
- * ```
- */
-export declare function createMockAccount(overrides?: Partial<Account>): Account;
-/**
- * Creates a mock blockchain chain configuration.
- *
- * @param overrides - Optional chain properties to override the defaults
- * @returns A complete Chain object configured for Moksha Testnet by default
- *
- * @example
- * ```typescript
- * const chain = createMockChain({
- *   id: 1480,
- *   name: "Vana Mainnet"
- * });
- * ```
- */
-export declare function createMockChain(overrides?: Partial<Chain>): Chain;
-/**
- * Creates a fully mocked Viem WalletClient for testing.
- *
- * @param overrides - Optional nested properties to override the defaults
- * @returns A complete WalletClient with all methods mocked
- *
- * @remarks
- * This factory creates a WalletClient with all required methods stubbed.
- * The client is configured with a local test account and Moksha Testnet by default.
- * All async methods return sensible default values.
- *
- * @example
- * ```typescript
- * const wallet = createTypedMockWalletClient({
- *   account: { address: "0xCustom" },
- *   chain: { id: 1480 }
- * });
- * ```
- */
-export declare function createTypedMockWalletClient(overrides?: DeepPartial<WalletClient>): WalletClient;
-/**
- * Creates a fully mocked Viem PublicClient for testing.
- *
- * @param overrides - Optional nested properties to override the defaults
- * @returns A complete PublicClient with all methods mocked
- *
- * @remarks
- * This factory creates a PublicClient with all required RPC methods stubbed.
- * The client returns sensible default values for blockchain queries.
- * Transaction receipts are configured to return success by default.
- *
- * @example
- * ```typescript
- * const client = createTypedMockPublicClient({
- *   chain: { id: 1480 }
- * });
- * ```
- */
-export declare function createTypedMockPublicClient(overrides?: DeepPartial<PublicClient>): PublicClient;
-/**
- * Creates a mock StorageManager using the FakeStorageManager implementation.
- *
- * @param overrides - Optional properties to override on the fake instance
- * @returns A complete StorageManager implementation for testing
- *
- * @remarks
- * This factory uses the FakeStorageManager class instead of complex mocking,
- * providing a simpler and more maintainable testing approach.
- * The fake maintains in-memory state and tracks method calls.
- *
- * @example
- * ```typescript
- * const storage = createTypedMockStorageManager();
- * const result = await storage.upload(blob, "test.txt");
- * ```
- */
-export declare function createTypedMockStorageManager(overrides?: Partial<StorageManager>): StorageManager;
-/**
- * Creates a complete mock ControllerContext for testing controllers.
- *
- * @param overrides - Optional nested properties to override the defaults
- * @returns A ControllerContext with guaranteed waitForTransactionEvents method
- *
- * @remarks
- * This factory creates a complete context object with all required dependencies:
- * - WalletClient and PublicClient for blockchain interactions
- * - StorageManager for file operations
- * - Platform adapter for encryption
- * - waitForTransactionEvents using FakeWaitForTransactionEvents
- *
- * The returned context guarantees that waitForTransactionEvents is always present,
- * eliminating the need for conditional checks in tests.
- *
- * @example
- * ```typescript
- * const context = createMockControllerContext({
- *   walletClient: { account: { address: "0xCustom" } }
- * });
- * const controller = new DataController(context);
- * ```
- */
-export declare function createMockControllerContext(overrides?: DeepPartial<ControllerContext>): ControllerContext & Required<Pick<ControllerContext, "waitForTransactionEvents">>;
-/**
- * Creates a mock VanaPlatformAdapter for testing.
- *
- * @param overrides - Optional properties to override the default mock adapter
- * @returns A complete VanaPlatformAdapter with encryption and key management methods
- *
- * @example
- * ```typescript
- * const platform = createMockPlatform({
- *   generateKeyPair: vi.fn().mockResolvedValue({ publicKey: "test", privateKey: "test" })
- * });
- * ```
- */
-export declare function createMockPlatform(overrides?: Partial<VanaPlatformAdapter>): VanaPlatformAdapter;
-/**
- * Creates a typed mock function compatible with vitest.
- *
- * @returns A vi.fn() mock with proper typing
- *
- * @example
- * ```typescript
- * const mockCallback = createMockFn<(value: string) => void>();
- * mockCallback.mockImplementation((value) => console.log(value));
- * ```
- */
-export declare function createMockFn<T extends (...args: unknown[]) => unknown>(): ReturnType<typeof vi.fn<T>>;
-/**
- * Safely casts a partial mock to the full type.
- *
- * @param value - Partial object to cast to full type
- * @returns The value cast to type T
- *
- * @remarks
- * Use this as a last resort when the mock factory doesn't cover all properties.
- * This is a type assertion helper that should be used sparingly.
- *
- * @example
- * ```typescript
- * const partialMock = { someProperty: 'value' };
- * const fullMock = safeCast<CompleteType>(partialMock);
- * ```
- */
-export declare function safeCast<T>(value: DeepPartial<T>): T;
-/**
- * Creates a mock viem Log object for testing.
- *
- * @param eventName - The name of the event
- * @param args - The event arguments
- * @returns A complete Log object with all required properties
- *
- * @remarks
- * This factory creates a complete viem Log object with all required blockchain
- * metadata. Use this when mocking parseEventLogs return values.
- *
- * @example
- * ```typescript
- * const mockLog = createMockLog("PermissionGranted", {
- *   permissionId: 123n,
- *   user: "0xUserAddress",
- *   grant: "grant-data"
- * });
- * ```
- */
-export declare function createMockLog(eventName: string, args: Record<string, unknown>): {
-    eventName: string;
-    args: Record<string, unknown>;
-    address: Address;
-    blockHash: Hash;
-    blockNumber: bigint;
-    data: Hash;
-    logIndex: number;
-    removed: boolean;
-    transactionHash: Hash;
-    transactionIndex: number;
-    topics: readonly Hash[];
-};
-/**
- * Creates a type-safe mock that only requires specified properties.
- *
- * @param partial - Partial object with only the properties you need
- * @returns The partial object cast to the full type T
- *
- * @remarks
- * This is useful for mocking interfaces where you only care about certain methods.
- * The unspecified properties will be undefined at runtime.
- *
- * @example
- * ```typescript
- * const mock = createPartialMock<MyInterface>({
- *   methodICareAbout: vi.fn().mockReturnValue('result'),
- * });
- * ```
- */
-export declare function createPartialMock<T>(partial: Partial<T>): T;
-/**
- * Creates a mock ControllerContext specifically configured for direct transaction testing.
- *
- * @param overrides - Optional nested properties to override the defaults
- * @returns A ControllerContext with no relayer callbacks or storage manager
- *
- * @remarks
- * This factory variant is optimized for testing direct blockchain transactions
- * without gasless relayer support. It sets both `relayer` and
- * `storageManager` to `undefined`, forcing the controller to use direct transactions.
- *
- * @example
- * ```typescript
- * const context = createMockControllerContextForDirectTransaction();
- * const controller = new PermissionsController(context);
- * // Test will throw "No storage available" error as expected
- * await expect(controller.grant(params)).rejects.toThrow("No storage available");
- * ```
- */
-export declare function createMockControllerContextForDirectTransaction(overrides?: DeepPartial<ControllerContext>): ControllerContext & Required<Pick<ControllerContext, "waitForTransactionEvents">>;
-/**
- * Creates a mock ControllerContext with relayer callbacks configured.
- *
- * @param overrides - Optional nested properties to override the defaults
- * @returns A ControllerContext with default relayer callbacks for gasless transactions
- *
- * @remarks
- * This factory variant provides sensible defaults for testing gasless transactions
- * with relayer support. It includes mock implementations for `storeGrantFile` and
- * `submitPermissionGrant` that return successful responses.
- *
- * @example
- * ```typescript
- * const context = createMockControllerContextWithRelayer();
- * const controller = new PermissionsController(context);
- * const result = await controller.grant(params);
- * expect(context.relayer?.storeGrantFile).toHaveBeenCalled();
- * ```
- */
-export declare function createMockControllerContextWithRelayer(overrides?: DeepPartial<ControllerContext>): ControllerContext & Required<Pick<ControllerContext, "waitForTransactionEvents">>;
-/**
- * Helper to properly type a mocked client for TypeScript.
- *
- * @param client - The client to type as mocked
- * @returns The client typed with vitest mock methods
- *
- * @remarks
- * Use this when you need TypeScript to recognize mock methods on factory-created clients.
- * This is a convenience wrapper around `vi.mocked()`.
- *
- * @example
- * ```typescript
- * const context = createMockControllerContext();
- * const mockedWallet = asMocked(context.walletClient);
- * mockedWallet.signTypedData.mockImplementation((data) => {
- *   // Custom implementation
- * });
- * ```
- */
-export declare function asMocked<T>(client: T): ReturnType<typeof vi.mocked<T>>;

package/dist/tests/fakes/FakeStorageManager.d.ts

@@ -1,200 +0,0 @@
-/**
- * Provides a controllable fake implementation of StorageManager for testing.
- *
- * @remarks
- * This test fake replaces complex storage mocking with a simple, in-memory implementation
- * that allows tests to configure upload/download behavior without external dependencies.
- * Use this when testing controllers that depend on StorageManager functionality.
- *
- * The fake maintains in-memory maps for uploads and downloads, tracks call counts,
- * and supports multiple storage providers for comprehensive testing scenarios.
- *
- * @category Testing
- * @internal
- */
-import type { StorageProvider, StorageUploadResult, StorageFile, StorageListOptions } from "../../types/storage";
-export declare class FakeStorageManager {
-    private uploads;
-    private downloads;
-    private storageProviders;
-    private defaultProvider;
-    private uploadCallCount;
-    private downloadCallCount;
-    constructor();
-    /**
-     * Creates a fake storage provider with basic functionality.
-     *
-     * @param name - The name identifier for this provider
-     * @returns A StorageProvider implementation for testing
-     */
-    private createFakeProvider;
-    /**
-     * Simulates uploading a file to storage.
-     *
-     * @param data - The Blob data to upload
-     * @param filename - Optional filename for the upload
-     * @param providerName - Optional storage provider to use (defaults to defaultProvider)
-     * @returns A promise resolving to the upload result with URL and metadata
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * const blob = new Blob(["test data"], { type: "text/plain" });
-     * const result = await fake.upload(blob, "test.txt");
-     * console.log(result.url); // "https://ipfs.io/ipfs/QmTest1"
-     * ```
-     */
-    upload(data: Blob, _filename?: string, providerName?: string): Promise<StorageUploadResult>;
-    /**
-     * Simulates downloading a file from storage.
-     *
-     * @param url - The URL to download from
-     * @returns A promise resolving to the Blob content
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * const content = new Blob(["hello world"]);
-     * fake.setDownloadResult("https://test.url", content);
-     * const downloaded = await fake.download("https://test.url");
-     * ```
-     */
-    download(url: string): Promise<Blob>;
-    /**
-     * Lists files in storage, optionally filtered by prefix.
-     *
-     * @param options - Optional filtering and pagination options
-     * @param _providerName - Optional provider name (unused in fake implementation)
-     * @returns A promise resolving to an array of file objects
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * await fake.upload(new Blob(["data"]), "file1.txt");
-     * await fake.upload(new Blob(["data"]), "file2.txt");
-     * const files = await fake.list();
-     * // Returns ["https://ipfs.io/ipfs/QmTest1", "https://ipfs.io/ipfs/QmTest2"]
-     * ```
-     */
-    list(options?: StorageListOptions, _providerName?: string): Promise<StorageFile[]>;
-    /**
-     * Simulates deleting a file from storage.
-     *
-     * @param url - The URL of the file to delete
-     * @returns A promise resolving to true if deleted, false if not found
-     */
-    delete(url: string): Promise<boolean>;
-    /**
-     * Registers a custom storage provider.
-     *
-     * @param name - The unique name for this provider
-     * @param provider - The StorageProvider implementation
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * const customProvider: StorageProvider = {
-     *   upload: async (data) => ({ url: "https://custom.com/file" }),
-     *   download: async (url) => new Blob(["custom"]),
-     *   list: async () => [],
-     *   delete: async () => true,
-     *   getConfig: () => ({})
-     * };
-     * fake.register("custom", customProvider);
-     * ```
-     */
-    register(name: string, provider: StorageProvider): void;
-    /**
-     * Retrieves a registered storage provider by name.
-     *
-     * @param name - The name of the provider to retrieve
-     * @returns The StorageProvider if found, undefined otherwise
-     */
-    getProvider(name?: string): StorageProvider;
-    /**
-     * Sets the default storage provider to use.
-     *
-     * @param name - The name of a registered provider
-     * @throws Error if the provider name is not registered
-     */
-    setDefaultProvider(name: string): void;
-    /**
-     * Lists all registered storage provider names.
-     *
-     * @returns Array of provider name strings
-     */
-    listProviders(): string[];
-    /**
-     * Gets the name of the current default storage provider.
-     *
-     * @returns The default provider name
-     */
-    getDefaultProvider(): string;
-    /**
-     * Gets all registered storage provider names (alias for listProviders).
-     *
-     * @returns Array of provider name strings
-     */
-    getStorageProviders(): string[];
-    /**
-     * Gets the name of the default storage provider (alias for getDefaultProvider).
-     *
-     * @returns The default provider name
-     */
-    getDefaultStorageProvider(): string;
-    /**
-     * Configures a specific upload result for testing.
-     *
-     * @param url - The URL to configure
-     * @param result - The upload result to return for this URL
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * fake.setUploadResult("https://test.url", {
-     *   url: "https://test.url",
-     *   size: 1024,
-     *   contentType: "application/json"
-     * });
-     * ```
-     */
-    setUploadResult(url: string, result: StorageUploadResult): void;
-    /**
-     * Configures specific download content for a URL.
-     *
-     * @param url - The URL to configure
-     * @param content - The Blob content to return when this URL is downloaded
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * const testContent = new Blob(["test data"], { type: "text/plain" });
-     * fake.setDownloadResult("https://test.url", testContent);
-     * ```
-     */
-    setDownloadResult(url: string, content: Blob): void;
-    /**
-     * Gets the number of times upload() has been called.
-     *
-     * @returns The upload call count
-     */
-    getUploadCallCount(): number;
-    /**
-     * Gets the number of times download() has been called.
-     *
-     * @returns The download call count
-     */
-    getDownloadCallCount(): number;
-    /**
-     * Resets all state, clearing uploads, downloads, and counters.
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeStorageManager();
-     * await fake.upload(new Blob(["data"]), "file.txt");
-     * fake.reset();
-     * const files = await fake.list(); // Returns []
-     * ```
-     */
-    reset(): void;
-}

package/dist/tests/fakes/FakeStorageManager.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/tests/fakes/FakeWaitForTransactionEvents.d.ts

@@ -1,170 +0,0 @@
-/**
- * Provides a controllable fake implementation of transaction event waiting for testing.
- *
- * @remarks
- * This test fake replaces complex mocking with a simple, predictable implementation
- * that allows tests to configure specific responses for transaction hashes.
- * Use this when testing controllers that depend on waitForTransactionEvents functionality.
- *
- * The fake maintains separate maps for responses and errors, allowing tests to
- * simulate both successful and failing transaction scenarios.
- *
- * @category Testing
- * @internal
- */
-import type { Hash, Address } from "viem";
-/**
- * Minimal TransactionResult interface to avoid circular dependencies.
- * Mirrors the actual TransactionResult from types/operations.
- */
-interface TransactionResultLike {
-    hash: Hash;
-    from?: Address;
-    contract?: string;
-    fn?: string;
-}
-/**
- * Represents the result of waiting for transaction events.
- */
-export interface TransactionEventResult {
-    /** The transaction hash that was monitored */
-    hash: Hash;
-    /** The address that initiated the transaction */
-    from: Address;
-    /** The name of the contract that was called */
-    contract: string;
-    /** The function name that was invoked */
-    fn: string;
-    /** Map of expected events that were emitted, keyed by event name */
-    expectedEvents: Record<string, unknown>;
-    /** Array of all events emitted by the transaction */
-    allEvents: unknown[];
-    /** Whether all expected events were found in the transaction */
-    hasExpectedEvents: boolean;
-}
-export declare class FakeWaitForTransactionEvents {
-    private responses;
-    private errors;
-    private defaultResponse;
-    /**
-     * Configures a specific response for a given transaction hash.
-     *
-     * @param hash - The transaction hash to configure a response for
-     * @param response - The response object to return when this hash is queried
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeWaitForTransactionEvents();
-     * fake.setResponse("0xabc123", {
-     *   hash: "0xabc123" as Hash,
-     *   from: "0xuser",
-     *   contract: "DataRegistry",
-     *   fn: "addFile",
-     *   expectedEvents: { FileAdded: { fileId: 1n } },
-     *   allEvents: [],
-     *   hasExpectedEvents: true
-     * });
-     * ```
-     */
-    setResponse(hash: string, response: TransactionEventResult): void;
-    /**
-     * Configures an error to be thrown for a specific transaction hash.
-     *
-     * @param hash - The transaction hash that should trigger an error
-     * @param error - The error to throw when this hash is queried
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeWaitForTransactionEvents();
-     * fake.setError("0xfailed", new Error("Transaction timeout"));
-     * ```
-     */
-    setError(hash: string, error: Error): void;
-    /**
-     * Sets the default response returned for any unconfigured transaction hash.
-     *
-     * @param response - The default response object to use
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeWaitForTransactionEvents();
-     * fake.setDefaultResponse({
-     *   hash: "0xdefault" as Hash,
-     *   from: "0xdefault",
-     *   contract: "TestContract",
-     *   fn: "testFunction",
-     *   expectedEvents: {},
-     *   allEvents: [],
-     *   hasExpectedEvents: false
-     * });
-     * ```
-     */
-    setDefaultResponse(response: TransactionEventResult): void;
-    /**
-     * Simulates waiting for transaction events, returning configured responses or throwing configured errors.
-     *
-     * @param txOrHash - A TransactionResult-like object or raw transaction hash string
-     * @returns A promise that resolves with the configured response for this hash
-     * @throws The configured error for this hash, if one was set
-     */
-    wait(txOrHash: TransactionResultLike | Hash | string): Promise<TransactionEventResult>;
-    /**
-     * Clears all configured responses and errors, resetting the fake to its initial state.
-     */
-    reset(): void;
-    /**
-     * Gets all transaction hashes that have configured responses.
-     *
-     * @returns Array of transaction hash strings
-     */
-    getConfiguredHashes(): string[];
-    /**
-     * Creates a function that can be used as a mock implementation in vitest.
-     *
-     * @returns A function compatible with vi.fn().mockImplementation()
-     *
-     * @example
-     * ```typescript
-     * const fake = new FakeWaitForTransactionEvents();
-     * const mockWaitForTransactionEvents = vi.fn()
-     *   .mockImplementation(fake.asMockFunction());
-     * ```
-     */
-    asMockFunction(): (txOrHash: TransactionResultLike | Hash | string) => Promise<TransactionEventResult>;
-    /**
-     * Creates a pre-configured response object for a successful SchemaAdded event.
-     *
-     * @param schemaId - The ID of the schema that was added
-     * @param name - The name of the schema
-     * @param dialect - The dialect/format of the schema (e.g., "json", "jsonschema")
-     * @param definitionUrl - The URL where the schema definition is stored
-     * @param hash - The transaction hash (defaults to "0xtxhash")
-     * @returns A complete TransactionEventResult object for a SchemaAdded event
-     *
-     * @example
-     * ```typescript
-     * const response = FakeWaitForTransactionEvents.createSchemaAddedResponse(
-     *   123n,
-     *   "UserProfile",
-     *   "jsonschema",
-     *   "https://ipfs.io/ipfs/QmHash"
-     * );
-     * fake.setResponse("0xtxhash", response);
-     * ```
-     */
-    static createSchemaAddedResponse(schemaId: bigint, name: string, dialect: string, definitionUrl: string, hash?: Hash): TransactionEventResult;
-    /**
-     * Creates a response object representing a transaction with no expected events.
-     *
-     * @param hash - The transaction hash (defaults to "0xtxhash")
-     * @returns A TransactionEventResult with hasExpectedEvents set to false
-     *
-     * @example
-     * ```typescript
-     * const emptyResponse = FakeWaitForTransactionEvents.createEmptyResponse();
-     * fake.setResponse("0xempty", emptyResponse);
-     * ```
-     */
-    static createEmptyResponse(hash?: Hash): TransactionEventResult;
-}
-export {};

package/dist/tests/fakes/FakeWaitForTransactionEvents.test.d.ts

@@ -1 +0,0 @@
-export {};