@opendatalabs/vana-sdk 0.1.0-alpha.db07fe1 → 0.1.0-alpha.dc68f39

package/dist/controllers/schemas.d.ts

@@ -0,0 +1,245 @@
+import type { Schema, CompleteSchema, AddSchemaParams } from "../types/index";
+import type { SchemaAddedResult } from "../types/transactionResults";
+import type { ControllerContext } from "./permissions";
+import { BaseController } from "./base";
+/**
+ * Parameters for creating a new schema with automatic IPFS upload.
+ *
+ * @remarks
+ * This interface is used with the high-level `schemas.create()` method which
+ * automatically uploads the schema definition to IPFS and registers it on-chain.
+ * @category Schema Management
+ */
+export interface CreateSchemaParams {
+    /** The name of the schema */
+    name: string;
+    /** The dialect of the schema (e.g., 'json' or 'sqlite') */
+    dialect: "json" | "sqlite";
+    /** The schema definition object or JSON string */
+    schema: object | string;
+}
+/**
+ * Result of creating a new schema.
+ *
+ * @remarks
+ * Returned by the `schemas.create()` method after successful upload and registration.
+ * @category Schema Management
+ */
+export interface CreateSchemaResult {
+    /** The schema ID assigned by the contract */
+    schemaId: bigint;
+    /** The IPFS URL where the schema definition is stored */
+    definitionUrl: string;
+    /** The transaction hash of the schema registration */
+    transactionHash: string;
+}
+/**
+ * Manages data schemas and refiners on the Vana network.
+ *
+ * @remarks
+ * This controller handles the complete lifecycle of data schemas including creation,
+ * validation, IPFS upload, and blockchain registration. It provides methods for managing
+ * both schemas (data structure definitions) and refiners (data processing definitions).
+ *
+ * **Schema Storage:**
+ * Schemas are stored unencrypted on IPFS for public access and reusability across the network.
+ * Schema definitions use JSON Schema format for data validation and structure definition.
+ *
+ * **Method Selection:**
+ * - `create()` validates, uploads to IPFS, and registers new schemas on blockchain
+ * - `get()` retrieves existing schema metadata by ID from blockchain contracts
+ * - `count()` returns total number of registered schemas for pagination
+ * - `list()` provides paginated access to all schemas with optional filtering
+ * - `addSchema()` provides lower-level schema registration with pre-uploaded URLs
+ *
+ * **Storage Requirements:**
+ * Methods requiring storage configuration: `create()`
+ * Methods working without storage: `get()`, `count()`, `list()`, `addSchema()`
+ *
+ * @example
+ * ```typescript
+ * // Create a new schema with automatic IPFS upload
+ * const result = await vana.schemas.create({
+ *   name: "User Profile",
+ *   dialect: "json",
+ *   schema: {
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *       age: { type: "number" }
+ *     },
+ *     required: ["name"]
+ *   }
+ * });
+ *
+ * // Get an existing schema
+ * const schema = await vana.schemas.get(1);
+ *
+ * // List all schemas
+ * const count = await vana.schemas.count();
+ * ```
+ * @category Schema Management
+ */
+export declare class SchemaController extends BaseController {
+    constructor(context: ControllerContext);
+    /**
+     * Creates a new schema with automatic validation and IPFS upload.
+     *
+     * @remarks
+     * This is the primary method for creating schemas on the Vana network. It handles
+     * the complete workflow including schema validation, IPFS upload, and blockchain
+     * registration. The schema definition is stored unencrypted on IPFS to enable
+     * public access and reusability.
+     *
+     * The method automatically:
+     * - Validates the schema definition against the Vana metaschema
+     * - Uploads the definition to IPFS to generate a permanent URL
+     * - Registers the schema on the blockchain with the generated URL
+     *
+     * @param params - Schema creation parameters including name, dialect, and definition
+     * @returns Promise resolving to creation results with schema ID and transaction hash
+     * @throws {SchemaValidationError} When the schema definition is invalid
+     * @throws {Error} When IPFS upload or blockchain registration fails
+     * @example
+     * ```typescript
+     * // Create a JSON schema for user profiles
+     * const result = await vana.schemas.create({
+     *   name: "User Profile",
+     *   dialect: "json",
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       age: { type: "number", minimum: 0 }
+     *     },
+     *     required: ["name"]
+     *   }
+     * });
+     *
+     * console.log(`Schema created with ID: ${result.schemaId}`);
+     * ```
+     */
+    create(params: CreateSchemaParams): Promise<CreateSchemaResult>;
+    /**
+     * 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);
+     * ```
+     */
+    get(schemaId: number, options?: {
+        subgraphUrl?: string;
+    }): Promise<CompleteSchema>;
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    count(options?: {
+        subgraphUrl?: string;
+    }): Promise<number>;
+    /**
+     * 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 });
+     * ```
+     */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+        subgraphUrl?: string;
+        includeDefinitions?: boolean;
+    }): Promise<Schema[]>;
+    /**
+     * 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
+     */
+    addSchema(params: AddSchemaParams): Promise<SchemaAddedResult>;
+    /**
+     * 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
+     */
+    private _getSchemaViaSubgraph;
+    /**
+     * 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
+     */
+    private _listSchemasViaSubgraph;
+    /**
+     * 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
+     */
+    private _countSchemasViaSubgraph;
+    /**
+     * 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
+     */
+    private _fetchDefinitionsForSchemas;
+}