SDKs

Official SDKs for integrating Conduit 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 Conduit API.

Features

• ✅ Full TypeScript support - Complete type definitions for all requests and responses
• ✅ Automatic retries - Built-in exponential backoff for transient failures
• ✅ Handle helpers - Fallback wait, stream, job, report, and cancel helpers on receipts
• ✅ 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/conduit

import { Conduit } from "@mappa-ai/conduit";

const conduitClient = new Conduit({
  apiKey: process.env.CONDUIT_API_KEY!,
});

const receipt = await conduitClient.reports.create({
  source: { url: "https://example.com/recording.mp3" },
  output: { template: "sales_playbook" },
  target: { strategy: "dominant" },
  webhook: { url: "https://your-app.com/api/webhooks/conduit" },
});

console.info(receipt.jobId);

View Node.js SDK Documentation →

What's included

Module	Description
Reports	Create report jobs and fetch completed reports
Webhooks	Verify webhook signatures
Advanced primitives	Stable entities, media, and jobs building blocks under conduitClient.primitives.*

---

Python SDK

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 receipt = await conduitClient.reports.create({
  source: { url: "https://example.com/call.mp3" },
  output: { template: "sales_playbook" },
  target: { strategy: "dominant" },
  webhook: { url: "https://your-app.com/webhooks/conduit" },
});

console.info(receipt.jobId);

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	✅ Cursor pagination on stable primitives	❌ Manual	🚧 Waitlist
Webhook verification	✅ Built-in	❌ Manual	🚧 Planned
Job polling	✅ receipt.handle?.wait() fallback	❌ Manual	🚧 Waitlist
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 receipt = await conduitClient.reports.create({
  source: { path: "./recording.mp3" },
  output: { template: "sales_playbook" },
  target: { strategy: "dominant" },
  webhook: { url: "https://your-app.com/webhooks/conduit" },
});

console.info(receipt.jobId);

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