Smart Tables SDK

npm install @odin-ai-staging/sdk

import { SmartTablesSDK } from '@odin-ai-staging/sdk';

// Initialize the SDK
const smartTablesSDK = new SmartTablesSDK({
  baseUrl: 'https://your-api-endpoint.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// Quick example: Create table and add data
async function quickExample() {
  // Create a new table
  const table = await smartTablesSDK.createTable(
    'Customer Database',
    'Manage customer information'
  );
  
  // Add columns
  await smartTablesSDK.addColumn(table.id, {
    name: 'name',
    type: 'text',
    description: 'Customer name'
  });
  
  await smartTablesSDK.addColumn(table.id, {
    name: 'email',
    type: 'email',
    description: 'Customer email address'
  });
  
  // Add data
  await smartTablesSDK.addRow(table.id, {
    name: 'John Doe',
    email: 'john@example.com'
  });
  
  // Query data
  const results = await smartTablesSDK.queryTable(table.id, {
    filters: [{ column: 'name', operator: 'contains', value: 'John' }],
    pagination: { limit: 10, page: 1 }
  });
  
  console.log('Query results:', results.data);
}

interface SmartTablesSDKConfig {
  baseUrl: string;          // API endpoint URL
  projectId: string;        // Your project identifier
  apiKey?: string;          // API key for authentication
  apiSecret?: string;       // API secret for authentication
  accessToken?: string;     // Access token for web app usage
}

interface SmartTable {
  id: string;                    // Unique table identifier
  project_id: string;            // Project this table belongs to
  title: string;                 // Display name of the table
  description: string;           // Table description
  schema: SmartTableColumn[];    // Column definitions
  table_name: string;           // Internal table name
  created_at?: number;          // Creation timestamp
  updated_at?: number;          // Last update timestamp
}

interface SmartTableColumn {
  name: string;                           // Column name
  type: ColumnType;                       // Data type
  description?: string;                   // Column description
  notNull?: boolean;                      // Required field
  unique?: boolean;                       // Unique constraint
  defaultValue?: string | number | boolean | null;  // Default value
  options?: Record<string, unknown>;      // Additional options
}

type ColumnType = 'text' | 'number' | 'boolean' | 'date' | 'email' | 'url' | 'json';

interface TableFilter {
  column: string;
  operator: FilterOperator;
  value: string | number | boolean | null;
}

type FilterOperator = 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'startswith' | 'endswith';

interface TableSort {
  column: string;
  direction: 'asc' | 'desc';
}

interface TablePagination {
  page?: number;
  limit?: number;
  search?: string;
}

async getAllTables(): Promise<SmartTable[]>

const tables = await smartTablesSDK.getAllTables();
tables.forEach(table => {
  console.log(`Table: ${table.title} (${table.id})`);
  console.log(`Columns: ${table.schema.length}`);
});

async getTable(tableId: string): Promise<SmartTable>

const table = await smartTablesSDK.getTable('table_123');
console.log('Table schema:', table.schema);

async createTable(
  title: string,
  description: string,
  metadata?: Record<string, unknown>
): Promise<SmartTable>

const table = await smartTablesSDK.createTable(
  'Product Catalog',
  'Manage product information and inventory',
  { category: 'inventory', owner: 'admin' }
);

async updateTable(
  tableId: string,
  title: string,
  description?: string,
  metadata?: Record<string, unknown>
): Promise<void>

await smartTablesSDK.updateTable(
  'table_123',
  'Updated Product Catalog',
  'Enhanced product management system',
  { version: '2.0' }
);

async deleteTable(tableId: string): Promise<void>

await smartTablesSDK.deleteTable('table_123');

async addColumn(tableId: string, column: SmartTableColumn): Promise<void>

// Add a text column
await smartTablesSDK.addColumn('table_123', {
  name: 'product_name',
  type: 'text',
  description: 'Name of the product',
  notNull: true
});

// Add a number column with default value
await smartTablesSDK.addColumn('table_123', {
  name: 'price',
  type: 'number',
  description: 'Product price in USD',
  defaultValue: 0,
  notNull: true
});

// Add an email column with validation
await smartTablesSDK.addColumn('table_123', {
  name: 'supplier_email',
  type: 'email',
  description: 'Supplier contact email',
  unique: true
});

async updateColumn(
  tableId: string,
  columnName: string,
  updates: Partial<SmartTableColumn>
): Promise<void>

await smartTablesSDK.updateColumn('table_123', 'product_name', {
  description: 'Updated product name field',
  notNull: true,
  unique: true
});

async deleteColumn(tableId: string, columnName: string): Promise<void>

await smartTablesSDK.deleteColumn('table_123', 'obsolete_column');

async addRow(tableId: string, data: Record<string, any>): Promise<any>

const newRow = await smartTablesSDK.addRow('table_123', {
  product_name: 'Wireless Headphones',
  price: 99.99,
  supplier_email: 'supplier@example.com',
  in_stock: true
});

console.log('New row ID:', newRow.id);

async updateRow(
  tableId: string,
  rowId: string,
  columnName: string,
  newValue: any
): Promise<void>

// Update product price
await smartTablesSDK.updateRow(
  'table_123',
  'row_456',
  'price',
  89.99
);

// Update stock status
await smartTablesSDK.updateRow(
  'table_123',
  'row_456',
  'in_stock',
  false
);

async deleteRow(tableId: string, rowId: string): Promise<void>

await smartTablesSDK.deleteRow('table_123', 'row_456');

async queryTable(
  tableId: string,
  options?: TableQueryOptions
): Promise<TableQueryResponse>

interface TableQueryOptions {
  filters?: TableFilter[];      // Filter conditions
  sort?: TableSort[];          // Sort configurations
  pagination?: TablePagination; // Pagination settings
}

const results = await smartTablesSDK.queryTable('table_123');
console.log('All data:', results.data);

const results = await smartTablesSDK.queryTable('table_123', {
  filters: [
    { column: 'price', operator: 'gte', value: 50 },
    { column: 'in_stock', operator: 'eq', value: true },
    { column: 'product_name', operator: 'contains', value: 'headphones' }
  ]
});

const results = await smartTablesSDK.queryTable('table_123', {
  sort: [
    { column: 'price', direction: 'desc' },
    { column: 'product_name', direction: 'asc' }
  ],
  pagination: {
    page: 2,
    limit: 20,
    search: 'wireless'
  }
});

console.log(`Found ${results.total} items`);
console.log(`Page ${results.page} of ${Math.ceil(results.total / results.limit)}`);

async importTable(
  title: string,
  description: string,
  columnMappings: ColumnMapping[],
  file: File
): Promise<ImportResult>

interface ColumnMapping {
  sourceColumn: string;     // Column name in source file
  targetColumn: string;     // Column name in target table
  dataType: string;         // Target data type
}

const fileInput = document.getElementById('csvFile') as HTMLInputElement;
const file = fileInput.files[0];

const columnMappings: ColumnMapping[] = [
  { sourceColumn: 'Name', targetColumn: 'product_name', dataType: 'text' },
  { sourceColumn: 'Price', targetColumn: 'price', dataType: 'number' },
  { sourceColumn: 'Email', targetColumn: 'supplier_email', dataType: 'email' }
];

const result = await smartTablesSDK.importTable(
  'Imported Products',
  'Products imported from CSV',
  columnMappings,
  file
);

console.log(`Imported ${result.rows_imported} rows`);
console.log(`Table ID: ${result.data_type_id}`);

async computeRowColumns(
  dataTypeId: string,
  rowId: string,
  columnNames?: string[]
): Promise<void>

// Compute specific columns for a row
await smartTablesSDK.computeRowColumns(
  'table_123',
  'row_456',
  ['ai_summary', 'sentiment_score']
);

async computeAllRows(dataTypeId: string): Promise<{
  message: string;
  total_rows_processed: number;
  total_columns_updated: number;
  updated_columns: string[];
  failed_rows: number[];
  stopped_due_to_failures: boolean;
  retry_attempts: Record<number, number>;
  computation_id?: string;
  history_table?: string;
}>

const result = await smartTablesSDK.computeAllRows('table_123');
console.log(`Processed ${result.total_rows_processed} rows`);
console.log(`Updated ${result.total_columns_updated} columns`);
console.log(`Updated columns: ${result.updated_columns.join(', ')}`);

if (result.failed_rows.length > 0) {
  console.log(`Failed rows: ${result.failed_rows.join(', ')}`);
}

try {
  const table = await smartTablesSDK.createTable('My Table', 'Description');
} catch (error) {
  if (error instanceof APIError) {
    console.error(`API Error ${error.status}: ${error.message}`);
    if (error.detail) {
      console.error('Details:', error.detail);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

import { SmartTablesSDK } from '@odin-ai-staging/sdk';

class ProductManager {
  private sdk: SmartTablesSDK;
  private tableId?: string;

  constructor() {
    this.sdk = new SmartTablesSDK({
      baseUrl: process.env.API_BASE_URL,
      projectId: process.env.PROJECT_ID,
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET
    });
  }

  async initializeTable() {
    try {
      // Create table
      const table = await this.sdk.createTable(
        'Product Catalog',
        'Manage product inventory and information'
      );
      this.tableId = table.id;

      // Add columns
      await this.addColumns();
      
      console.log('Table initialized:', this.tableId);
      return table;
    } catch (error) {
      console.error('Failed to initialize table:', error);
      throw error;
    }
  }

  private async addColumns() {
    const columns = [
      { name: 'name', type: 'text', description: 'Product name', notNull: true },
      { name: 'description', type: 'text', description: 'Product description' },
      { name: 'price', type: 'number', description: 'Price in USD', notNull: true },
      { name: 'category', type: 'text', description: 'Product category' },
      { name: 'in_stock', type: 'boolean', description: 'Stock availability', defaultValue: true },
      { name: 'supplier_email', type: 'email', description: 'Supplier contact' },
      { name: 'website', type: 'url', description: 'Product website' },
      { name: 'created_at', type: 'date', description: 'Creation date' }
    ];

    for (const column of columns) {
      await this.sdk.addColumn(this.tableId!, column);
    }
  }

  async addProduct(productData: any) {
    if (!this.tableId) throw new Error('Table not initialized');
    
    try {
      const result = await this.sdk.addRow(this.tableId, {
        ...productData,
        created_at: new Date().toISOString()
      });
      
      console.log('Product added:', result);
      return result;
    } catch (error) {
      console.error('Failed to add product:', error);
      throw error;
    }
  }

  async searchProducts(searchTerm: string, category?: string, minPrice?: number, maxPrice?: number) {
    if (!this.tableId) throw new Error('Table not initialized');

    const filters = [];
    
    if (category) {
      filters.push({ column: 'category', operator: 'eq', value: category });
    }
    
    if (minPrice !== undefined) {
      filters.push({ column: 'price', operator: 'gte', value: minPrice });
    }
    
    if (maxPrice !== undefined) {
      filters.push({ column: 'price', operator: 'lte', value: maxPrice });
    }

    try {
      const results = await this.sdk.queryTable(this.tableId, {
        filters,
        pagination: {
          search: searchTerm,
          limit: 50
        },
        sort: [
          { column: 'name', direction: 'asc' }
        ]
      });

      return results;
    } catch (error) {
      console.error('Search failed:', error);
      throw error;
    }
  }
}

// Usage
const productManager = new ProductManager();
await productManager.initializeTable();
await productManager.addProduct({
  name: 'Wireless Headphones',
  price: 199.99,
  category: 'Electronics'
});

// Good: Efficient query with filters and pagination
const results = await smartTablesSDK.queryTable(tableId, {
  filters: [{ column: 'status', operator: 'eq', value: 'active' }],
  pagination: { limit: 50, page: 1 },
  sort: [{ column: 'created_at', direction: 'desc' }]
});

// Bad: Fetching all data without filters
const allResults = await smartTablesSDK.queryTable(tableId);

// Good: Well-defined column schema
await smartTablesSDK.addColumn(tableId, {
  name: 'email',
  type: 'email',
  description: 'Customer email address',
  notNull: true,
  unique: true
});

// Bad: Vague column definition
await smartTablesSDK.addColumn(tableId, {
  name: 'data',
  type: 'text'
});

async function safeTableOperation(tableId: string, data: any) {
  try {
    // Validate data first
    if (!data.email || !data.email.includes('@')) {
      throw new Error('Invalid email format');
    }
    
    // Perform operation
    const result = await smartTablesSDK.addRow(tableId, data);
    return result;
  } catch (error) {
    console.error('Operation failed:', error);
    // Handle specific error types
    if (error.message.includes('unique constraint')) {
      throw new Error('Email already exists');
    }
    throw error;
  }
}