Skip to main content

Usage

Use these patterns as the default integration path for the current SDK surface.

Create a client​

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

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

Quick blocking flow​

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

console.info(report.id, report.output.template);

Production async flow​

const receipt = await mappa.reports.createJobFromUrl({
  url: "https://example.com/call.mp3",
  output: { template: "sales_playbook" },
  target: { strategy: "dominant" },
  webhook: { url: "https://your-app.com/webhooks/mappa" },
});

console.info(receipt.jobId, receipt.status); // queued | running

Wait/stream via handle​

const receipt = await mappa.reports.createJob({
  media: { mediaId: "media_123" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
});

const handle = receipt.handle ?? mappa.reports.makeHandle(receipt.jobId);

for await (const event of handle.stream()) {
  if (event.type === "stage") console.info(event.stage, event.progress);
  if (event.type === "terminal") break;
}

const report = await handle.wait({ timeoutMs: 600_000 });
console.info(report.id);

Jobs API directly​

const job = await mappa.jobs.get("job_123");
if (job.status === "succeeded" && job.reportId) {
  const report = await mappa.reports.get(job.reportId);
  console.info(report.id);
}

Matching analysis​

const receipt = await mappa.matchingAnalysis.createJob({
  entityA: { type: "entity_id", entityId: "ent_a" },
  entityB: { type: "entity_id", entityId: "ent_b" },
  context: "Compare collaboration style",
  output: { template: "matching_analysis" },
});

const analysis = await (receipt.handle ?? mappa.matchingAnalysis.makeHandle(receipt.jobId)).wait();
console.info(analysis.id);