@onchaindb/sdk 0.4.4 → 1.0.0

package/src/types.ts

@@ -7,12 +7,68 @@ export interface OnChainDBConfig {
     apiKey?: string; // Deprecated: use appKey instead
     appKey?: string; // App API key for write operations (X-App-Key header)
     userKey?: string; // User API key for Auto-Pay (X-User-Key header)
+    agentKey?: string; // Agent Key with Pay permission (X-Agent-Key header)
     appId?: string; // Application ID for automatic root building
     timeout?: number;
     retryCount?: number;
     retryDelay?: number;
 }
 
+// ============================================================================
+// App Key Management Types
+// ============================================================================
+
+/**
+ * Permissions that can be granted to an app key.
+ * A key with "Pay" permission is an Agent Key — it can pay other apps inline
+ * when accessing their data using USDC via EIP-3009.
+ */
+export type AppKeyPermission = 'Read' | 'Write' | 'Admin' | 'Pay';
+
+/**
+ * Spend limits for Agent Keys (keys with "Pay" permission).
+ * All fields are optional — omitting a field means no limit on that dimension.
+ */
+export interface PayLimits {
+    /** Optional expiry time (ISO 8601). Key stops working after this. */
+    expires_at?: string;
+    /** Max USDC per single transaction, in base units (6 decimals). e.g. 5000000 = 5 USDC */
+    max_payment_per_tx?: number;
+    /** Lifetime spend cap in USDC base units. */
+    spend_allowance?: number;
+    /** Whitelist of target app IDs this key may pay. Omit to allow all apps. */
+    allowed_target_apps?: string[];
+}
+
+/**
+ * Request body for POST /api/apps/:app_id/regenerate-key
+ */
+export interface CreateKeyRequest {
+    name?: string;
+    permissions?: AppKeyPermission[];
+    /** Only used when permissions includes "Pay". Ignored otherwise. */
+    pay_limits?: PayLimits;
+}
+
+/**
+ * App key entry returned by POST /api/apps/:app_id/keys/list
+ */
+export interface AppKeyInfo {
+    key_hash: string;
+    name: string;
+    permissions: AppKeyPermission[];
+    /** ISO 8601 expiry (only present on keys with pay_limits.expires_at set) */
+    expires_at?: string;
+    /** Max USDC per transaction in base units (6 decimals) */
+    max_payment_per_tx?: number;
+    /** Lifetime spend cap in USDC base units */
+    spend_allowance?: number;
+    /** Cumulative USDC spent so far in base units — increments after each on-chain payment */
+    spend_allowance_used?: number;
+    /** Whitelisted target app IDs (undefined = no restriction) */
+    allowed_target_apps?: string[];
+}
+
 export interface StoreRequest {
     root?: string; // Format: "app::collection" or just "collection" for system
     collection?: string; // Collection name (will be combined with appId if provided)
@@ -315,17 +371,9 @@ export interface PricingQuoteResponse {
 
 // Re-export from database.ts for consistency
 export type {
-    Collection,
-    CollectionSchema,
-    FieldDefinition,
-    FieldValidation,
-    Relationship,
     Index,
     IndexOptions,
-    IndexStatus,
-    IndexStatistics,
     PriceConfig,
-    CollectionMetadata
 } from './database';
 
 /**
@@ -519,10 +567,183 @@ export interface SyncCollectionResult {
         field: string;
         type: string;
     }[];
+    sharding_configured?: boolean;
     success: boolean;
     errors?: string[];
 }
 
+// ============================================================================
+// Collection Management
+// ============================================================================
+
+export interface UpdateCollectionRequest {
+    description?: string;
+    public?: boolean;
+    default_sort_column?: string;
+    retention_days?: number | null;
+    collection_type?: 'local' | 'offline' | 'api' | 'hybrid';
+    api_config?: ApiConfig;
+}
+
+export interface ApiConfig {
+    base_url: string;
+    authentication: any;
+    query_mapping: any;
+    response_mapping: any;
+}
+
+export interface CollectionResponse {
+    id: string;
+    name: string;
+    namespace: string;
+    primary_column: string;
+    sort_column?: string;
+    status: string;
+    collection_type: string;
+    document_count: number;
+    size_kb: number;
+    created_at: string;
+    last_modified: string;
+}
+
+export interface SetRetentionRequest {
+    retention_days: number | null;
+}
+
+export interface RetentionConfig {
+    collection: string;
+    retention_days?: number;
+    monthly_cost_per_kb: number;
+    last_cleanup?: string;
+    status: string;
+}
+
+export interface CollectionRetentionCost {
+    collection: string;
+    retention_days?: number;
+    size_kb: number;
+    monthly_cost_per_kb: number;
+    monthly_cost_tia: number;
+    projected_size_kb: number;
+    projected_monthly_cost_tia: number;
+}
+
+export interface RetentionCostResponse {
+    app_id: string;
+    collections: CollectionRetentionCost[];
+    total_monthly_cost_tia: number;
+    projected_next_month_cost_tia: number;
+}
+
+// ============================================================================
+// SQL Interface
+// ============================================================================
+
+export interface SqlQueryRequest {
+    sql: string;
+    include_history?: boolean;
+}
+
+export interface SqlQueryResponse {
+    data: any[];
+    count: number;
+    query: string;
+    app_id: string;
+    collection: string;
+}
+
+export interface SqlInsertRequest {
+    sql: string;
+}
+
+// ============================================================================
+// Predefined Queries
+// ============================================================================
+
+export interface QueryParameter {
+    /** Parameter name (used in URL query params) */
+    name: string;
+    /** Field path in the query (e.g., "market" or "price.$gte") */
+    field_path: string;
+    /** Default value if not provided */
+    default?: any;
+    /** Whether this parameter is required (no default, must be provided) */
+    required?: boolean;
+    /** Description of the parameter */
+    description?: string;
+}
+
+export interface QueryDefinition {
+    name: string;
+    source_collection: string;
+    base_query: any;
+    parameters?: QueryParameter[];
+    created_at: string;
+    description?: string;
+}
+
+export interface CreateQueryRequest {
+    name: string;
+    source_collection: string;
+    base_query: any;
+    parameters?: QueryParameter[];
+    description?: string;
+    version?: number;
+    response_schema?: any;
+    sample_response?: any;
+    example_request?: any;
+    example_response?: any;
+}
+
+export interface CreateQueryResponse {
+    success: boolean;
+    message: string;
+    query_name: string;
+}
+
+export interface QueryDataResponse {
+    success: boolean;
+    query_name: string;
+    data: any[];
+    count: number;
+    query_time_ms: number;
+}
+
+// ============================================================================
+// Views
+// ============================================================================
+
+export interface SqlCreateViewRequest {
+    sql: string;
+    refresh_mode?: 'live' | 'lazy';
+}
+
+export interface ViewDataResponse<T = any> {
+    success: boolean;
+    view_name: string;
+    data: T[];
+    count: number;
+    query_time_ms: number;
+}
+
+export interface ViewQueryRequest {
+    find?: any;
+    select?: string[];
+    sort_by?: string[];
+    limit?: number;
+    offset?: number;
+}
+
+// ============================================================================
+// API Collections
+// ============================================================================
+
+export interface CreateApiCollectionRequest {
+    name: string;
+    description: string;
+    api_config: ApiConfig;
+}
+
 /**
  * Base document fields (auto-added when useBaseFields is true)
  */

package/src/batch.ts

@@ -1,257 +0,0 @@
-import { OnChainDBClient } from './client';
-import { StoreRequest, StoreResponse, TransactionStatus } from './types';
-import { EventEmitter } from 'eventemitter3';
-
-/**
- * Batch operations for OnChainDB
- * 
- * Allows efficient batch insertion with transaction management
- * and progress tracking for large datasets.
- */
-export class BatchOperations extends EventEmitter {
-  constructor(private client: OnChainDBClient) {
-    super();
-  }
-
-  /**
-   * Batch store multiple records
-   * 
-   * @param requests - Array of store requests
-   * @param options - Batch options including payment configuration
-   * @returns Promise resolving to array of store responses
-   * 
-   * @example
-   * ```typescript
-   * const batch = new BatchOperations(db);
-   * 
-   * const results = await batch.store([
-   *   { data: { message: 'Tweet 1' }, collection: 'tweets' },
-   *   { data: { message: 'Tweet 2' }, collection: 'tweets' },
-   *   { data: { message: 'Tweet 3' }, collection: 'tweets' }
-   * ], {
-   *   concurrency: 5,
-   *   waitForConfirmation: true,
-   *   paymentOptions: {
-   *     userWallet: keplrWallet,
-   *     brokerAddress: 'celestia1xyz...'
-   *   }
-   * });
-   * ```
-   */
-  async store(
-    requests: StoreRequest[],
-    options: {
-      concurrency?: number;
-      waitForConfirmation?: boolean;
-      onProgress?: (completed: number, total: number) => void;
-      paymentOptions?: {
-        userWallet?: any;
-        brokerAddress?: string;
-      };
-    } = {}
-  ): Promise<StoreResponse[]> {
-    const {
-      concurrency = 10,
-      waitForConfirmation = false,
-      onProgress,
-      paymentOptions
-    } = options;
-
-    const results: StoreResponse[] = [];
-    const errors: Array<{ index: number; error: Error }> = [];
-    let completed = 0;
-
-    // Process requests in batches with concurrency limit
-    for (let i = 0; i < requests.length; i += concurrency) {
-      const batch = requests.slice(i, i + concurrency);
-      const batchPromises = batch.map(async (request, batchIndex) => {
-        const globalIndex = i + batchIndex;
-        try {
-          const result = await this.client.store(request, undefined, waitForConfirmation);
-          results[globalIndex] = result;
-          completed++;
-          onProgress?.(completed, requests.length);
-          this.emit('progress', { completed, total: requests.length, success: true });
-          return result;
-        } catch (error) {
-          errors.push({ index: globalIndex, error: error as Error });
-          completed++;
-          onProgress?.(completed, requests.length);
-          this.emit('progress', { completed, total: requests.length, success: false, error });
-          throw error;
-        }
-      });
-
-      // Wait for current batch to complete before starting next
-      await Promise.allSettled(batchPromises);
-    }
-
-    if (errors.length > 0) {
-      this.emit('batchComplete', { results, errors });
-      throw new Error(`Batch operation failed: ${errors.length}/${requests.length} requests failed`);
-    }
-
-    this.emit('batchComplete', { results, errors: [] });
-    return results;
-  }
-
-  /**
-   * Batch store with retry logic
-   * 
-   * @param requests - Store requests
-   * @param options - Batch options with retry configuration and payment support
-   * @returns Store responses
-   */
-  async storeWithRetry(
-    requests: StoreRequest[],
-    options: {
-      concurrency?: number;
-      waitForConfirmation?: boolean;
-      maxRetries?: number;
-      retryDelay?: number;
-      onProgress?: (completed: number, total: number) => void;
-      paymentOptions?: {
-        userWallet?: any;
-        brokerAddress?: string;
-      };
-    } = {}
-  ): Promise<StoreResponse[]> {
-    const {
-      maxRetries = 3,
-      retryDelay = 1000,
-      ...batchOptions
-    } = options;
-
-    let attempt = 0;
-    let lastError: Error;
-
-    while (attempt <= maxRetries) {
-      try {
-        return await this.store(requests, batchOptions);
-      } catch (error) {
-        lastError = error as Error;
-        attempt++;
-        
-        if (attempt <= maxRetries) {
-          this.emit('retryAttempt', { attempt, maxRetries, error });
-          await this.sleep(retryDelay * attempt); // Exponential backoff
-        }
-      }
-    }
-
-    throw lastError!;
-  }
-
-  /**
-   * Monitor multiple transactions for confirmation
-   * 
-   * @param transactionIds - Array of transaction IDs to monitor
-   * @param maxWaitTime - Maximum wait time per transaction
-   * @returns Promise resolving when all transactions are confirmed
-   */
-  async waitForBatchConfirmation(
-    transactionIds: string[],
-    maxWaitTime: number = 300000
-  ): Promise<TransactionStatus[]> {
-    const confirmationPromises = transactionIds.map(async (id, index) => {
-      try {
-        const result = await this.client.waitForConfirmation(id, maxWaitTime);
-        this.emit('transactionConfirmed', { id, index, result });
-        return {
-          id,
-          status: 'confirmed' as const,
-          block_height: result.block_height,
-          transaction_hash: result.transaction_hash,
-          celestia_height: result.celestia_height
-        };
-      } catch (error) {
-        this.emit('transactionFailed', { id, index, error });
-        return {
-          id,
-          status: 'failed' as const,
-          error: (error as Error).message
-        };
-      }
-    });
-
-    return Promise.all(confirmationPromises);
-  }
-
-  private sleep(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms));
-  }
-}
-
-/**
- * Utility class for building bulk operations
- * 
- * @example
- * ```typescript
- * const builder = new BulkBuilder()
- *   .collection('tweets')
- *   .add({ message: 'Tweet 1', author: 'alice' })
- *   .add({ message: 'Tweet 2', author: 'bob' })
- *   .add({ message: 'Tweet 3', author: 'charlie' });
- * 
- * const results = await db.batch().store(builder.build());
- * ```
- */
-export class BulkBuilder {
-  private requests: StoreRequest[] = [];
-  private defaultCollection?: string;
-  private defaultApp?: string;
-
-  /**
-   * Set default collection for all subsequent operations
-   */
-  collection(name: string): this {
-    this.defaultCollection = name;
-    return this;
-  }
-
-  /**
-   * Set default app for all subsequent operations
-   */
-  app(name: string): this {
-    this.defaultApp = name;
-    return this;
-  }
-
-  /**
-   * Add a data record to the bulk operation
-   */
-  add(data: Record<string, any>, collection?: string, app?: string): this {
-    this.requests.push({data: [data], root: `${app}::${collection}`});
-    return this;
-  }
-
-  /**
-   * Add multiple data records
-   */
-  addMany(records: Record<string, any>[], collection?: string, app?: string): this {
-    records.forEach(data => this.add(data, collection, app));
-    return this;
-  }
-
-  /**
-   * Build the final array of store requests
-   */
-  build(): StoreRequest[] {
-    return [...this.requests];
-  }
-
-  /**
-   * Get the number of operations in the builder
-   */
-  count(): number {
-    return this.requests.length;
-  }
-
-  /**
-   * Clear all operations
-   */
-  clear(): this {
-    this.requests = [];
-    return this;
-  }
-}

package/src/query-sdk/dist/ConditionBuilder.d.ts

@@ -1,22 +0,0 @@
-import { LogicalOperator, FieldConditionBuilder } from './operators';
-import { NestedConditionBuilder } from './NestedBuilders';
-export declare class ConditionBuilder {
-    private conditions;
-    private currentOperator?;
-    constructor();
-    static new(): ConditionBuilder;
-    field(fieldName: string): FieldConditionBuilder;
-    nested(fieldName: string, builderFn: (builder: NestedConditionBuilder) => LogicalOperator): LogicalOperator;
-    and(): ConditionBuilder;
-    or(): ConditionBuilder;
-    not(): ConditionBuilder;
-    andGroup(builderFn: (builder: ConditionBuilder) => LogicalOperator[]): LogicalOperator;
-    orGroup(builderFn: (builder: ConditionBuilder) => LogicalOperator[]): LogicalOperator;
-    notGroup(builderFn: (builder: ConditionBuilder) => LogicalOperator[]): LogicalOperator;
-    addCondition(condition: LogicalOperator): ConditionBuilder;
-    build(): LogicalOperator[];
-    buildSingle(): LogicalOperator;
-    clear(): ConditionBuilder;
-    isEmpty(): boolean;
-    getConditionCount(): number;
-}

package/src/query-sdk/dist/ConditionBuilder.js

@@ -1,90 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConditionBuilder = void 0;
-const operators_1 = require("./operators");
-const NestedBuilders_1 = require("./NestedBuilders");
-// Builder for creating complex conditions with logical operators
-class ConditionBuilder {
-    constructor() {
-        this.conditions = [];
-    }
-    static new() {
-        return new ConditionBuilder();
-    }
-    // Create a field condition builder
-    field(fieldName) {
-        return new operators_1.FieldConditionBuilder(fieldName);
-    }
-    // Create a nested field condition with fluent API (like Rust SDK)
-    nested(fieldName, builderFn) {
-        const nestedBuilder = new NestedBuilders_1.NestedConditionBuilder(fieldName);
-        return builderFn(nestedBuilder);
-    }
-    // Add an AND operator context
-    and() {
-        this.currentOperator = 'and';
-        return this;
-    }
-    // Add an OR operator context
-    or() {
-        this.currentOperator = 'or';
-        return this;
-    }
-    // Add a NOT operator context
-    not() {
-        this.currentOperator = 'not';
-        return this;
-    }
-    // Group conditions with AND logic
-    andGroup(builderFn) {
-        const nestedBuilder = new ConditionBuilder();
-        const conditions = builderFn(nestedBuilder);
-        return operators_1.LogicalOperator.And(conditions);
-    }
-    // Group conditions with OR logic
-    orGroup(builderFn) {
-        const nestedBuilder = new ConditionBuilder();
-        const conditions = builderFn(nestedBuilder);
-        return operators_1.LogicalOperator.Or(conditions);
-    }
-    // Group conditions with NOT logic
-    notGroup(builderFn) {
-        const nestedBuilder = new ConditionBuilder();
-        const conditions = builderFn(nestedBuilder);
-        return operators_1.LogicalOperator.Not(conditions);
-    }
-    // Add a condition to the current builder
-    addCondition(condition) {
-        this.conditions.push(condition);
-        return this;
-    }
-    // Build and return all conditions
-    build() {
-        return [...this.conditions];
-    }
-    // Build as a single logical operator (combines all conditions with AND by default)
-    buildSingle() {
-        if (this.conditions.length === 0) {
-            throw new Error('No conditions to build');
-        }
-        if (this.conditions.length === 1) {
-            return this.conditions[0];
-        }
-        return operators_1.LogicalOperator.And(this.conditions);
-    }
-    // Clear all conditions
-    clear() {
-        this.conditions = [];
-        this.currentOperator = undefined;
-        return this;
-    }
-    // Check if any conditions have been added
-    isEmpty() {
-        return this.conditions.length === 0;
-    }
-    // Get the number of conditions
-    getConditionCount() {
-        return this.conditions.length;
-    }
-}
-exports.ConditionBuilder = ConditionBuilder;

package/src/query-sdk/dist/FieldConditionBuilder.d.ts

@@ -1 +0,0 @@
-export { FieldConditionBuilder } from './operators';

package/src/query-sdk/dist/FieldConditionBuilder.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FieldConditionBuilder = void 0;
-// Re-export from operators for convenience
-var operators_1 = require("./operators");
-Object.defineProperty(exports, "FieldConditionBuilder", { enumerable: true, get: function () { return operators_1.FieldConditionBuilder; } });

package/src/query-sdk/dist/NestedBuilders.d.ts

@@ -1,43 +0,0 @@
-import { LogicalOperator, Condition } from './operators';
-export declare class NestedConditionBuilder {
-    private path;
-    constructor(rootField: string);
-    field(fieldName: string): NestedFieldConditionBuilder;
-    nested(fieldName: string, builderFn: (builder: NestedConditionBuilder) => LogicalOperator): LogicalOperator;
-    andGroup(builderFn: (builder: NestedConditionBuilder) => LogicalOperator[]): LogicalOperator;
-    orGroup(builderFn: (builder: NestedConditionBuilder) => LogicalOperator[]): LogicalOperator;
-    notGroup(builderFn: (builder: NestedConditionBuilder) => LogicalOperator[]): LogicalOperator;
-}
-export declare class NestedFieldConditionBuilder {
-    private fieldPath;
-    constructor(fieldPath: string[]);
-    private createCondition;
-    equals(value: any): Condition;
-    notEquals(value: any): Condition;
-    in(values: any[]): Condition;
-    notIn(values: any[]): Condition;
-    isNull(): Condition;
-    isNotNull(): Condition;
-    exists(): Condition;
-    notExists(): Condition;
-    startsWith(value: string): Condition;
-    endsWith(value: string): Condition;
-    contains(value: string): Condition;
-    regExpMatches(pattern: string): Condition;
-    includesCaseInsensitive(value: string): Condition;
-    startsWithCaseInsensitive(value: string): Condition;
-    endsWithCaseInsensitive(value: string): Condition;
-    greaterThan(value: any): Condition;
-    lessThan(value: any): Condition;
-    greaterThanOrEqual(value: any): Condition;
-    lessThanOrEqual(value: any): Condition;
-    isLocalIp(): Condition;
-    isExternalIp(): Condition;
-    b64(value: string): Condition;
-    inDataset(dataset: string): Condition;
-    inCountry(countryCode: string): Condition;
-    cidr(cidr: string): Condition;
-    between(min: any, max: any): Condition;
-    isTrue(): Condition;
-    isFalse(): Condition;
-}