@onchaindb/sdk 0.4.4 → 1.0.0

package/README.md

@@ -1,13 +1,11 @@
 # OnChainDB TypeScript SDK
 
-A TypeScript SDK for OnChainDB - the decentralized database built on Celestia blockchain with x402 payment protocol integration.
+A TypeScript SDK for OnChainDB — the decentralized database built on Celestia with x402 payment protocol integration.
 
 ## Installation
 
 ```bash
 npm install @onchaindb/sdk
-# or
-yarn add @onchaindb/sdk
 ```
 
 ## Quick Start
@@ -18,7 +16,7 @@ import { createClient } from '@onchaindb/sdk';
 const db = createClient({
   endpoint: 'https://api.onchaindb.io',
   appId: 'my_app',
-  apiKey: 'your_api_key'
+  appKey: 'your_app_key'
 });
 
 // Store data
@@ -42,20 +40,34 @@ console.log(result.records);
 
 ```typescript
 interface OnChainDBConfig {
-  endpoint: string;       // OnChainDB server endpoint
-  appId?: string;         // Application ID
-  apiKey?: string;        // API key for authentication
-  timeout?: number;       // Request timeout (default: 30000ms)
-  retryCount?: number;    // Retry attempts (default: 3)
-  retryDelay?: number;    // Retry delay (default: 1000ms)
+  endpoint: string;      // OnChainDB server endpoint
+  appId?: string;        // Application ID
+  appKey?: string;       // App key for write operations (X-App-Key header)
+  userKey?: string;      // User key for Auto-Pay (X-User-Key header)
+  agentKey?: string;     // Agent key with Pay permission (X-Agent-Key header)
+  timeout?: number;      // Request timeout in ms (default: 30000)
+  retryCount?: number;   // Retry attempts (default: 3)
+  retryDelay?: number;   // Retry delay in ms (default: 1000)
 }
 ```
 
+### Agent Keys
+
+Keys with the `Pay` permission are Agent Keys — they can pay other apps inline using USDC via EIP-3009.
+
+```typescript
+const db = createClient({
+  endpoint: 'https://api.onchaindb.io',
+  appId: 'my_app',
+  agentKey: 'agent_key_with_pay_permission'
+});
+```
+
 ## Storing Data
 
 ```typescript
 // Basic store
-const result = await db.store({
+await db.store({
   collection: 'tweets',
   data: [
     { id: 'tweet_1', content: 'Hello!', author: 'alice' },
@@ -63,24 +75,29 @@ const result = await db.store({
   ]
 });
 
-// Store with payment (x402 protocol)
-const result = await db.store(
+// Store with x402 payment callback
+await db.store(
   { collection: 'tweets', data: [{ content: 'Paid tweet' }] },
   async (quote) => {
-    // Pay via wallet (e.g., Keplr)
-    const txHash = await wallet.signAndBroadcast(
-      quote.broker_address,
-      `${quote.total_cost_utia}utia`,
-      'OnChainDB storage'
-    );
-    return { txHash, network: 'mocha-4' };
+    // quote is an X402Quote — sign and broadcast payment via your wallet
+    const txHash = await wallet.sendTransaction({
+      to: quote.payTo,
+      value: quote.maxAmountRequired
+    });
+    return {
+      txHash,
+      network: quote.network,
+      sender: wallet.address,
+      chainType: quote.chainType,
+      paymentMethod: quote.paymentMethod
+    };
   }
 );
 ```
 
 ## Query Builder
 
-The SDK provides a fluent query builder for constructing queries. For comprehensive query documentation including all operators, nested queries, and advanced patterns, see the [Query SDK Reference](./src/query-sdk/README.md).
+The SDK provides a fluent query builder for constructing queries. See the [Query SDK Reference](./src/query-sdk/README.md) for the full operator and aggregation reference.
 
 ### Basic Queries
 
@@ -92,25 +109,35 @@ const result = await db.queryBuilder()
   .limit(50)
   .execute();
 
-// Access results - records have flat structure
-result.records.forEach(user => {
-  console.log(user.name, user.email);
-});
+result.records.forEach(user => console.log(user.name, user.email));
 ```
 
-### Query Operators
+### All Field Operators
 
 ```typescript
-.equals(value)
-.notEquals(value)
-.greaterThan(value)
-.lessThan(value)
-.contains(value)
-.startsWith(value)
-.isNull()
-.isNotNull()
-.in(values)
-.notIn(values)
+// Comparison
+.equals(value)           .notEquals(value)
+.greaterThan(value)      .greaterThanOrEqual(value)
+.lessThan(value)         .lessThanOrEqual(value)
+.between(min, max)
+
+// String
+.contains(value)         .startsWith(value)        .endsWith(value)
+.regExpMatches(pattern)
+.includesCaseInsensitive(value)
+.startsWithCaseInsensitive(value)
+.endsWithCaseInsensitive(value)
+
+// Array
+.in(values)              .notIn(values)
+
+// Existence
+.exists()    .notExists()    .isNull()    .isNotNull()
+.isTrue()    .isFalse()
+
+// Network / security
+.isLocalIp()    .isExternalIp()    .inCountry(code)    .cidr(range)
+.b64(value)     .inDataset(name)
 ```
 
 ### Complex Queries with Logical Operators
@@ -122,10 +149,13 @@ const result = await db.queryBuilder()
   .collection('posts')
   .find(builder =>
     LogicalOperator.And([
-      LogicalOperator.Condition(builder.field('published').equals(true)),
+      builder.field('published').isTrue(),
       LogicalOperator.Or([
-        LogicalOperator.Condition(builder.field('category').equals('tech')),
-        LogicalOperator.Condition(builder.field('views').greaterThan(1000))
+        builder.field('category').equals('tech'),
+        builder.field('views').greaterThan(1000)
+      ]),
+      LogicalOperator.Not([
+        builder.field('archived').isTrue()
       ])
     ])
   )
@@ -134,124 +164,84 @@ const result = await db.queryBuilder()
   .execute();
 ```
 
-## Server-Side JOINs
-
-Server-side JOINs execute on the backend for optimal performance. Use `$data.fieldname` to reference parent record fields.
-
-### One-to-One JOIN (joinOne)
-
-Returns a single object or null.
+### Sorting & Pagination
 
 ```typescript
-// Get tweets with author profile
 const result = await db.queryBuilder()
-  .collection('tweets')
-  .joinOne('author_info', 'users')
-    .onField('address').equals('$data.author')
-    .selectFields(['address', 'display_name', 'avatar_url', 'verified'])
-    .build()
-  .selectAll()
+  .collection('posts')
+  .whereField('published').isTrue()
+  .orderBy('created_at', 'DESC')
   .limit(20)
+  .offset(40)
+  .selectAll()
   .execute();
-
-// Result structure:
-// {
-//   id: 'tweet_123',
-//   content: 'Hello world!',
-//   author: 'celestia1abc...',
-//   author_info: {
-//     address: 'celestia1abc...',
-//     display_name: 'Alice',
-//     avatar_url: 'https://...',
-//     verified: true
-//   }
-// }
 ```
 
-### One-to-Many JOIN (joinMany)
-
-Returns an array of related records.
+### Server-Side Aggregations
 
 ```typescript
-// Get users with their tweets
-const result = await db.queryBuilder()
+// Count
+const total = await db.queryBuilder()
   .collection('users')
-  .whereField('address').equals(userAddress)
-  .joinMany('user_tweets', 'tweets')
-    .onField('author').equals('$data.address')
-    .selectFields(['id', 'content', 'created_at'])
-    .build()
-  .selectAll()
-  .execute();
+  .whereField('active').isTrue()
+  .count();
+
+// Sum / average
+const revenue = await db.queryBuilder().collection('orders').sumBy('amount');
+const avg     = await db.queryBuilder().collection('orders').avgBy('amount');
 
-// Result structure:
-// {
-//   address: 'celestia1abc...',
-//   display_name: 'Alice',
-//   user_tweets: [
-//     { id: 'tweet_1', content: 'Hello!', created_at: '...' },
-//     { id: 'tweet_2', content: 'World!', created_at: '...' }
-//   ]
-// }
+// Group by
+const byCountry = await db.queryBuilder()
+  .collection('users')
+  .groupBy('country')
+  .count();
+// { "USA": 150, "UK": 75, ... }
 ```
 
-### Multiple JOINs
+## Server-Side JOINs
+
+JOINs execute on the backend in a single request. Use `$data.fieldname` to reference parent record fields.
+
+### joinOne (one-to-one)
 
 ```typescript
-// Timeline with likes, replies, and author info
 const result = await db.queryBuilder()
   .collection('tweets')
-  .whereField('reply_to_id').isNull()
   .joinOne('author_info', 'users')
     .onField('address').equals('$data.author')
     .selectFields(['display_name', 'avatar_url', 'verified'])
     .build()
-  .joinMany('likes', 'likes')
-    .onField('tweet_id').equals('$data.id')
-    .selectFields(['user', 'created_at'])
-    .build()
-  .joinMany('replies', 'tweets')
-    .onField('reply_to_id').equals('$data.id')
-    .selectFields(['id', 'author', 'content'])
-    .build()
   .selectAll()
-  .offset(offset)
-  .limit(limit)
+  .limit(20)
   .execute();
+
+// result.records[0].author_info => { display_name, avatar_url, verified } | null
 ```
 
-### Nested JOINs
+### joinMany (one-to-many)
 
 ```typescript
-// Get tweet with replies, each reply includes author info
 const result = await db.queryBuilder()
-  .collection('tweets')
-  .whereField('id').equals(tweetId)
-  .joinMany('replies', 'tweets')
-    .onField('reply_to_id').equals('$data.id')
-    .selectAll()
-    // Nested: get author for each reply
-    .joinOne('author_info', 'users')
-      .onField('address').equals('$data.author')
-      .selectFields(['display_name', 'avatar_url', 'verified'])
-      .build()
+  .collection('users')
+  .whereField('address').equals(userAddress)
+  .joinMany('tweets', 'tweets')
+    .onField('author').equals('$data.address')
+    .selectFields(['id', 'content', 'created_at'])
     .build()
   .selectAll()
-  .limit(1)
   .execute();
+
+// result.records[0].tweets => [{ id, content, created_at }, ...]
 ```
 
-### Self-Referential JOINs
+### Nested JOINs
 
 ```typescript
-// Get tweets with quoted tweet info
 const result = await db.queryBuilder()
   .collection('tweets')
-  .whereField('quote_tweet_id').isNotNull()
-  .joinOne('quote_tweet', 'tweets')
-    .onField('id').equals('$data.quote_tweet_id')
-    .selectFields(['id', 'content', 'author', 'created_at'])
-    // Nested: get quoted tweet's author
+  .joinMany('replies', 'tweets')
+    .onField('reply_to_id').equals('$data.id')
+    .selectAll()
     .joinOne('author_info', 'users')
       .onField('address').equals('$data.author')
       .selectFields(['display_name', 'avatar_url'])
@@ -261,299 +251,331 @@ const result = await db.queryBuilder()
   .execute();
 ```
 
-## Blob Storage
+## Collection Management
+
+### Create & Sync Collections
 
 ```typescript
-// Get pricing quote
-const quote = await db.getPricingQuote({
-  app_id: 'my_app',
-  operation_type: 'write',
-  size_kb: Math.ceil(file.size / 1024),
-  collection: 'images'
-});
+import { SimpleCollectionSchema } from '@onchaindb/sdk';
 
-const costInUtia = Math.ceil(quote.total_cost * 1_000_000);
+const schema: SimpleCollectionSchema = {
+  name: 'users',
+  fields: {
+    email:          { type: 'string', index: true },
+    age:            { type: 'number', index: true },
+    status:         { type: 'string', index: true, indexType: 'hash' },
+    bio:            { type: 'string', index: true, indexType: 'fulltext' },
+    'address.city': { type: 'string', index: true },
+  },
+  useBaseFields: true, // Auto-index id, createdAt, updatedAt, deletedAt
+};
 
-// Pay for storage
-const txHash = await wallet.signAndBroadcast(
-  brokerAddress,
-  `${costInUtia}utia`,
-  'Image upload'
-);
+// Create collection with indexes
+await db.createCollection(schema);
 
-// Upload blob
-const upload = await db.uploadBlob({
-  collection: 'images',
-  blob: file,
-  metadata: { user_address: userAddress },
-  payment_tx_hash: txHash,
-  user_address: userAddress,
-  broker_address: brokerAddress,
-  amount_utia: costInUtia
-});
+// Sync: creates new indexes, removes none (broker handles upsert)
+await db.syncCollection(schema);
+```
 
-// Wait for completion
-const task = await db.waitForTaskCompletion(upload.ticket_id);
+### Sharding
 
-if (task.status === 'Completed') {
-  console.log('Blob ID:', upload.blob_id);
-}
+Partition large collections across multiple files for massive datasets.
 
-// Retrieve blob
-const blob = await db.retrieveBlob({
-  collection: 'images',
-  blob_id: upload.blob_id
-});
-```
+```typescript
+import { SimpleCollectionSchemaWithSharding, ShardingStrategy } from '@onchaindb/sdk';
 
-## Task Tracking
+const schema: SimpleCollectionSchemaWithSharding = {
+  name: 'orderbook_snapshots',
+  fields: {
+    market:    { type: 'string', index: true },
+    timestamp: { type: 'number', index: true },
+    mid_price: { type: 'number' }
+  },
+  sharding: {
+    keys: [
+      { field: 'market',    type: 'discrete' },
+      { field: 'timestamp', type: 'time_range', granularity: 'hour' }
+    ],
+    enforce_in_queries: true
+  }
+};
 
-```typescript
-// Check task status
-const task = await db.getTaskStatus(ticket_id);
-console.log('Status:', task.status);
-// Pending, PaymentBroadcast, PaymentConfirming, Completed, Failed
-
-// Wait with polling
-const completed = await db.waitForTaskCompletion(
-  ticket_id,
-  2000,   // Poll interval (ms)
-  600000  // Max wait (ms)
-);
+// syncCollection applies sharding automatically if present
+await db.syncCollection(schema);
+
+// Or configure sharding separately
+await db.setupSharding('orderbook_snapshots', schema.sharding!);
 ```
 
-## Cost Estimation
+### Update & Delete Collections
 
 ```typescript
-const quote = await db.getPricingQuote({
-  app_id: 'my_app',
-  operation_type: 'write',
-  size_kb: 50,
-  collection: 'tweets'
+// Update collection properties
+await db.updateCollection('users', {
+  public: true,
+  description: 'User profiles',
+  default_sort_column: 'created_at',
+  collection_type: 'local' // 'local' | 'offline' | 'api' | 'hybrid'
 });
 
-console.log('Total cost:', quote.total_cost, 'TIA');
-console.log('In utia:', Math.ceil(quote.total_cost * 1_000_000));
-```
+// Delete a collection
+await db.deleteCollection('old_collection');
 
-## Collection Schema Management
+// Get collection info by ID (ID format: "{appId}_{index}", from listCollections)
+const info = await db.getCollectionInfo('myapp_0');
+// { id, name, namespace, primary_column, sort_column, status, collection_type,
+//   document_count, size_kb, created_at, last_modified }
+```
 
-Define and manage collection indexes using a schema-first approach:
+## Data Retention
 
-### Create Collection
+Configure per-collection retention policies. First 30 days are always free.
 
 ```typescript
-import { SimpleCollectionSchema } from '@onchaindb/sdk';
+// Get current retention config
+const config = await db.getRetention('orders');
+// { collection, retention_days, monthly_cost_per_kb, last_cleanup, status }
 
-const schema: SimpleCollectionSchema = {
-  name: 'users',
-  fields: {
-    email: { type: 'string', index: true },
-    age: { type: 'number', index: true },
-    status: { type: 'string', index: true, indexType: 'hash' },
-    bio: { type: 'string', index: true, indexType: 'fulltext' },
-    'address.city': { type: 'string', index: true }, // Nested field
-  },
-  useBaseFields: true, // Auto-index id, createdAt, updatedAt, deletedAt
-};
+// Set retention (null = permanent storage)
+const result = await db.setRetention('orders', { retention_days: 90 });
+// { message, config: RetentionConfig }
 
-const result = await db.createCollection(schema);
-// { collection: 'users', indexes: [...], success: true, warnings: [] }
+// Get cost estimate for all collections
+const costs = await db.getRetentionCost();
+// { app_id, collections: CollectionRetentionCost[], total_monthly_cost_tia, projected_next_month_cost_tia }
 ```
 
-### Sync Collection
+## SQL Interface
 
-Update indexes to match schema (creates new, removes old):
+Query and insert data using SQL syntax. Table references use `app::collection` format.
 
 ```typescript
-const updatedSchema: SimpleCollectionSchema = {
-  name: 'users',
-  fields: {
-    email: { type: 'string', index: true },
-    username: { type: 'string', index: true }, // New index
-    // 'age' index removed
-  },
-};
+// SQL query
+const result = await db.sql(
+  'SELECT * FROM myapp::orders WHERE amount > 100 ORDER BY created_at DESC LIMIT 50'
+);
+// { data: any[], count, query, app_id, collection }
 
-const result = await db.syncCollection(updatedSchema);
-// { collection: 'users', created: [...], removed: [...], unchanged: [...], success: true }
-```
+// SQL query with history (includes all versions of records)
+const withHistory = await db.sql(
+  'SELECT * FROM myapp::orders',
+  { includeHistory: true }
+);
 
-### Field Types & Index Types
+// SQL insert
+await db.sqlInsert(
+  "INSERT INTO myapp::orders (id, amount, status) VALUES ('ord_1', 250, 'pending')"
+);
+```
 
-| Field Type | Index Types |
-|------------|-------------|
-| `string` | `string` (default), `hash`, `fulltext` |
-| `number` | `number` (default) |
-| `boolean` | `boolean` (default) |
-| `date` | `date` (default) |
-| `object` | `string` |
-| `array` | `string` |
+## Predefined Queries
 
-### Read Pricing on Fields
+Named, parameterized queries that can be executed publicly without authentication.
 
 ```typescript
-const schema: SimpleCollectionSchema = {
-  name: 'premium_content',
-  fields: {
-    title: { type: 'string', index: true },
-    content: {
-      type: 'string',
-      index: true,
-      readPricing: {
-        pricePerAccess: 0.001, // 0.001 TIA per read
-      },
+import { CreateQueryRequest } from '@onchaindb/sdk';
+
+// Create a predefined query
+const created = await db.createQuery({
+  name: 'active_markets',
+  source_collection: 'orderbook_snapshots',
+  base_query: { find: { status: { $eq: 'active' } } },
+  parameters: [
+    {
+      name: 'market',
+      field_path: 'market',   // maps to find.market.$eq
+      required: true,
+      description: 'Market symbol (e.g. BTC, ETH)'
     },
-  },
-};
+    {
+      name: 'min_price',
+      field_path: 'price.$gte',
+      default: 0,
+      description: 'Minimum price filter'
+    }
+  ],
+  description: 'Query active orderbook snapshots by market'
+});
+
+// List all queries
+const queries = await db.listQueries();
+// QueryDefinition[]
+
+// Get a specific query definition
+const query = await db.getQuery('active_markets');
+
+// Execute a predefined query (public endpoint — no auth required)
+const data = await db.executeQuery(
+  'active_markets',
+  { market: 'BTC', min_price: '1000' }  // params as Record<string, string>
+);
+// { success, query_name, data, count, query_time_ms }
+
+// Execute a specific version
+const v2data = await db.executeQuery('active_markets', { market: 'ETH' }, 2);
+
+// Delete a query
+await db.deleteQuery('active_markets');
 ```
 
 ## Materialized Views
 
-Create pre-computed views for complex queries:
-
-### Create View
+### Create via JSON Query
 
 ```typescript
-const view = await db.createView(
-  'active_users_summary',
-  ['users', 'orders'], // Source collections
-  {
-    // Query definition
-    filter: { status: 'active' },
-    groupBy: 'region',
-    aggregate: { totalOrders: { $count: 'orders' } },
-  }
+const db_manager = db.database();
+
+await db_manager.createView(
+  'top_sellers',
+  ['products', 'orders'],
+  { find: { status: { $eq: 'completed' } }, sort_by: ['-total'], limit: 100 }
 );
 ```
 
-### List Views
+### Create via SQL
 
 ```typescript
-const views = await db.listViews();
-// [{ name: 'active_users_summary', source_collections: [...], created_at: '...' }]
+await db_manager.createViewSql(
+  'SELECT market, AVG(price) as avg_price FROM myapp::trades GROUP BY market',
+  'live' // 'live' | 'lazy'
+);
 ```
 
-### Get View Details
+### Query & Manage Views
 
 ```typescript
-const view = await db.getView('active_users_summary');
-// { name: '...', source_collections: [...], query: {...}, created_at: '...' }
+// Query view data
+const result = await db_manager.queryView<TradeStats>('top_sellers', {
+  find: { avg_price: { $gte: 1000 } },
+  sort_by: ['-avg_price'],
+  limit: 20
+});
+// { success, view_name, data: T[], count, query_time_ms }
+
+// Count records in a view
+const count = await db_manager.countView('top_sellers', { market: 'BTC' });
+
+await db_manager.listViews();
+await db_manager.getView('top_sellers');
+await db_manager.refreshView('top_sellers');
+await db_manager.deleteView('top_sellers');
 ```
 
-### Refresh View
+## API Collections
+
+Collections backed by external APIs instead of on-chain data.
 
 ```typescript
-await db.refreshView('active_users_summary');
+const db_manager = db.database();
+
+await db_manager.createApiCollection({
+  name: 'live_prices',
+  description: 'Real-time price feed from external API',
+  api_config: {
+    base_url: 'https://api.example.com',
+    authentication: { type: 'bearer', token: 'xxx' },
+    query_mapping: { path_template: '/v1/prices/{market}' },
+    response_mapping: { records_path: 'data.prices' }
+  }
+});
+
+const collections = await db_manager.listApiCollections();
+const collection  = await db_manager.getApiCollection('live_prices');
+await db_manager.deleteApiCollection('live_prices');
 ```
 
-### Delete View
+## Index Management
+
+Access the `DatabaseManager` via `db.database()` for direct index control.
 
 ```typescript
-await db.deleteView('active_users_summary');
+const dbm = db.database();
+
+// List all indexes
+const indexes = await dbm.listIndexes();
+
+// Create an index
+await dbm.createIndex({
+  name: 'users_email_idx',
+  collection: 'users',
+  field_name: 'email',
+  index_type: 'btree'
+});
+
+// Create multiple indexes at once
+await dbm.createIndexes('users', [
+  { name: 'email_idx',    field_name: 'email',    index_type: 'btree' },
+  { name: 'status_idx',   field_name: 'status',   index_type: 'hash' },
+  { name: 'bio_idx',      field_name: 'bio',      index_type: 'fulltext' },
+]);
+
+// Create a price index (enables payment splits on write)
+await dbm.createPriceIndex('orders', 'total_price', {
+  app_owner_percentage: 0.80,
+  platform_percentage: 0.20,
+  app_owner_address: 'celestia1abc...'
+});
+
+// Drop an index by ID
+await dbm.dropIndex('users_email_idx');
 ```
 
-## Real-World Example: Social App
+## Blob Storage
 
 ```typescript
-import { createClient, OnChainDBClient } from '@onchaindb/sdk';
+// Upload
+const upload = await db.uploadBlob({
+  collection: 'images',
+  blob: file,
+  metadata: { user_address: userAddress }
+});
 
-class SocialService {
-  private client: OnChainDBClient;
+// Wait for on-chain confirmation
+const task = await db.waitForTaskCompletion(upload.ticket_id);
+console.log('Blob ID:', upload.blob_id);
 
-  constructor(endpoint: string, appId: string, apiKey?: string) {
-    this.client = createClient({ endpoint, appId, apiKey });
-  }
+// Retrieve
+const blob = await db.retrieveBlob({
+  collection: 'images',
+  blob_id: upload.blob_id
+});
+```
 
-  async getTimeline(limit = 20, offset = 0) {
-    const result = await this.client.queryBuilder()
-      .collection('tweets')
-      .whereField('reply_to_id').isNull()
-      .joinOne('author_info', 'users')
-        .onField('address').equals('$data.author')
-        .selectFields(['display_name', 'avatar_url', 'verified'])
-        .build()
-      .joinMany('likes', 'likes')
-        .onField('tweet_id').equals('$data.id')
-        .selectFields(['user'])
-        .build()
-      .joinMany('replies', 'tweets')
-        .onField('reply_to_id').equals('$data.id')
-        .selectFields(['id'])
-        .build()
-      .selectAll()
-      .offset(offset)
-      .limit(limit)
-      .execute();
-
-    return result.records.map(tweet => ({
-      ...tweet,
-      like_count: tweet.likes?.length || 0,
-      reply_count: tweet.replies?.length || 0
-    }));
-  }
+## Task Tracking
 
-  async createTweet(content: string, author: string, paymentCallback: Function) {
-    const tweet = {
-      id: `tweet_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-      content,
-      author,
-      created_at: new Date().toISOString()
-    };
+```typescript
+const task = await db.getTaskStatus(ticketId);
+// status: 'Pending' | 'PaymentBroadcast' | 'PaymentConfirming' |
+//         'PaymentConfirmed' | 'StoringData' | 'Completed' | { Failed: { error } }
 
-    await this.client.store(
-      { collection: 'tweets', data: [tweet] },
-      paymentCallback
-    );
+const completed = await db.waitForTaskCompletion(ticketId, 2000, 600000);
+// Polls every 2s, times out after 600s
+```
 
-    return tweet;
-  }
+## Pricing Quotes
 
-  async getUserProfile(address: string) {
-    const result = await this.client.queryBuilder()
-      .collection('users')
-      .whereField('address').equals(address)
-      .joinMany('tweets', 'tweets')
-        .onField('author').equals('$data.address')
-        .selectAll()
-        .build()
-      .joinMany('followers', 'follows')
-        .onField('following').equals('$data.address')
-        .selectFields(['follower'])
-        .build()
-      .joinMany('following', 'follows')
-        .onField('follower').equals('$data.address')
-        .selectFields(['following'])
-        .build()
-      .selectAll()
-      .limit(1)
-      .execute();
-
-    if (!result.records.length) return null;
-
-    const user = result.records[0];
-    return {
-      ...user,
-      follower_count: user.followers?.length || 0,
-      following_count: user.following?.length || 0
-    };
-  }
-}
+```typescript
+const quote = await db.getPricingQuote({
+  app_id: 'my_app',
+  operation_type: 'write',
+  size_kb: 10,
+  collection: 'orders',
+  data: { amount: 150 } // for price index calculation
+});
+// { total_cost, total_cost_utia, indexing_costs, ... }
 ```
 
 ## Error Handling
 
 ```typescript
-import { OnChainDBError, ValidationError } from '@onchaindb/sdk';
+import { OnChainDBError, ValidationError, PaymentRequiredError } from '@onchaindb/sdk';
 
 try {
-  await db.store({ collection: 'test', data: [{ test: 'data' }] });
+  await db.store({ collection: 'test', data: [{ value: 1 }] });
 } catch (error) {
-  if (error instanceof ValidationError) {
-    console.log('Validation failed:', error.message);
-  } else if (error instanceof OnChainDBError) {
-    console.log('Error:', error.code, error.message);
-  }
+  if (error instanceof ValidationError)      console.log('Validation:', error.message);
+  if (error instanceof PaymentRequiredError) console.log('Quote:', error.quote);
+  if (error instanceof OnChainDBError)       console.log(error.code, error.message);
 }
 ```
 
@@ -563,37 +585,82 @@ try {
 
 | Method | Description |
 |--------|-------------|
-| `store(request, paymentCallback?, wait?)` | Store data |
-| `queryBuilder()` | Create query builder |
-| `uploadBlob(request)` | Upload binary file |
-| `retrieveBlob(request)` | Download binary file |
-| `getTaskStatus(ticketId)` | Get task status |
-| `waitForTaskCompletion(ticketId)` | Poll until complete |
-| `getPricingQuote(request)` | Get pricing quote |
+| `store(request, paymentCallback?)` | Store data on-chain |
+| `queryBuilder()` | Fluent query builder |
 | `createCollection(schema)` | Create collection with indexes |
-| `syncCollection(schema)` | Sync indexes to match schema |
+| `syncCollection(schema)` | Sync indexes to schema (supports sharding) |
+| `setupSharding(collection, sharding)` | Configure sharding on an existing collection |
+| `deleteCollection(collection)` | Delete a collection |
+| `updateCollection(collection, updates)` | Update collection properties |
+| `getCollectionInfo(collectionId)` | Get collection details by ID |
+| `getRetention(collection)` | Get retention config |
+| `setRetention(collection, request)` | Set retention period |
+| `getRetentionCost()` | Get retention cost estimate for all collections |
+| `sql(query, options?)` | Execute SQL query |
+| `sqlInsert(sql)` | Execute SQL insert |
+| `listQueries()` | List predefined queries |
+| `createQuery(request)` | Create a predefined query |
+| `getQuery(name)` | Get query definition |
+| `deleteQuery(name)` | Delete a predefined query |
+| `executeQuery(name, params?, version?)` | Execute a predefined query |
+| `createRelation(request)` | Create a collection relation |
+| `createIndex(request)` | Create a single index |
+| `getPricingQuote(request)` | Estimate storage cost |
+| `uploadBlob(request, paymentCallback?)` | Upload binary file |
+| `retrieveBlob(request)` | Download binary file |
+| `getTaskStatus(ticketId)` | Get async task status |
+| `waitForTaskCompletion(ticketId)` | Poll until task completes |
+| `health()` | Server health check |
+| `database(appId?)` | Access `DatabaseManager` |
+
+### DatabaseManager (`db.database()`)
+
+| Method | Description |
+|--------|-------------|
+| `listIndexes()` | List all indexes for the app |
+| `createIndex(definition)` | Create an index |
+| `createIndexes(collection, indexes)` | Bulk create indexes |
+| `createPriceIndex(collection, field, config?)` | Create payment-split price index |
+| `dropIndex(indexId)` | Delete an index by ID |
 | `createView(name, sources, query)` | Create materialized view |
+| `createViewSql(sql, refreshMode?)` | Create view from SQL |
+| `queryView(viewName, query?)` | Query view data |
+| `countView(viewName, filter?)` | Count view records |
 | `listViews()` | List all views |
-| `getView(name)` | Get view details |
+| `getView(name)` | Get view definition |
+| `refreshView(name)` | Rebuild view |
 | `deleteView(name)` | Delete a view |
-| `refreshView(name)` | Refresh view data |
-| `health()` | Health check |
+| `createApiCollection(request)` | Create API-backed collection |
+| `listApiCollections()` | List API collections |
+| `getApiCollection(name)` | Get API collection details |
+| `deleteApiCollection(name)` | Delete API collection |
 
 ### QueryBuilder
 
 | Method | Description |
 |--------|-------------|
-| `collection(name)` | Set collection |
-| `whereField(name)` | Start field condition |
-| `find(builderFn)` | Complex conditions |
+| `collection(name)` | Set target collection |
+| `whereField(name)` | Start a field condition |
+| `find(builderFn)` | Set complex logical conditions |
 | `selectFields(fields)` | Select specific fields |
 | `selectAll()` | Select all fields |
-| `joinOne(alias, model)` | One-to-one JOIN |
-| `joinMany(alias, model)` | One-to-many JOIN |
-| `limit(n)` | Limit results |
+| `joinOne(alias, model)` | One-to-one server JOIN |
+| `joinMany(alias, model)` | One-to-many server JOIN |
+| `orderBy(field, dir?)` | Sort results |
+| `limit(n)` | Limit result count |
 | `offset(n)` | Skip results |
-| `execute()` | Execute query |
+| `execute()` | Execute and return records |
+| `executeUnique()` | Return latest single record |
+| `count()` | Count matching records |
+| `sumBy(field)` | Sum numeric field |
+| `avgBy(field)` | Average numeric field |
+| `maxBy(field)` | Maximum field value |
+| `minBy(field)` | Minimum field value |
+| `distinctBy(field)` | Distinct field values |
+| `groupBy(field)` | Start grouped aggregation |
+| `buildRawQuery()` | Inspect raw query object |
+| `clone()` | Clone builder |
 
 ## License
 
-MIT License
+MIT