Skip to main content

Async processing

Use asynchronous jobs for production workloads. Create a job, store jobId, and process completion via webhook or handle polling.

Start a job (non-blocking)​

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

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

async function startAnalysis(url: string, webhookUrl: string) {
  const receipt = await mappa.reports.createJobFromUrl({
    url,
    output: { template: "general_report" },
    target: { strategy: "dominant" },
    webhook: { url: webhookUrl },
  });

  return receipt.jobId;
}

const jobId = await startAnalysis(
  "https://example.com/long-recording.mp3",
  "https://your-app.com/webhooks/mappa",
);

console.info(`Started job: ${jobId}`);

Polling alternative (no webhook)​

async function waitForReport(jobId: string, timeoutMs = 300_000) {
  const handle = mappa.reports.makeHandle(jobId);
  return handle.wait({ timeoutMs });
}

Stream progress​

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(event.stage, event.progress);
  if (event.type === "terminal") break;
}

const report = await receipt.handle!.wait();
console.info(report.id);