@opendatalabs/vana-sdk 0.1.0-alpha.f54fafd → 0.1.0-alpha.f732fa2

package/dist/controllers/base.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Base controller class providing common functionality for all controllers.
+ *
+ * @remarks
+ * This abstract class establishes the foundation for all Vana SDK controllers,
+ * providing shared utilities like wallet validation and context management.
+ * All controllers should extend this base class to ensure consistency and
+ * shared behavior across the SDK.
+ *
+ * The class follows the Single Responsibility Principle by handling only
+ * the core controller concerns while leaving specific functionality to
+ * implementing classes.
+ *
+ * @category Controllers
+ */
+import type { WalletClient } from "viem";
+import type { ControllerContext } from "../types/controller-context";
+/**
+ * Abstract base controller that all Vana SDK controllers extend.
+ *
+ * @remarks
+ * Provides common functionality and patterns used across all controllers,
+ * including wallet validation and context management. This ensures
+ * consistency and reduces code duplication throughout the SDK.
+ *
+ * Key features:
+ * - Wallet client validation with TypeScript assertion signatures
+ * - Consistent error handling for read-only scenarios
+ * - Shared context management patterns
+ * - Type-safe wallet operations
+ *
+ * @example
+ * ```typescript
+ * class MyController extends BaseController {
+ *   async performWalletOperation() {
+ *     this.assertWallet(); // Ensures wallet is available
+ *     // Now this.context.walletClient is guaranteed to be available
+ *     const address = await this.context.walletClient.getAddresses();
+ *     return address[0];
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseController {
+    protected readonly context: ControllerContext;
+    /**
+     * Creates a new controller instance with the provided context.
+     *
+     * @param context - The controller context containing clients and configuration
+     */
+    constructor(context: ControllerContext);
+    /**
+     * Asserts that a wallet client with an account is available for operations requiring signing.
+     *
+     * @remarks
+     * This method uses TypeScript assertion signatures to narrow the type of
+     * `this.context` to guarantee that `walletClient` with an account is available
+     * after the call succeeds. This provides compile-time safety for wallet operations
+     * while enabling clear error messages for read-only scenarios.
+     *
+     * The assertion signature ensures that after calling this method,
+     * TypeScript knows that `this.context.walletClient` is definitely available
+     * with a configured account.
+     *
+     * @throws {ReadOnlyError} When no wallet client is configured
+     * @throws {Error} When wallet client exists but no account is configured
+     *
+     * @example
+     * ```typescript
+     * async performWalletOperation() {
+     *   this.assertWallet(); // Type assertion + runtime check
+     *
+     *   // TypeScript now knows walletClient and account are available
+     *   const account = this.context.walletClient.account;
+     *   const address = typeof account === 'string' ? account : account.address;
+     * }
+     * ```
+     */
+    protected assertWallet(): asserts this is {
+        context: ControllerContext & {
+            walletClient: WalletClient;
+        };
+    };
+}

package/dist/controllers/base.js

@@ -0,0 +1,59 @@
+import { ReadOnlyError } from "../errors";
+class BaseController {
+  /**
+   * Creates a new controller instance with the provided context.
+   *
+   * @param context - The controller context containing clients and configuration
+   */
+  constructor(context) {
+    this.context = context;
+  }
+  /**
+   * Asserts that a wallet client with an account is available for operations requiring signing.
+   *
+   * @remarks
+   * This method uses TypeScript assertion signatures to narrow the type of
+   * `this.context` to guarantee that `walletClient` with an account is available
+   * after the call succeeds. This provides compile-time safety for wallet operations
+   * while enabling clear error messages for read-only scenarios.
+   *
+   * The assertion signature ensures that after calling this method,
+   * TypeScript knows that `this.context.walletClient` is definitely available
+   * with a configured account.
+   *
+   * @throws {ReadOnlyError} When no wallet client is configured
+   * @throws {Error} When wallet client exists but no account is configured
+   *
+   * @example
+   * ```typescript
+   * async performWalletOperation() {
+   *   this.assertWallet(); // Type assertion + runtime check
+   *
+   *   // TypeScript now knows walletClient and account are available
+   *   const account = this.context.walletClient.account;
+   *   const address = typeof account === 'string' ? account : account.address;
+   * }
+   * ```
+   */
+  assertWallet() {
+    if (!this.context.walletClient) {
+      const stack = new Error().stack;
+      const callingMethod = stack?.split("\n")[2]?.match(/at \w+\.(\w+)/)?.[1] ?? "this operation";
+      throw new ReadOnlyError(
+        callingMethod,
+        "Initialize the SDK with a walletClient to perform this operation"
+      );
+    }
+    if (!this.context.walletClient.account) {
+      const stack = new Error().stack;
+      const callingMethod = stack?.split("\n")[2]?.match(/at \w+\.(\w+)/)?.[1] ?? "this operation";
+      throw new Error(
+        `No wallet account connected. Cannot perform ${callingMethod} without an account.`
+      );
+    }
+  }
+}
+export {
+  BaseController
+};
+//# sourceMappingURL=base.js.map

package/dist/controllers/base.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/base.ts"],"sourcesContent":["/**\n * Base controller class providing common functionality for all controllers.\n *\n * @remarks\n * This abstract class establishes the foundation for all Vana SDK controllers,\n * providing shared utilities like wallet validation and context management.\n * All controllers should extend this base class to ensure consistency and\n * shared behavior across the SDK.\n *\n * The class follows the Single Responsibility Principle by handling only\n * the core controller concerns while leaving specific functionality to\n * implementing classes.\n *\n * @category Controllers\n */\n\nimport type { WalletClient } from \"viem\";\nimport type { ControllerContext } from \"../types/controller-context\";\nimport { ReadOnlyError } from \"../errors\";\n\n/**\n * Abstract base controller that all Vana SDK controllers extend.\n *\n * @remarks\n * Provides common functionality and patterns used across all controllers,\n * including wallet validation and context management. This ensures\n * consistency and reduces code duplication throughout the SDK.\n *\n * Key features:\n * - Wallet client validation with TypeScript assertion signatures\n * - Consistent error handling for read-only scenarios\n * - Shared context management patterns\n * - Type-safe wallet operations\n *\n * @example\n * ```typescript\n * class MyController extends BaseController {\n *   async performWalletOperation() {\n *     this.assertWallet(); // Ensures wallet is available\n *     // Now this.context.walletClient is guaranteed to be available\n *     const address = await this.context.walletClient.getAddresses();\n *     return address[0];\n *   }\n * }\n * ```\n */\nexport abstract class BaseController {\n  /**\n   * Creates a new controller instance with the provided context.\n   *\n   * @param context - The controller context containing clients and configuration\n   */\n  constructor(protected readonly context: ControllerContext) {}\n\n  /**\n   * Asserts that a wallet client with an account is available for operations requiring signing.\n   *\n   * @remarks\n   * This method uses TypeScript assertion signatures to narrow the type of\n   * `this.context` to guarantee that `walletClient` with an account is available\n   * after the call succeeds. This provides compile-time safety for wallet operations\n   * while enabling clear error messages for read-only scenarios.\n   *\n   * The assertion signature ensures that after calling this method,\n   * TypeScript knows that `this.context.walletClient` is definitely available\n   * with a configured account.\n   *\n   * @throws {ReadOnlyError} When no wallet client is configured\n   * @throws {Error} When wallet client exists but no account is configured\n   *\n   * @example\n   * ```typescript\n   * async performWalletOperation() {\n   *   this.assertWallet(); // Type assertion + runtime check\n   *\n   *   // TypeScript now knows walletClient and account are available\n   *   const account = this.context.walletClient.account;\n   *   const address = typeof account === 'string' ? account : account.address;\n   * }\n   * ```\n   */\n  protected assertWallet(): asserts this is {\n    context: ControllerContext & { walletClient: WalletClient };\n  } {\n    if (!this.context.walletClient) {\n      // Get the calling method name from the stack trace for better error messages\n      const stack = new Error().stack;\n      const callingMethod =\n        stack?.split(\"\\n\")[2]?.match(/at \\w+\\.(\\w+)/)?.[1] ?? \"this operation\";\n\n      throw new ReadOnlyError(\n        callingMethod,\n        \"Initialize the SDK with a walletClient to perform this operation\",\n      );\n    }\n\n    if (!this.context.walletClient.account) {\n      // Get the calling method name from the stack trace for better error messages\n      const stack = new Error().stack;\n      const callingMethod =\n        stack?.split(\"\\n\")[2]?.match(/at \\w+\\.(\\w+)/)?.[1] ?? \"this operation\";\n\n      throw new Error(\n        `No wallet account connected. Cannot perform ${callingMethod} without an account.`,\n      );\n    }\n  }\n}\n"],"mappings":"AAkBA,SAAS,qBAAqB;AA4BvB,MAAe,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMnC,YAA+B,SAA4B;AAA5B;AAAA,EAA6B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA6BlD,eAER;AACA,QAAI,CAAC,KAAK,QAAQ,cAAc;AAE9B,YAAM,QAAQ,IAAI,MAAM,EAAE;AAC1B,YAAM,gBACJ,OAAO,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,eAAe,IAAI,CAAC,KAAK;AAExD,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAEA,QAAI,CAAC,KAAK,QAAQ,aAAa,SAAS;AAEtC,YAAM,QAAQ,IAAI,MAAM,EAAE;AAC1B,YAAM,gBACJ,OAAO,MAAM,IAAI,EAAE,CAAC,GAAG,MAAM,eAAe,IAAI,CAAC,KAAK;AAExD,YAAM,IAAI;AAAA,QACR,+CAA+C,aAAa;AAAA,MAC9D;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/controllers/data-error-handling.test.d.ts

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