TypeScript / JavaScript Quick Start

WoWSQL TypeScript SDK — Get started in minutes

Get your API key: Use the WoWSQL project dashboard to create or copy your API key. The same key works for database, auth, and storage (unified API key).

Installation

Official package: View on npm →

npm install @wowsql/sdk
# or: yarn add @wowsql/sdk
# or: pnpm add @wowsql/sdk

Initialize Client

import WowSQLClient from '@wowsql/sdk';

// Initialize client with your API key
// Note: The same key works for database, auth, and storage operations
const client = new WowSQLClient({
  projectUrl: 'myproject',  // Your project subdomain
  apiKey: 'your_api_key_here'  // Single key for all operations
});

// Or with full URL
const clientFull = new WowSQLClient({
  projectUrl: 'https://myproject.wowsql.com',
  apiKey: 'your_api_key'
});

// CORRECT: Use .select() before .get()
const users = await client.table('users').select('*').get();

Example API Call (REST)

You can also call the API directly with fetch:

const response = await fetch(`${API_URL}/api/v1/db/tables/users/query`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    select: ['id', 'email', 'name'],
    filters: [{ column: 'status', operator: 'eq', value: 'active' }],
    order_by: [{ column: 'created_at', direction: 'desc' }],
    limit: 10
  })
});
const data = await response.json();
console.log(data);

Query Data

Basic Queries

// Get all records - use .select() before .get()
const users = await client.table('users').select('*').get();

// With filters - use .filter() or helper methods
const adults = await client.table('users')
  .select('*')
  .filter({ column: 'age', operator: 'gte', value: 18 })
  .get();

// Or using filter(column, operator, value)
const adults2 = await client.table('users')
  .select('*')
  .filter('age', 'gte', 18)
  .get();

// Select specific columns
const names = await client.table('users')
  .select(['id', 'name'])
  .get();

Advanced Queries

// Multiple filters with sorting
const activeUsers = await client.table('users')
  .filter({ column: 'status', operator: 'eq', value: 'active' })
  .filter({ column: 'age', operator: 'gt', value: 18 })
  .order('created_at', 'desc')
  .limit(20)
  .offset(0)
  .get();

console.log(`Found ${activeUsers.count} users`);
activeUsers.data.forEach(user => console.log(user.name));

Filter Helper Methods

// Using helper methods (more readable)
const users = await client.table('users')
  .eq('status', 'active')
  .gt('age', 18)
  .like('email', '%@gmail.com')
  .isNotNull('email_verified_at')
  .in('role', ['admin', 'moderator'])
  .between('created_at', '2024-01-01', '2024-12-31')
  .get();

// OR conditions
const usersOr = await client.table('users')
  .eq('status', 'active')
  .or('role', 'eq', 'admin')
  .get();

GROUP BY and Aggregates

Basic GROUP BY

// Group by category with counts
const result = await client.table('products')
  .select('category', 'COUNT(*) as count', 'AVG(price) as avg_price')
  .groupBy('category')
  .get();

// Group by date
const result2 = 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();

// Multiple GROUP BY columns
const result3 = await client.table('sales')
  .select('region', 'category', 'SUM(amount) as total')
  .groupBy(['region', 'category'])
  .get();

HAVING Clause

// 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 result2 = 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();

Multiple ORDER BY

// 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();

CRUD Operations

Create Record

const result = await client.table('users').create({
  name: 'John Doe',
  email: 'john@example.com',
  age: 30
});

console.log(`Created user with ID: ${result.id}`);

Update Record

await client.table('users').update(123, {
  email: 'newemail@example.com'
});

console.log('User updated successfully');

Delete Record

await client.table('users').delete(123);
console.log('User deleted successfully');

Get Single Record by ID

const user = await client.table('users').getById(123);
console.log(`User: ${user.name}`);

Get First Record

// Get first matching record
const user = await client.table('users')
  .filter({ column: 'status', operator: 'eq', value: 'active' })
  .first();

if (user) {
  console.log(`First active user: ${user.name}`);
}

Type-safe Queries

Use generics for full type safety and autocomplete:

import { WowSQLClient, QueryResponse } from '@wowsql/sdk';

interface User {
  id: number;
  name: string;
  email: string;
  age: number;
}

const client = new WowSQLClient({ projectUrl: 'myproject', apiKey: 'key' });

// Type-safe table access
const users: QueryResponse<User> = await client.table<User>('users').get();

// Full type safety and autocomplete
users.data.forEach((user: User) => {
  console.log(user.name);  // TypeScript knows this is a string
});

Error Handling

import { WowSQLError } from '@wowsql/sdk';

try {
  const users = await client.table('users').select('*').get();
  console.log(`Success: ${users.data.length} users`);
} catch (error) {
  if (error instanceof WowSQLError) {
    if (error.statusCode === 401) console.error('Authentication failed — check your API key');
    else if (error.statusCode === 404) console.error('Table or resource not found');
    else console.error(`Error (${error.statusCode}): ${error.message}`);
  } else throw error;
}

Filter Operators

Available operators for filtering data:

Authentication

Use the same API key for authentication operations. The unified key system means one key works for both database and auth.

Sign Up & Sign In

import { ProjectAuthClient } from '@wowsql/sdk';

const auth = new ProjectAuthClient({
  projectUrl: 'myproject',
  apiKey: 'your_api_key'  // Same key as database client
});

// Sign up
const result = await auth.signUp({
  email: 'user@example.com',
  password: 'SecurePassword123',
  full_name: 'John Doe'
});
console.log(`Access token: ${result.session.accessToken}`);

// Sign in
const login = await auth.signIn({
  email: 'user@example.com',
  password: 'SecurePassword123'
});
console.log(`User ID: ${login.user?.id}`);

Password Reset

// Request password reset
await auth.forgotPassword('user@example.com');

// Reset password with token from email
await auth.resetPassword('reset_token_from_email', 'NewSecurePassword123');

OTP Authentication

// Send OTP for login
await auth.sendOtp({ email: 'user@example.com', purpose: 'login' });

// Verify OTP and login
const result = await auth.verifyOtp({
  email: 'user@example.com',
  otp: '123456',
  purpose: 'login'
});
console.log(`Logged in: ${result.user?.id}`);

Magic Link & Email Verification

// Send magic link
await auth.sendMagicLink({ email: 'user@example.com', purpose: 'login' });

// Verify email with token
await auth.verifyEmail('verification_token_from_email');

// Resend verification email
await auth.resendVerification('user@example.com');

OAuth Authentication

// Get OAuth authorization URL
const { authorizationUrl } = await auth.getOAuthAuthorizationUrl(
  'github',
  'http://localhost:5000/auth/callback'
);
// Redirect user to authorizationUrl

// After OAuth callback, exchange code for tokens
const result = await auth.exchangeOAuthCallback(
  'github',
  'authorization_code_from_callback',
  'http://localhost:5000/auth/callback'
);
console.log(`OAuth login successful: ${result.user?.id}`);

Storage Operations

Initialize Storage

import { WowSQLStorage } from '@wowsql/sdk';

const storage = new WowSQLStorage({
  projectUrl: 'myproject',
  apiKey: 'your_api_key'  // Same key for all operations
});

File Operations

// Upload file (from Buffer/Blob/File)
const result = await storage.upload(file, 'uploads/document.pdf', {
  folder: 'documents'
});
console.log(`Uploaded: ${result.file_key}`);

// Get file URL (with metadata)
const urlData = await storage.getFileUrl('uploads/document.pdf', { expiresIn: 3600 });
console.log(`Download URL: ${urlData.file_url}`);
console.log(`Expires at: ${urlData.expires_at}`);

// Get presigned URL
const presignedUrl = await storage.getPresignedUrl({
  objectKey: 'uploads/document.pdf',
  expiresIn: 3600,
  operation: 'get_object'
});
console.log(`URL: ${presignedUrl}`);

// List files
const files = await storage.listFiles({ prefix: 'uploads/' });
files.forEach(file => console.log(`${file.key}: ${file.size_mb?.toFixed(2)} MB`));

// Delete file
await storage.deleteFile('uploads/document.pdf');

// Check quota
const quota = await storage.getQuota();
console.log(`Used: ${quota.used_gb?.toFixed(2)} GB / ${quota.quota_gb?.toFixed(2)} GB`);

Download or View File

Via REST: use GET .../files/{file_key}/download for attachment download, or GET .../files/{file_key}/view to view inline in the browser.