Developers

TypeScript SDK

@credcheck/sdk is a typed client for Node.js 18 and later. It handles authentication, errors, pagination, overload retries and webhook signatures.

Install

shell

npm install @credcheck/sdk

Package availability on npm: [[CONFIRM NPM PUBLICATION BEFORE LAUNCH]]

Server-side only

Never use the SDK with an API key in a browser or mobile app.

Create a client

typescript

import { CredCheck } from '@credcheck/sdk';

const cc = new CredCheck({
  apiKey: process.env.CREDCHECK_API_KEY,
  // Production is https://api.credchek.com. Use the sandbox with cc_test_ keys:
  baseUrl: 'https://api.sandbox.credchek.com',
});

Verify a code

Verification is public, so it works without an API key.

typescript

const result = await cc.verify.check({ code: 'ABCDE-FGHJK-LMNPQ' });

switch (result.outcome) {
  case 'verified':
    // The code and product record match.
    break;
  case 'unable_to_verify':
    // No conclusive match. This is not a verdict that the product is fake.
    break;
  case 'suspected_counterfeit':
  case 'recalled':
  case 'expired':
    // Show the safety guidance for this outcome.
    break;
}
console.log(result.referenceId);

Products and batches

typescript

const product = await cc.products.create({
  name: 'Paracetamol 500mg',
  sku: 'PARA-500',
  category: 'pharmaceuticals',
});

const batch = await cc.products.createBatch(product.id, {
  batchNumber: 'B2026-001',
  expiryDate: '2028-12-31',
});

// Iterate every product; pages are fetched as you go.
for await (const p of cc.products.iterate()) {
  console.log(p.sku);
}

Generate and download codes

typescript

const { jobId } = await cc.codes.generate({
  batchId: batch.id,
  quantity: 10000,
  codeType: 'qr',
  idempotencyKey: 'B2026-001-run-1', // safe to retry
});

await cc.codes.jobs.waitForCompletion(jobId);

// Plaintext serials (CSV). Single use: store it securely straight away.
const csv = await cc.codes.jobs.download(jobId);

Handle errors

Every failure is a CredCheckError with a stable code, the HTTP status (0 when no response was received) and, for 429 and 503, retryAfterSeconds.

typescript

import { CredCheckError } from '@credcheck/sdk';

try {
  await cc.products.create({ name: 'Example', sku: 'EX-1', category: 'other' });
} catch (err) {
  if (err instanceof CredCheckError) {
    if (err.status === 429) {
      console.warn(`Rate limited. Try again in ${err.retryAfterSeconds}s.`);
    } else if (err.code === 'insufficient_scope') {
      console.error('This key needs the products:write scope.');
    } else {
      console.error(err.code, err.status, err.message);
    }
  } else {
    throw err;
  }
}

The SDK retries safe requests (reads and POST /v1/verify) once when the API returns 503 overloaded, after Retry-After plus jitter. It never retries other writes automatically.

Verify webhooks

typescript

import { verifyWebhookSignature } from '@credcheck/sdk';

const ok = verifyWebhookSignature({
  payload: rawBody, // the raw request body, not re-serialised JSON
  header: request.headers['x-credcheck-signature'],
  secret: process.env.CREDCHECK_WEBHOOK_SECRET!,
});
if (!ok) return reply.status(400).send();

Next: API reference