@wowsql/sdk 3.6.0 → 3.8.0

package/dist/index.js

@@ -100,6 +100,27 @@ class WowSQLClient {
         const response = await this.client.get('/health');
         return response.data;
     }
+    /**
+     * Get the underlying axios instance for advanced use cases
+     */
+    getHttpClient() {
+        return this.client;
+    }
+    /**
+     * Get the base URL for this client
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Close the client and clean up resources.
+     * Cancels any pending requests.
+     */
+    close() {
+        // Nothing to explicitly close with axios, but clear defaults to prevent reuse
+        this.client.defaults.baseURL = '';
+        this.client.defaults.headers.common = {};
+    }
 }
 exports.WowSQLClient = WowSQLClient;
 // ==================== Table Class ====================
@@ -148,6 +169,37 @@ class Table {
         const response = await this.client.post(`/${this.tableName}`, data);
         return response.data;
     }
+    /**
+     * Insert a new record (alias for create)
+     */
+    async insert(data) {
+        return this.create(data);
+    }
+    /**
+     * Insert multiple records at once
+     */
+    async bulkInsert(records) {
+        const promises = records.map(record => this.client.post(`/${this.tableName}`, record).then(r => r.data));
+        return Promise.all(promises);
+    }
+    /**
+     * Upsert a record — insert or update on conflict.
+     *
+     * @param data - Record data to upsert
+     * @param onConflict - Column to detect conflict on (default: 'id')
+     */
+    async upsert(data, onConflict = 'id') {
+        try {
+            return await this.create(data);
+        }
+        catch {
+            const id = data[onConflict];
+            if (id !== undefined) {
+                return await this.update(id, data);
+            }
+            throw new errors_1.WOWSQLError(`Upsert failed: no '${onConflict}' field in data for conflict resolution`);
+        }
+    }
     /**
      * Update a record by ID
      */
@@ -162,6 +214,34 @@ class Table {
         const response = await this.client.delete(`/${this.tableName}/${id}`);
         return response.data;
     }
+    // ==================== Convenience Shortcuts ====================
+    eq(column, value) {
+        return new QueryBuilder(this.client, this.tableName).eq(column, value);
+    }
+    neq(column, value) {
+        return new QueryBuilder(this.client, this.tableName).neq(column, value);
+    }
+    gt(column, value) {
+        return new QueryBuilder(this.client, this.tableName).gt(column, value);
+    }
+    gte(column, value) {
+        return new QueryBuilder(this.client, this.tableName).gte(column, value);
+    }
+    lt(column, value) {
+        return new QueryBuilder(this.client, this.tableName).lt(column, value);
+    }
+    lte(column, value) {
+        return new QueryBuilder(this.client, this.tableName).lte(column, value);
+    }
+    orderBy(column, direction) {
+        return new QueryBuilder(this.client, this.tableName).orderBy(column, direction);
+    }
+    async count() {
+        return new QueryBuilder(this.client, this.tableName).count();
+    }
+    async paginate(page = 1, perPage = 20) {
+        return new QueryBuilder(this.client, this.tableName).paginate(page, perPage);
+    }
 }
 exports.Table = Table;
 // ==================== Query Builder ====================
@@ -272,6 +352,91 @@ class QueryBuilder {
         this.options.offset = offset;
         return this;
     }
+    // ==================== Convenience Methods ====================
+    /**
+     * Filter where column equals value
+     */
+    eq(column, value) {
+        return this.filter(column, 'eq', value);
+    }
+    /**
+     * Filter where column does not equal value
+     */
+    neq(column, value) {
+        return this.filter(column, 'neq', value);
+    }
+    /**
+     * Filter where column is greater than value
+     */
+    gt(column, value) {
+        return this.filter(column, 'gt', value);
+    }
+    /**
+     * Filter where column is greater than or equal to value
+     */
+    gte(column, value) {
+        return this.filter(column, 'gte', value);
+    }
+    /**
+     * Filter where column is less than value
+     */
+    lt(column, value) {
+        return this.filter(column, 'lt', value);
+    }
+    /**
+     * Filter where column is less than or equal to value
+     */
+    lte(column, value) {
+        return this.filter(column, 'lte', value);
+    }
+    /**
+     * Filter where column matches pattern (SQL LIKE)
+     */
+    like(column, value) {
+        return this.filter(column, 'like', value);
+    }
+    /**
+     * Filter where column IS NULL
+     */
+    isNull(column) {
+        return this.filter(column, 'is', null);
+    }
+    /**
+     * Filter where column IS NOT NULL
+     */
+    isNotNull(column) {
+        return this.filter(column, 'is_not', null);
+    }
+    /**
+     * Filter where column is in list of values
+     */
+    in(column, values) {
+        return this.filter(column, 'in', values);
+    }
+    /**
+     * Filter where column is not in list of values
+     */
+    notIn(column, values) {
+        return this.filter(column, 'not_in', values);
+    }
+    /**
+     * Filter where column is between min and max values
+     */
+    between(column, minValue, maxValue) {
+        return this.filter(column, 'between', [minValue, maxValue]);
+    }
+    /**
+     * Filter where column is not between min and max values
+     */
+    notBetween(column, minValue, maxValue) {
+        return this.filter(column, 'not_between', [minValue, maxValue]);
+    }
+    /**
+     * Add an OR filter condition
+     */
+    or(column, operator, value) {
+        return this.filter(column, operator, value, 'OR');
+    }
     /**
      * Execute query - uses POST /{table}/query for advanced features, GET for simple queries
      */
@@ -366,6 +531,12 @@ class QueryBuilder {
             return response.data;
         }
     }
+    /**
+     * Execute the query (alias for get)
+     */
+    async execute(additionalOptions) {
+        return this.get(additionalOptions);
+    }
     /**
      * Get first record
      */
@@ -373,6 +544,94 @@ class QueryBuilder {
         const result = await this.limit(1).get();
         return result.data[0] || null;
     }
+    /**
+     * Get exactly one record. Throws if zero or multiple results.
+     */
+    async single() {
+        const result = await this.limit(2).get();
+        if (result.data.length === 0) {
+            throw new errors_1.WOWSQLError('No records found', 404);
+        }
+        if (result.data.length > 1) {
+            throw new errors_1.WOWSQLError('Multiple records found when expecting single result', 400);
+        }
+        return result.data[0];
+    }
+    /**
+     * Get record count matching current filters (uses COUNT(*) aggregate).
+     */
+    async count() {
+        const saved = { ...this.options };
+        this.options.select = ['COUNT(*) as count'];
+        this.options.group_by = undefined;
+        this.options.having = undefined;
+        this.options.order = undefined;
+        this.options.limit = undefined;
+        this.options.offset = undefined;
+        try {
+            const result = await this.get();
+            return result.data[0]?.count ?? 0;
+        }
+        finally {
+            this.options = saved;
+        }
+    }
+    /**
+     * Get sum of a column matching current filters.
+     */
+    async sum(column) {
+        const saved = { ...this.options };
+        this.options.select = [`SUM("${column}") as total`];
+        this.options.group_by = undefined;
+        this.options.having = undefined;
+        this.options.order = undefined;
+        this.options.limit = undefined;
+        this.options.offset = undefined;
+        try {
+            const result = await this.get();
+            return result.data[0]?.total ?? 0;
+        }
+        finally {
+            this.options = saved;
+        }
+    }
+    /**
+     * Get average of a column matching current filters.
+     */
+    async avg(column) {
+        const saved = { ...this.options };
+        this.options.select = [`AVG("${column}") as average`];
+        this.options.group_by = undefined;
+        this.options.having = undefined;
+        this.options.order = undefined;
+        this.options.limit = undefined;
+        this.options.offset = undefined;
+        try {
+            const result = await this.get();
+            return result.data[0]?.average ?? 0;
+        }
+        finally {
+            this.options = saved;
+        }
+    }
+    /**
+     * Paginate results. Returns data along with pagination metadata.
+     */
+    async paginate(page = 1, perPage = 20) {
+        this.options.limit = perPage;
+        this.options.offset = (page - 1) * perPage;
+        const result = await this.get();
+        const totalPages = Math.ceil(result.total / perPage);
+        return {
+            data: result.data,
+            page,
+            perPage,
+            total: result.total,
+            totalPages,
+            hasNext: page < totalPages,
+            hasPrev: page > 1,
+        };
+    }
 }
 exports.QueryBuilder = QueryBuilder;
 // ==================== Exports ====================

package/dist/schema.d.ts

@@ -1,9 +1,15 @@
 /**
- * Schema management client for WowSQL.
- * Requires SERVICE ROLE key.
+ * WowSQL Schema SDK - DDL operations for PostgreSQL.
+ * Requires a SERVICE ROLE key (wowsql_service_...).
+ *
+ * @version 3.0.0
+ * @license MIT
  */
+import { SchemaPermissionError } from './errors';
+export { SchemaPermissionError };
 export interface ColumnDefinition {
     name: string;
+    /** PostgreSQL type: SERIAL, BIGSERIAL, VARCHAR(n), TEXT, INT, BIGINT, BOOLEAN, TIMESTAMPTZ, UUID, JSONB, etc. */
     type: string;
     auto_increment?: boolean;
     unique?: boolean;
@@ -25,34 +31,180 @@ export interface AlterTableOptions {
     nullable?: boolean;
     default?: string;
 }
+export interface SchemaConfig {
+    /** Project subdomain or full URL (e.g., 'myproject' or 'https://myproject.wowsql.com') */
+    projectUrl: string;
+    /** SERVICE ROLE key (wowsql_service_...) — NOT an anonymous key */
+    serviceKey: string;
+    /** Base domain (default: wowsql.com) */
+    baseDomain?: string;
+    /** Use HTTPS (default: true) */
+    secure?: boolean;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Verify SSL certificates (default: true). Set to false for self-signed certs in dev. */
+    verifySsl?: boolean;
+}
+export interface TableSchema {
+    table: string;
+    columns: SchemaColumnInfo[];
+    primary_key: string | null;
+}
+export interface SchemaColumnInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+    key: string;
+    default: any;
+    extra: string;
+}
 export declare class WowSQLSchema {
+    private client;
     private baseUrl;
-    private serviceKey;
     /**
      * Initialize schema client.
      *
-     * ⚠️ IMPORTANT: Requires SERVICE ROLE key, not anonymous key!
+     * Requires a SERVICE ROLE key. Anonymous keys cannot perform DDL operations.
+     *
+     * @example
+     * ```typescript
+     * const schema = new WowSQLSchema({
+     *   projectUrl: 'myproject',
+     *   serviceKey: 'wowsql_service_...'
+     * });
      *
-     * @param projectUrl - Project URL (e.g., "https://myproject.wowsql.com")
-     * @param serviceKey - SERVICE ROLE key (not anonymous key!)
+     * await schema.createTable({
+     *   tableName: 'products',
+     *   columns: [
+     *     { name: 'id', type: 'SERIAL', auto_increment: true },
+     *     { name: 'name', type: 'VARCHAR(255)', nullable: false },
+     *     { name: 'price', type: 'NUMERIC(10,2)', default: '0' },
+     *     { name: 'tags', type: 'TEXT[]' },
+     *     { name: 'metadata', type: 'JSONB', default: "'{}'" },
+     *     { name: 'created_at', type: 'TIMESTAMPTZ', default: 'CURRENT_TIMESTAMP' }
+     *   ],
+     *   primaryKey: 'id',
+     *   indexes: ['name']
+     * });
+     * ```
      */
-    constructor(projectUrl: string, serviceKey: string);
+    constructor(config: SchemaConfig | string, serviceKey?: string);
     /**
-     * Create a new table.
+     * Create a new table with PostgreSQL column types.
+     *
+     * Supported PostgreSQL types: SERIAL, BIGSERIAL, VARCHAR(n), TEXT, INT, BIGINT,
+     * BOOLEAN, NUMERIC(p,s), REAL, DOUBLE PRECISION, TIMESTAMPTZ, DATE, TIME,
+     * UUID, JSONB, TEXT[], INT[], BYTEA, etc.
      */
-    createTable(options: CreateTableOptions): Promise<any>;
+    createTable(options: CreateTableOptions): Promise<{
+        success: boolean;
+        message: string;
+        table: string;
+        already_exists?: boolean;
+    }>;
     /**
      * Alter an existing table.
+     *
+     * Operations:
+     * - `add_column`: Add a new column
+     * - `drop_column`: Remove a column
+     * - `modify_column`: Change column type/constraints (PostgreSQL ALTER COLUMN ... TYPE)
+     * - `rename_column`: Rename a column
      */
-    alterTable(options: AlterTableOptions): Promise<any>;
+    alterTable(options: AlterTableOptions): Promise<{
+        success: boolean;
+        message: string;
+        operation: string;
+    }>;
     /**
      * Drop a table.
      *
-     * ⚠️ WARNING: This operation cannot be undone!
+     * WARNING: This operation cannot be undone!
+     *
+     * @param tableName - Table to drop
+     * @param cascade - If true, also drops dependent objects (foreign keys, views, etc.)
      */
-    dropTable(tableName: string, cascade?: boolean): Promise<any>;
+    dropTable(tableName: string, cascade?: boolean): Promise<{
+        success: boolean;
+        message: string;
+        warning: string;
+    }>;
     /**
      * Execute raw SQL for schema operations.
+     *
+     * Only DDL statements are allowed: CREATE TABLE, ALTER TABLE, DROP TABLE,
+     * CREATE INDEX, DROP INDEX, CREATE EXTENSION, CREATE TYPE, ALTER TYPE,
+     * CREATE SEQUENCE, ALTER SEQUENCE, DROP SEQUENCE.
+     *
+     * @param sql - SQL DDL statement
+     */
+    executeSQL(sql: string): Promise<{
+        success: boolean;
+        message: string;
+        rows_affected: number;
+    }>;
+    /**
+     * Add a column to an existing table.
+     */
+    addColumn(tableName: string, columnName: string, columnType: string, options?: {
+        nullable?: boolean;
+        default?: string;
+    }): Promise<{
+        success: boolean;
+        message: string;
+        operation: string;
+    }>;
+    /**
+     * Drop a column from a table.
+     */
+    dropColumn(tableName: string, columnName: string): Promise<{
+        success: boolean;
+        message: string;
+        operation: string;
+    }>;
+    /**
+     * Rename a column in a table.
+     */
+    renameColumn(tableName: string, oldName: string, newName: string): Promise<{
+        success: boolean;
+        message: string;
+        operation: string;
+    }>;
+    /**
+     * Modify a column's type or constraints.
+     */
+    modifyColumn(tableName: string, columnName: string, columnType: string, options?: {
+        nullable?: boolean;
+        default?: string;
+    }): Promise<{
+        success: boolean;
+        message: string;
+        operation: string;
+    }>;
+    /**
+     * Create an index using raw SQL.
+     *
+     * @param tableName - Table to index
+     * @param columnNames - Column(s) to include in the index
+     * @param options - Index options
+     */
+    createIndex(tableName: string, columnNames: string | string[], options?: {
+        unique?: boolean;
+        name?: string;
+        using?: 'btree' | 'hash' | 'gin' | 'gist';
+    }): Promise<{
+        success: boolean;
+        message: string;
+        rows_affected: number;
+    }>;
+    /**
+     * List all tables in the database.
+     * Uses the v2 tables endpoint (GET /api/v2/tables).
+     */
+    listTables(): Promise<string[]>;
+    /**
+     * Get the schema for a specific table.
+     * Uses the v2 tables endpoint (GET /api/v2/tables/{name}/schema).
      */
-    executeSQL(sql: string): Promise<any>;
+    getTableSchema(tableName: string): Promise<TableSchema>;
 }