TextQL Playbooks API Client

A comprehensive TypeScript client and CLI tool for interacting with TextQL's Playbooks API. This tool allows you to create, update, and manage SQL-based playbooks that can be scheduled to run automatically and send results via email.

Features

• 🚀 Full API Coverage: Complete implementation of TextQL Playbooks API
• 🛠️ TypeScript Support: Fully typed with comprehensive type definitions
• 🖥️ CLI Interface: Easy-to-use command-line interface
• ⚙️ Configuration Management: Persistent settings and API key management
• 📊 Connector Management: List and manage database connectors
• 📅 Cron Scheduling: Support for complex scheduling patterns
• 📧 Email Notifications: Configure multiple email recipients
• 🔧 Error Handling: Robust error handling and user-friendly messages

Installation

This project uses Bun as the runtime. Make sure you have Bun installed:

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash
# Clone or download this projectcd textql
# Install dependencies
bun install

Quick Start

1. Set up your API Key

Get your API key from TextQL Settings:

# Using the CLI
bun run index.ts config set-api-key your-api-key-here
# Or set environment variableexport TEXTQL_API_KEY=your-api-key-here

2. List Available Connectors

bun run index.ts connectors

3. Create Your First Playbook

bun run index.ts create \
--id="my-first-playbook" \
--prompt="SELECT COUNT(*) as total_users FROM users" \
--name="User Count Report" \
--emails="admin@company.com,analyst@company.com" \
--connector=213

CLI Usage

Configuration Commands

# Set API key
bun run index.ts config set-api-key <your-key># Set default connector ID
bun run index.ts config set-connector <connector-id># Set default cron schedule
bun run index.ts config set-cron "0 9 * * *"# View current configuration
bun run index.ts config show

Playbook Management

# List all connectors
bun run index.ts connectors
# Create a new playbook
bun run index.ts create \
--id=<playbook-id> \
--prompt="<sql-query>" \
--name="<playbook-name>" \
--emails="email1@example.com,email2@example.com" \
[--connector=<id>] \
[--cron="0 13 * * *"]
# Update an existing playbook
bun run index.ts update \
--id=<playbook-id> \
[--prompt="<new-sql-query>"] \
[--name="<new-name>"] \
[--emails="new@example.com"] \
[--status=STATUS_ACTIVE|STATUS_INACTIVE]

Programmatic Usage

Basic Example

import{TextQLClient,ConfigManager}from'./index.js';// Initialize clientconstconfigManager=newConfigManager();constclient=newTextQLClient({apiKey: configManager.getApiKey(),});// List connectorsconstconnectors=awaitclient.listConnectors();console.log('Available connectors:',connectors);// Create a playbookconstresult=awaitclient.createCompletePlaybook({playbookId: 'my-playbook-123',prompt: 'SELECT * FROM users WHERE created_at > NOW() - INTERVAL 7 DAY',name: 'Weekly Active Users',emailAddresses: ['admin@company.com'],connectorId: 213,cronString: '0 9 * * 1',// Every Monday at 9 AM});if(result.success){console.log('Playbook created:',result.data);}else{console.error('Error:',result.error);}

Advanced Example

import{TextQLClient}from'./index.js';constclient=newTextQLClient({apiKey: process.env.TEXTQL_API_KEY!,});// Find a specific connectorconstpostgresConnector=awaitclient.findConnectorByName('postgres');// Create multiple playbooksconstplaybooks=[{id: 'daily-sales',name: 'Daily Sales Report',prompt: 'SELECT DATE(created_at) as date, SUM(total) as revenue FROM orders GROUP BY DATE(created_at)',emails: ['sales@company.com'],cron: '0 8 * * *',},{id: 'weekly-inventory',name: 'Weekly Inventory Alert',prompt: 'SELECT * FROM products WHERE stock < reorder_level',emails: ['inventory@company.com'],cron: '0 9 * * 1',}];for(constplaybookofplaybooks){awaitclient.createCompletePlaybook({
...playbook,connectorId: postgresConnector!.id,});}

API Reference

TextQLClient

Methods

• createPlaybook(playbookId: string) - Create a new playbook
• updatePlaybook(playbook: UpdatePlaybookRequest) - Update an existing playbook
• getConnectors() - Get all available connectors
• createCompletePlaybook(params) - Create a playbook with full configuration
• listConnectors() - List all connectors
• findConnectorByName(name: string) - Find a connector by name

Types

• Playbook - Complete playbook configuration
• UpdatePlaybookRequest - Request payload for updating playbooks
• Connector - Database connector information
• TextQLConfig - Client configuration
• TextQLResponse<T> - Standardized API response wrapper

Examples

Run the included examples:

# Basic usage example
bun run example:basic
# Advanced usage example
bun run example:advanced

Configuration

The tool stores configuration in ~/.textql/config.json:

{
"apiKey": "your-api-key",
"baseUrl": "https://app.textql.com",
"defaultConnectorId": 213,
"defaultCronString": "0 13 * * *"
}

Environment Variables

• TEXTQL_API_KEY - Your TextQL API key (alternative to config file)

Error Handling

All API calls return a standardized response:

interfaceTextQLResponse<T>{success: boolean;data?: T;error?: {message: string;code?: string;status?: number;};}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the TextQL Documentation
• Open an issue in this repository
• Contact TextQL support