Skip to content
Survey Coder Pro Survey Coder Pro

TypeScript SDK

The TypeScript SDK wraps the Survey Coder Pro REST API with full type safety, automatic retries, and idempotency-key handling.

Install

Section titled “Install”
Terminal window
npm install surveycoder-sdk
# or
pnpm add surveycoder-sdk
# or
yarn add surveycoder-sdk

Requires Node 18+ (uses the built-in fetch). Also works in Bun, Deno, Cloudflare Workers, and modern browsers — anywhere fetch exists.

Quickstart

Section titled “Quickstart”
import { SurveyCoder } from 'surveycoder-sdk';


const sc = new SurveyCoder({
  apiKey: process.env.SCP_API_KEY!,
});


const result = await sc.code({
  question: 'Which brand of laundry detergent do you prefer and why?',
  responses: [
    'Tide because it removes stains better',
    'Ariel - bigger pack, lasts longer',
    'Persil because my mom always used it',
  ],
});


console.log(result.codebook);

Constructor options

Section titled “Constructor options”
new SurveyCoder({
  apiKey: string;                        // required
  baseUrl?: string;                      // default: 'https://api.surveycoder.io'
  timeoutMs?: number;                    // default: 60_000
  maxRetries?: number;                   // default: 2 (on 5xx and 429)
  defaultIdempotencyKey?: 'auto' | 'off' // default: 'auto' — generates a UUID per mutating call
  fetch?: typeof globalThis.fetch;       // inject a custom fetch (e.g. for Cloudflare Workers)
})

Sub-clients

Section titled “Sub-clients”

The client groups endpoints by resource:

Sub-clientWhat it does
sc.code()The one-call hero. POST /v1/code.
sc.projectsCRUD on projects and questions.
sc.jobsGet, list, and wait for async jobs.
sc.codebooksGenerate, import, clone, estimate.
sc.qualityCross-coder consistency.
sc.refinementsList, apply, and resolve refinement suggestions.
sc.usageRead credit balance and history.
sc.webhooksRegister and rotate webhooks.

Waiting for async jobs

Section titled “Waiting for async jobs”
const { job_id } = await sc.code({ /* >= 50 responses */ });


const result = await sc.jobs.wait(job_id, {
  pollInterval: 3000,   // ms
  timeout: 600_000,     // 10 minutes
});


console.log(result.codebook);

sc.jobs.wait resolves with the data.result payload, or throws if the job ends with status: 'failed'. Internally it uses GET /v1/jobs/{id} and respects the Retry-After header.

Errors

Section titled “Errors”

Every error thrown by the SDK is an instance of SurveyCoderError and carries the structured envelope from the API:

import { SurveyCoder, SurveyCoderError } from 'surveycoder-sdk';


try {
  await sc.code({ /* ... */ });
} catch (err) {
  if (err instanceof SurveyCoderError) {
    console.error(err.code);       // e.g. 'INSUFFICIENT_CREDITS'
    console.error(err.message);
    console.error(err.requestId);  // 'req_01HXJZK4...'
    console.error(err.docUrl);     // 'https://docs.surveycoder.io/errors/...'
    console.error(err.status);     // HTTP status
  } else {
    throw err;
  }
}

Browse every code in the error reference.

TypeScript

Section titled “TypeScript”

The SDK ships with full types generated from the OpenAPI spec. Request and response shapes are exported:

import type {
  CodeRequest,
  CodeResponse,
  Codebook,
  CodedRow,
} from 'surveycoder-sdk';

Edge runtimes

Section titled “Edge runtimes”

For Cloudflare Workers, Vercel Edge, and Deno Deploy, inject the platform’s fetch and avoid Node-only modules:

const sc = new SurveyCoder({
  apiKey: env.SCP_API_KEY,
  fetch: globalThis.fetch,
});
Section titled “Related”