SDKsTypeScript

TypeScript SDK

Official TypeScript/JavaScript SDK for FirstHandAPI.

Installation

npm install @firsthand/sdk

Quick Start

import { FirstHandClient } from '@firsthand/sdk';
 
const client = new FirstHandClient({ apiKey: 'fh_live_...' });
 
// Post a job
const job = await client.createJob({
  type: 'data_collection',
  description: 'Take a clear photo of any coffee cup from above. Must show the full cup.',
  files_needed: 50,
  accepted_formats: ['image/jpeg', 'image/png'],
  price_per_file_cents: 75,
});
 
// Get approved files
const files = await client.getJobFiles(job.id);

Configuration

const client = new FirstHandClient({
  apiKey: 'fh_live_...',
  baseUrl: 'https://api.firsthandapi.com', // default
  timeout: 30_000,                          // 30s default
  maxRetries: 3,                            // default
});

Features

  • Auto-retry — Exponential backoff with jitter on 429 and 5xx errors
  • Idempotency — Automatic UUID generation for all POST requests
  • Webhook verification — verifyWebhookSignature() with timing-safe comparison

Methods

Jobs

  • createJob(body) — Post a content collection job
  • getJob(jobId) — Get job by ID
  • listJobs(params?) — List jobs with filters
  • cancelJob(jobId) — Cancel an open job
  • getJobFiles(jobId, params?) — Get approved files for a job
  • getJobSubmissions(jobId, params?) — List all submissions for a job

Submissions

  • listSubmissions(params?) — List submissions across all jobs
  • getSubmission(submissionId) — Get submission by ID
  • getSubmissionSummary(params?) — Aggregate submission metrics

API Keys

  • createApiKey(body) — Create a new API key
  • listApiKeys() — List API keys
  • rotateApiKey(keyId) — Rotate with 24h overlap
  • revokeApiKey(keyId) — Revoke immediately

Webhooks

  • createWebhookEndpoint(body) — Create endpoint
  • listWebhookEndpoints() — List endpoints
  • getWebhookEndpoint(id) — Get endpoint
  • updateWebhookEndpoint(id, body) — Update endpoint
  • deleteWebhookEndpoint(id) — Delete endpoint
  • rotateWebhookSecret(id) — Rotate signing secret

Webhook Events

  • listWebhookEvents() — List events
  • replayWebhookEvent(id) — Replay an event

Billing

  • getCreditBalance() — Current credit balance
  • listTransactions() — Transaction history
  • purchaseCredits(body) — Initiate Stripe Checkout

Organization

  • getSettings() — Get org settings
  • updateSettings(body) — Update org settings
Webhook HandlingPython