ll-callmobile-backend/USAGE.md

VoIP Mobile Communications Backend with Supabase, Drizzle ORM, and Dynamic Querying - Deployable as Cloudflare Worker

# LL CallMobile Backend - Usage Guide

This package provides a VoIP Mobile Communications Backend with Supabase and Drizzle ORM, deployable as a Cloudflare Worker.

## Installation

```bash
npm install ll-callmobile-backend
```

## Quick Start

### 1. Direct Service Usage

```typescript
import { TestCaseService, createDb } from "ll-callmobile-backend";

// Initialize database connection
const db = createDb({
  DATABASE_URL: "your-supabase-connection-string",
  SUPABASE_URL: "your-supabase-url",
  SUPABASE_ANON_KEY: "your-supabase-anon-key",
});

// Create service instance
const testCaseService = new TestCaseService(db);

// Create a test case
const testCase = await testCaseService.createTestCase({
  name: "Test VoIP Call",
  description: "Testing voice quality",
  phoneNumber: "+1234567890",
  userId: "user123",
  code: "test-code-123",
});

console.log("Created test case:", testCase);
```

### 2. Dynamic Database Querying

```typescript
import { DynamicQuery, createDb } from "ll-callmobile-backend";

// Initialize database connection
const db = createDb({
  DATABASE_URL: "your-supabase-connection-string",
  SUPABASE_URL: "your-supabase-url",
  SUPABASE_ANON_KEY: "your-supabase-anon-key",
});

// Create DynamicQuery instance
const query = new DynamicQuery(db);

// Simple filtering
const activeTests = await query.findByFilters("test_cases", {
  status: "active",
});

// Complex queries with pagination
const results = await query.query("test_cases", {
  where: [
    { field: "status", operator: "eq", value: "active" },
    { field: "created_on", operator: "gte", value: "2024-01-01" },
  ],
  orderBy: [{ field: "created_on", direction: "desc" }],
  pagination: { limit: 20, offset: 0 },
});

// Count records
const totalTests = await query.count("test_cases", { status: "active" });

// Find by ID
const testCase = await query.findById("test_cases", 123);
```

### 3. Cloudflare Worker Deployment

#### Using the Worker directly:

```typescript
// wrangler.toml
[env.production];
name = "ll-callmobile-backend";
main = "node_modules/ll-callmobile-backend/dist/worker.js";
compatibility_date = "2024-01-01"[env.production.vars];
ENVIRONMENT = "production"[[env.production.secret]];
name = "DATABASE_URL"[[env.production.secret]];
name = "SUPABASE_URL"[[env.production.secret]];
name = "SUPABASE_ANON_KEY";
```

#### Using with custom worker:

```typescript
import worker from "ll-callmobile-backend/worker";

// The worker is already configured with all routes
export default worker;
```

### 4. Express Server Usage

```typescript
import express from "express";
import { testCasesApi } from "ll-callmobile-backend";

const app = express();

// Use the API routes
app.use("/api", testCasesApi);

app.listen(3000, () => {
  console.log("Server running on port 3000");
});
```

## API Endpoints

### Create Test Case

```bash
POST /api/testcases
Content-Type: application/json

{
  "name": "Test VoIP Call",
  "description": "Testing voice quality",
  "phoneNumber": "+1234567890",
  "userId": "user123",
  "code": "test-code-123"
}
```

### Get Test Case by ID

```bash
GET /api/testcases/{id}
```

### Get Client ACS Token

```bash
GET /api/testcases/{id}/client-token
```

## Environment Variables

Set these environment variables for database connection:

- `DATABASE_URL`: Supabase PostgreSQL connection string
- `SUPABASE_URL`: Your Supabase project URL
- `SUPABASE_ANON_KEY`: Your Supabase anonymous key

## Database Schema

The package includes Drizzle ORM schema for test cases:

```typescript
import { testCases } from "ll-callmobile-backend";

// Access the schema
console.log(testCases);
```

## Development

For local development:

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run database migrations
npm run db:migrate

# Start development server
npm run dev
```

## Deployment

### Cloudflare Workers

```bash
# Deploy to Cloudflare Workers
npm run deploy
```

### Set Secrets in Cloudflare

```bash
# Set database connection secrets
wrangler secret put DATABASE_URL
wrangler secret put SUPABASE_URL
wrangler secret put SUPABASE_ANON_KEY
```

## Types

The package exports TypeScript types for all operations:

```typescript
import type {
  CreateTestCaseRequest,
  CreateTestCaseResponse,
  QueryOptions,
  QueryResult,
  FilterOperator,
} from "ll-callmobile-backend";
```

## Examples

### Complete Example with Error Handling

```typescript
import { TestCaseService, DynamicQuery, createDb } from "ll-callmobile-backend";

async function main() {
  try {
    // Initialize database
    const db = createDb({
      DATABASE_URL: process.env.DATABASE_URL!,
      SUPABASE_URL: process.env.SUPABASE_URL!,
      SUPABASE_ANON_KEY: process.env.SUPABASE_ANON_KEY!,
    });

    const service = new TestCaseService(db);
    const query = new DynamicQuery(db);

    // Create test case
    const testCase = await service.createTestCase({
      name: "VoIP Quality Test",
      description: "Testing call quality under various conditions",
      phoneNumber: "+1234567890",
      userId: "user-123",
      code: "test-abc-123",
    });

    console.log("Test case created:", testCase.id);

    // Query recent test cases
    const recentTests = await query.query("test_cases", {
      where: [{ field: "status", operator: "eq", value: "active" }],
      orderBy: [{ field: "created_on", direction: "desc" }],
      pagination: { limit: 10 },
    });

    console.log("Recent tests:", recentTests.data);

    // Get client token
    const token = await service.getClientToken(testCase.id);
    console.log("Client token:", token);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();
```

### Dynamic Query Examples

```typescript
// Dashboard data
const dashboardData = await query.query("test_cases", {
  where: [{ field: "status", operator: "eq", value: "active" }],
  orderBy: [{ field: "created_on", direction: "desc" }],
  pagination: { limit: 10 },
});

// Search functionality
const searchResults = await query.query("test_cases", {
  where: [{ field: "description", operator: "like", value: "%voip%" }],
  orderBy: [{ field: "created_on", direction: "desc" }],
  pagination: { page: 1, pageSize: 20 },
});

// Analytics
const activeCount = await query.count("test_cases", { status: "active" });
const pendingCount = await query.count("test_cases", { status: "pending" });

// Date range queries
const recentTests = await query.query("test_cases", {
  where: [
    { field: "created_on", operator: "gte", value: "2024-01-01" },
    { field: "created_on", operator: "lte", value: "2024-12-31" },
  ],
});
```

## Support

For issues and questions, please visit our [GitHub repository](https://github.com/andrepainha-acolad/callmobile_backend).