TypeScript

Integrate the Flimpa API into your TypeScript applications with full type safety.

Installation

For modern Node.js (v18+), use the native fetch and FormData APIs. No external dependencies are required.

Types

Define the API response types for a robust integration.

typescript

export type TaskStatus = 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';

export interface CreateTaskResponse {
  taskId: string;
  status: TaskStatus;
  pollUrl: string;
  accessToken: string;
  idempotentReplay?: boolean;
}

export interface TaskStatusResponse {
  taskId: string;
  status: TaskStatus;
  pollUrl: string;
  accessToken: string;
  error?: string;
  code?: string;
}

Initialization

Set up your API key and base URL.

typescript

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.flimpa.com/api/v1';

Authentication

Authenticate your requests using the X-API-Key header for task creation, and the X-Task-Access-Token header for status and download requests.

Usage Example

This example demonstrates how to create a task, poll for its status, and download the result. Operations supported are compress-pdf and image-to-webp.

typescript

import { openAsBlob } from 'node:fs';

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.flimpa.com/api/v1';

export async function processFile(filePath: string, operation: string): Promise<Buffer> {
  // 1. Create Task (Upload)
  const formData = new FormData();
  formData.append('operation', operation);
  formData.append('file', await openAsBlob(filePath));

  const createRes = await fetch(`${BASE_URL}/tasks`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: formData
  });
  
  if (!createRes.ok) {
    const errorData = await createRes.json() as { error: string, code: string };
    throw new Error(`Failed to create task: ${errorData.error} (${errorData.code})`);
  }
  const { taskId, accessToken } = await createRes.json() as CreateTaskResponse;

  // 2. Poll Status
  let delay = 1000;
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/tasks/${taskId}`, {
      headers: { 'X-Task-Access-Token': accessToken }
    });
    const statusData = await statusRes.json() as TaskStatusResponse;

    if (statusData.status === 'COMPLETED') break;
    if (statusData.status === 'FAILED') {
      throw new Error(`Task failed: ${statusData.error} (${statusData.code})`);
    }

    await new Promise(resolve => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 10000);
  }

  // 3. Download Result
  const downloadRes = await fetch(`${BASE_URL}/tasks/${taskId}/download`, {
    headers: { 'X-Task-Access-Token': accessToken }
  });
  
  if (!downloadRes.ok) {
    throw new Error('Failed to download result');
  }
  
  const arrayBuffer = await downloadRes.arrayBuffer();
  return Buffer.from(arrayBuffer);
}

Error Handling

Always check the response status and handle potential errors. The API returns JSON with error and code fields when a request fails.

Best Practices

Implement exponential backoff for polling (as shown in the example).
Files are limited to 20MB.
Tasks have a TTL of 1 hour. Download your results promptly.
Do not expose your API key in client-side code.

Webhooks

Webhooks for task completion are Coming Soon. For now, please use polling.