@opendatalabs/vana-sdk 0.1.0-alpha.a6b60fc → 0.1.0-alpha.a78ce5c

package/dist/utils/subgraphMetaCache.js

@@ -0,0 +1,76 @@
+class SubgraphMetaCache {
+  cache = /* @__PURE__ */ new Map();
+  maxSize;
+  ttl;
+  /**
+   * Create a new metadata cache
+   *
+   * @param ttl - Time to live in milliseconds (default: 2000ms)
+   * @param maxSize - Maximum cache entries (default: 10)
+   */
+  constructor(ttl = 2e3, maxSize = 10) {
+    this.ttl = ttl;
+    this.maxSize = maxSize;
+  }
+  /**
+   * Get cached metadata if fresh
+   *
+   * @param url - Subgraph URL as cache key
+   * @returns Cached metadata or undefined if stale/missing
+   */
+  get(url) {
+    const entry = this.cache.get(url);
+    if (!entry) {
+      return void 0;
+    }
+    if (Date.now() - entry.timestamp > this.ttl) {
+      this.cache.delete(url);
+      return void 0;
+    }
+    this.cache.delete(url);
+    this.cache.set(url, entry);
+    return entry.meta;
+  }
+  /**
+   * Store metadata in cache
+   *
+   * @param url - Subgraph URL as cache key
+   * @param meta - Metadata to cache
+   */
+  set(url, meta) {
+    if (this.cache.size >= this.maxSize && !this.cache.has(url)) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(url, {
+      meta,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Clear all cached entries
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Get cache statistics
+   *
+   * @returns Cache size and TTL info
+   */
+  stats() {
+    return {
+      size: this.cache.size,
+      ttl: this.ttl,
+      maxSize: this.maxSize
+    };
+  }
+}
+const globalMetaCache = new SubgraphMetaCache();
+export {
+  SubgraphMetaCache,
+  globalMetaCache
+};
+//# sourceMappingURL=subgraphMetaCache.js.map

package/dist/utils/subgraphMetaCache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/subgraphMetaCache.ts"],"sourcesContent":["/**\n * @file Simple cache for subgraph metadata to reduce redundant queries\n * @module vana-sdk/utils/subgraphMetaCache\n */\n\nimport type { SubgraphMeta } from \"./subgraphConsistency\";\n\ninterface CacheEntry {\n  meta: SubgraphMeta;\n  timestamp: number;\n}\n\n/**\n * Simple LRU cache for subgraph metadata\n *\n * @remarks\n * Reduces redundant _meta queries when multiple SDK methods are called\n * in quick succession. Uses a very short TTL to avoid masking staleness.\n */\nexport class SubgraphMetaCache {\n  private cache = new Map<string, CacheEntry>();\n  private readonly maxSize: number;\n  private readonly ttl: number;\n\n  /**\n   * Create a new metadata cache\n   *\n   * @param ttl - Time to live in milliseconds (default: 2000ms)\n   * @param maxSize - Maximum cache entries (default: 10)\n   */\n  constructor(ttl = 2000, maxSize = 10) {\n    this.ttl = ttl;\n    this.maxSize = maxSize;\n  }\n\n  /**\n   * Get cached metadata if fresh\n   *\n   * @param url - Subgraph URL as cache key\n   * @returns Cached metadata or undefined if stale/missing\n   */\n  get(url: string): SubgraphMeta | undefined {\n    const entry = this.cache.get(url);\n\n    if (!entry) {\n      return undefined;\n    }\n\n    // Check if still fresh\n    if (Date.now() - entry.timestamp > this.ttl) {\n      // Expired, remove it\n      this.cache.delete(url);\n      return undefined;\n    }\n\n    // Move to end (LRU)\n    this.cache.delete(url);\n    this.cache.set(url, entry);\n\n    return entry.meta;\n  }\n\n  /**\n   * Store metadata in cache\n   *\n   * @param url - Subgraph URL as cache key\n   * @param meta - Metadata to cache\n   */\n  set(url: string, meta: SubgraphMeta): void {\n    // Remove oldest if at capacity\n    if (this.cache.size >= this.maxSize && !this.cache.has(url)) {\n      const firstKey = this.cache.keys().next().value;\n      if (firstKey) {\n        this.cache.delete(firstKey);\n      }\n    }\n\n    this.cache.set(url, {\n      meta,\n      timestamp: Date.now(),\n    });\n  }\n\n  /**\n   * Clear all cached entries\n   */\n  clear(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Get cache statistics\n   *\n   * @returns Cache size and TTL info\n   */\n  stats(): { size: number; ttl: number; maxSize: number } {\n    return {\n      size: this.cache.size,\n      ttl: this.ttl,\n      maxSize: this.maxSize,\n    };\n  }\n}\n\n/**\n * Global cache instance (optional, can be configured per SDK instance)\n */\nexport const globalMetaCache = new SubgraphMetaCache();\n"],"mappings":"AAmBO,MAAM,kBAAkB;AAAA,EACrB,QAAQ,oBAAI,IAAwB;AAAA,EAC3B;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQjB,YAAY,MAAM,KAAM,UAAU,IAAI;AACpC,SAAK,MAAM;AACX,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,KAAuC;AACzC,UAAM,QAAQ,KAAK,MAAM,IAAI,GAAG;AAEhC,QAAI,CAAC,OAAO;AACV,aAAO;AAAA,IACT;AAGA,QAAI,KAAK,IAAI,IAAI,MAAM,YAAY,KAAK,KAAK;AAE3C,WAAK,MAAM,OAAO,GAAG;AACrB,aAAO;AAAA,IACT;AAGA,SAAK,MAAM,OAAO,GAAG;AACrB,SAAK,MAAM,IAAI,KAAK,KAAK;AAEzB,WAAO,MAAM;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,KAAa,MAA0B;AAEzC,QAAI,KAAK,MAAM,QAAQ,KAAK,WAAW,CAAC,KAAK,MAAM,IAAI,GAAG,GAAG;AAC3D,YAAM,WAAW,KAAK,MAAM,KAAK,EAAE,KAAK,EAAE;AAC1C,UAAI,UAAU;AACZ,aAAK,MAAM,OAAO,QAAQ;AAAA,MAC5B;AAAA,IACF;AAEA,SAAK,MAAM,IAAI,KAAK;AAAA,MAClB;AAAA,MACA,WAAW,KAAK,IAAI;AAAA,IACtB,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACZ,SAAK,MAAM,MAAM;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAwD;AACtD,WAAO;AAAA,MACL,MAAM,KAAK,MAAM;AAAA,MACjB,KAAK,KAAK;AAAA,MACV,SAAS,KAAK;AAAA,IAChB;AAAA,EACF;AACF;AAKO,MAAM,kBAAkB,IAAI,kBAAkB;","names":[]}

package/dist/utils/subgraphPagination.cjs

@@ -0,0 +1,104 @@
+"use strict";
+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))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var subgraphPagination_exports = {};
+__export(subgraphPagination_exports, {
+  executePaginatedQuery: () => executePaginatedQuery,
+  mapOrderByToEnum: () => mapOrderByToEnum,
+  mapOrderDirection: () => mapOrderDirection
+});
+module.exports = __toCommonJS(subgraphPagination_exports);
+var import_graphql = require("graphql");
+async function executePaginatedQuery(config) {
+  const {
+    endpoint,
+    document,
+    baseVariables,
+    options,
+    extractItems,
+    transformItem,
+    maxPerQuery = 1e3
+  } = config;
+  const limit = options?.fetchAll ? Number.MAX_SAFE_INTEGER : options?.limit ?? 100;
+  const offset = options?.offset ?? 0;
+  const orderBy = options?.orderBy;
+  const orderDirection = options?.orderDirection;
+  const allItems = [];
+  let currentOffset = offset;
+  const pageSize = Math.min(limit, maxPerQuery);
+  while (true) {
+    const currentLimit = options?.fetchAll ? pageSize : Math.min(pageSize, limit - allItems.length);
+    const variables = {
+      ...baseVariables,
+      first: currentLimit,
+      skip: currentOffset,
+      ...orderBy && { orderBy },
+      ...orderDirection && { orderDirection }
+    };
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        query: (0, import_graphql.print)(document),
+        variables
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    const items = extractItems(result.data);
+    if (!items || items.length === 0) {
+      break;
+    }
+    const transformedItems = transformItem ? items.map(transformItem) : items;
+    allItems.push(...transformedItems);
+    if (!options?.fetchAll && allItems.length >= limit) {
+      return allItems.slice(0, limit);
+    }
+    if (items.length < currentLimit) {
+      break;
+    }
+    currentOffset += items.length;
+  }
+  return allItems;
+}
+function mapOrderByToEnum(orderBy, enumMap, defaultValue) {
+  if (!orderBy) return defaultValue;
+  return enumMap[orderBy] ?? defaultValue;
+}
+function mapOrderDirection(direction, ascValue, descValue, defaultValue) {
+  if (!direction) return defaultValue ?? descValue;
+  return direction === "asc" ? ascValue : descValue;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  executePaginatedQuery,
+  mapOrderByToEnum,
+  mapOrderDirection
+});
+//# sourceMappingURL=subgraphPagination.cjs.map

package/dist/utils/subgraphPagination.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/subgraphPagination.ts"],"sourcesContent":["/**\n * @file Utilities for handling paginated subgraph queries\n * @module vana-sdk/utils/subgraphPagination\n */\n\nimport { print, type DocumentNode } from \"graphql\";\nimport type { PaginationOptions } from \"../types/options\";\n\n/**\n * Generic subgraph response structure\n */\nexport interface SubgraphResponse<T> {\n  data?: T;\n  errors?: Array<{ message: string }>;\n}\n\n/**\n * Configuration for paginated subgraph queries\n */\nexport interface PaginatedQueryConfig<TData, TItem, TRawItem = any> {\n  /** The GraphQL endpoint URL */\n  endpoint: string;\n\n  /** The GraphQL document to execute */\n  document: DocumentNode;\n\n  /** Base variables for the query (e.g., userId) */\n  baseVariables: Record<string, any>;\n\n  /** Pagination options from the user */\n  options?: PaginationOptions;\n\n  /** Function to extract items from the response */\n  extractItems: (data: TData) => TRawItem[] | undefined;\n\n  /** Function to transform items if needed */\n  transformItem?: (item: TRawItem) => TItem;\n\n  /** Maximum items per GraphQL query (default: 1000) */\n  maxPerQuery?: number;\n}\n\n/**\n * Generic paginated query executor for subgraph queries\n *\n * @remarks\n * Handles pagination, fetchAll, and proper GraphQL query construction.\n * Abstracts the common pattern of paginated subgraph queries.\n *\n * @param config - Configuration for the paginated query\n * @returns Array of items from all pages\n *\n * @example\n * ```typescript\n * const files = await executePaginatedQuery({\n *   endpoint: subgraphUrl,\n *   document: GetUserFilesPaginatedDocument,\n *   baseVariables: { userId: owner.toLowerCase() },\n *   options: { limit: 50, orderBy: 'addedAtBlock' },\n *   extractItems: (data) => data?.user?.files,\n *   transformItem: (file) => ({\n *     id: parseInt(file.id),\n *     url: file.url,\n *     // ... transform to UserFile\n *   })\n * });\n * ```\n */\nexport async function executePaginatedQuery<TData, TItem, TRawItem = any>(\n  config: PaginatedQueryConfig<TData, TItem, TRawItem>,\n): Promise<TItem[]> {\n  const {\n    endpoint,\n    document,\n    baseVariables,\n    options,\n    extractItems,\n    transformItem,\n    maxPerQuery = 1000,\n  } = config;\n\n  // Set pagination defaults\n  const limit = options?.fetchAll\n    ? Number.MAX_SAFE_INTEGER\n    : (options?.limit ?? 100);\n  const offset = options?.offset ?? 0;\n  const orderBy = options?.orderBy;\n  const orderDirection = options?.orderDirection;\n\n  const allItems: TItem[] = [];\n  let currentOffset = offset;\n  const pageSize = Math.min(limit, maxPerQuery);\n\n  // Handle fetchAll by making multiple queries if needed\n  while (true) {\n    const currentLimit = options?.fetchAll\n      ? pageSize\n      : Math.min(pageSize, limit - allItems.length);\n\n    // Build query variables\n    const variables = {\n      ...baseVariables,\n      first: currentLimit,\n      skip: currentOffset,\n      ...(orderBy && { orderBy }),\n      ...(orderDirection && { orderDirection }),\n    };\n\n    // Execute query\n    const response = await fetch(endpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({\n        query: print(document),\n        variables,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(\n        `Subgraph request failed: ${response.status} ${response.statusText}`,\n      );\n    }\n\n    const result = (await response.json()) as SubgraphResponse<TData>;\n\n    if (result.errors) {\n      throw new Error(\n        `Subgraph errors: ${result.errors.map((e) => e.message).join(\", \")}`,\n      );\n    }\n\n    // Extract items from response\n    const items = extractItems(result.data as TData);\n\n    if (!items || items.length === 0) {\n      // No more items\n      break;\n    }\n\n    // Transform items if transformer provided\n    const transformedItems: TItem[] = transformItem\n      ? items.map(transformItem)\n      : (items as unknown as TItem[]);\n\n    allItems.push(...transformedItems);\n\n    // Check if we have enough items or should continue\n    if (!options?.fetchAll && allItems.length >= limit) {\n      // We have enough items\n      return allItems.slice(0, limit); // Trim to exact limit\n    }\n\n    if (items.length < currentLimit) {\n      // No more items available\n      break;\n    }\n\n    // Continue to next page\n    currentOffset += items.length;\n  }\n\n  return allItems;\n}\n\n/**\n * Helper to map string orderBy values to GraphQL enums\n *\n * @param orderBy - String orderBy value from options\n * @param enumMap - Map of string values to GraphQL enum values\n * @returns The mapped enum value or undefined\n */\nexport function mapOrderByToEnum<T>(\n  orderBy: string | undefined,\n  enumMap: Record<string, T>,\n  defaultValue?: T,\n): T | undefined {\n  if (!orderBy) return defaultValue;\n  return enumMap[orderBy] ?? defaultValue;\n}\n\n/**\n * Helper to map string orderDirection to GraphQL enum\n *\n * @param direction - Direction string ('asc' or 'desc')\n * @param ascValue - The GraphQL enum value for ascending\n * @param descValue - The GraphQL enum value for descending\n * @returns The mapped enum value\n */\nexport function mapOrderDirection<T>(\n  direction: \"asc\" | \"desc\" | undefined,\n  ascValue: T,\n  descValue: T,\n  defaultValue?: T,\n): T {\n  if (!direction) return defaultValue ?? descValue;\n  return direction === \"asc\" ? ascValue : descValue;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,qBAAyC;AA+DzC,eAAsB,sBACpB,QACkB;AAClB,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,EAChB,IAAI;AAGJ,QAAM,QAAQ,SAAS,WACnB,OAAO,mBACN,SAAS,SAAS;AACvB,QAAM,SAAS,SAAS,UAAU;AAClC,QAAM,UAAU,SAAS;AACzB,QAAM,iBAAiB,SAAS;AAEhC,QAAM,WAAoB,CAAC;AAC3B,MAAI,gBAAgB;AACpB,QAAM,WAAW,KAAK,IAAI,OAAO,WAAW;AAG5C,SAAO,MAAM;AACX,UAAM,eAAe,SAAS,WAC1B,WACA,KAAK,IAAI,UAAU,QAAQ,SAAS,MAAM;AAG9C,UAAM,YAAY;AAAA,MAChB,GAAG;AAAA,MACH,OAAO;AAAA,MACP,MAAM;AAAA,MACN,GAAI,WAAW,EAAE,QAAQ;AAAA,MACzB,GAAI,kBAAkB,EAAE,eAAe;AAAA,IACzC;AAGA,UAAM,WAAW,MAAM,MAAM,UAAU;AAAA,MACrC,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,MAClB;AAAA,MACA,MAAM,KAAK,UAAU;AAAA,QACnB,WAAO,sBAAM,QAAQ;AAAA,QACrB;AAAA,MACF,CAAC;AAAA,IACH,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI;AAAA,QACR,4BAA4B,SAAS,MAAM,IAAI,SAAS,UAAU;AAAA,MACpE;AAAA,IACF;AAEA,UAAM,SAAU,MAAM,SAAS,KAAK;AAEpC,QAAI,OAAO,QAAQ;AACjB,YAAM,IAAI;AAAA,QACR,oBAAoB,OAAO,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAAA,MACpE;AAAA,IACF;AAGA,UAAM,QAAQ,aAAa,OAAO,IAAa;AAE/C,QAAI,CAAC,SAAS,MAAM,WAAW,GAAG;AAEhC;AAAA,IACF;AAGA,UAAM,mBAA4B,gBAC9B,MAAM,IAAI,aAAa,IACtB;AAEL,aAAS,KAAK,GAAG,gBAAgB;AAGjC,QAAI,CAAC,SAAS,YAAY,SAAS,UAAU,OAAO;AAElD,aAAO,SAAS,MAAM,GAAG,KAAK;AAAA,IAChC;AAEA,QAAI,MAAM,SAAS,cAAc;AAE/B;AAAA,IACF;AAGA,qBAAiB,MAAM;AAAA,EACzB;AAEA,SAAO;AACT;AASO,SAAS,iBACd,SACA,SACA,cACe;AACf,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAUO,SAAS,kBACd,WACA,UACA,WACA,cACG;AACH,MAAI,CAAC,UAAW,QAAO,gBAAgB;AACvC,SAAO,cAAc,QAAQ,WAAW;AAC1C;","names":[]}

package/dist/utils/subgraphPagination.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file Utilities for handling paginated subgraph queries
+ * @module vana-sdk/utils/subgraphPagination
+ */
+import { type DocumentNode } from "graphql";
+import type { PaginationOptions } from "../types/options";
+/**
+ * Generic subgraph response structure
+ */
+export interface SubgraphResponse<T> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+    }>;
+}
+/**
+ * Configuration for paginated subgraph queries
+ */
+export interface PaginatedQueryConfig<TData, TItem, TRawItem = any> {
+    /** The GraphQL endpoint URL */
+    endpoint: string;
+    /** The GraphQL document to execute */
+    document: DocumentNode;
+    /** Base variables for the query (e.g., userId) */
+    baseVariables: Record<string, any>;
+    /** Pagination options from the user */
+    options?: PaginationOptions;
+    /** Function to extract items from the response */
+    extractItems: (data: TData) => TRawItem[] | undefined;
+    /** Function to transform items if needed */
+    transformItem?: (item: TRawItem) => TItem;
+    /** Maximum items per GraphQL query (default: 1000) */
+    maxPerQuery?: number;
+}
+/**
+ * Generic paginated query executor for subgraph queries
+ *
+ * @remarks
+ * Handles pagination, fetchAll, and proper GraphQL query construction.
+ * Abstracts the common pattern of paginated subgraph queries.
+ *
+ * @param config - Configuration for the paginated query
+ * @returns Array of items from all pages
+ *
+ * @example
+ * ```typescript
+ * const files = await executePaginatedQuery({
+ *   endpoint: subgraphUrl,
+ *   document: GetUserFilesPaginatedDocument,
+ *   baseVariables: { userId: owner.toLowerCase() },
+ *   options: { limit: 50, orderBy: 'addedAtBlock' },
+ *   extractItems: (data) => data?.user?.files,
+ *   transformItem: (file) => ({
+ *     id: parseInt(file.id),
+ *     url: file.url,
+ *     // ... transform to UserFile
+ *   })
+ * });
+ * ```
+ */
+export declare function executePaginatedQuery<TData, TItem, TRawItem = any>(config: PaginatedQueryConfig<TData, TItem, TRawItem>): Promise<TItem[]>;
+/**
+ * Helper to map string orderBy values to GraphQL enums
+ *
+ * @param orderBy - String orderBy value from options
+ * @param enumMap - Map of string values to GraphQL enum values
+ * @returns The mapped enum value or undefined
+ */
+export declare function mapOrderByToEnum<T>(orderBy: string | undefined, enumMap: Record<string, T>, defaultValue?: T): T | undefined;
+/**
+ * Helper to map string orderDirection to GraphQL enum
+ *
+ * @param direction - Direction string ('asc' or 'desc')
+ * @param ascValue - The GraphQL enum value for ascending
+ * @param descValue - The GraphQL enum value for descending
+ * @returns The mapped enum value
+ */
+export declare function mapOrderDirection<T>(direction: "asc" | "desc" | undefined, ascValue: T, descValue: T, defaultValue?: T): T;

package/dist/utils/subgraphPagination.js

@@ -0,0 +1,78 @@
+import { print } from "graphql";
+async function executePaginatedQuery(config) {
+  const {
+    endpoint,
+    document,
+    baseVariables,
+    options,
+    extractItems,
+    transformItem,
+    maxPerQuery = 1e3
+  } = config;
+  const limit = options?.fetchAll ? Number.MAX_SAFE_INTEGER : options?.limit ?? 100;
+  const offset = options?.offset ?? 0;
+  const orderBy = options?.orderBy;
+  const orderDirection = options?.orderDirection;
+  const allItems = [];
+  let currentOffset = offset;
+  const pageSize = Math.min(limit, maxPerQuery);
+  while (true) {
+    const currentLimit = options?.fetchAll ? pageSize : Math.min(pageSize, limit - allItems.length);
+    const variables = {
+      ...baseVariables,
+      first: currentLimit,
+      skip: currentOffset,
+      ...orderBy && { orderBy },
+      ...orderDirection && { orderDirection }
+    };
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        query: print(document),
+        variables
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    const items = extractItems(result.data);
+    if (!items || items.length === 0) {
+      break;
+    }
+    const transformedItems = transformItem ? items.map(transformItem) : items;
+    allItems.push(...transformedItems);
+    if (!options?.fetchAll && allItems.length >= limit) {
+      return allItems.slice(0, limit);
+    }
+    if (items.length < currentLimit) {
+      break;
+    }
+    currentOffset += items.length;
+  }
+  return allItems;
+}
+function mapOrderByToEnum(orderBy, enumMap, defaultValue) {
+  if (!orderBy) return defaultValue;
+  return enumMap[orderBy] ?? defaultValue;
+}
+function mapOrderDirection(direction, ascValue, descValue, defaultValue) {
+  if (!direction) return defaultValue ?? descValue;
+  return direction === "asc" ? ascValue : descValue;
+}
+export {
+  executePaginatedQuery,
+  mapOrderByToEnum,
+  mapOrderDirection
+};
+//# sourceMappingURL=subgraphPagination.js.map

package/dist/utils/subgraphPagination.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/subgraphPagination.ts"],"sourcesContent":["/**\n * @file Utilities for handling paginated subgraph queries\n * @module vana-sdk/utils/subgraphPagination\n */\n\nimport { print, type DocumentNode } from \"graphql\";\nimport type { PaginationOptions } from \"../types/options\";\n\n/**\n * Generic subgraph response structure\n */\nexport interface SubgraphResponse<T> {\n  data?: T;\n  errors?: Array<{ message: string }>;\n}\n\n/**\n * Configuration for paginated subgraph queries\n */\nexport interface PaginatedQueryConfig<TData, TItem, TRawItem = any> {\n  /** The GraphQL endpoint URL */\n  endpoint: string;\n\n  /** The GraphQL document to execute */\n  document: DocumentNode;\n\n  /** Base variables for the query (e.g., userId) */\n  baseVariables: Record<string, any>;\n\n  /** Pagination options from the user */\n  options?: PaginationOptions;\n\n  /** Function to extract items from the response */\n  extractItems: (data: TData) => TRawItem[] | undefined;\n\n  /** Function to transform items if needed */\n  transformItem?: (item: TRawItem) => TItem;\n\n  /** Maximum items per GraphQL query (default: 1000) */\n  maxPerQuery?: number;\n}\n\n/**\n * Generic paginated query executor for subgraph queries\n *\n * @remarks\n * Handles pagination, fetchAll, and proper GraphQL query construction.\n * Abstracts the common pattern of paginated subgraph queries.\n *\n * @param config - Configuration for the paginated query\n * @returns Array of items from all pages\n *\n * @example\n * ```typescript\n * const files = await executePaginatedQuery({\n *   endpoint: subgraphUrl,\n *   document: GetUserFilesPaginatedDocument,\n *   baseVariables: { userId: owner.toLowerCase() },\n *   options: { limit: 50, orderBy: 'addedAtBlock' },\n *   extractItems: (data) => data?.user?.files,\n *   transformItem: (file) => ({\n *     id: parseInt(file.id),\n *     url: file.url,\n *     // ... transform to UserFile\n *   })\n * });\n * ```\n */\nexport async function executePaginatedQuery<TData, TItem, TRawItem = any>(\n  config: PaginatedQueryConfig<TData, TItem, TRawItem>,\n): Promise<TItem[]> {\n  const {\n    endpoint,\n    document,\n    baseVariables,\n    options,\n    extractItems,\n    transformItem,\n    maxPerQuery = 1000,\n  } = config;\n\n  // Set pagination defaults\n  const limit = options?.fetchAll\n    ? Number.MAX_SAFE_INTEGER\n    : (options?.limit ?? 100);\n  const offset = options?.offset ?? 0;\n  const orderBy = options?.orderBy;\n  const orderDirection = options?.orderDirection;\n\n  const allItems: TItem[] = [];\n  let currentOffset = offset;\n  const pageSize = Math.min(limit, maxPerQuery);\n\n  // Handle fetchAll by making multiple queries if needed\n  while (true) {\n    const currentLimit = options?.fetchAll\n      ? pageSize\n      : Math.min(pageSize, limit - allItems.length);\n\n    // Build query variables\n    const variables = {\n      ...baseVariables,\n      first: currentLimit,\n      skip: currentOffset,\n      ...(orderBy && { orderBy }),\n      ...(orderDirection && { orderDirection }),\n    };\n\n    // Execute query\n    const response = await fetch(endpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({\n        query: print(document),\n        variables,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(\n        `Subgraph request failed: ${response.status} ${response.statusText}`,\n      );\n    }\n\n    const result = (await response.json()) as SubgraphResponse<TData>;\n\n    if (result.errors) {\n      throw new Error(\n        `Subgraph errors: ${result.errors.map((e) => e.message).join(\", \")}`,\n      );\n    }\n\n    // Extract items from response\n    const items = extractItems(result.data as TData);\n\n    if (!items || items.length === 0) {\n      // No more items\n      break;\n    }\n\n    // Transform items if transformer provided\n    const transformedItems: TItem[] = transformItem\n      ? items.map(transformItem)\n      : (items as unknown as TItem[]);\n\n    allItems.push(...transformedItems);\n\n    // Check if we have enough items or should continue\n    if (!options?.fetchAll && allItems.length >= limit) {\n      // We have enough items\n      return allItems.slice(0, limit); // Trim to exact limit\n    }\n\n    if (items.length < currentLimit) {\n      // No more items available\n      break;\n    }\n\n    // Continue to next page\n    currentOffset += items.length;\n  }\n\n  return allItems;\n}\n\n/**\n * Helper to map string orderBy values to GraphQL enums\n *\n * @param orderBy - String orderBy value from options\n * @param enumMap - Map of string values to GraphQL enum values\n * @returns The mapped enum value or undefined\n */\nexport function mapOrderByToEnum<T>(\n  orderBy: string | undefined,\n  enumMap: Record<string, T>,\n  defaultValue?: T,\n): T | undefined {\n  if (!orderBy) return defaultValue;\n  return enumMap[orderBy] ?? defaultValue;\n}\n\n/**\n * Helper to map string orderDirection to GraphQL enum\n *\n * @param direction - Direction string ('asc' or 'desc')\n * @param ascValue - The GraphQL enum value for ascending\n * @param descValue - The GraphQL enum value for descending\n * @returns The mapped enum value\n */\nexport function mapOrderDirection<T>(\n  direction: \"asc\" | \"desc\" | undefined,\n  ascValue: T,\n  descValue: T,\n  defaultValue?: T,\n): T {\n  if (!direction) return defaultValue ?? descValue;\n  return direction === \"asc\" ? ascValue : descValue;\n}\n"],"mappings":"AAKA,SAAS,aAAgC;AA+DzC,eAAsB,sBACpB,QACkB;AAClB,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,EAChB,IAAI;AAGJ,QAAM,QAAQ,SAAS,WACnB,OAAO,mBACN,SAAS,SAAS;AACvB,QAAM,SAAS,SAAS,UAAU;AAClC,QAAM,UAAU,SAAS;AACzB,QAAM,iBAAiB,SAAS;AAEhC,QAAM,WAAoB,CAAC;AAC3B,MAAI,gBAAgB;AACpB,QAAM,WAAW,KAAK,IAAI,OAAO,WAAW;AAG5C,SAAO,MAAM;AACX,UAAM,eAAe,SAAS,WAC1B,WACA,KAAK,IAAI,UAAU,QAAQ,SAAS,MAAM;AAG9C,UAAM,YAAY;AAAA,MAChB,GAAG;AAAA,MACH,OAAO;AAAA,MACP,MAAM;AAAA,MACN,GAAI,WAAW,EAAE,QAAQ;AAAA,MACzB,GAAI,kBAAkB,EAAE,eAAe;AAAA,IACzC;AAGA,UAAM,WAAW,MAAM,MAAM,UAAU;AAAA,MACrC,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,MAClB;AAAA,MACA,MAAM,KAAK,UAAU;AAAA,QACnB,OAAO,MAAM,QAAQ;AAAA,QACrB;AAAA,MACF,CAAC;AAAA,IACH,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI;AAAA,QACR,4BAA4B,SAAS,MAAM,IAAI,SAAS,UAAU;AAAA,MACpE;AAAA,IACF;AAEA,UAAM,SAAU,MAAM,SAAS,KAAK;AAEpC,QAAI,OAAO,QAAQ;AACjB,YAAM,IAAI;AAAA,QACR,oBAAoB,OAAO,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAAA,MACpE;AAAA,IACF;AAGA,UAAM,QAAQ,aAAa,OAAO,IAAa;AAE/C,QAAI,CAAC,SAAS,MAAM,WAAW,GAAG;AAEhC;AAAA,IACF;AAGA,UAAM,mBAA4B,gBAC9B,MAAM,IAAI,aAAa,IACtB;AAEL,aAAS,KAAK,GAAG,gBAAgB;AAGjC,QAAI,CAAC,SAAS,YAAY,SAAS,UAAU,OAAO;AAElD,aAAO,SAAS,MAAM,GAAG,KAAK;AAAA,IAChC;AAEA,QAAI,MAAM,SAAS,cAAc;AAE/B;AAAA,IACF;AAGA,qBAAiB,MAAM;AAAA,EACzB;AAEA,SAAO;AACT;AASO,SAAS,iBACd,SACA,SACA,cACe;AACf,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAUO,SAAS,kBACd,WACA,UACA,WACA,cACG;AACH,MAAI,CAAC,UAAW,QAAO,gBAAgB;AACvC,SAAO,cAAc,QAAQ,WAAW;AAC1C;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/vana-sdk",
-  "version": "0.1.0-alpha.a6b60fc",
+  "version": "0.1.0-alpha.a78ce5c",
   "description": "A TypeScript library for interacting with Vana Network smart contracts.",
   "publishConfig": {
     "access": "public"
@@ -122,6 +122,7 @@
     "eccrypto-js": "^5.4.0",
     "graphql": "^16.11.0",
     "openpgp": "^6.1.1",
+    "uuid": "^13.0.0",
     "viem": "^2.35.1"
   },
   "devDependencies": {
@@ -131,6 +132,7 @@
     "@graphql-codegen/typescript-operations": "^4.6.1",
     "@types/node": "^24.3.0",
     "@types/secp256k1": "^4.0.6",
+    "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^8.41.0",
     "@typescript-eslint/parser": "^8.41.0",
     "@vitest/coverage-v8": "^3.2.4",