Process Historical Sync

Background worker function invoked on a schedule (cron) that claims pending or in-progress historical sync jobs and imports call data from the Ultravox API in paginated batches. Each invocation processes up to 3 jobs, with each job fetching up to 50 calls per batch (configurable via max_calls).

Endpoint

Property	Value
Function Name	process-historical-sync
HTTP Method	Any (no method restriction)
Authentication	None (cron/internal invocation). No JWT or user authentication is performed.
Required Role	None (cron)

Request

Headers

No headers are required. This function is designed to be invoked by a Supabase cron scheduler or internal trigger without user authentication.

Body

No request body is expected. The function discovers work by claiming pending jobs from the database.

Response

Success -- Jobs Processed (200)

{
  "results": [
    {
      "job_id": "uuid-1",
      "status": "in_progress",
      "imported": 12,
      "skipped": 3,
      "failed": 0,
      "cursor": "next-page-cursor"
    },
    {
      "job_id": "uuid-2",
      "status": "completed",
      "imported": 8,
      "skipped": 1,
      "failed": 0,
      "reason": "all_calls_fetched"
    }
  ]
}

Success -- No Pending Jobs (200)

{
  "processed": 0,
  "message": "No pending jobs"
}

Error Response -- Job Failure

When an individual job fails, it is recorded in the results array alongside successful jobs:

{
  "results": [
    {
      "job_id": "uuid-3",
      "error": "Agency API key not configured"
    }
  ]
}

Error Responses

Status	Condition
200	Always returns 200 for per-job results, even when individual jobs fail (failures are reported in the response body)
500	Unhandled top-level exception (not specific to a single job)

Behavior

1. Claim jobs: Calls claim_sync_jobs_batch RPC to atomically claim up to 3 pending/in-progress sync jobs, preventing concurrent workers from processing the same job.
2. Per-job processing:
   • Retrieves the agency's encrypted Ultravox API key from the agencies table.
   • Decrypts the key via decrypt_api_key RPC.
   • Calls the Ultravox GET /api/calls endpoint with pagination (cursor), date filters (created_after / created_before), and a batch size of up to 50 calls.
   • For each returned call:
     • Skips calls that have not ended (no ended timestamp).
     • Calls upsert_call_from_sync RPC to insert or update the call in the database.
   • Extracts the cursor from the next URL in the Ultravox response for pagination.
   • Updates job progress via update_sync_job_progress RPC.
3. Completion conditions (calls complete_sync_job RPC):
   • The total number of imported calls reaches the job's max_calls limit (default: 100).
   • No more pages of results are available (no next cursor or results count is less than batch size).
4. Failure handling: On per-job error, calls fail_sync_job RPC with the error message.

Constants

Constant	Value	Description
CALLS_PER_BATCH	50	Maximum calls fetched from Ultravox per batch
DEFAULT_MAX_CALLS	100	Default limit on total imported calls per job if max_calls is not set

Database Tables / RPCs

Table / RPC	Operation	Description
claim_sync_jobs_batch (RPC)	Read/Write	Atomically claims up to N pending jobs
agencies	Read	Fetches encrypted Ultravox API key
decrypt_api_key (RPC)	Read	Decrypts the agency's stored API key
upsert_call_from_sync (RPC)	Write	Inserts or updates a call record
update_sync_job_progress (RPC)	Write	Updates job cursor, counters, and total
complete_sync_job (RPC)	Write	Marks a job as completed
fail_sync_job (RPC)	Write	Marks a job as failed with an error message

External APIs

API	Method	Endpoint	Description
Ultravox	GET	/api/calls	Lists calls with pagination, date range filters

Related Functions

• start-historical-sync -- Creates new sync jobs for this function to process
• cancel-historical-sync -- Cancels a running or pending sync job
• get-sync-status -- Retrieves progress information for active and recent sync jobs