SDKs

Official SDKs for integrating Mappa Behavioral Engine into your applications.

Available SDKs

SDK	Status	Documentation
Node.js / TypeScript	✅ Stable	View Docs
Python	🚧 Coming Soon	Placeholder

---

Node.js / TypeScript SDK

The official Node.js SDK provides a type-safe, production-ready client for the Mappa API.

Features

• ✅ Full TypeScript support - Complete type definitions for all requests and responses
• ✅ Automatic retries - Built-in exponential backoff for transient failures
• ✅ Job helpers - Convenient polling, streaming, and async iteration
• ✅ Webhook verification - HMAC-SHA256 signature verification
• ✅ Production-ready - Idempotency, request tracing, and telemetry hooks
• ✅ Zero dependencies - Only one runtime dependency (cuid2 for ID generation)

Quick start

npm install @mappa-ai/mappa-node

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

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

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

console.info(report.markdown);

View Node.js SDK Documentation →

What's included

Module	Description
Files	Upload, list, and manage media files
Reports	Generate behavioral analysis reports
Jobs	Monitor job status and progress
Entities	Track and tag speakers across recordings
Credits	Track credit usage and balance
Feedback	Submit feedback for reports
Webhooks	Verify webhook signatures

---

Python SDK

The Python SDK is under development and will be available soon.

Planned features

• 🔄 Pythonic async/await interface
• 🔄 Type hints with Pydantic models
• 🔄 Automatic pagination
• 🔄 Built-in retry logic
• 🔄 Webhook signature verification

Notify me

Want to be notified when the Python SDK is ready? Join the waitlist.

---

SDK vs direct API

When to use an SDK

✅ Use an SDK if:

• You're using Node.js/TypeScript (or Python when available)
• You want type safety and autocomplete
• You need built-in retries and error handling
• You want convenience helpers for common workflows

Example (SDK):

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

When to use direct API

✅ Use the REST API directly if:

• Your language doesn't have an SDK yet
• You prefer full control over HTTP requests
• You're building a custom integration

Example (cURL):

curl -X POST https://api.mappa.ai/v1/reports/jobs \
  -H "Mappa-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media": { "mediaId": "media_abc123" },
    "output": { "type": "markdown", "template": "sales_playbook" }
  }'

View REST API Documentation →

---

Feature comparison

Feature	Node.js SDK	REST API	Python SDK
Type safety	✅ TypeScript	❌	🚧 Planned
Auto retries	✅ Built-in	❌ Manual	🚧 Planned
Pagination helpers	✅ Async iterators	❌ Manual	🚧 Planned
Webhook verification	✅ Built-in	❌ Manual	🚧 Planned
Job polling	✅ .wait() helper	❌ Manual	🚧 Planned
Event streaming	✅ Async iterator	❌ Manual	🚧 Planned
Request tracing	✅ Auto requestId	❌ Manual	🚧 Planned
Idempotency	✅ Auto-generated	❌ Manual	🚧 Planned

---

Migration from REST API

Already using the REST API? The SDK provides drop-in replacements:

Before (REST API)

# Upload file
curl -X POST https://api.mappa.ai/v1/files \
  -H "Mappa-Api-Key: $API_KEY" \
  -F "file=@recording.mp3"

# Create job
curl -X POST https://api.mappa.ai/v1/reports/jobs \
  -H "Mappa-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media":{"mediaId":"media_abc"},"output":{"type":"markdown","template":"sales_playbook"}}'

# Poll for status
while true; do
  curl https://api.mappa.ai/v1/jobs/job_xyz \
    -H "Mappa-Api-Key: $API_KEY"
  sleep 2
done

After (SDK)

const report = await mappa.reports.generateFromFile({
  file: await readFile("recording.mp3"),
  output: { template: "sales_playbook" },
  target: { strategy: "dominant" },
});

Benefits:

• 90% less code
• Built-in error handling
• Type safety
• Automatic retries

---

Community SDKs

Building an SDK for another language? Let us know! We'd love to feature community-built SDKs here.

Guidelines for community SDKs:

• Follow REST API conventions
• Include webhook signature verification
• Provide type safety where applicable
• Include examples and documentation

Contact us to list your SDK.

---

Next steps

Get started

• Quickstart - Generate your first report in 5 minutes
• Node.js SDK Docs - Complete SDK documentation
• API Reference - REST API documentation

Learn more

• Core Concepts - Understand jobs, reports, and credits
• Authentication - API key security
• Production Guide - Best practices for production