@opendatalabs/vana-sdk 2.3.0 → 3.0.1

package/dist/storage/providers/vana-storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/storage/providers/vana-storage.ts"],"sourcesContent":["import {\n  StorageError,\n  type StorageProvider,\n  type StorageUploadResult,\n  type StorageFile,\n  type StorageListOptions,\n  type StorageProviderConfig,\n} from \"../index\";\nimport {\n  buildWeb3SignedHeader,\n  type Web3SignedSignFn,\n} from \"../../auth/web3-signed-builder\";\n\nconst DEFAULT_ENDPOINT = \"https://storage.vana.com\";\nconst BLOB_PATH_PREFIX = \"/v1/blobs\";\nconst DEFAULT_TOKEN_TTL_SECONDS = 300;\n\n/**\n * Wallet-style signer used by {@link VanaStorage} to authenticate every\n * request. For Personal Server flows this can be a registered server wallet\n * signing requests for the owner's storage namespace.\n *\n * @category Storage\n */\nexport interface VanaStorageSigner {\n  /** EIP-191 address (`0x...`). */\n  address: `0x${string}`;\n  /** EIP-191 personal_sign callback (e.g. viem `account.signMessage`). */\n  signMessage: Web3SignedSignFn;\n}\n\n/**\n * Configuration for {@link VanaStorage}.\n *\n * @category Storage\n */\nexport interface VanaStorageConfig {\n  /**\n   * Base URL of the vana-storage Worker. Defaults to `https://storage.vana.com`.\n   */\n  endpoint?: string;\n  /**\n   * Wallet signer used to authenticate writes and reads.\n   */\n  signer: VanaStorageSigner;\n  /**\n   * Owner namespace under which blobs are stored. Defaults to the signer address.\n   */\n  ownerAddress?: `0x${string}`;\n  /**\n   * Optional `fetch` implementation. Defaults to the global `fetch`.\n   * Useful for tests and for environments that need a custom HTTP client.\n   */\n  fetchImpl?: typeof fetch;\n}\n\ninterface VanaStorageUploadResponse {\n  key: string;\n  url: string;\n  etag: string;\n  size: number;\n}\n\n/**\n * Storage provider that talks to the vana-storage Worker\n * (`https://storage.vana.com` by default). All requests are authenticated\n * with Web3Signed headers signed by the configured wallet.\n *\n * @remarks\n * Filenames passed to {@link VanaStorage.upload} must be of the form\n * `\"{scope}/{collectedAt}\"` (e.g. `\"instagram.profile/2026-05-08T20:00:00.000Z\"`).\n * The owner address is prepended automatically to produce the canonical\n * blob path `/v1/blobs/{owner}/{scope}/{collectedAt}`.\n *\n * @category Storage\n *\n * @example\n * ```typescript\n * import { privateKeyToAccount } from \"viem/accounts\";\n * import { VanaStorage } from \"@opendatalabs/vana-sdk/node\";\n *\n * const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);\n * const storage = new VanaStorage({\n *   signer: {\n *     address: account.address,\n *     signMessage: (msg) => account.signMessage({ message: msg }),\n *   },\n * });\n *\n * const result = await storage.upload(\n *   new Blob([ciphertext]),\n *   \"instagram.profile/2026-05-08T20:00:00.000Z\",\n * );\n * ```\n */\nexport class VanaStorage implements StorageProvider {\n  private readonly endpoint: string;\n  private readonly signer: VanaStorageSigner;\n  private readonly ownerAddress: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: VanaStorageConfig) {\n    if (!config?.signer?.address || !config?.signer?.signMessage) {\n      throw new StorageError(\n        \"VanaStorage requires a signer with address and signMessage\",\n        \"MISSING_SIGNER\",\n        \"vana-storage\",\n      );\n    }\n    this.endpoint = (config.endpoint ?? DEFAULT_ENDPOINT).replace(/\\/+$/, \"\");\n    this.signer = config.signer;\n    this.ownerAddress = (\n      config.ownerAddress ?? config.signer.address\n    ).toLowerCase();\n    this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);\n  }\n\n  /**\n   * Upload an encrypted blob to vana-storage.\n   *\n   * @param file - The blob to upload.\n   * @param filename - Required relative key in the form `\"{scope}/{collectedAt}\"`.\n   *   The owner address is prepended automatically.\n   */\n  async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n    if (!filename) {\n      throw new StorageError(\n        \"VanaStorage.upload requires a filename of the form '{scope}/{collectedAt}'\",\n        \"MISSING_FILENAME\",\n        \"vana-storage\",\n      );\n    }\n\n    const subpath = encodeRelativePath(filename);\n    const path = `${BLOB_PATH_PREFIX}/${this.ownerAddress}/${subpath}`;\n    const body = new Uint8Array(await file.arrayBuffer());\n    const contentType =\n      file.type !== \"\" ? file.type : \"application/octet-stream\";\n\n    const header = await this.signRequest(\"PUT\", path, body);\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: \"PUT\",\n        headers: {\n          authorization: header,\n          \"content-type\": contentType,\n        },\n        body,\n      });\n    } catch (cause) {\n      throw new StorageError(\n        `vana-storage upload network error: ${describe(cause)}`,\n        \"UPLOAD_ERROR\",\n        \"vana-storage\",\n        { cause: cause instanceof Error ? cause : undefined },\n      );\n    }\n\n    if (!response.ok) {\n      throw new StorageError(\n        `vana-storage upload failed: ${response.status} ${response.statusText} - ${await safeText(response)}`,\n        \"UPLOAD_FAILED\",\n        \"vana-storage\",\n      );\n    }\n\n    const result = (await response.json()) as VanaStorageUploadResponse;\n    return {\n      url: result.url,\n      size: result.size,\n      contentType,\n      metadata: { key: result.key, etag: result.etag },\n    };\n  }\n\n  /**\n   * Download a blob by URL. The URL must point at a path under this\n   * provider's endpoint.\n   */\n  async download(url: string): Promise<Blob> {\n    const path = this.pathFromUrl(url);\n    const header = await this.signRequest(\"GET\", path);\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: \"GET\",\n        headers: { authorization: header },\n      });\n    } catch (cause) {\n      throw new StorageError(\n        `vana-storage download network error: ${describe(cause)}`,\n        \"DOWNLOAD_ERROR\",\n        \"vana-storage\",\n        { cause: cause instanceof Error ? cause : undefined },\n      );\n    }\n\n    if (!response.ok) {\n      throw new StorageError(\n        `vana-storage download failed: ${response.status} ${response.statusText}`,\n        \"DOWNLOAD_FAILED\",\n        \"vana-storage\",\n      );\n    }\n\n    return await response.blob();\n  }\n\n  /**\n   * Listing is not supported by vana-storage — file discovery is handled by\n   * the Gateway DataRegistry, not the storage layer.\n   */\n  async list(_options?: StorageListOptions): Promise<StorageFile[]> {\n    throw new StorageError(\n      \"list is not supported by vana-storage; query the Gateway DataRegistry instead\",\n      \"NOT_IMPLEMENTED\",\n      \"vana-storage\",\n    );\n  }\n\n  async delete(url: string): Promise<boolean> {\n    const path = this.pathFromUrl(url);\n    const header = await this.signRequest(\"DELETE\", path);\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: \"DELETE\",\n        headers: { authorization: header },\n      });\n    } catch (cause) {\n      throw new StorageError(\n        `vana-storage delete network error: ${describe(cause)}`,\n        \"DELETE_ERROR\",\n        \"vana-storage\",\n        { cause: cause instanceof Error ? cause : undefined },\n      );\n    }\n\n    if (response.status === 404) return false;\n    if (!response.ok) {\n      throw new StorageError(\n        `vana-storage delete failed: ${response.status} ${response.statusText}`,\n        \"DELETE_FAILED\",\n        \"vana-storage\",\n      );\n    }\n    return true;\n  }\n\n  getConfig(): StorageProviderConfig {\n    return {\n      name: \"vana-storage\",\n      type: \"vana-storage\",\n      requiresAuth: true,\n      features: {\n        upload: true,\n        download: true,\n        list: false,\n        delete: true,\n      },\n    };\n  }\n\n  private async signRequest(\n    method: \"GET\" | \"PUT\" | \"DELETE\",\n    path: string,\n    body?: Uint8Array,\n  ): Promise<string> {\n    const now = Math.floor(Date.now() / 1000);\n    return buildWeb3SignedHeader({\n      signMessage: this.signer.signMessage,\n      aud: this.endpoint,\n      method,\n      uri: path,\n      iat: now,\n      exp: now + DEFAULT_TOKEN_TTL_SECONDS,\n      ...(body !== undefined && body.length > 0 && { body }),\n    });\n  }\n\n  private pathFromUrl(url: string): string {\n    let parsed: URL;\n    try {\n      parsed = new URL(url);\n    } catch {\n      throw new StorageError(\n        `Invalid URL: ${url}`,\n        \"INVALID_URL\",\n        \"vana-storage\",\n      );\n    }\n    const expectedHost = new URL(this.endpoint).host;\n    if (parsed.host !== expectedHost) {\n      throw new StorageError(\n        `URL host '${parsed.host}' does not match storage endpoint '${expectedHost}'`,\n        \"INVALID_URL\",\n        \"vana-storage\",\n      );\n    }\n    // Restrict to /v1/blobs/{owner}/{scope}/{collectedAt} so a caller\n    // cannot induce this wallet to sign arbitrary same-host paths.\n    const segments = parsed.pathname.split(\"/\").filter((s) => s.length > 0);\n    const isTraversal = (s: string): boolean => s === \".\" || s === \"..\";\n    const valid =\n      segments.length === 5 &&\n      segments[0] === \"v1\" &&\n      segments[1] === \"blobs\" &&\n      segments[2]?.toLowerCase() === this.ownerAddress &&\n      segments[3] !== undefined &&\n      !isTraversal(segments[3]) &&\n      segments[4] !== undefined &&\n      !isTraversal(segments[4]);\n    if (!valid) {\n      throw new StorageError(\n        `URL path '${parsed.pathname}' must be /v1/blobs/${this.ownerAddress}/{scope}/{collectedAt}`,\n        \"INVALID_URL\",\n        \"vana-storage\",\n      );\n    }\n    return parsed.pathname;\n  }\n}\n\nfunction encodeRelativePath(filename: string): string {\n  const parts = filename.split(\"/\");\n  if (\n    parts.length !== 2 ||\n    parts.some((p) => p.length === 0 || p === \".\" || p === \"..\")\n  ) {\n    throw new StorageError(\n      `filename must be exactly '{scope}/{collectedAt}' with non-empty segments, got '${filename}'`,\n      \"INVALID_FILENAME\",\n      \"vana-storage\",\n    );\n  }\n  return parts.map((p) => encodeURIComponent(p)).join(\"/\");\n}\n\nfunction describe(value: unknown): string {\n  if (value instanceof Error) return value.message;\n  return String(value);\n}\n\nasync function safeText(response: Response): Promise<string> {\n  try {\n    return await response.text();\n  } catch {\n    return \"\";\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/storage/providers/vana-storage.d.ts

@@ -0,0 +1,100 @@
+import { type StorageProvider, type StorageUploadResult, type StorageFile, type StorageListOptions, type StorageProviderConfig } from "../index";
+import { type Web3SignedSignFn } from "../../auth/web3-signed-builder";
+/**
+ * Wallet-style signer used by {@link VanaStorage} to authenticate every
+ * request. For Personal Server flows this can be a registered server wallet
+ * signing requests for the owner's storage namespace.
+ *
+ * @category Storage
+ */
+export interface VanaStorageSigner {
+    /** EIP-191 address (`0x...`). */
+    address: `0x${string}`;
+    /** EIP-191 personal_sign callback (e.g. viem `account.signMessage`). */
+    signMessage: Web3SignedSignFn;
+}
+/**
+ * Configuration for {@link VanaStorage}.
+ *
+ * @category Storage
+ */
+export interface VanaStorageConfig {
+    /**
+     * Base URL of the vana-storage Worker. Defaults to `https://storage.vana.com`.
+     */
+    endpoint?: string;
+    /**
+     * Wallet signer used to authenticate writes and reads.
+     */
+    signer: VanaStorageSigner;
+    /**
+     * Owner namespace under which blobs are stored. Defaults to the signer address.
+     */
+    ownerAddress?: `0x${string}`;
+    /**
+     * Optional `fetch` implementation. Defaults to the global `fetch`.
+     * Useful for tests and for environments that need a custom HTTP client.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Storage provider that talks to the vana-storage Worker
+ * (`https://storage.vana.com` by default). All requests are authenticated
+ * with Web3Signed headers signed by the configured wallet.
+ *
+ * @remarks
+ * Filenames passed to {@link VanaStorage.upload} must be of the form
+ * `"{scope}/{collectedAt}"` (e.g. `"instagram.profile/2026-05-08T20:00:00.000Z"`).
+ * The owner address is prepended automatically to produce the canonical
+ * blob path `/v1/blobs/{owner}/{scope}/{collectedAt}`.
+ *
+ * @category Storage
+ *
+ * @example
+ * ```typescript
+ * import { privateKeyToAccount } from "viem/accounts";
+ * import { VanaStorage } from "@opendatalabs/vana-sdk/node";
+ *
+ * const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+ * const storage = new VanaStorage({
+ *   signer: {
+ *     address: account.address,
+ *     signMessage: (msg) => account.signMessage({ message: msg }),
+ *   },
+ * });
+ *
+ * const result = await storage.upload(
+ *   new Blob([ciphertext]),
+ *   "instagram.profile/2026-05-08T20:00:00.000Z",
+ * );
+ * ```
+ */
+export declare class VanaStorage implements StorageProvider {
+    private readonly endpoint;
+    private readonly signer;
+    private readonly ownerAddress;
+    private readonly fetchImpl;
+    constructor(config: VanaStorageConfig);
+    /**
+     * Upload an encrypted blob to vana-storage.
+     *
+     * @param file - The blob to upload.
+     * @param filename - Required relative key in the form `"{scope}/{collectedAt}"`.
+     *   The owner address is prepended automatically.
+     */
+    upload(file: Blob, filename?: string): Promise<StorageUploadResult>;
+    /**
+     * Download a blob by URL. The URL must point at a path under this
+     * provider's endpoint.
+     */
+    download(url: string): Promise<Blob>;
+    /**
+     * Listing is not supported by vana-storage — file discovery is handled by
+     * the Gateway DataRegistry, not the storage layer.
+     */
+    list(_options?: StorageListOptions): Promise<StorageFile[]>;
+    delete(url: string): Promise<boolean>;
+    getConfig(): StorageProviderConfig;
+    private signRequest;
+    private pathFromUrl;
+}

package/dist/storage/providers/vana-storage.js

@@ -0,0 +1,231 @@
+import {
+  StorageError
+} from "../index";
+import {
+  buildWeb3SignedHeader
+} from "../../auth/web3-signed-builder";
+const DEFAULT_ENDPOINT = "https://storage.vana.com";
+const BLOB_PATH_PREFIX = "/v1/blobs";
+const DEFAULT_TOKEN_TTL_SECONDS = 300;
+class VanaStorage {
+  endpoint;
+  signer;
+  ownerAddress;
+  fetchImpl;
+  constructor(config) {
+    if (!config?.signer?.address || !config?.signer?.signMessage) {
+      throw new StorageError(
+        "VanaStorage requires a signer with address and signMessage",
+        "MISSING_SIGNER",
+        "vana-storage"
+      );
+    }
+    this.endpoint = (config.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "");
+    this.signer = config.signer;
+    this.ownerAddress = (config.ownerAddress ?? config.signer.address).toLowerCase();
+    this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
+  }
+  /**
+   * Upload an encrypted blob to vana-storage.
+   *
+   * @param file - The blob to upload.
+   * @param filename - Required relative key in the form `"{scope}/{collectedAt}"`.
+   *   The owner address is prepended automatically.
+   */
+  async upload(file, filename) {
+    if (!filename) {
+      throw new StorageError(
+        "VanaStorage.upload requires a filename of the form '{scope}/{collectedAt}'",
+        "MISSING_FILENAME",
+        "vana-storage"
+      );
+    }
+    const subpath = encodeRelativePath(filename);
+    const path = `${BLOB_PATH_PREFIX}/${this.ownerAddress}/${subpath}`;
+    const body = new Uint8Array(await file.arrayBuffer());
+    const contentType = file.type !== "" ? file.type : "application/octet-stream";
+    const header = await this.signRequest("PUT", path, body);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.endpoint}${path}`, {
+        method: "PUT",
+        headers: {
+          authorization: header,
+          "content-type": contentType
+        },
+        body
+      });
+    } catch (cause) {
+      throw new StorageError(
+        `vana-storage upload network error: ${describe(cause)}`,
+        "UPLOAD_ERROR",
+        "vana-storage",
+        { cause: cause instanceof Error ? cause : void 0 }
+      );
+    }
+    if (!response.ok) {
+      throw new StorageError(
+        `vana-storage upload failed: ${response.status} ${response.statusText} - ${await safeText(response)}`,
+        "UPLOAD_FAILED",
+        "vana-storage"
+      );
+    }
+    const result = await response.json();
+    return {
+      url: result.url,
+      size: result.size,
+      contentType,
+      metadata: { key: result.key, etag: result.etag }
+    };
+  }
+  /**
+   * Download a blob by URL. The URL must point at a path under this
+   * provider's endpoint.
+   */
+  async download(url) {
+    const path = this.pathFromUrl(url);
+    const header = await this.signRequest("GET", path);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.endpoint}${path}`, {
+        method: "GET",
+        headers: { authorization: header }
+      });
+    } catch (cause) {
+      throw new StorageError(
+        `vana-storage download network error: ${describe(cause)}`,
+        "DOWNLOAD_ERROR",
+        "vana-storage",
+        { cause: cause instanceof Error ? cause : void 0 }
+      );
+    }
+    if (!response.ok) {
+      throw new StorageError(
+        `vana-storage download failed: ${response.status} ${response.statusText}`,
+        "DOWNLOAD_FAILED",
+        "vana-storage"
+      );
+    }
+    return await response.blob();
+  }
+  /**
+   * Listing is not supported by vana-storage — file discovery is handled by
+   * the Gateway DataRegistry, not the storage layer.
+   */
+  async list(_options) {
+    throw new StorageError(
+      "list is not supported by vana-storage; query the Gateway DataRegistry instead",
+      "NOT_IMPLEMENTED",
+      "vana-storage"
+    );
+  }
+  async delete(url) {
+    const path = this.pathFromUrl(url);
+    const header = await this.signRequest("DELETE", path);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.endpoint}${path}`, {
+        method: "DELETE",
+        headers: { authorization: header }
+      });
+    } catch (cause) {
+      throw new StorageError(
+        `vana-storage delete network error: ${describe(cause)}`,
+        "DELETE_ERROR",
+        "vana-storage",
+        { cause: cause instanceof Error ? cause : void 0 }
+      );
+    }
+    if (response.status === 404) return false;
+    if (!response.ok) {
+      throw new StorageError(
+        `vana-storage delete failed: ${response.status} ${response.statusText}`,
+        "DELETE_FAILED",
+        "vana-storage"
+      );
+    }
+    return true;
+  }
+  getConfig() {
+    return {
+      name: "vana-storage",
+      type: "vana-storage",
+      requiresAuth: true,
+      features: {
+        upload: true,
+        download: true,
+        list: false,
+        delete: true
+      }
+    };
+  }
+  async signRequest(method, path, body) {
+    const now = Math.floor(Date.now() / 1e3);
+    return buildWeb3SignedHeader({
+      signMessage: this.signer.signMessage,
+      aud: this.endpoint,
+      method,
+      uri: path,
+      iat: now,
+      exp: now + DEFAULT_TOKEN_TTL_SECONDS,
+      ...body !== void 0 && body.length > 0 && { body }
+    });
+  }
+  pathFromUrl(url) {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new StorageError(
+        `Invalid URL: ${url}`,
+        "INVALID_URL",
+        "vana-storage"
+      );
+    }
+    const expectedHost = new URL(this.endpoint).host;
+    if (parsed.host !== expectedHost) {
+      throw new StorageError(
+        `URL host '${parsed.host}' does not match storage endpoint '${expectedHost}'`,
+        "INVALID_URL",
+        "vana-storage"
+      );
+    }
+    const segments = parsed.pathname.split("/").filter((s) => s.length > 0);
+    const isTraversal = (s) => s === "." || s === "..";
+    const valid = segments.length === 5 && segments[0] === "v1" && segments[1] === "blobs" && segments[2]?.toLowerCase() === this.ownerAddress && segments[3] !== void 0 && !isTraversal(segments[3]) && segments[4] !== void 0 && !isTraversal(segments[4]);
+    if (!valid) {
+      throw new StorageError(
+        `URL path '${parsed.pathname}' must be /v1/blobs/${this.ownerAddress}/{scope}/{collectedAt}`,
+        "INVALID_URL",
+        "vana-storage"
+      );
+    }
+    return parsed.pathname;
+  }
+}
+function encodeRelativePath(filename) {
+  const parts = filename.split("/");
+  if (parts.length !== 2 || parts.some((p) => p.length === 0 || p === "." || p === "..")) {
+    throw new StorageError(
+      `filename must be exactly '{scope}/{collectedAt}' with non-empty segments, got '${filename}'`,
+      "INVALID_FILENAME",
+      "vana-storage"
+    );
+  }
+  return parts.map((p) => encodeURIComponent(p)).join("/");
+}
+function describe(value) {
+  if (value instanceof Error) return value.message;
+  return String(value);
+}
+async function safeText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+export {
+  VanaStorage
+};
+//# sourceMappingURL=vana-storage.js.map

package/dist/storage/providers/vana-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/storage/providers/vana-storage.ts"],"sourcesContent":["import {\n  StorageError,\n  type StorageProvider,\n  type StorageUploadResult,\n  type StorageFile,\n  type StorageListOptions,\n  type StorageProviderConfig,\n} from \"../index\";\nimport {\n  buildWeb3SignedHeader,\n  type Web3SignedSignFn,\n} from \"../../auth/web3-signed-builder\";\n\nconst DEFAULT_ENDPOINT = \"https://storage.vana.com\";\nconst BLOB_PATH_PREFIX = \"/v1/blobs\";\nconst DEFAULT_TOKEN_TTL_SECONDS = 300;\n\n/**\n * Wallet-style signer used by {@link VanaStorage} to authenticate every\n * request. For Personal Server flows this can be a registered server wallet\n * signing requests for the owner's storage namespace.\n *\n * @category Storage\n */\nexport interface VanaStorageSigner {\n  /** EIP-191 address (`0x...`). */\n  address: `0x${string}`;\n  /** EIP-191 personal_sign callback (e.g. viem `account.signMessage`). */\n  signMessage: Web3SignedSignFn;\n}\n\n/**\n * Configuration for {@link VanaStorage}.\n *\n * @category Storage\n */\nexport interface VanaStorageConfig {\n  /**\n   * Base URL of the vana-storage Worker. Defaults to `https://storage.vana.com`.\n   */\n  endpoint?: string;\n  /**\n   * Wallet signer used to authenticate writes and reads.\n   */\n  signer: VanaStorageSigner;\n  /**\n   * Owner namespace under which blobs are stored. Defaults to the signer address.\n   */\n  ownerAddress?: `0x${string}`;\n  /**\n   * Optional `fetch` implementation. Defaults to the global `fetch`.\n   * Useful for tests and for environments that need a custom HTTP client.\n   */\n  fetchImpl?: typeof fetch;\n}\n\ninterface VanaStorageUploadResponse {\n  key: string;\n  url: string;\n  etag: string;\n  size: number;\n}\n\n/**\n * Storage provider that talks to the vana-storage Worker\n * (`https://storage.vana.com` by default). All requests are authenticated\n * with Web3Signed headers signed by the configured wallet.\n *\n * @remarks\n * Filenames passed to {@link VanaStorage.upload} must be of the form\n * `\"{scope}/{collectedAt}\"` (e.g. `\"instagram.profile/2026-05-08T20:00:00.000Z\"`).\n * The owner address is prepended automatically to produce the canonical\n * blob path `/v1/blobs/{owner}/{scope}/{collectedAt}`.\n *\n * @category Storage\n *\n * @example\n * ```typescript\n * import { privateKeyToAccount } from \"viem/accounts\";\n * import { VanaStorage } from \"@opendatalabs/vana-sdk/node\";\n *\n * const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);\n * const storage = new VanaStorage({\n *   signer: {\n *     address: account.address,\n *     signMessage: (msg) => account.signMessage({ message: msg }),\n *   },\n * });\n *\n * const result = await storage.upload(\n *   new Blob([ciphertext]),\n *   \"instagram.profile/2026-05-08T20:00:00.000Z\",\n * );\n * ```\n */\nexport class VanaStorage implements StorageProvider {\n  private readonly endpoint: string;\n  private readonly signer: VanaStorageSigner;\n  private readonly ownerAddress: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(config: VanaStorageConfig) {\n    if (!config?.signer?.address || !config?.signer?.signMessage) {\n      throw new StorageError(\n        \"VanaStorage requires a signer with address and signMessage\",\n        \"MISSING_SIGNER\",\n        \"vana-storage\",\n      );\n    }\n    this.endpoint = (config.endpoint ?? DEFAULT_ENDPOINT).replace(/\\/+$/, \"\");\n    this.signer = config.signer;\n    this.ownerAddress = (\n      config.ownerAddress ?? config.signer.address\n    ).toLowerCase();\n    this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);\n  }\n\n  /**\n   * Upload an encrypted blob to vana-storage.\n   *\n   * @param file - The blob to upload.\n   * @param filename - Required relative key in the form `\"{scope}/{collectedAt}\"`.\n   *   The owner address is prepended automatically.\n   */\n  async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n    if (!filename) {\n      throw new StorageError(\n        \"VanaStorage.upload requires a filename of the form '{scope}/{collectedAt}'\",\n        \"MISSING_FILENAME\",\n        \"vana-storage\",\n      );\n    }\n\n    const subpath = encodeRelativePath(filename);\n    const path = `${BLOB_PATH_PREFIX}/${this.ownerAddress}/${subpath}`;\n    const body = new Uint8Array(await file.arrayBuffer());\n    const contentType =\n      file.type !== \"\" ? file.type : \"application/octet-stream\";\n\n    const header = await this.signRequest(\"PUT\", path, body);\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: \"PUT\",\n        headers: {\n          authorization: header,\n          \"content-type\": contentType,\n        },\n        body,\n      });\n    } catch (cause) {\n      throw new StorageError(\n        `vana-storage upload network error: ${describe(cause)}`,\n        \"UPLOAD_ERROR\",\n        \"vana-storage\",\n        { cause: cause instanceof Error ? cause : undefined },\n      );\n    }\n\n    if (!response.ok) {\n      throw new StorageError(\n        `vana-storage upload failed: ${response.status} ${response.statusText} - ${await safeText(response)}`,\n        \"UPLOAD_FAILED\",\n        \"vana-storage\",\n      );\n    }\n\n    const result = (await response.json()) as VanaStorageUploadResponse;\n    return {\n      url: result.url,\n      size: result.size,\n      contentType,\n      metadata: { key: result.key, etag: result.etag },\n    };\n  }\n\n  /**\n   * Download a blob by URL. The URL must point at a path under this\n   * provider's endpoint.\n   */\n  async download(url: string): Promise<Blob> {\n    const path = this.pathFromUrl(url);\n    const header = await this.signRequest(\"GET\", path);\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: \"GET\",\n        headers: { authorization: header },\n      });\n    } catch (cause) {\n      throw new StorageError(\n        `vana-storage download network error: ${describe(cause)}`,\n        \"DOWNLOAD_ERROR\",\n        \"vana-storage\",\n        { cause: cause instanceof Error ? cause : undefined },\n      );\n    }\n\n    if (!response.ok) {\n      throw new StorageError(\n        `vana-storage download failed: ${response.status} ${response.statusText}`,\n        \"DOWNLOAD_FAILED\",\n        \"vana-storage\",\n      );\n    }\n\n    return await response.blob();\n  }\n\n  /**\n   * Listing is not supported by vana-storage — file discovery is handled by\n   * the Gateway DataRegistry, not the storage layer.\n   */\n  async list(_options?: StorageListOptions): Promise<StorageFile[]> {\n    throw new StorageError(\n      \"list is not supported by vana-storage; query the Gateway DataRegistry instead\",\n      \"NOT_IMPLEMENTED\",\n      \"vana-storage\",\n    );\n  }\n\n  async delete(url: string): Promise<boolean> {\n    const path = this.pathFromUrl(url);\n    const header = await this.signRequest(\"DELETE\", path);\n\n    let response: Response;\n    try {\n      response = await this.fetchImpl(`${this.endpoint}${path}`, {\n        method: \"DELETE\",\n        headers: { authorization: header },\n      });\n    } catch (cause) {\n      throw new StorageError(\n        `vana-storage delete network error: ${describe(cause)}`,\n        \"DELETE_ERROR\",\n        \"vana-storage\",\n        { cause: cause instanceof Error ? cause : undefined },\n      );\n    }\n\n    if (response.status === 404) return false;\n    if (!response.ok) {\n      throw new StorageError(\n        `vana-storage delete failed: ${response.status} ${response.statusText}`,\n        \"DELETE_FAILED\",\n        \"vana-storage\",\n      );\n    }\n    return true;\n  }\n\n  getConfig(): StorageProviderConfig {\n    return {\n      name: \"vana-storage\",\n      type: \"vana-storage\",\n      requiresAuth: true,\n      features: {\n        upload: true,\n        download: true,\n        list: false,\n        delete: true,\n      },\n    };\n  }\n\n  private async signRequest(\n    method: \"GET\" | \"PUT\" | \"DELETE\",\n    path: string,\n    body?: Uint8Array,\n  ): Promise<string> {\n    const now = Math.floor(Date.now() / 1000);\n    return buildWeb3SignedHeader({\n      signMessage: this.signer.signMessage,\n      aud: this.endpoint,\n      method,\n      uri: path,\n      iat: now,\n      exp: now + DEFAULT_TOKEN_TTL_SECONDS,\n      ...(body !== undefined && body.length > 0 && { body }),\n    });\n  }\n\n  private pathFromUrl(url: string): string {\n    let parsed: URL;\n    try {\n      parsed = new URL(url);\n    } catch {\n      throw new StorageError(\n        `Invalid URL: ${url}`,\n        \"INVALID_URL\",\n        \"vana-storage\",\n      );\n    }\n    const expectedHost = new URL(this.endpoint).host;\n    if (parsed.host !== expectedHost) {\n      throw new StorageError(\n        `URL host '${parsed.host}' does not match storage endpoint '${expectedHost}'`,\n        \"INVALID_URL\",\n        \"vana-storage\",\n      );\n    }\n    // Restrict to /v1/blobs/{owner}/{scope}/{collectedAt} so a caller\n    // cannot induce this wallet to sign arbitrary same-host paths.\n    const segments = parsed.pathname.split(\"/\").filter((s) => s.length > 0);\n    const isTraversal = (s: string): boolean => s === \".\" || s === \"..\";\n    const valid =\n      segments.length === 5 &&\n      segments[0] === \"v1\" &&\n      segments[1] === \"blobs\" &&\n      segments[2]?.toLowerCase() === this.ownerAddress &&\n      segments[3] !== undefined &&\n      !isTraversal(segments[3]) &&\n      segments[4] !== undefined &&\n      !isTraversal(segments[4]);\n    if (!valid) {\n      throw new StorageError(\n        `URL path '${parsed.pathname}' must be /v1/blobs/${this.ownerAddress}/{scope}/{collectedAt}`,\n        \"INVALID_URL\",\n        \"vana-storage\",\n      );\n    }\n    return parsed.pathname;\n  }\n}\n\nfunction encodeRelativePath(filename: string): string {\n  const parts = filename.split(\"/\");\n  if (\n    parts.length !== 2 ||\n    parts.some((p) => p.length === 0 || p === \".\" || p === \"..\")\n  ) {\n    throw new StorageError(\n      `filename must be exactly '{scope}/{collectedAt}' with non-empty segments, got '${filename}'`,\n      \"INVALID_FILENAME\",\n      \"vana-storage\",\n    );\n  }\n  return parts.map((p) => encodeURIComponent(p)).join(\"/\");\n}\n\nfunction describe(value: unknown): string {\n  if (value instanceof Error) return value.message;\n  return String(value);\n}\n\nasync function safeText(response: Response): Promise<string> {\n  try {\n    return await response.text();\n  } catch {\n    return \"\";\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/types/config.cjs

@@ -3,10 +3,6 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -17,35 +13,5 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var config_exports = {};
-__export(config_exports, {
-  hasStorageConfig: () => hasStorageConfig,
-  isAddressOnlyConfig: () => isAddressOnlyConfig,
-  isChainConfig: () => isChainConfig,
-  isReadOnlyConfig: () => isReadOnlyConfig,
-  isWalletConfig: () => isWalletConfig
-});
 module.exports = __toCommonJS(config_exports);
-function isWalletConfig(config) {
-  return "walletClient" in config;
-}
-function isReadOnlyConfig(config) {
-  return "publicClient" in config && "address" in config && !("walletClient" in config);
-}
-function isAddressOnlyConfig(config) {
-  return "address" in config && !("publicClient" in config) && !("walletClient" in config) && !("chainId" in config);
-}
-function isChainConfig(config) {
-  return "chainId" in config && !("walletClient" in config);
-}
-function hasStorageConfig(config) {
-  return config.storage?.providers !== void 0 && Object.keys(config.storage.providers).length > 0;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  hasStorageConfig,
-  isAddressOnlyConfig,
-  isChainConfig,
-  isReadOnlyConfig,
-  isWalletConfig
-});
 //# sourceMappingURL=config.cjs.map

package/dist/types/config.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { WalletClient, PublicClient, Account, Address, Chain } from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\n\nimport type { RelayerConfig } from \"./relayer\";\nimport type { IOperationStore, IRelayerStateStore } from \"./operationStore\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configures storage providers for SDK file operations.\n *\n * @remarks\n * Supports multiple backends with automatic fallback.\n * IPFS for decentralization, Pinata for reliability,\n * Google Drive for development, custom for flexibility.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'key', secretKey: 'secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n\n  /**\n   * Optional operation store for tracking async relayed transactions.\n   * When provided with a relayer, enables resilient transaction management\n   * with polling support for pending operations.\n   *\n   * @example\n   * ```typescript\n   * const vana = createVana({\n   *   walletClient,\n   *   relayer: '/api/relay',\n   *   operationStore: myOperationStore\n   * });\n   * ```\n   */\n  operationStore?: IOperationStore | IRelayerStateStore;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer configuration for handling gasless transactions.\n   * Can be a URL string for convenience, or a callback for full control.\n   *\n   * @example\n   * ```typescript\n   * // Simple URL (SDK handles transport)\n   * relayer: '/api/relay'\n   *\n   * // Full control with callback\n   * relayer: async (request) => {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  relayer?: RelayerConfig;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n\n  /**\n   * Optional operation store for tracking async relayed transactions.\n   * When provided with a relayer, enables resilient transaction management\n   * with polling support for pending operations.\n   */\n  operationStore?: IOperationStore | IRelayerStateStore;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Configuration with wallet client and optional public client\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWallet extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnly extends BaseConfig {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnly extends BaseConfig {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Configuration with wallet client and optional public client that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnlyWithStorage\n  extends BaseConfigWithStorage {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * The SDK supports three initialization modes:\n * 1. Full mode with wallet client for signing transactions\n * 2. Read-only mode with public client and address for read operations\n * 3. Minimal mode with just an address and optional chain\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Mode 1: Full configuration with wallet client\n * const configWithWallet: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   })\n * };\n *\n * // Mode 2: Read-only with public client and address\n * const configReadOnly: VanaConfig = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...'\n * };\n *\n * // Mode 3: Minimal with just address\n * const configMinimal: VanaConfig = {\n *   address: '0x1234...',\n *   chain: moksha // optional\n * };\n * ```\n */\nexport type VanaConfig =\n  | VanaConfigWithWallet\n  | VanaConfigReadOnly\n  | VanaConfigAddressOnly\n  | WalletConfig\n  | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n * Supports all three initialization modes with required storage.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Full configuration with wallet client and storage\n * const configWithWallet: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n *\n * // Read-only configuration with storage\n * const configReadOnly: VanaConfigWithStorage = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...',\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | VanaConfigWithWalletWithStorage\n  | VanaConfigReadOnlyWithStorage\n  | VanaConfigAddressOnlyWithStorage\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer configuration */\n  relayerConfig?: RelayerConfig;\n}\n\n/**\n * Validates whether a configuration object has a wallet client (any wallet-based config).\n *\n * @param config - The configuration object to check\n * @returns True if the config contains a walletClient\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Read-only or chain config');\n * }\n * ```\n */\nexport function isWalletConfig(\n  config: VanaConfig,\n): config is VanaConfigWithWallet | WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a read-only config with public client.\n *\n * @param config - The configuration object to check\n * @returns True if the config has publicClient and address but no walletClient\n * @example\n * ```typescript\n * if (isReadOnlyConfig(config)) {\n *   console.log('Read-only mode with address:', config.address);\n * }\n * ```\n */\nexport function isReadOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigReadOnly {\n  return (\n    \"publicClient\" in config &&\n    \"address\" in config &&\n    !(\"walletClient\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is an address-only config.\n *\n * @param config - The configuration object to check\n * @returns True if the config has only address (and optionally chain) but no clients\n * @example\n * ```typescript\n * if (isAddressOnlyConfig(config)) {\n *   console.log('Address-only mode:', config.address);\n * }\n * ```\n */\nexport function isAddressOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigAddressOnly {\n  return (\n    \"address\" in config &&\n    !(\"publicClient\" in config) &&\n    !(\"walletClient\" in config) &&\n    !(\"chainId\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n\n/**\n * Marker interface to enforce the presence of operationStore at compile time.\n * This interface is used to ensure that certain operations requiring a relayer\n * can only be called when the SDK has been properly configured with an operation store.\n *\n * @category Configuration\n */\nexport interface RelayerRequiredMarker {\n  readonly __relayerConfigured: true;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyqBO,SAAS,eACd,QAC+C;AAC/C,SAAO,kBAAkB;AAC3B;AAcO,SAAS,iBACd,QAC8B;AAC9B,SACE,kBAAkB,UAClB,aAAa,UACb,EAAE,kBAAkB;AAExB;AAcO,SAAS,oBACd,QACiC;AACjC,SACE,aAAa,UACb,EAAE,kBAAkB,WACpB,EAAE,kBAAkB,WACpB,EAAE,aAAa;AAEnB;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}
+{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { StorageUploadResult, StorageListOptions } from \"./storage\";\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}