@verifyapi/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,478 @@
+/**
+ * @module @firsthandapi/sdk/client
+ * @description FirstHandAPI TypeScript SDK client.
+ * Typed client wrapping all v1 REST endpoints with auto-retry,
+ * idempotency key generation, and proper error handling.
+ *
+ * @example
+ * ```ts
+ * import { FirstHandClient } from '@firsthandapi/sdk';
+ *
+ * const client = new FirstHandClient({ apiKey: 'fh_live_...' });
+ * const job = await client.createJob({
+ *   job_type: 'product_photo',
+ *   title: 'Product photo for listing #1234',
+ *   instructions: 'Take a clean photo of the product on white background',
+ * });
+ * ```
+ *
+ * @see api-contract.md — Full API specification
+ */
+
+import type { Static } from '@sinclair/typebox';
+import type {
+  CreateJobRequest,
+  JobResponse,
+  JobListParams,
+  CreateApiKeyRequest,
+  CreateApiKeyResponse,
+  ApiKeyListItem,
+  RotateApiKeyResponse,
+  CreateWebhookEndpointRequest,
+  WebhookEndpointResponse,
+  UpdateWebhookEndpointRequest,
+  RotateWebhookSecretResponse,
+  WebhookEventResponse,
+  CreditBalanceResponse,
+  CreditTransaction,
+  PurchaseCreditsRequest,
+  PurchaseCreditsResponse,
+} from '@verifyapi/api-contracts';
+import { FirstHandApiError, FirstHandConnectionError, type FirstHandErrorDetail } from './errors.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────
+
+export interface FirstHandClientOptions {
+  /** API key (fh_live_* or fh_test_*) */
+  apiKey: string;
+  /** Base URL (default: https://api.firsthandapi.com) */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeoutMs?: number;
+  /** Maximum retry attempts for retryable errors (default: 3) */
+  maxRetries?: number;
+  /** Custom fetch implementation (default: global fetch) */
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface ListResponse<T> {
+  object: 'list';
+  data: T[];
+  has_more: boolean;
+  next_cursor: string | null;
+}
+
+export interface ListOptions {
+  [key: string]: unknown;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface GetJobOptions {
+  /** Long-poll: wait up to N seconds for job to complete (max 60) */
+  waitSeconds?: number;
+}
+
+// ─── Client ─────────────────────────────────────────────────────────────
+
+const DEFAULT_BASE_URL = 'https://api.firsthandapi.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 1_000;
+
+export class FirstHandClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+  private readonly fetchFn: typeof globalThis.fetch;
+
+  constructor(options: FirstHandClientOptions) {
+    if (!options.apiKey) {
+      throw new Error('apiKey is required');
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  // ── Jobs ───────────────────────────────────────────────────────────
+
+  /** Create a new job for content collection */
+  async createJob(
+    body: Static<typeof CreateJobRequest>,
+    idempotencyKey?: string,
+  ): Promise<Static<typeof JobResponse>> {
+    const key = idempotencyKey ?? generateIdempotencyKey();
+    return this.request('POST', '/v1/jobs', {
+      body,
+      headers: { 'Idempotency-Key': key },
+      expectedStatus: 201,
+    });
+  }
+
+  /** Get a job by ID. Supports long-polling via waitSeconds option. */
+  async getJob(
+    jobId: string,
+    options?: GetJobOptions,
+  ): Promise<Static<typeof JobResponse>> {
+    const headers: Record<string, string> = {};
+    if (options?.waitSeconds) {
+      headers['Prefer'] = `wait=${Math.min(options.waitSeconds, 60)}`;
+    }
+    return this.request('GET', `/v1/jobs/${jobId}`, { headers });
+  }
+
+  /** List jobs with optional filters */
+  async listJobs(
+    params?: Static<typeof JobListParams>,
+  ): Promise<ListResponse<Static<typeof JobResponse>>> {
+    return this.request('GET', '/v1/jobs', { query: params });
+  }
+
+  /** Get audit trail for a job */
+  async getJobAudit(
+    jobId: string,
+  ): Promise<Record<string, unknown>> {
+    return this.request('GET', `/v1/jobs/${jobId}/audit`);
+  }
+
+  /** Cancel a pending job */
+  async cancelJob(
+    jobId: string,
+  ): Promise<Static<typeof JobResponse>> {
+    return this.request('POST', `/v1/jobs/${jobId}/cancel`, {
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+    });
+  }
+
+  /** Get files associated with a job (approved submissions with download URLs) */
+  async getJobFiles(
+    jobId: string,
+  ): Promise<ListResponse<unknown>> {
+    return this.request('GET', `/v1/jobs/${jobId}/files`);
+  }
+
+  /** Get submissions for a job */
+  async getJobSubmissions(
+    jobId: string,
+  ): Promise<ListResponse<unknown>> {
+    return this.request('GET', `/v1/jobs/${jobId}/submissions`);
+  }
+
+  /** Rate a completed job (1-5 stars with optional feedback) */
+  async rateJob(
+    jobId: string,
+    body: { rating: number; feedback?: string },
+  ): Promise<Static<typeof JobResponse>> {
+    return this.request('POST', `/v1/jobs/${jobId}/rate`, { body });
+  }
+
+  /**
+   * Create a job and wait for it to complete.
+   * Polls using long-poll until the job reaches a terminal state or timeout.
+   *
+   * @param body - Job creation request
+   * @param maxWaitSeconds - Maximum total wait time (default: 120)
+   * @param pollIntervalSeconds - Long-poll interval per request (default: 30)
+   */
+  async createJobAndWait(
+    body: Static<typeof CreateJobRequest>,
+    maxWaitSeconds = 120,
+    pollIntervalSeconds = 30,
+  ): Promise<Static<typeof JobResponse>> {
+    const job = await this.createJob(body);
+
+    const terminalStatuses = new Set(['resolved', 'completed', 'timed_out', 'failed', 'cancelled']);
+    if (terminalStatuses.has(job.status)) {
+      return job;
+    }
+
+    const deadline = Date.now() + maxWaitSeconds * 1000;
+
+    while (Date.now() < deadline) {
+      const remaining = Math.ceil((deadline - Date.now()) / 1000);
+      const waitSeconds = Math.min(pollIntervalSeconds, remaining, 60);
+
+      if (waitSeconds <= 0) break;
+
+      const updated = await this.getJob(job.id, { waitSeconds });
+      if (terminalStatuses.has(updated.status)) {
+        return updated;
+      }
+    }
+
+    // Return latest state even if not terminal
+    return this.getJob(job.id);
+  }
+
+  // ── API Keys ────────────────────────────────────────────────────────
+
+  /** Create a new API key */
+  async createApiKey(
+    body: Static<typeof CreateApiKeyRequest>,
+  ): Promise<Static<typeof CreateApiKeyResponse>> {
+    return this.request('POST', '/v1/api_keys', {
+      body,
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+      expectedStatus: 201,
+    });
+  }
+
+  /** List API keys (secrets masked) */
+  async listApiKeys(
+    options?: ListOptions,
+  ): Promise<ListResponse<Static<typeof ApiKeyListItem>>> {
+    return this.request('GET', '/v1/api_keys', { query: options });
+  }
+
+  /** Rotate an API key (24h overlap window) */
+  async rotateApiKey(
+    keyId: string,
+  ): Promise<Static<typeof RotateApiKeyResponse>> {
+    return this.request('POST', `/v1/api_keys/${keyId}/rotate`, {
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+    });
+  }
+
+  /** Revoke an API key immediately */
+  async revokeApiKey(keyId: string): Promise<void> {
+    await this.request('POST', `/v1/api_keys/${keyId}/revoke`, {
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+      expectedStatus: 204,
+      parseBody: false,
+    });
+  }
+
+  // ── Webhooks ────────────────────────────────────────────────────────
+
+  /** Create a webhook endpoint */
+  async createWebhookEndpoint(
+    body: Static<typeof CreateWebhookEndpointRequest>,
+  ): Promise<Static<typeof WebhookEndpointResponse>> {
+    return this.request('POST', '/v1/webhook_endpoints', {
+      body,
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+      expectedStatus: 201,
+    });
+  }
+
+  /** List webhook endpoints */
+  async listWebhookEndpoints(
+    options?: ListOptions,
+  ): Promise<ListResponse<Static<typeof WebhookEndpointResponse>>> {
+    return this.request('GET', '/v1/webhook_endpoints', { query: options });
+  }
+
+  /** Get a webhook endpoint by ID */
+  async getWebhookEndpoint(
+    endpointId: string,
+  ): Promise<Static<typeof WebhookEndpointResponse>> {
+    return this.request('GET', `/v1/webhook_endpoints/${endpointId}`);
+  }
+
+  /** Update a webhook endpoint */
+  async updateWebhookEndpoint(
+    endpointId: string,
+    body: Static<typeof UpdateWebhookEndpointRequest>,
+  ): Promise<Static<typeof WebhookEndpointResponse>> {
+    return this.request('PATCH', `/v1/webhook_endpoints/${endpointId}`, { body });
+  }
+
+  /** Delete a webhook endpoint */
+  async deleteWebhookEndpoint(endpointId: string): Promise<void> {
+    await this.request('DELETE', `/v1/webhook_endpoints/${endpointId}`, {
+      expectedStatus: 204,
+      parseBody: false,
+    });
+  }
+
+  /** Rotate webhook signing secret */
+  async rotateWebhookSecret(
+    endpointId: string,
+  ): Promise<Static<typeof RotateWebhookSecretResponse>> {
+    return this.request('POST', `/v1/webhook_endpoints/${endpointId}/rotate_secret`, {
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+    });
+  }
+
+  // ── Webhook Events ─────────────────────────────────────────────────
+
+  /** List webhook events */
+  async listWebhookEvents(
+    options?: ListOptions & { status?: string; event_type?: string },
+  ): Promise<ListResponse<Static<typeof WebhookEventResponse>>> {
+    return this.request('GET', '/v1/webhook_events', { query: options });
+  }
+
+  /** Replay a webhook event */
+  async replayWebhookEvent(
+    eventId: string,
+  ): Promise<Static<typeof WebhookEventResponse>> {
+    return this.request('POST', `/v1/webhook_events/${eventId}/replay`, {
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+      expectedStatus: 202,
+    });
+  }
+
+  // ── Billing ────────────────────────────────────────────────────────
+
+  /** Get current credit balance */
+  async getCreditBalance(): Promise<Static<typeof CreditBalanceResponse>> {
+    return this.request('GET', '/v1/billing/credits');
+  }
+
+  /** List credit transactions */
+  async listTransactions(
+    options?: ListOptions & { type?: string },
+  ): Promise<ListResponse<Static<typeof CreditTransaction>>> {
+    return this.request('GET', '/v1/billing/transactions', { query: options });
+  }
+
+  /** Initiate credit purchase via Stripe Checkout */
+  async purchaseCredits(
+    body: Static<typeof PurchaseCreditsRequest>,
+  ): Promise<Static<typeof PurchaseCreditsResponse>> {
+    return this.request('POST', '/v1/billing/credits/purchase', {
+      body,
+      headers: { 'Idempotency-Key': generateIdempotencyKey() },
+    });
+  }
+
+  // ── HTTP Layer ─────────────────────────────────────────────────────
+
+  private async request<T = unknown>(
+    method: string,
+    path: string,
+    options: {
+      body?: unknown;
+      query?: Record<string, unknown>;
+      headers?: Record<string, string>;
+      expectedStatus?: number;
+      parseBody?: boolean;
+    } = {},
+  ): Promise<T> {
+    const { body, query, headers: extraHeaders, expectedStatus, parseBody = true } = options;
+
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null) {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+      ...extraHeaders,
+    };
+    if (body) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        // Exponential backoff with jitter
+        const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1);
+        const jitter = delay * 0.1 * Math.random();
+        await sleep(delay + jitter);
+      }
+
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+        let response: Response;
+        try {
+          response = await this.fetchFn(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: controller.signal,
+          });
+        } finally {
+          clearTimeout(timer);
+        }
+
+        // Success range
+        if (response.ok) {
+          if (!parseBody || response.status === 204) {
+            return undefined as T;
+          }
+          return (await response.json()) as T;
+        }
+
+        // Check expected status
+        if (expectedStatus && response.status === expectedStatus) {
+          if (!parseBody) return undefined as T;
+          return (await response.json()) as T;
+        }
+
+        // Parse error body
+        let errorBody: { error?: { type: string; message: string; request_id: string; details?: unknown[] } };
+        try {
+          errorBody = (await response.json()) as typeof errorBody;
+        } catch {
+          errorBody = {
+            error: {
+              type: 'unknown',
+              message: `HTTP ${response.status}`,
+              request_id: 'unknown',
+            },
+          };
+        }
+
+        const apiError = new FirstHandApiError(response.status, {
+          type: errorBody.error?.type ?? 'unknown',
+          message: errorBody.error?.message ?? `HTTP ${response.status}`,
+          request_id: errorBody.error?.request_id ?? 'unknown',
+          details: errorBody.error?.details as FirstHandErrorDetail[] | undefined,
+        });
+
+        // Only retry on retryable errors
+        if (!apiError.retryable || attempt >= this.maxRetries) {
+          throw apiError;
+        }
+
+        lastError = apiError;
+      } catch (err) {
+        if (err instanceof FirstHandApiError) throw err;
+
+        const connError = new FirstHandConnectionError(
+          `Connection failed: ${(err as Error).message}`,
+          err as Error,
+        );
+
+        if (attempt >= this.maxRetries) throw connError;
+        lastError = connError;
+      }
+    }
+
+    throw lastError ?? new FirstHandConnectionError('Request failed after retries');
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Generates a random idempotency key (UUID v4 format) */
+export function generateIdempotencyKey(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80; // variant 1
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/errors.ts

@@ -0,0 +1,55 @@
+/**
+ * @module @firsthandapi/sdk/errors
+ * @description SDK error types for FirstHandAPI API responses.
+ */
+
+export interface FirstHandErrorDetail {
+  field?: string;
+  message: string;
+  code?: string;
+}
+
+export interface FirstHandErrorBody {
+  type: string;
+  message: string;
+  request_id: string;
+  details?: FirstHandErrorDetail[];
+}
+
+/**
+ * Error thrown when FirstHandAPI returns a non-2xx response.
+ * Contains the parsed error envelope from the response body.
+ */
+export class FirstHandApiError extends Error {
+  readonly status: number;
+  readonly type: string;
+  readonly requestId: string;
+  readonly details?: FirstHandErrorDetail[];
+
+  constructor(status: number, body: FirstHandErrorBody) {
+    super(body.message);
+    this.name = 'FirstHandApiError';
+    this.status = status;
+    this.type = body.type;
+    this.requestId = body.request_id;
+    this.details = body.details;
+  }
+
+  /** True if the error is retryable (429, 500, 502, 503, 504) */
+  get retryable(): boolean {
+    return this.status === 429 || this.status >= 500;
+  }
+}
+
+/**
+ * Error thrown when a network failure or timeout occurs.
+ */
+export class FirstHandConnectionError extends Error {
+  readonly cause?: Error;
+
+  constructor(message: string, cause?: Error) {
+    super(message);
+    this.name = 'FirstHandConnectionError';
+    this.cause = cause;
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @module @firsthandapi/sdk
+ * @description TypeScript SDK for the FirstHandAPI REST API.
+ * Typed client wrapping all v1 endpoints with auto-retry,
+ * idempotency key generation, and webhook signature verification.
+ *
+ * @example
+ * ```ts
+ * import { FirstHandClient } from '@firsthandapi/sdk';
+ *
+ * const client = new FirstHandClient({ apiKey: 'fh_live_...' });
+ * const job = await client.createJob({
+ *   job_type: 'product_photo',
+ *   title: 'Product photo for listing #1234',
+ *   instructions: 'Take a clean photo of the product on white background',
+ * });
+ * ```
+ */
+
+export { FirstHandClient, generateIdempotencyKey } from './client.js';
+export type { FirstHandClientOptions, ListResponse, ListOptions, GetJobOptions } from './client.js';
+export { FirstHandApiError, FirstHandConnectionError } from './errors.js';
+export type { FirstHandErrorBody, FirstHandErrorDetail } from './errors.js';
+export { verifyWebhookSignature } from './webhooks.js';

package/src/webhooks.ts

@@ -0,0 +1,69 @@
+/**
+ * @module @firsthandapi/sdk/webhooks
+ * @description Webhook signature verification for FirstHandAPI webhook events.
+ * Clients use this to verify that webhook payloads were sent by FirstHandAPI.
+ *
+ * @see webhook-contract.md — Webhook signing specification
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * Verifies a webhook signature from FirstHandAPI.
+ *
+ * @param payload - Raw request body (string or Buffer)
+ * @param signature - Value of the `X-FirstHandAPI-Signature` header
+ * @param secret - Webhook signing secret from endpoint creation
+ * @param toleranceSeconds - Maximum age of the event in seconds (default: 300 = 5 minutes)
+ * @returns true if the signature is valid
+ * @throws Error if signature is invalid, expired, or malformed
+ */
+export function verifyWebhookSignature(
+  payload: string | Buffer,
+  signature: string,
+  secret: string,
+  toleranceSeconds = 300,
+): boolean {
+  // Parse signature: "t=<timestamp>,v1=<hash>"
+  const parts = signature.split(',');
+  const timestampPart = parts.find((p) => p.startsWith('t='));
+  const hashPart = parts.find((p) => p.startsWith('v1='));
+
+  if (!timestampPart || !hashPart) {
+    throw new Error('Invalid webhook signature format. Expected "t=<timestamp>,v1=<hash>"');
+  }
+
+  const timestamp = parseInt(timestampPart.slice(2), 10);
+  const expectedHash = hashPart.slice(3);
+
+  if (isNaN(timestamp)) {
+    throw new Error('Invalid timestamp in webhook signature');
+  }
+
+  // Check tolerance
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - timestamp) > toleranceSeconds) {
+    throw new Error(
+      `Webhook timestamp too old (${Math.abs(now - timestamp)}s, tolerance: ${toleranceSeconds}s)`,
+    );
+  }
+
+  // Compute expected signature
+  const body = typeof payload === 'string' ? payload : payload.toString('utf8');
+  const signedPayload = `${timestamp}.${body}`;
+  const computedHash = createHmac('sha256', secret).update(signedPayload).digest('hex');
+
+  // Timing-safe comparison
+  const expected = Buffer.from(expectedHash, 'hex');
+  const computed = Buffer.from(computedHash, 'hex');
+
+  if (expected.length !== computed.length) {
+    throw new Error('Webhook signature verification failed');
+  }
+
+  if (!timingSafeEqual(expected, computed)) {
+    throw new Error('Webhook signature verification failed');
+  }
+
+  return true;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+}