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

package/dist/controllers/schemas.d.ts

@@ -0,0 +1,252 @@
+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 for validation and structure definition on Vana.
+ *
+ * @remarks
+ * Handles schema lifecycle from creation through registration. Schemas define
+ * data structure and validation rules, ensuring consistency across the network.
+ * Stored unencrypted on IPFS for public reusability.
+ *
+ * **Architecture:**
+ * Schemas use dual storage: definitions on IPFS (public), metadata on blockchain.
+ * Supports JSON Schema and SQLite dialects for flexible data modeling.
+ *
+ * **Method Selection:**
+ * - `create()` - Validate, upload to IPFS, register on blockchain
+ * - `get()` - Retrieve schema with definition by ID
+ * - `list()` - Paginated schema browsing with metadata
+ * - `count()` - Total schemas for pagination
+ * - `addSchema()` - Low-level registration with pre-uploaded URL
+ *
+ * **Storage Requirements:**
+ * - Methods requiring storage: `create()`
+ * - Methods without storage: `get()`, `list()`, `count()`, `addSchema()`
+ *
+ * @example
+ * ```typescript
+ * // Create schema with validation rules
+ * 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, maximum: 150 }
+ *     },
+ *     required: ["name"]
+ *   }
+ * });
+ * console.log(`Schema ${result.schemaId} created`);
+ *
+ * // Retrieve for validation
+ * const schema = await vana.schemas.get(result.schemaId);
+ * console.log(`Schema: ${schema.name} (${schema.dialect})`);
+ *
+ * // Browse available schemas
+ * const schemas = await vana.schemas.list({ limit: 10 });
+ * schemas.forEach(s => console.log(`${s.id}: ${s.name}`));
+ * ```
+ *
+ * @category Schema Management
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/schemas}
+ */
+export declare class SchemaController extends BaseController {
+    constructor(context: ControllerContext);
+    /**
+     * 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}`);
+     * ```
+     */
+    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;
+}