Skip to main content

Node.js / TypeScript SDK

Official SDK for integrating Mappa Behavioral Engine into your Node.js and TypeScript applications.

Why use the SDK?​

The Node.js SDK provides a type-safe, batteries-included client that handles the complexity of API integration:

  • Type-safe - Complete TypeScript definitions for all requests and responses
  • Resilient - Built-in retries with exponential backoff and jitter
  • Convenient - High-level helpers for common workflows (polling, streaming, uploads)
  • Production-ready - Idempotency, request tracing, webhook verification
  • Modern - Native fetch, async iterators, discriminated unions
  • Zero dependencies - Only one runtime dependency (cuid2 for ID generation)

Quick example​

import { Mappa } from "@mappa-ai/mappa-node";

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
});

// One-liner: download → upload → analyze → wait → get report
const report = await mappa.reports.generateFromUrl({
  url: "https://example.com/sales-call.mp3",
  output: { template: "sales_playbook",
  },
  target: { strategy: "dominant" },
});

console.info(report.markdown);

Features​

Type-Safe reports​

Reports are discriminated unions typed by output format:

const report = await mappa.reports.generateFromUrl({
  url: "https://example.com/interview.mp3",
  output: { template: "hiring_report" },
  target: { strategy: "dominant" },
});

if (report.sections) {
  for (const section of report.sections) {
    console.info(section.section_title, section.section_content);
  }
}

Automatic pagination​

Iterate through large datasets without manual cursor management:

// Automatically handles pagination
for await (const file of mappa.files.listAll()) {
  console.info(`${file.mediaId}: ${file.sizeBytes} bytes`);
}

// Or with filters
for await (const entity of mappa.entities.listAll()) {
  console.info(`Entity ${entity.id} has ${entity.mediaCount} recordings`);
}

Job streaming​

Stream real-time progress updates:

const receipt = await mappa.reports.createJobFromUrl({
  url: "https://example.com/recording.mp3",
  output: { template: "general_report" },
  target: { strategy: "dominant" },
});

for await (const event of receipt.handle!.stream()) {
  if (event.type === "stage") {
    console.info(`Stage: ${event.stage}, Progress: ${event.progress}`);
  }
  if (event.type === "terminal") break;
}

const report = await receipt.handle!.report();

Built-in retries​

Automatic retry with exponential backoff for transient failures:

const mappa = new Mappa({
  apiKey: process.env.MAPPA_API_KEY!,
  maxRetries: 3, // Retry up to 3 times (default: 2)
  timeoutMs: 60_000, // 60s per request (default: 30s)
});

Webhook verification​

Secure webhook handling with HMAC-SHA256 signature verification:

import express from "express";

app.post("/webhooks/mappa", express.text({ type: "*/*" }), async (req, res) => {
  await mappa.webhooks.verifySignature({
    payload: req.body,
    headers: req.headers as Record<string, string | string[] | undefined>,
    secret: process.env.MAPPA_WEBHOOK_SECRET!,
  });

  const event = mappa.webhooks.parseEvent(req.body);
  // Process webhook safely
  res.status(200).send("OK");
});

Installation​

npm install @mappa-ai/mappa-node

Works with Node.js 18+ and modern JavaScript runtimes (Bun, Deno with Node compatibility).

View Installation Guide →

Documentation​

Getting started​

  • Installation - Install and configure the SDK
  • Usage - Core patterns for reports, jobs, and files
  • Examples - Copy-paste code for common tasks

API resources​

  • Files - Upload, list, and manage media files
  • Reports - Generate behavioral analysis reports
  • Jobs - Monitor job status and progress
  • Matching analysis - Compare two entities or media targets
  • Entities - Manage speaker entities and labels
  • Feedback - Submit feedback on reports

Advanced topics​

Requirements​

  • Node.js 18 or later (or Bun, Deno with Node compatibility)
  • TypeScript 4.7+ (recommended, but JavaScript works too)

Package information​

Support​