API Cookbook

import axios, { AxiosInstance } from 'axios';
import * as fs from 'fs';
import * as path from 'path';

interface Workspace {
  id: number;
  name: string;
  icon: string;
}

interface Template {
  id: string;
  name: string;
  description?: string;
}

interface Session {
  id: string;
  name: string;
  created_at: string;
}

interface ExtractionResult {
  id: string;
  status: 'created' | 'processing' | 'completed' | 'failed';
  data: Record<string, any>;
  reasoning?: Record<string, any>;
}

class RaydocsClient {
  private client: AxiosInstance;

  constructor(apiKey: string, baseUrl: string = 'https://api.raydocs.com') {
    this.client = axios.create({
      baseURL: baseUrl,
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
    });
  }

  // ─────────────────────────────────────────────────────────────
  // Workspaces
  // ─────────────────────────────────────────────────────────────

  async createWorkspace(name: string, icon: string = '📊'): Promise<Workspace> {
    const { data } = await this.client.post('/workspaces/create', { name, icon });
    return data;
  }

  async listWorkspaces(): Promise<Workspace[]> {
    const { data } = await this.client.get('/workspaces');
    return data.data;
  }

  // ─────────────────────────────────────────────────────────────
  // Templates
  // ─────────────────────────────────────────────────────────────

  async createTemplate(
    workspaceId: number,
    name: string,
    schema: object,
    description?: string
  ): Promise<Template> {
    const { data } = await this.client.post('/extractions/templates', {
      workspace_id: workspaceId,
      name,
      schema_json: schema,
      description,
    });
    return data;
  }

  async listTemplates(workspaceId: number): Promise<Template[]> {
    const { data } = await this.client.get(
      `/workspaces/${workspaceId}/extractions/templates`
    );
    return data.data;
  }

  // ─────────────────────────────────────────────────────────────
  // File Upload
  // ─────────────────────────────────────────────────────────────

  async getUploadUrl(
    contentType: string = 'application/pdf'
  ): Promise<{ url: string; key: string; headers: Record<string, string> }> {
    const { data } = await this.client.post('/vapor/signed-storage-url', {
      content_type: contentType,
      visibility: 'private',
    });
    return data;
  }

  async uploadFile(filePath: string): Promise<string> {
    const filename = path.basename(filePath);
    const ext = filename.toLowerCase().split('.').pop();

    const contentTypes: Record<string, string> = {
      pdf: 'application/pdf',
      png: 'image/png',
      jpg: 'image/jpeg',
      jpeg: 'image/jpeg',
    };
    const contentType = contentTypes[ext || ''] || 'application/octet-stream';

    // Get signed upload URL
    const uploadData = await this.getUploadUrl(contentType);

    // Upload file directly to S3
    const fileBuffer = fs.readFileSync(filePath);
    await axios.put(uploadData.url, fileBuffer, {
      headers: {
        'Content-Type': contentType,
        ...uploadData.headers,
      },
    });

    return uploadData.key;
  }

  // ─────────────────────────────────────────────────────────────
  // Batch Operations
  // ─────────────────────────────────────────────────────────────

  async batchCreateSessions(
    templateId: string,
    fileKeys: string[],
    autoExtract: boolean = true
  ): Promise<Session[]> {
    const { data } = await this.client.post(
      `/extractions/templates/${templateId}/sessions/batch`,
      {
        files: fileKeys,
        settings: {
          auto_extract: autoExtract,
        },
      }
    );
    return data;
  }

  // ─────────────────────────────────────────────────────────────
  // Sessions & Results
  // ─────────────────────────────────────────────────────────────

  async getSession(sessionId: string): Promise<any> {
    const { data } = await this.client.get(`/extractions/sessions/${sessionId}`);
    return data;
  }

  async getResults(sessionId: string): Promise<ExtractionResult[]> {
    const { data } = await this.client.get(
      `/extractions/sessions/${sessionId}/results`
    );
    return data.data;
  }

  async getResult(resultId: string): Promise<ExtractionResult> {
    const { data } = await this.client.get(`/extractions/results/${resultId}`);
    return data;
  }

  async waitForCompletion(
    sessionId: string,
    timeout: number = 300000,
    pollInterval: number = 5000
  ): Promise<ExtractionResult> {
    const start = Date.now();

    while (Date.now() - start < timeout) {
      const results = await this.getResults(sessionId);

      if (results.length > 0) {
        const result = results[0];

        if (result.status === 'completed') {
          return this.getResult(result.id);
        } else if (result.status === 'failed') {
          throw new Error(`Extraction failed`);
        }
      }

      console.log(`Status: Processing... (${Math.floor((Date.now() - start) / 1000)}s)`);
      await new Promise((resolve) => setTimeout(resolve, pollInterval));
    }

    throw new Error(`Extraction did not complete within ${timeout / 1000}s`);
  }
}

// ═══════════════════════════════════════════════════════════════════
// Example Usage
// ═══════════════════════════════════════════════════════════════════

async function main() {
  const client = new RaydocsClient('your_api_token_here');

  // Step 1: Get or create workspace
  let workspaces = await client.listWorkspaces();
  let workspace: Workspace;

  if (workspaces.length > 0) {
    workspace = workspaces[0];
    console.log(`Using existing workspace: ${workspace.name}`);
  } else {
    workspace = await client.createWorkspace('My Extraction Project', '📄');
    console.log(`Created workspace: ${workspace.name}`);
  }

  // Step 2: Create template
  const invoiceSchema = {
    config: {
      reasoning_enabled: true,
      system_message: 'Extract invoice data accurately. Return null for missing fields.',
    },
    groups: {
      invoice_header: {
        search_query: 'invoice number, date, due date, total amount',
        fields: {
          invoice_number: {
            type: 'string',
            extraction_prompt: 'Extract the invoice number or ID',
          },
          invoice_date: {
            type: 'string',
            extraction_prompt: 'Extract the invoice date in YYYY-MM-DD format',
          },
          total_amount: {
            type: 'number',
            extraction_prompt: 'Extract the total amount due as a number',
          },
          currency: {
            type: 'string',
            extraction_prompt: 'Extract the currency code (USD, EUR, etc.)',
          },
        },
      },
      vendor_info: {
        search_query: 'vendor, supplier, company name, address',
        fields: {
          vendor_name: {
            type: 'string',
            extraction_prompt: 'Extract the vendor/supplier company name',
          },
        },
      },
    },
  };

  const template = await client.createTemplate(
    workspace.id,
    'Invoice Extractor',
    invoiceSchema,
    'Extracts key data from invoices'
  );
  console.log(`Created template: ${template.name} (${template.id})`);

  // Step 3: Upload documents with auto-extract
  const documents = ['invoice1.pdf', 'invoice2.pdf'];
  const fileKeys: string[] = [];

  for (const docPath of documents) {
    console.log(`Uploading: ${docPath}`);
    const key = await client.uploadFile(docPath);
    fileKeys.push(key);
    console.log(`  → Uploaded as: ${key}`);
  }

  const sessions = await client.batchCreateSessions(
    template.id,
    fileKeys,
    true // auto_extract enabled
  );
  console.log(`Created ${sessions.length} sessions with auto-extraction enabled`);

  // Step 4: Wait for results
  for (const session of sessions) {
    console.log(`\nWaiting for session ${session.id}...`);

    try {
      const result = await client.waitForCompletion(session.id);

      console.log('✅ Extraction complete!');
      console.log(`   Invoice #: ${result.data.invoice_header?.invoice_number}`);
      console.log(`   Total: ${result.data.invoice_header?.total_amount}`);
      console.log(`   Vendor: ${result.data.vendor_info?.vendor_name}`);
    } catch (error) {
      console.log(`❌ Error: ${error}`);
    }
  }
}

main().catch(console.error);

#!/bin/bash

# Configuration
API_KEY="your_api_token_here"
BASE_URL="https://api.raydocs.com"

# Helper function for API calls
api_call() {
    local method=$1
    local endpoint=$2
    local data=$3
    
    curl -s -X "$method" "$BASE_URL$endpoint" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        ${data:+-d "$data"}
}

# ─────────────────────────────────────────────────────────────────
# Step 1: List workspaces (or create one)
# ─────────────────────────────────────────────────────────────────
echo "📁 Listing workspaces..."
WORKSPACES=$(api_call GET "/workspaces")
WORKSPACE_ID=$(echo "$WORKSPACES" | jq -r '.data[0].id')

if [ "$WORKSPACE_ID" == "null" ] || [ -z "$WORKSPACE_ID" ]; then
    echo "Creating new workspace..."
    WORKSPACE=$(api_call POST "/workspaces/create" '{"name": "API Cookbook", "icon": "📄"}')
    WORKSPACE_ID=$(echo "$WORKSPACE" | jq -r '.id')
fi

echo "Using workspace ID: $WORKSPACE_ID"

# ─────────────────────────────────────────────────────────────────
# Step 2: Create an extraction template
# ─────────────────────────────────────────────────────────────────
echo ""
echo "📋 Creating extraction template..."

TEMPLATE_SCHEMA='{
    "workspace_id": '"$WORKSPACE_ID"',
    "name": "Invoice Extractor",
    "description": "Extracts key invoice data",
    "schema_json": {
        "config": {
            "reasoning_enabled": true
        },
        "groups": {
            "invoice_header": {
                "search_query": "invoice number, date, total amount",
                "fields": {
                    "invoice_number": {
                        "type": "string",
                        "extraction_prompt": "Extract the invoice number"
                    },
                    "total_amount": {
                        "type": "number",
                        "extraction_prompt": "Extract the total amount"
                    }
                }
            }
        }
    }
}'

TEMPLATE=$(api_call POST "/extractions/templates" "$TEMPLATE_SCHEMA")
TEMPLATE_ID=$(echo "$TEMPLATE" | jq -r '.id')
echo "Created template: $TEMPLATE_ID"

# ─────────────────────────────────────────────────────────────────
# Step 3: Upload a file
# ─────────────────────────────────────────────────────────────────
echo ""
echo "📤 Getting upload URL..."

UPLOAD_DATA=$(api_call POST "/vapor/signed-storage-url" '{
    "content_type": "application/pdf",
    "visibility": "private"
}')

UPLOAD_URL=$(echo "$UPLOAD_DATA" | jq -r '.url')
FILE_KEY=$(echo "$UPLOAD_DATA" | jq -r '.key')

echo "Uploading file to S3..."
curl -s -X PUT "$UPLOAD_URL" \
    -H "Content-Type: application/pdf" \
    --data-binary @"invoice.pdf"

echo "File key: $FILE_KEY"

# ─────────────────────────────────────────────────────────────────
# Step 4: Batch create session with auto-extract
# ─────────────────────────────────────────────────────────────────
echo ""
echo "🚀 Creating session with auto-extract..."

SESSIONS=$(api_call POST "/extractions/templates/$TEMPLATE_ID/sessions/batch" "{
    \"files\": [\"$FILE_KEY\"],
    \"settings\": {
        \"auto_extract\": true
    }
}")

SESSION_ID=$(echo "$SESSIONS" | jq -r '.[0].id')
echo "Created session: $SESSION_ID"

# ─────────────────────────────────────────────────────────────────
# Step 5: Poll for completion
# ─────────────────────────────────────────────────────────────────
echo ""
echo "⏳ Waiting for extraction to complete..."

for i in {1..60}; do
    RESULTS=$(api_call GET "/extractions/sessions/$SESSION_ID/results")
    STATUS=$(echo "$RESULTS" | jq -r '.data[0].status // "pending"')
    
    echo "  Status: $STATUS"
    
    if [ "$STATUS" == "completed" ]; then
        RESULT_ID=$(echo "$RESULTS" | jq -r '.data[0].id')
        echo ""
        echo "✅ Extraction complete!"
        
        # Get full result
        RESULT=$(api_call GET "/extractions/results/$RESULT_ID")
        echo "$RESULT" | jq '.data'
        break
    elif [ "$STATUS" == "failed" ]; then
        echo "❌ Extraction failed"
        break
    fi
    
    sleep 5
done