@opendatalabs/vana-sdk 2.3.0 → 3.0.0

package/dist/controllers/schemas.js

@@ -1,654 +0,0 @@
-import { BaseController } from "./base";
-import { getContractAddress } from "../generated/addresses";
-import { getAbi } from "../generated/abi";
-import { gasAwareMulticall } from "../utils/multicall";
-import {
-  validateDataSchemaAgainstMetaSchema,
-  SchemaValidationError
-} from "../utils/schemaValidation";
-import {
-  fetchSchemaFromChain,
-  fetchSchemaCountFromChain
-} from "../utils/blockchain/registry";
-import {
-  GetSchemaDocument,
-  ListSchemasDocument,
-  CountSchemasDocument
-} from "../generated/subgraph";
-import { print } from "graphql";
-import { fetchFromUrl, UrlResolutionError } from "../utils/urlResolver";
-class SchemaController extends BaseController {
-  constructor(context) {
-    super(context);
-  }
-  /**
-   * Creates a schema with validation and IPFS upload.
-   *
-   * @remarks
-   * Primary method for schema creation. Validates definition,
-   * uploads to IPFS (unencrypted for reusability), and registers
-   * on blockchain. Schema becomes immediately available network-wide.
-   *
-   * @param params - Creation configuration
-   * @param params.name - Human-readable schema name
-   * @param params.dialect - Schema format (`"json"` or `"sqlite"`)
-   * @param params.schema - Definition object or JSON string
-   *
-   * @returns Schema ID, IPFS URL, and transaction hash
-   *
-   * @throws {SchemaValidationError} Invalid schema definition.
-   *   Verify schema follows JSON Schema or SQLite format.
-   * @throws {Error} Storage not configured.
-   *   Configure storage providers in VanaConfig.
-   * @throws {Error} IPFS upload failed.
-   *   Check network and storage provider status.
-   *
-   * @example
-   * ```typescript
-   * const result = await vana.schemas.create({
-   *   name: "User Profile",
-   *   dialect: "json",
-   *   schema: {
-   *     type: "object",
-   *     properties: {
-   *       name: { type: "string", minLength: 1 },
-   *       age: { type: "number", minimum: 0 }
-   *     },
-   *     required: ["name"]
-   *   }
-   * });
-   * console.log(`Schema ${result.schemaId} at ${result.definitionUrl}`);
-   * ```
-   */
-  async create(params) {
-    this.assertWallet();
-    const { name, dialect, schema } = params;
-    try {
-      let schemaDefinition;
-      if (typeof schema === "string") {
-        try {
-          schemaDefinition = JSON.parse(schema);
-        } catch {
-          throw new SchemaValidationError(
-            "Invalid JSON in schema definition",
-            []
-          );
-        }
-      } else {
-        schemaDefinition = schema;
-      }
-      const dataSchema = {
-        name,
-        version: "1.0.0",
-        dialect,
-        schema: schemaDefinition
-      };
-      validateDataSchemaAgainstMetaSchema(dataSchema);
-      if (!this.context.storageManager) {
-        if (this.context.validateStorageRequired) {
-          this.context.validateStorageRequired();
-          throw new Error("Storage validation failed");
-        } else {
-          throw new Error(
-            "Storage manager not configured. Please provide storage providers in VanaConfig."
-          );
-        }
-      }
-      const schemaBlob = new Blob([JSON.stringify(dataSchema)], {
-        type: "application/json"
-      });
-      const uploadResult = await this.context.storageManager.upload(
-        schemaBlob,
-        `${name.replace(/[^a-zA-Z0-9]/g, "_")}.json`
-      );
-      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
-      if (!chainId) {
-        throw new Error("Chain ID not available");
-      }
-      const dataRefinerRegistryAddress = getContractAddress(
-        chainId,
-        "DataRefinerRegistry"
-      );
-      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const account = this.context.walletClient.account ?? this.context.userAddress;
-      const from = typeof account === "string" ? account : account?.address;
-      const hash = await this.context.walletClient.writeContract({
-        address: dataRefinerRegistryAddress,
-        abi: dataRefinerRegistryAbi,
-        functionName: "addSchema",
-        args: [name, dialect, uploadResult.url],
-        account,
-        chain: this.context.walletClient.chain ?? null
-      });
-      const { tx } = await import("../utils/transactionHelpers");
-      const txResult = tx({
-        hash,
-        from,
-        contract: "DataRefinerRegistry",
-        fn: "addSchema"
-      });
-      if (!this.context.waitForTransactionEvents) {
-        throw new Error("waitForTransactionEvents not configured");
-      }
-      const result = await this.context.waitForTransactionEvents(txResult);
-      const event = result.expectedEvents.SchemaAdded;
-      if (!event) {
-        throw new Error("SchemaAdded event not found in transaction");
-      }
-      return {
-        schemaId: event.schemaId,
-        definitionUrl: uploadResult.url,
-        transactionHash: hash
-      };
-    } catch (error) {
-      if (error instanceof SchemaValidationError) {
-        throw error;
-      }
-      throw new Error(
-        `Schema creation failed: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Retrieves a complete schema by its ID with definition fetched and flattened.
-   *
-   * @param schemaId - The ID of the schema to retrieve
-   * @param options - Optional parameters
-   * @param options.subgraphUrl - Custom subgraph URL to use instead of default
-   * @returns Promise resolving to the complete schema object with all fields populated
-   * @throws {Error} When the schema is not found, definition cannot be fetched, or chain is unavailable
-   * @example
-   * ```typescript
-   * const schema = await vana.schemas.get(1);
-   * console.log(`Schema: ${schema.name} (${schema.dialect})`);
-   * console.log(`Version: ${schema.version}`);
-   * console.log(`Description: ${schema.description}`);
-   * console.log('Schema:', schema.schema);
-   *
-   * // Use directly with validator (schema has all required fields)
-   * validator.validateDataAgainstSchema(data, schema);
-   * ```
-   */
-  async get(schemaId, options = {}) {
-    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
-    let metadata;
-    if (subgraphUrl) {
-      try {
-        metadata = await this._getSchemaViaSubgraph({ schemaId, subgraphUrl });
-      } catch (error) {
-        console.debug("Subgraph query failed, falling back to RPC:", error);
-        try {
-          metadata = await fetchSchemaFromChain(this.context, schemaId);
-        } catch (rpcError) {
-          throw new Error(
-            `Failed to get schema: ${rpcError instanceof Error ? rpcError.message : "Unknown error"}`
-          );
-        }
-      }
-    } else {
-      try {
-        metadata = await fetchSchemaFromChain(this.context, schemaId);
-      } catch (error) {
-        throw new Error(
-          `Failed to get schema: ${error instanceof Error ? error.message : "Unknown error"}`
-        );
-      }
-    }
-    const definition = await fetchFromUrl(
-      metadata.definitionUrl,
-      this.context.downloadRelayer
-    );
-    if (!definition || typeof definition !== "object") {
-      throw new Error(
-        `Invalid schema definition format for schema ${schemaId}`
-      );
-    }
-    validateDataSchemaAgainstMetaSchema(definition);
-    const dataSchema = definition;
-    if (dataSchema.name !== metadata.name) {
-      console.warn(
-        `Schema name mismatch for ID ${schemaId}: on-chain="${metadata.name}" off-chain="${dataSchema.name}" (using on-chain value)`
-      );
-    }
-    if (dataSchema.dialect !== metadata.dialect) {
-      console.warn(
-        `Schema dialect mismatch for ID ${schemaId}: on-chain="${metadata.dialect}" off-chain="${dataSchema.dialect}" (using on-chain value)`
-      );
-    }
-    return {
-      ...metadata,
-      version: dataSchema.version,
-      description: dataSchema.description,
-      schema: dataSchema.schema
-    };
-  }
-  /**
-   * Gets the total number of schemas registered on the network.
-   *
-   * @param options - Optional parameters
-   * @param options.subgraphUrl - Custom subgraph URL to use instead of default
-   * @returns Promise resolving to the total schema count
-   * @throws {Error} When the count cannot be retrieved
-   * @example
-   * ```typescript
-   * const count = await vana.schemas.count();
-   * console.log(`Total schemas: ${count}`);
-   *
-   * // With custom subgraph
-   * const count = await vana.schemas.count({
-   *   subgraphUrl: 'https://custom-subgraph.com/graphql'
-   * });
-   * ```
-   */
-  async count(options = {}) {
-    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
-    if (subgraphUrl) {
-      try {
-        return await this._countSchemasViaSubgraph({ subgraphUrl });
-      } catch (error) {
-        console.debug("Subgraph query failed, falling back to RPC:", error);
-      }
-    }
-    try {
-      return await fetchSchemaCountFromChain(this.context);
-    } catch (error) {
-      throw new Error(
-        `Failed to get schemas count: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Lists all schemas with pagination.
-   *
-   * @param options - Optional parameters for listing schemas
-   * @param options.limit - Maximum number of schemas to return
-   * @param options.offset - Number of schemas to skip
-   * @param options.subgraphUrl - Custom subgraph URL to use instead of default
-   * @param options.includeDefinitions - Whether to fetch and include schema definitions (default: false for performance)
-   * @returns Promise resolving to an array of schemas
-   * @example
-   * ```typescript
-   * // Get all schemas (without definitions for performance)
-   * const schemas = await vana.schemas.list();
-   *
-   * // Get schemas with definitions
-   * const schemas = await vana.schemas.list({ includeDefinitions: true });
-   *
-   * // Get schemas with pagination
-   * const schemas = await vana.schemas.list({ limit: 10, offset: 0 });
-   * ```
-   */
-  async list(options = {}) {
-    const {
-      limit = 100,
-      offset = 0,
-      includeDefinitions = false,
-      minBlock,
-      waitForSync
-    } = options;
-    const subgraphUrl = options.subgraphUrl ?? this.context.subgraphUrl;
-    if (subgraphUrl && (minBlock || waitForSync)) {
-      const { checkSubgraphConsistency } = await import("../utils/subgraphConsistency");
-      await checkSubgraphConsistency(subgraphUrl, { minBlock, waitForSync });
-    }
-    if (subgraphUrl) {
-      try {
-        return await this._listSchemasViaSubgraph({
-          limit,
-          offset,
-          subgraphUrl
-        });
-      } catch (error) {
-        console.debug("Subgraph query failed, falling back to RPC:", error);
-      }
-    }
-    try {
-      const totalCount = await this.count();
-      const start = offset;
-      const end = Math.min(start + limit, totalCount);
-      if (end <= start) {
-        return [];
-      }
-      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
-      if (!chainId) {
-        throw new Error("Chain ID not available");
-      }
-      const dataRefinerRegistryAddress = getContractAddress(
-        chainId,
-        "DataRefinerRegistry"
-      );
-      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const schemaCalls = [];
-      for (let i = start; i < end; i++) {
-        schemaCalls.push({
-          address: dataRefinerRegistryAddress,
-          abi: dataRefinerRegistryAbi,
-          functionName: "schemas",
-          args: [BigInt(i + 1)]
-          // Schema IDs are 1-based
-        });
-      }
-      const schemaResults = await gasAwareMulticall(this.context.publicClient, {
-        contracts: schemaCalls,
-        allowFailure: true
-      });
-      const schemas = [];
-      schemaResults.forEach((result, index) => {
-        if (result.status === "success" && result.result) {
-          const schemaId = start + index + 1;
-          const schemaData = result.result;
-          if (schemaData.name && schemaData.dialect && schemaData.definitionUrl) {
-            schemas.push({
-              id: schemaId,
-              name: schemaData.name,
-              dialect: schemaData.dialect,
-              definitionUrl: schemaData.definitionUrl
-            });
-          } else {
-            console.warn(`Incomplete schema data for ID ${schemaId}`);
-          }
-        } else {
-          console.warn(`Failed to retrieve schema ${start + index + 1}`);
-        }
-      });
-      if (includeDefinitions) {
-        await this._fetchDefinitionsForSchemas(schemas);
-      }
-      return schemas;
-    } catch (error) {
-      throw new Error(
-        `Failed to list schemas: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Retrieves schema definition content directly from a URL.
-   *
-   * @remarks
-   * Use this method to fetch and format schema definitions from IPFS or HTTP URLs.
-   * Automatically uses the SDK's configured download proxy to bypass CORS restrictions.
-   * Returns formatted JSON string if content is valid JSON, otherwise raw content.
-   *
-   * @param url - The definition URL (typically from schema.definitionUrl)
-   * @returns Promise resolving to the formatted definition content
-   * @throws {Error} When the content cannot be fetched or network errors occur
-   * @example
-   * ```typescript
-   * const schema = await vana.schemas.get(1);
-   * const definition = await vana.schemas.retrieveDefinition(schema.definitionUrl);
-   * console.log(definition); // Pretty-printed JSON
-   * ```
-   */
-  async retrieveDefinition(url) {
-    try {
-      const { universalFetch } = await import("../utils/download");
-      const response = await universalFetch(url, this.context.downloadRelayer);
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-      const text = await response.text();
-      try {
-        const json = JSON.parse(text);
-        return JSON.stringify(json, null, 2);
-      } catch {
-        return text;
-      }
-    } catch (error) {
-      throw new Error(
-        `Failed to retrieve schema definition: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Retrieves refinement instruction content from a URL.
-   *
-   * @remarks
-   * Use this method to fetch refinement instructions from IPFS or HTTP URLs.
-   * Temporarily housed in SchemaController since refiners use schemas and we don't
-   * have a dedicated RefinerController yet. Uses the SDK's configured download proxy.
-   *
-   * @param url - The instruction URL (typically from refiner.refinementInstructionUrl)
-   * @returns Promise resolving to the formatted instruction content
-   * @throws {Error} When the content cannot be fetched or network errors occur
-   * @example
-   * ```typescript
-   * const instructions = await vana.schemas.retrieveRefinementInstructions(
-   *   refiner.refinementInstructionUrl
-   * );
-   * console.log(instructions);
-   * ```
-   */
-  async retrieveRefinementInstructions(url) {
-    try {
-      return await this.retrieveDefinition(url);
-    } catch (error) {
-      throw new Error(
-        `Failed to retrieve refinement instructions: ${error instanceof Error ? error.message.replace(
-          "Failed to retrieve schema definition: ",
-          ""
-        ) : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Adds a schema using the legacy method (low-level API).
-   *
-   * @deprecated Use create() instead for the high-level API with automatic IPFS upload
-   * @param params - Schema parameters including pre-generated definition URL
-   * @returns Promise resolving to the add schema result
-   */
-  async addSchema(params) {
-    this.assertWallet();
-    try {
-      const chainId = this.context.walletClient?.chain?.id ?? this.context.publicClient.chain?.id;
-      if (!chainId) {
-        throw new Error("Chain ID not available");
-      }
-      const dataRefinerRegistryAddress = getContractAddress(
-        chainId,
-        "DataRefinerRegistry"
-      );
-      const dataRefinerRegistryAbi = getAbi("DataRefinerRegistry");
-      const account = this.context.walletClient.account ?? this.context.userAddress;
-      const from = typeof account === "string" ? account : account?.address;
-      const hash = await this.context.walletClient.writeContract({
-        address: dataRefinerRegistryAddress,
-        abi: dataRefinerRegistryAbi,
-        functionName: "addSchema",
-        args: [params.name, params.dialect, params.definitionUrl],
-        account,
-        chain: this.context.walletClient.chain ?? null
-      });
-      const { tx } = await import("../utils/transactionHelpers");
-      const txResult = tx({
-        hash,
-        from,
-        contract: "DataRefinerRegistry",
-        fn: "addSchema"
-      });
-      if (!this.context.waitForTransactionEvents) {
-        throw new Error("waitForTransactionEvents not configured");
-      }
-      const result = await this.context.waitForTransactionEvents(txResult);
-      const event = result.expectedEvents.SchemaAdded;
-      if (!event) {
-        throw new Error("SchemaAdded event not found in transaction");
-      }
-      const receipt = await this.context.publicClient.getTransactionReceipt({
-        hash
-      });
-      return {
-        transactionHash: hash,
-        blockNumber: receipt.blockNumber,
-        gasUsed: receipt.gasUsed,
-        schemaId: event.schemaId,
-        name: event.name,
-        dialect: event.dialect,
-        definitionUrl: event.definitionUrl
-      };
-    } catch (error) {
-      throw new Error(
-        `Failed to add schema: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-    }
-  }
-  /**
-   * Internal method: Query schema via subgraph
-   *
-   * @param params - Query parameters
-   * @param params.schemaId - The ID of the schema to retrieve
-   * @param params.subgraphUrl - The subgraph URL to query
-   * @returns Promise resolving to the schema object
-   * @private
-   */
-  async _getSchemaViaSubgraph(params) {
-    const { schemaId, subgraphUrl } = params;
-    const response = await fetch(subgraphUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        query: print(GetSchemaDocument),
-        variables: { id: schemaId.toString() }
-      })
-    });
-    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 query errors: ${result.errors.map((e) => e.message).join(", ")}`
-      );
-    }
-    if (!result.data?.schema) {
-      throw new Error(`Schema ${schemaId} not found in subgraph`);
-    }
-    const subgraphSchema = result.data.schema;
-    return {
-      id: parseInt(subgraphSchema.id),
-      name: subgraphSchema.name,
-      dialect: subgraphSchema.dialect,
-      definitionUrl: subgraphSchema.definitionUrl
-    };
-  }
-  /**
-   * Internal method: List schemas via subgraph
-   *
-   * @param params - Query parameters
-   * @param params.limit - Maximum number of schemas to return
-   * @param params.offset - Number of schemas to skip
-   * @param params.subgraphUrl - The subgraph URL to query
-   * @returns Promise resolving to an array of schemas
-   * @private
-   */
-  async _listSchemasViaSubgraph(params) {
-    const { limit, offset, subgraphUrl } = params;
-    const response = await fetch(subgraphUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        query: print(ListSchemasDocument),
-        variables: { first: limit, skip: offset }
-      })
-    });
-    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 query errors: ${result.errors.map((e) => e.message).join(", ")}`
-      );
-    }
-    if (!result.data?.schemas) {
-      return [];
-    }
-    const schemas = result.data.schemas.map((schema) => ({
-      id: parseInt(schema.id),
-      name: schema.name,
-      dialect: schema.dialect,
-      definitionUrl: schema.definitionUrl
-    }));
-    const { includeDefinitions } = params;
-    if (includeDefinitions) {
-      await this._fetchDefinitionsForSchemas(schemas);
-    }
-    return schemas;
-  }
-  /**
-   * Internal method: Count schemas via subgraph
-   *
-   * @param params - Query parameters
-   * @param params.subgraphUrl - The subgraph URL to query
-   * @returns Promise resolving to the total schema count
-   * @private
-   */
-  async _countSchemasViaSubgraph(params) {
-    const { subgraphUrl } = params;
-    const response = await fetch(subgraphUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        query: print(CountSchemasDocument),
-        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 query errors: ${result.errors.map((e) => e.message).join(", ")}`
-      );
-    }
-    return result.data?.schemas?.length ?? 0;
-  }
-  /**
-   * Gets the user's wallet address.
-   *
-   * @private
-   * @returns Promise resolving to the user's address
-   */
-  /**
-   * Fetches and attaches definitions to an array of schemas.
-   *
-   * @param schemas - Array of schemas to fetch definitions for
-   * @private
-   */
-  async _fetchDefinitionsForSchemas(schemas) {
-    await Promise.all(
-      schemas.map(async (schema) => {
-        if (!schema.definitionUrl) return;
-        try {
-          const definition = await fetchFromUrl(
-            schema.definitionUrl,
-            this.context.downloadRelayer
-          );
-          if (definition && typeof definition === "object") {
-            validateDataSchemaAgainstMetaSchema(definition);
-            const dataSchema = definition;
-            schema.version = dataSchema.version;
-            schema.description = dataSchema.description;
-            schema.schema = dataSchema.schema;
-          }
-        } catch (error) {
-          console.error(
-            `Failed to fetch/validate definition for schema ${schema.id}:`,
-            error instanceof UrlResolutionError || error instanceof SchemaValidationError ? error.message : error
-          );
-        }
-      })
-    );
-  }
-}
-export {
-  SchemaController
-};
-//# sourceMappingURL=schemas.js.map