Worqhat TypeScript SDK

Official TypeScript SDK for the Worqhat API. This SDK provides a type-safe interface to interact with Worqhat's database, workflows, and storage services.

Installation

npm install worqhat

Quick Start

import Worqhat from 'worqhat';

const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY, // This is the default and can be omitted
});

// Execute a database query
const response = await client.db.executeQuery({
  query: 'SELECT * FROM users WHERE email = {email}',
  params: { email: '[email protected]' }
});

console.log(response.data);

Configuration

Basic Configuration

import Worqhat from 'worqhat';

const client = new Worqhat({
  apiKey: 'your-api-key',
});

Advanced Configuration

const client = new Worqhat({
  apiKey: 'your-api-key',
  baseURL: 'https://api.worqhat.app', // Custom base URL (optional)
  target: 'app', // Backend target: 'app' or 'fyi' (optional)
});

Database Operations

Execute Raw SQL Query

Execute SQL queries with named or positional parameters.

Named Parameters

const response = await client.db.executeQuery({
  query: 'SELECT * FROM users WHERE email = {email} AND status = {status}',
  params: {
    email: '[email protected]',
    status: 'active'
  },
  environment: 'production' // optional
});

console.log(response.data);

Positional Parameters

const response = await client.db.executeQuery({
  query: 'SELECT * FROM users WHERE email = $1 AND status = $2',
  params: ['[email protected]', 'active']
});

console.log(response.data);

Insert Data

Insert single or multiple records into a table.

Single Record

const response = await client.db.insert({
  table: 'users',
  data: {
    email: '[email protected]',
    name: 'New User',
    status: 'active'
  }
});

console.log(response.data);

Multiple Records

const response = await client.db.insert({
  table: 'users',
  data: [
    { email: '[email protected]', name: 'User 1' },
    { email: '[email protected]', name: 'User 2' }
  ]
});

console.log(`Inserted ${response.count} records`);

Update Data

const response = await client.db.update({
  table: 'users',
  data: {
    status: 'inactive'
  },
  where: {
    email: '[email protected]'
  }
});

console.log(`Updated ${response.count} records`);

Delete Data

const response = await client.db.delete({
  table: 'users',
  where: {
    id: '123'
  }
});

console.log(response.message);

List Tables

const response = await client.db.listTables('production', 'public');

console.log(response.tables);

Get Table Schema

const response = await client.db.getTableSchema('users', 'production');

console.log(response.schema.columns);
console.log(response.schema.indexes);
console.log(response.schema.constraints);

Get Table Count

// Get total count
const response = await client.db.getTableCount('users');
console.log(`Total users: ${response.count}`);

// Get count with filters
const activeUsers = await client.db.getTableCount('users', { status: 'active' });
console.log(`Active users: ${activeUsers.count}`);

Batch Operations

Execute multiple operations in a single transaction.

const response = await client.db.batch({
  operations: [
    {
      type: 'insert',
      table: 'users',
      data: { email: '[email protected]', name: 'User 1' }
    },
    {
      type: 'update',
      table: 'users',
      data: { status: 'active' },
      where: { email: '[email protected]' }
    },
    {
      type: 'query',
      query: 'SELECT * FROM users WHERE email = $1',
      params: ['[email protected]']
    }
  ],
  transactional: true // All operations succeed or all fail
});

console.log(response.results);

Vector Search Operations

Semantic Search

Perform semantic similarity search using vector embeddings.

Single Table Search

const response = await client.db.semanticSearch({
  query: 'find products similar to wireless headphones',
  table: 'products',
  limit: 10,
  threshold: 0.7,
  filters: {
    category: 'electronics'
  }
});

response.results.forEach(result => {
  console.log(`${result.record.name} - Similarity: ${result.similarity}`);
});

Cross-Table Search

const response = await client.db.semanticSearch({
  query: 'customer support issues',
  tables: ['tickets', 'support_requests', 'feedback'],
  limit: 20,
  threshold: 0.6
});

response.results.forEach(result => {
  console.log(`Table: ${result.table}, Similarity: ${result.similarity}`);
});

Hybrid Search

Combine semantic similarity with keyword search for better relevance.

const response = await client.db.hybridSearch({
  query: 'affordable wireless headphones',
  table: 'products',
  text_columns: ['name', 'description', 'tags'],
  semantic_weight: 0.7,
  keyword_weight: 0.3,
  limit: 10
});

response.results.forEach(result => {
  console.log(`Combined Score: ${result.combined_score}`);
  console.log(`Semantic: ${result.semantic_score}, Keyword: ${result.keyword_score}`);
});

Find Similar Records

Find records similar to a specific record.

const response = await client.db.findSimilar({
  table: 'products',
  record_id: '123',
  limit: 5,
  threshold: 0.75,
  exclude_self: true
});

console.log('Source Record:', response.source_record);
response.similar_records.forEach(similar => {
  console.log(`${similar.record.name} - Similarity: ${similar.similarity}`);
});

Workflow Operations

Trigger a Workflow

const response = await client.flows.trigger({
  flowId: 'your-flow-id',
  input: {
    key: 'value',
    data: 'your data here'
  }
});

console.log(response);

Trigger Workflow with File

Upload a file

import * as fs from 'fs';

const fileBuffer = fs.readFileSync('/path/to/file.pdf');

const response = await client.flows.triggerWithFile({
  flowId: 'your-flow-id',
  file: fileBuffer,
  data: {
    note: 'process this file'
  }
});

Download from URL

const response = await client.flows.triggerWithFile({
  flowId: 'your-flow-id',
  url: 'https://example.com/file.pdf',
  data: {
    note: 'process downloaded file'
  }
});

Get Workflow Metrics

const response = await client.flows.getMetrics({
  start_date: '2024-01-01',
  end_date: '2024-02-01',
  status: 'completed'
});

console.log(`Total workflows: ${response.metrics.total_workflows}`);
console.log(`Completed: ${response.metrics.completed_workflows}`);
console.log(`Failed: ${response.metrics.failed_workflows}`);
console.log(`Average duration: ${response.metrics.avg_duration_ms}ms`);

Storage Operations

Upload a File

import * as fs from 'fs';

const fileBuffer = fs.readFileSync('/path/to/file.png');

const response = await client.storage.upload({
  file: fileBuffer,
  path: 'uploads/images'
});

console.log('File ID:', response.fileId);
console.log('URL:', response.url);

Fetch a File

By File ID

const response = await client.storage.fetch('file-id-123');
console.log('Download URL:', response.url);

By File Path

const response = await client.storage.fetchByPath('uploads/images/1700000000000-file.png');
console.log('Download URL:', response.url);

Delete a File

const response = await client.storage.delete('file-id-123');
console.log(response.message);

Error Handling

The SDK throws typed errors that you can catch and handle.

import Worqhat, { WorqhatError } from 'worqhat';

const client = new Worqhat();

try {
  const response = await client.db.executeQuery({
    query: 'SELECT * FROM users'
  });
} catch (error) {
  if (error && typeof error === 'object' && 'error' in error) {
    const worqhatError = error as WorqhatError;
    console.error(`Error: ${worqhatError.error}`);
    console.error(`Message: ${worqhatError.message}`);
    console.error(`Code: ${worqhatError.code}`);
  } else {
    console.error('Unknown error:', error);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions.

import Worqhat, { QueryResponse, InsertResponse } from 'worqhat';

const client = new Worqhat();

// Type-safe responses
const queryResponse: QueryResponse<User> = await client.db.executeQuery({
  query: 'SELECT * FROM users'
});

const insertResponse: InsertResponse<User> = await client.db.insert({
  table: 'users',
  data: { email: '[email protected]' }
});

interface User {
  id: string;
  email: string;
  name: string;
  status: string;
}

Environment Variables

The SDK automatically reads the WORQHAT_API_KEY environment variable if no API key is provided in the configuration.

export WORQHAT_API_KEY=your-api-key

// API key will be read from environment variable
const client = new Worqhat();

License

ISC

Support

For API support, contact [email protected] or visit worqhat.com.