ll-callmobile-backend/README.md

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

# LL CallMobile Backend

A TypeScript-based backend package for VoIP Mobile Communications using Supabase and Drizzle ORM, deployable as a Cloudflare Worker.

## Features

- **Database Management**: PostgreSQL with Supabase using Drizzle ORM
- **API Layer**: Hono-based REST API endpoints (Cloudflare Workers compatible)
- **Type Safety**: Full TypeScript support with generated types
- **Transaction Support**: ACID-compliant database operations
- **Error Handling**: Comprehensive error handling with user-friendly messages
- **Cloudflare Workers**: Ready for serverless deployment
- **Multiple Usage Patterns**: Use as a package, API server, or 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. Cloudflare Worker Deployment

```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";
```

### 3. Express Server Usage

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

const app = express();
app.use("/api", testCasesApi);

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

## Database Schema

### Tables

- **test_cases**: Stores test case information

  - `id` (Primary Key)
  - `description` (Text)
  - `code` (Enum: CVT, CVT2, GPP)
  - `created_on` (Timestamp)

- **clients**: Stores client information

  - `id` (Primary Key)
  - `acs_identity_id` (Text)
  - `name` (Text)
  - `acs_token` (Text)

- **vendors**: Stores vendor information

  - `id` (Primary Key)
  - `acs_identity_id` (Text)
  - `name` (Text)
  - `acs_token` (Text)

- **jobs**: Stores job information linking test cases, clients, and vendors
  - `id` (Primary Key)
  - `client_id` (Foreign Key to clients.id)
  - `vendor_id` (Foreign Key to vendors.id)
  - `details` (Text)
  - `start_date` (Timestamp)
  - `end_date` (Timestamp, nullable)

## Setup

### Prerequisites

- Node.js 18+
- Supabase account and project
- PostgreSQL database access

### 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 Setup

1. Generate and run database migrations:

```bash
npm run db:generate
npm run db:migrate
```

2. Build the package:

```bash
npm run build
```

## API Endpoints

### POST /api/testcases

Creates a new test case with associated client, vendor, and job.

**Request Body:**

```json
{
  "description": "Test VoIP communication",
  "code": "CVT",
  "client": {
    "acsIdentityId": "client-identity-123",
    "name": "Test Client",
    "acsToken": "client-token-456"
  },
  "vendor": {
    "acsIdentityId": "vendor-identity-789",
    "name": "Test Vendor",
    "acsToken": "vendor-token-012"
  }
}
```

**Response:**

```json
{
  "testCaseId": 1,
  "client": {
    "acsIdentityId": "client-identity-123",
    "acsToken": "client-token-456"
  },
  "vendor": {
    "acsIdentityId": "vendor-identity-789",
    "acsToken": "vendor-token-012"
  }
}
```

### GET /api/testcases/:id

Retrieves a test case by ID.

**Response:**

```json
{
  "id": 1,
  "description": "Test VoIP communication",
  "code": "CVT",
  "createdOn": "2024-01-15T10:30:00Z"
}
```

### GET /api/testcases/:id/client-token

Retrieves a client's ACS token by test case ID.

**Response:**

```json
{
  "acsToken": "client-token-456"
}
```

## 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,
} from "ll-callmobile-backend";
```

## Examples

See [USAGE.md](./USAGE.md) for comprehensive usage examples and patterns.

## Support

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