Introduction

# Browser SDK for opening the widget in your frontend.
# Server-side calls go directly to the REST API. No separate package.
npm install transcrypts
# or
yarn add transcrypts
# or
pnpm add transcrypts

// On your server
const response = await fetch(
  `${process.env.TRANSCRYPTS_BASE_URL}/api/sdk/v1/verification_sessions`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TRANSCRYPTS_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      applicant_hint: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'john@example.com',
      },
      metadata: { your_internal_id: 'LN_12345' },
      return_url: 'https://yourapp.com/verified',
    }),
  }
);

const session = await response.json();
// Send session.client_secret to your frontend.
// { id, client_secret, expires_at, status, ... }

// In your frontend
import { Transcrypts } from 'transcrypts';

const transcrypts = new Transcrypts({
  publishableKey: 'pk_live_your_publishable_key',
  // Drop or set to 'production' when you go live.
  mode: 'sandbox',
});

const result = await transcrypts.verify({
  clientSecret: 'cs_secret_from_your_server',
});

// result contains UI signals only, no PII.
// { sessionId, status: 'completed' | 'pending' | 'failed' }
console.log(result.sessionId, result.status);

// On your server
import crypto from 'crypto';

app.post(
  '/webhooks/transcrypts',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-transcrypts-signature'];
    const secret = process.env.TRANSCRYPTS_WEBHOOK_SECRET;
    const body = req.body.toString('utf8');

    // Parse "t=<timestamp>,v1=<hex>" header
    const parts = Object.fromEntries(
      signature.split(',').map((p) => p.split('='))
    );

    // Reject stale events (>5 min) as a replay-attack defense.
    const tolerance = 5 * 60;
    if (Math.abs(Date.now() / 1000 - parseInt(parts.t, 10)) > tolerance) {
      return res.status(401).end();
    }

    // Recompute the HMAC and compare in constant time.
    const expected = crypto
      .createHmac('sha256', secret)
      .update(`${parts.t}.${body}`)
      .digest('hex');

    if (
      !crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(parts.v1)
      )
    ) {
      return res.status(401).end();
    }

    const event = JSON.parse(body);

    if (event.type === 'verification_session.verified') {
      // event.environment is 'sandbox' or 'production'. Branch on it if you
      // share one handler across both deployments.
      // event.data.result_data has the normalized subject + employers + earnings.
    }

    res.json({ received: true });
  }
);

// On your server
const response = await fetch(
  `${process.env.TRANSCRYPTS_BASE_URL}/api/sdk/v1/verification_sessions`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TRANSCRYPTS_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      applicant_hint: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'john@example.com',
      },
      metadata: { your_internal_id: 'LN_12345' },
      return_url: 'https://yourapp.com/verified',
    }),
  }
);

const session = await response.json();
// Send session.client_secret to your frontend.
// { id, client_secret, expires_at, status, ... }

{
  "id": "vs_01H8X7B3K5Z6Y2W9V4Q1N8M7L0",
  "client_secret": "cs_live_zR3vP9...xK1qLp",
  "status": "requires_input",
  "expires_at": "2026-05-20T19:14:00Z"
}

// On your server
const response = await fetch(
  `${process.env.TRANSCRYPTS_BASE_URL}/api/sdk/v1/verification_sessions/${sessionId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.TRANSCRYPTS_SECRET_KEY}`,
    },
  }
);

const session = await response.json();
// {
//   id, status, vendor, applicant_hint, result_data,
//   failure_reason, metadata, created_at, updated_at, expires_at
// }

{
  "id": "vs_01H8X7B3K5Z6Y2W9V4Q1N8M7L0",
  "status": "verified",
  "vendor": "irs",
  "applicant_hint": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  },
  "result_data": {
    "subject": {
      "name": "JOHN DOE",
      "address": "123 MAIN ST
ANYTOWN CA 94016",
      "ssn": "XXX-XX-1234"
    },
    "employers": [
      {
        "name": "Acme Corp",
        "jobTitle": null,
        "startDate": null,
        "endDate": null,
        "startYear": 2023,
        "endYear": 2024,
        "employmentStatus": "unknown",
        "source": "irs"
      }
    ],
    "earnings": [
      {
        "year": 2024,
        "employerName": "Acme Corp",
        "employerEin": "12-3456789",
        "totalWages": 95500
      }
    ]
  },
  "failure_reason": null,
  "metadata": { "your_internal_id": "LN_12345" },
  "return_url": "https://yourapp.com/verified",
  "created_at": "2026-05-20T18:14:00Z",
  "updated_at": "2026-05-20T18:24:11Z",
  "expires_at": "2026-05-20T18:44:00Z"
}

const transcrypts = new Transcrypts({
  // Required: Your publishable key from the dashboard
  publishableKey: 'pk_live_xxx',

  // Optional: 'sandbox' while building, omit (or 'production') when live.
  mode: 'sandbox',

  // Optional: Custom container styles for the overlay
  containerStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.8)',
  },
});

// In your frontend
import { Transcrypts } from 'transcrypts';

const transcrypts = new Transcrypts({
  publishableKey: 'pk_live_your_publishable_key',
  // Drop or set to 'production' when you go live.
  mode: 'sandbox',
});

const result = await transcrypts.verify({
  clientSecret: 'cs_secret_from_your_server',
});

// result contains UI signals only, no PII.
// { sessionId, status: 'completed' | 'pending' | 'failed' }
console.log(result.sessionId, result.status);

transcrypts.on('ready', () => {
  console.log('Widget loaded');
});

transcrypts.on('verification_session_completed', (event) => {
  // UI signal only. Trust the webhook for data.
  console.log(event.payload.sessionId, event.payload.status);
});

transcrypts.on('close', () => {
  console.log('User closed the widget');
});

// POST https://yourapp.com/webhooks/transcrypts
// Headers:
//   X-Transcrypts-Signature: t=1731600000,v1=4b3a...
//   Content-Type: application/json

{
  "id": "evt_01H8X7...",
  "type": "verification_session.verified",
  "created_at": "2026-05-14T18:24:11Z",
  "environment": "production",
  "data": {
    "id": "vs_01H8X7...",
    "status": "verified",
    "vendor": "irs",
    "result_data": {
      "subject": {
        "name": "JOHN DOE",
        "address": "123 MAIN ST\nANYTOWN CA 94016",
        "ssn": "XXX-XX-1234"
      },
      "employers": [
        {
          "name": "Acme Corp",
          "jobTitle": null,
          "startDate": null,
          "endDate": null,
          "startYear": 2023,
          "endYear": 2024,
          "employmentStatus": "unknown",
          "source": "irs"
        }
      ],
      "earnings": [
        { "year": 2024, "employerName": "Acme Corp", "employerEin": "12-3456789", "totalWages": 95500 },
        { "year": 2023, "employerName": "Acme Corp", "employerEin": "12-3456789", "totalWages": 92100 }
      ]
    },
    "metadata": { "your_internal_id": "LN_12345" }
  }
}

// Node.js helper
function verifySignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('='))
  );

  const timestamp = parseInt(parts.t, 10);
  const tolerance = 5 * 60; // 5 minutes
  if (Math.abs(Date.now() / 1000 - timestamp) > tolerance) {
    return false;
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}