@wowsql/sdk 3.4.0 → 3.6.0

package/README.md

@@ -58,7 +58,7 @@ import { ProjectAuthClient } from '@wowsql/sdk';
 
 const auth = new ProjectAuthClient({
   projectUrl: 'myproject',        // or https://myproject.wowsql.com
-  publicApiKey: 'public-auth-key'
+  apiKey: 'your-anon-key'  // Use anon key for client-side, service key for server-side
 });
 ```
 
@@ -312,6 +312,138 @@ console.log(result.affected_rows); // Number of rows deleted
 
 // Is null
 .filter({ column: 'deleted_at', operator: 'is', value: null })
+
+// IN operator (value must be an array)
+.filter('category', 'in', ['electronics', 'books', 'clothing'])
+
+// NOT IN operator
+.filter('status', 'not_in', ['deleted', 'archived'])
+
+// BETWEEN operator (value must be an array of 2 values)
+.filter('price', 'between', [10, 100])
+
+// NOT BETWEEN operator
+.filter('age', 'not_between', [18, 65])
+
+// OR logical operator
+.filter('category', 'eq', 'electronics', 'AND')
+.filter('price', 'gt', 1000, 'OR')  // OR condition
+```
+
+## Advanced Query Features
+
+### GROUP BY and Aggregates
+
+GROUP BY supports both simple column names and SQL expressions with functions. All expressions are validated for security.
+
+#### Basic GROUP BY
+
+```typescript
+// Group by single column
+const result = await client.table("products")
+  .select("category", "COUNT(*) as count", "AVG(price) as avg_price")
+  .groupBy("category")
+  .get();
+
+// Group by multiple columns
+const result = await client.table("sales")
+  .select("region", "category", "SUM(amount) as total")
+  .groupBy(["region", "category"])
+  .get();
+```
+
+#### GROUP BY with Date/Time Functions
+
+```typescript
+// Group by date
+const result = await client.table("orders")
+  .select("DATE(created_at) as date", "COUNT(*) as orders", "SUM(total) as revenue")
+  .groupBy("DATE(created_at)")
+  .orderBy("date", "desc")
+  .get();
+
+// Group by year and month
+const result = await client.table("orders")
+  .select("YEAR(created_at) as year", "MONTH(created_at) as month", "SUM(total) as revenue")
+  .groupBy(["YEAR(created_at)", "MONTH(created_at)"])
+  .get();
+
+// Group by week
+const result = await client.table("orders")
+  .select("WEEK(created_at) as week", "COUNT(*) as orders")
+  .groupBy("WEEK(created_at)")
+  .get();
+```
+
+#### Supported Functions in GROUP BY
+
+**Date/Time:** `DATE()`, `YEAR()`, `MONTH()`, `DAY()`, `WEEK()`, `QUARTER()`, `HOUR()`, `MINUTE()`, `SECOND()`, `DATE_FORMAT()`, `DATE_ADD()`, `DATE_SUB()`, `DATEDIFF()`, `NOW()`, `CURRENT_TIMESTAMP()`, etc.
+
+**String:** `CONCAT()`, `SUBSTRING()`, `LEFT()`, `RIGHT()`, `UPPER()`, `LOWER()`, `LENGTH()`, `TRIM()`, etc.
+
+**Mathematical:** `ROUND()`, `CEIL()`, `FLOOR()`, `ABS()`, `POW()`, `SQRT()`, `MOD()`, etc.
+
+### HAVING Clause
+
+HAVING filters aggregated results after GROUP BY. Supports aggregate functions and comparison operators.
+
+```typescript
+// Filter aggregated results
+const result = await client.table("products")
+  .select("category", "COUNT(*) as count")
+  .groupBy("category")
+  .having("COUNT(*)", "gt", 10)
+  .get();
+
+// Multiple HAVING conditions
+const result = await client.table("orders")
+  .select("DATE(created_at) as date", "SUM(total) as revenue")
+  .groupBy("DATE(created_at)")
+  .having("SUM(total)", "gt", 1000)
+  .having("COUNT(*)", "gte", 5)
+  .get();
+
+// HAVING with different aggregate functions
+const result = await client.table("products")
+  .select("category", "AVG(price) as avg_price", "COUNT(*) as count")
+  .groupBy("category")
+  .having("AVG(price)", "gt", 100)
+  .having("COUNT(*)", "gte", 5)
+  .get();
+```
+
+**Supported HAVING Operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
+
+**Supported Aggregate Functions:** `COUNT(*)`, `SUM()`, `AVG()`, `MAX()`, `MIN()`, `GROUP_CONCAT()`, `STDDEV()`, `VARIANCE()`
+
+### Multiple ORDER BY
+
+```typescript
+// Order by multiple columns
+const result = await client.table("products")
+  .select("*")
+  .orderByMultiple([
+    { column: "category", direction: "asc" },
+    { column: "price", direction: "desc" },
+    { column: "created_at", direction: "desc" }
+  ])
+  .get();
+```
+
+### Date/Time Functions
+
+```typescript
+// Filter by date range using functions
+const result = await client.table("orders")
+  .select("*")
+  .filter("created_at", "gte", "DATE_SUB(NOW(), INTERVAL 7 DAY)")
+  .get();
+
+// Group by date
+const result = await client.table("orders")
+  .select("DATE(created_at) as date", "COUNT(*) as count")
+  .groupBy("DATE(created_at)")
+  .get();
 ```
 
 ### Complex Queries
@@ -646,30 +778,34 @@ WOWSQL uses **different API keys for different operations**. Understanding which
 
 ### Key Types Overview
 
+## 🔑 Unified Authentication
+
+**✨ One Project = One Set of Keys for ALL Operations**
+
+WOWSQL uses **unified authentication** - the same API keys work for both database operations AND authentication operations.
+
 | Operation Type | Recommended Key | Alternative Key | Used By |
 |---------------|----------------|-----------------|---------|
-| **Database Operations** (CRUD) | Service Role Key (`wowbase_service_...`) | Anonymous Key (`wowbase_anon_...`) | `WOWSQLClient` |
-| **Authentication Operations** (OAuth, sign-in) | Public API Key (`wowbase_auth_...`) | Service Role Key (`wowbase_service_...`) | `ProjectAuthClient` |
+| **Database Operations** (CRUD) | Service Role Key (`wowsql_service_...`) | Anonymous Key (`wowsql_anon_...`) | `WOWSQLClient` |
+| **Authentication Operations** (OAuth, sign-in) | Anonymous Key (`wowsql_anon_...`) | Service Role Key (`wowsql_service_...`) | `ProjectAuthClient` |
 
 ### Where to Find Your Keys
 
-All keys are found in: **WOWSQL Dashboard → Authentication → PROJECT KEYS**
-
-1. **Service Role Key** (`wowbase_service_...`)
-   - Location: "Service Role Key (keep secret)"
-   - Used for: Database CRUD operations (recommended for server-side)
-   - Can also be used for authentication operations (fallback)
-   - **Important**: Click the eye icon to reveal this key
+All keys are found in: **WOWSQL Dashboard → Settings → API Keys** or **Authentication → PROJECT KEYS**
 
-2. **Public API Key** (`wowbase_auth_...`)
-   - Location: "Public API Key"
-   - Used for: OAuth, sign-in, sign-up, user management
-   - Recommended for client-side/public authentication flows
+1. **Anonymous Key** (`wowsql_anon_...`) ✨ **Unified Key**
+   - Location: "Anonymous Key (Public)"
+   - Used for: 
+     - ✅ Client-side auth operations (signup, login, OAuth)
+     - ✅ Public/client-side database operations with limited permissions
+   - **Safe to expose** in frontend code (browser, mobile apps)
 
-3. **Anonymous Key** (`wowbase_anon_...`)
-   - Location: "Anonymous Key"
-   - Used for: Public/client-side database operations with limited permissions
-   - Optional: Use when exposing database access to frontend/client
+2. **Service Role Key** (`wowsql_service_...`) ✨ **Unified Key**
+   - Location: "Service Role Key (keep secret)"
+   - Used for:
+     - ✅ Server-side auth operations (admin, full access)
+     - ✅ Server-side database operations (full access, bypass RLS)
+   - **NEVER expose** in frontend code - server-side only!
 
 ### Database Operations
 
@@ -681,13 +817,13 @@ import WOWSQLClient from '@wowsql/sdk';
 // Using Service Role Key (recommended for server-side, full access)
 const client = new WOWSQLClient({
   projectUrl: 'myproject',
-  apiKey: 'wowbase_service_your-service-key-here'  // Service Role Key
+  apiKey: 'wowsql_service_your-service-key-here'  // Service Role Key
 });
 
 // Using Anonymous Key (for public/client-side access with limited permissions)
 const client = new WOWSQLClient({
   projectUrl: 'myproject',
-  apiKey: 'wowbase_anon_your-anon-key-here'  // Anonymous Key
+  apiKey: 'wowsql_anon_your-anon-key-here'  // Anonymous Key
 });
 
 // Query data
@@ -696,21 +832,21 @@ const users = await client.table('users').get();
 
 ### Authentication Operations
 
-Use **Public API Key** or **Service Role Key** for authentication:
+**✨ UNIFIED AUTHENTICATION:** Use the **same keys** as database operations!
 
 ```typescript
 import { ProjectAuthClient } from '@wowsql/sdk';
 
-// Using Public API Key (recommended for OAuth, sign-in, sign-up)
+// Using Anonymous Key (recommended for client-side auth operations)
 const auth = new ProjectAuthClient({
   projectUrl: 'myproject',
-  publicApiKey: 'wowbase_auth_your-public-key-here'  // Public API Key
+  apiKey: 'wowsql_anon_your-anon-key-here'  // Same key as database operations!
 });
 
-// Using Service Role Key (can be used for auth operations too)
+// Using Service Role Key (for server-side auth operations)
 const auth = new ProjectAuthClient({
   projectUrl: 'myproject',
-  publicApiKey: 'wowbase_service_your-service-key-here'  // Service Role Key
+  apiKey: 'wowsql_service_your-service-key-here'  // Same key as database operations!
 });
 
 // OAuth authentication
@@ -720,36 +856,42 @@ const { authorizationUrl } = await auth.getOAuthAuthorizationUrl(
 );
 ```
 
+**Note:** The `publicApiKey` parameter is deprecated but still works for backward compatibility. Use `apiKey` instead.
+
 ### Environment Variables
 
 Best practice: Use environment variables for API keys:
 
 ```typescript
+// UNIFIED AUTHENTICATION: Same keys for both operations!
+
 // Database operations - Service Role Key
 const dbClient = new WOWSQLClient({
   projectUrl: process.env.WOWSQL_PROJECT_URL!,
   apiKey: process.env.WOWSQL_SERVICE_ROLE_KEY!  // or WOWSQL_ANON_KEY
 });
 
-// Authentication operations - Public API Key
+// Authentication operations - Use the SAME key!
 const authClient = new ProjectAuthClient({
   projectUrl: process.env.WOWSQL_PROJECT_URL!,
-  publicApiKey: process.env.WOWSQL_PUBLIC_API_KEY!
+  apiKey: process.env.WOWSQL_ANON_KEY!  // Same key for client-side auth
+  // Or use WOWSQL_SERVICE_ROLE_KEY for server-side auth
 });
 ```
 
 ### Key Usage Summary
 
+**✨ UNIFIED AUTHENTICATION:**
 - **`WOWSQLClient`** → Uses **Service Role Key** or **Anonymous Key** for database operations
-- **`ProjectAuthClient`** → Uses **Public API Key** or **Service Role Key** for authentication operations
-- **Service Role Key** can be used for both database AND authentication operations
-- **Public API Key** is specifically for authentication operations only
-- **Anonymous Key** is optional and provides limited permissions for public database access
+- **`ProjectAuthClient`** → Uses **Anonymous Key** (client-side) or **Service Role Key** (server-side) for authentication operations
+- **Same keys work for both** database AND authentication operations! 🎉
+- **Anonymous Key** (`wowsql_anon_...`) → Client-side operations (auth + database)
+- **Service Role Key** (`wowsql_service_...`) → Server-side operations (auth + database)
 
 ### Security Best Practices
 
 1. **Never expose Service Role Key** in client-side code or public repositories
-2. **Use Public API Key** for client-side authentication flows
+2. **Use Anonymous Key** for client-side authentication flows (same key as database operations)
 3. **Use Anonymous Key** for public database access with limited permissions
 4. **Store keys in environment variables**, never hardcode them
 5. **Rotate keys regularly** if compromised
@@ -759,11 +901,11 @@ const authClient = new ProjectAuthClient({
 **Error: "Invalid API key for project"**
 - Ensure you're using the correct key type for the operation
 - Database operations require Service Role Key or Anonymous Key
-- Authentication operations require Public API Key or Service Role Key
+- Authentication operations require Anonymous Key (client-side) or Service Role Key (server-side)
 - Verify the key is copied correctly (no extra spaces)
 
 **Error: "Authentication failed"**
-- Check that you're using Public API Key (not Anonymous Key) for auth operations
+- Check that you're using the correct key: Anonymous Key for client-side, Service Role Key for server-side
 - Verify the project URL matches your dashboard
 - Ensure the key hasn't been revoked or expired
 
@@ -948,7 +1090,7 @@ try {
 
 ### Can I use this in the browser?
 
-Yes! The SDK works in both Node.js and browser environments. However, **never expose your Service Role Key in client-side code** for production applications. Use Public API Key for authentication or Anonymous Key for limited database access. For full database operations, use a backend proxy.
+Yes! The SDK works in both Node.js and browser environments. However, **never expose your Service Role Key in client-side code** for production applications. Use **Anonymous Key** for both authentication and limited database access. For full database operations, use a backend proxy with Service Role Key.
 
 ### What about rate limits?
 

package/dist/auth.d.ts

@@ -7,7 +7,16 @@ export interface ProjectAuthClientConfig {
     secure?: boolean;
     /** Request timeout in milliseconds */
     timeout?: number;
-    /** Optional public API key for analytics/future enforcement */
+    /**
+     * Unified API key - Anonymous Key (wowsql_anon_...) for client-side,
+     * or Service Role Key (wowsql_service_...) for server-side.
+     * UNIFIED AUTHENTICATION: Same key works for both auth and database operations.
+     */
+    apiKey?: string;
+    /**
+     * @deprecated Use apiKey instead. Kept for backward compatibility.
+     * Unified API key - same as apiKey parameter.
+     */
     publicApiKey?: string;
     /** Custom token storage implementation (defaults to in-memory) */
     storage?: AuthTokenStorage;

package/dist/auth.js

@@ -31,12 +31,15 @@ class ProjectAuthClient {
         this.storage = config.storage || new MemoryAuthTokenStorage();
         this.accessToken = this.storage.getAccessToken();
         this.refreshToken = this.storage.getRefreshToken();
+        // UNIFIED AUTHENTICATION: Use apiKey (new) or publicApiKey (deprecated) for backward compatibility
+        const unifiedApiKey = config.apiKey || config.publicApiKey;
         this.client = axios_1.default.create({
             baseURL: baseUrl,
             timeout: config.timeout ?? 30000,
             headers: {
                 'Content-Type': 'application/json',
-                ...(config.publicApiKey ? { 'X-Wow-Public-Key': config.publicApiKey } : {}),
+                // UNIFIED AUTHENTICATION: Use Authorization header (same as database operations)
+                ...(unifiedApiKey ? { 'Authorization': `Bearer ${unifiedApiKey}` } : {}),
             },
         });
     }

package/dist/index.d.ts

@@ -20,13 +20,17 @@ export interface WowSQLConfig {
     timeout?: number;
 }
 export interface QueryOptions {
-    /** Columns to select (comma-separated or array) */
+    /** Columns to select (comma-separated or array) - can include expressions like "COUNT(*)", "DATE(created_at) as date" */
     select?: string | string[];
     /** Filter expressions */
     filter?: FilterExpression | FilterExpression[];
-    /** Column to sort by */
-    order?: string;
-    /** Sort direction */
+    /** Columns to group by */
+    group_by?: string | string[];
+    /** HAVING clause filters for aggregated results */
+    having?: HavingFilter | HavingFilter[];
+    /** Column(s) to sort by - can be string or array of OrderByItem */
+    order?: string | OrderByItem[];
+    /** Sort direction (used only if order is a string) */
     orderDirection?: 'asc' | 'desc';
     /** Maximum records to return */
     limit?: number;
@@ -35,9 +39,19 @@ export interface QueryOptions {
 }
 export interface FilterExpression {
     column: string;
-    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'is';
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'is' | 'in' | 'not_in' | 'between' | 'not_between' | 'is_not';
+    value: string | number | boolean | null | any[] | [any, any];
+    logical_op?: 'AND' | 'OR';
+}
+export interface HavingFilter {
+    column: string;
+    operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
     value: string | number | boolean | null;
 }
+export interface OrderByItem {
+    column: string;
+    direction: 'asc' | 'desc';
+}
 export interface QueryResponse<T = any> {
     data: T[];
     count: number;
@@ -117,7 +131,7 @@ export declare class Table<T = any> {
     /**
      * Query with filter
      */
-    filter(filter: FilterExpression): QueryBuilder<T>;
+    filter(column: string, operator: FilterExpression['operator'], value: any, logical_op?: 'AND' | 'OR'): QueryBuilder<T>;
     /**
      * Get all records (with optional limit)
      */
@@ -145,15 +159,39 @@ export declare class QueryBuilder<T = any> {
     private options;
     constructor(client: AxiosInstance, tableName: string);
     /**
-     * Select specific columns
+     * Select specific columns or expressions
+     * @example query.select('id', 'name')
+     * @example query.select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
      */
-    select(columns: string | string[]): this;
+    select(...columns: (string | string[])[]): this;
     /**
      * Add filter condition
+     * @example query.filter('age', 'gt', 18)
+     * @example query.filter('category', 'in', ['electronics', 'books'])
+     * @example query.filter('price', 'between', [10, 100])
+     */
+    filter(column: string, operator: FilterExpression['operator'], value: any, logical_op?: 'AND' | 'OR'): this;
+    /**
+     * Group results by column(s)
+     * @example query.groupBy('category')
+     * @example query.groupBy(['category', 'status'])
+     * @example query.groupBy('DATE(created_at)')
+     */
+    groupBy(columns: string | string[]): this;
+    /**
+     * Add HAVING clause filter (for filtering aggregated results)
+     * @example query.having('COUNT(*)', 'gt', 10)
+     * @example query.having('AVG(price)', 'gte', 50)
+     */
+    having(column: string, operator: HavingFilter['operator'], value: any): this;
+    /**
+     * Order by column(s)
+     * @example query.orderBy('created_at', 'desc')
+     * @example query.orderBy([{column: 'category', direction: 'asc'}, {column: 'price', direction: 'desc'}])
      */
-    filter(filter: FilterExpression): this;
+    orderBy(column: string | OrderByItem[], direction?: 'asc' | 'desc'): this;
     /**
-     * Order by column
+     * Order by a single column (alias for orderBy for backward compatibility)
      */
     order(column: string, direction?: 'asc' | 'desc'): this;
     /**
@@ -165,7 +203,7 @@ export declare class QueryBuilder<T = any> {
      */
     offset(offset: number): this;
     /**
-     * Execute query
+     * Execute query - uses POST /{table}/query for advanced features, GET for simple queries
      */
     get(additionalOptions?: QueryOptions): Promise<QueryResponse<T>>;
     /**

package/dist/index.js

@@ -125,8 +125,8 @@ class Table {
     /**
      * Query with filter
      */
-    filter(filter) {
-        return new QueryBuilder(this.client, this.tableName).filter(filter);
+    filter(column, operator, value, logical_op = 'AND') {
+        return new QueryBuilder(this.client, this.tableName).filter(column, operator, value, logical_op);
     }
     /**
      * Get all records (with optional limit)
@@ -172,19 +172,33 @@ class QueryBuilder {
         this.options = {};
     }
     /**
-     * Select specific columns
+     * Select specific columns or expressions
+     * @example query.select('id', 'name')
+     * @example query.select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
      */
-    select(columns) {
-        this.options.select = Array.isArray(columns) ? columns.join(',') : columns;
+    select(...columns) {
+        if (columns.length === 1 && Array.isArray(columns[0])) {
+            this.options.select = columns[0];
+        }
+        else if (columns.length === 1 && typeof columns[0] === 'string') {
+            this.options.select = columns[0];
+        }
+        else {
+            this.options.select = columns;
+        }
         return this;
     }
     /**
      * Add filter condition
+     * @example query.filter('age', 'gt', 18)
+     * @example query.filter('category', 'in', ['electronics', 'books'])
+     * @example query.filter('price', 'between', [10, 100])
      */
-    filter(filter) {
+    filter(column, operator, value, logical_op = 'AND') {
         if (!this.options.filter) {
             this.options.filter = [];
         }
+        const filter = { column, operator, value, logical_op };
         if (Array.isArray(this.options.filter)) {
             this.options.filter.push(filter);
         }
@@ -194,13 +208,56 @@ class QueryBuilder {
         return this;
     }
     /**
-     * Order by column
+     * Group results by column(s)
+     * @example query.groupBy('category')
+     * @example query.groupBy(['category', 'status'])
+     * @example query.groupBy('DATE(created_at)')
      */
-    order(column, direction = 'asc') {
-        this.options.order = column;
-        this.options.orderDirection = direction;
+    groupBy(columns) {
+        this.options.group_by = columns;
+        return this;
+    }
+    /**
+     * Add HAVING clause filter (for filtering aggregated results)
+     * @example query.having('COUNT(*)', 'gt', 10)
+     * @example query.having('AVG(price)', 'gte', 50)
+     */
+    having(column, operator, value) {
+        if (!this.options.having) {
+            this.options.having = [];
+        }
+        const havingFilter = { column, operator, value };
+        if (Array.isArray(this.options.having)) {
+            this.options.having.push(havingFilter);
+        }
+        else {
+            this.options.having = [this.options.having, havingFilter];
+        }
+        return this;
+    }
+    /**
+     * Order by column(s)
+     * @example query.orderBy('created_at', 'desc')
+     * @example query.orderBy([{column: 'category', direction: 'asc'}, {column: 'price', direction: 'desc'}])
+     */
+    orderBy(column, direction) {
+        if (typeof column === 'string') {
+            this.options.order = column;
+            if (direction) {
+                this.options.orderDirection = direction;
+            }
+        }
+        else {
+            this.options.order = column;
+        }
         return this;
     }
+    /**
+     * Order by a single column (alias for orderBy for backward compatibility)
+     */
+    order(column, direction = 'asc') {
+        return this.orderBy(column, direction);
+    }
     /**
      * Limit number of results
      */
@@ -216,35 +273,98 @@ class QueryBuilder {
         return this;
     }
     /**
-     * Execute query
+     * Execute query - uses POST /{table}/query for advanced features, GET for simple queries
      */
     async get(additionalOptions) {
         const finalOptions = { ...this.options, ...additionalOptions };
-        // Build query parameters
-        const params = {};
+        // Build query request body for POST endpoint
+        const body = {};
+        // Select
         if (finalOptions.select) {
-            params.select = finalOptions.select;
+            body.select = Array.isArray(finalOptions.select)
+                ? finalOptions.select
+                : typeof finalOptions.select === 'string'
+                    ? finalOptions.select.split(',').map(s => s.trim())
+                    : [finalOptions.select];
         }
+        // Filters
         if (finalOptions.filter) {
-            const filters = Array.isArray(finalOptions.filter)
+            body.filters = Array.isArray(finalOptions.filter)
                 ? finalOptions.filter
                 : [finalOptions.filter];
-            params.filter = filters
-                .map((f) => `${f.column}.${f.operator}.${f.value}`)
-                .join(',');
         }
+        // Group by
+        if (finalOptions.group_by) {
+            body.group_by = Array.isArray(finalOptions.group_by)
+                ? finalOptions.group_by
+                : typeof finalOptions.group_by === 'string'
+                    ? finalOptions.group_by.split(',').map(s => s.trim())
+                    : [finalOptions.group_by];
+        }
+        // Having
+        if (finalOptions.having) {
+            body.having = Array.isArray(finalOptions.having)
+                ? finalOptions.having
+                : [finalOptions.having];
+        }
+        // Order by
         if (finalOptions.order) {
-            params.order = finalOptions.order;
-            params.order_direction = finalOptions.orderDirection || 'asc';
+            if (typeof finalOptions.order === 'string') {
+                body.order_by = finalOptions.order;
+                body.order_direction = finalOptions.orderDirection || 'asc';
+            }
+            else {
+                body.order_by = finalOptions.order;
+            }
         }
+        // Limit and offset
         if (finalOptions.limit !== undefined) {
-            params.limit = finalOptions.limit;
+            body.limit = finalOptions.limit;
         }
         if (finalOptions.offset !== undefined) {
-            params.offset = finalOptions.offset;
+            body.offset = finalOptions.offset;
+        }
+        // Check if we need POST endpoint (advanced features)
+        const hasAdvancedFeatures = body.group_by ||
+            body.having ||
+            Array.isArray(body.order_by) ||
+            (body.filters && body.filters.some((f) => ['in', 'not_in', 'between', 'not_between'].includes(f.operator)));
+        if (hasAdvancedFeatures) {
+            // Use POST endpoint for advanced queries
+            const response = await this.client.post(`/${this.tableName}/query`, body);
+            return response.data;
+        }
+        else {
+            // Use GET endpoint for simple queries (backward compatibility)
+            const params = {};
+            if (body.select) {
+                params.select = Array.isArray(body.select) ? body.select.join(',') : body.select;
+            }
+            if (body.filters && body.filters.length > 0) {
+                // Check if any filter uses array values (can't use GET)
+                const hasArrayValues = body.filters.some((f) => Array.isArray(f.value));
+                if (hasArrayValues) {
+                    // Must use POST
+                    const response = await this.client.post(`/${this.tableName}/query`, body);
+                    return response.data;
+                }
+                params.filter = body.filters
+                    .map((f) => `${f.column}.${f.operator}.${f.value}`)
+                    .join(',');
+            }
+            if (body.order_by && typeof body.order_by === 'string') {
+                params.order = body.order_by;
+                params.order_direction = body.order_direction || 'asc';
+            }
+            if (body.limit !== undefined) {
+                params.limit = body.limit;
+            }
+            if (body.offset !== undefined) {
+                params.offset = body.offset;
+            }
+            const response = await this.client.get(`/${this.tableName}`, { params });
+            return response.data;
         }
-        const response = await this.client.get(`/${this.tableName}`, { params });
-        return response.data;
     }
     /**
      * Get first record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowsql/sdk",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "Official TypeScript/JavaScript SDK for WowSQL - MySQL Backend-as-a-Service with S3 Storage, type-safe queries and fluent API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",