@mappa-ai/mappa-node 2.0.9 → 2.0.11

package/README.md

@@ -1,239 +1,236 @@
 # @mappa-ai/mappa-node
 
-Official TypeScript SDK for the Mappa API.
+[![npm version](https://img.shields.io/npm/v/@mappa-ai/mappa-node.svg)](https://www.npmjs.com/package/@mappa-ai/mappa-node)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-Built for server and worker runtimes. Primary targets are Node.js and Bun.
+Behavioral intelligence for your app. Type-safe. Async-first. Production-ready.
 
-## Agent + Dev Quickstart
+## Install
+
+```bash
+# npm
+npm install @mappa-ai/mappa-node
+
+# yarn
+yarn add @mappa-ai/mappa-node
 
-- Install package: `npm install @mappa-ai/mappa-node`
-- Use server-side only with `MAPPA_API_KEY`
-- Validate package changes: `bun run check && bun run type-check && bun test`
-- Build distribution artifacts: `bun run build`
-- Follow package-specific agent rules: `packages/sdk-ts/AGENTS.md`
+# pnpm
+pnpm add @mappa-ai/mappa-node
+
+# bun
+bun add @mappa-ai/mappa-node
+```
 
 ## Runtime support
 
-- Primary: Node.js, Bun
-- Compatible: Deno, Cloudflare Workers, other fetch-compatible server/edge runtimes
-- Browser: blocked by default to protect secret API keys
+Runs anywhere fetch runs. Node, Bun, Deno, Cloudflare Workers. Browser blocked by default — your API key stays secret.
 
-## Security model
+## Security
 
-This SDK is designed for secret API keys.
+Your API key is secret. We enforce it.
 
-- Do not call Mappa directly from browser apps with a private API key
-- Put your key in a server or edge function and proxy requests
-- The client throws in browser-like runtimes unless you set `dangerouslyAllowBrowser: true`
+- Keep `MAPPA_API_KEY` server-side.
+- Proxy requests through your backend.
+- Browser calls throw unless you set `dangerouslyAllowBrowser: true`.
 
-## Server proxy pattern
+## Choose a workflow
 
-Use your backend as a trust boundary:
+Three paths. Pick yours.
 
-- Browser uploads/calls your endpoint
-- Your endpoint uses this SDK with `MAPPA_API_KEY`
-- Your endpoint returns only safe response fields
+| Method | When to use |
+| --- | --- |
+| `generateFromFile` / `generateFromUrl` | One call. Done. |
+| `createJob` + `webhook` | Fire and forget. We call you. |
+| `createJob` + `wait()` / `stream()` | Stay in control. |
 
-### Next.js App Router example
+## Webhooks — the production path
 
-```ts
-// app/api/mappa/report/route.ts
-import { NextResponse } from "next/server";
-import { Mappa, isMappaError } from "@mappa-ai/mappa-node";
-
-const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });
-
-export async function POST(req: Request) {
-	try {
-		const form = await req.formData();
-		const file = form.get("file");
-
-		if (!(file instanceof File)) {
-			return NextResponse.json({ error: "file is required" }, { status: 400 });
-		}
-
-		const report = await mappa.reports.generateFromFile({
-			file,
-			output: { template: "general_report" },
-			target: { strategy: "dominant" },
-		});
-
-		return NextResponse.json({
-			id: report.id,
-			template: report.output.template,
-			summary: report.summary ?? null,
-		});
-	} catch (err) {
-		if (isMappaError(err)) {
-			return NextResponse.json(
-				{ error: err.message, requestId: err.requestId ?? null },
-				{ status: 502 },
-			);
-		}
-		return NextResponse.json({ error: "Unexpected error" }, { status: 500 });
-	}
-}
-```
+Submit jobs. Move on. Mappa calls your endpoint when it's done. Signatures included.
 
-For advanced flow control, prefer `createJob` + `handle.wait()` or `handle.stream()`.
+### Publish
 
-### Framework-agnostic pattern
+One field. That's it.
 
 ```ts
-// POST /api/report
-// 1) Validate auth and input
-// 2) Call Mappa on the server
-// 3) Return sanitized output
+import { Mappa } from "@mappa-ai/mappa-node"
+
+const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! })
+
+const receipt = await mappa.reports.createJobFromFile({
+  file: audioBlob,
+  output: { template: "general_report" },
+  target: { strategy: "dominant" },
+  webhook: {
+    url: "https://your-app.com/api/webhooks/mappa",
+    headers: { "x-tenant-id": "tenant_123" },
+  },
+})
+
+console.log(receipt.jobId)
 ```
 
+Already have media uploaded? Same idea.
+
 ```ts
-const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });
-const report = await mappa.reports.generateFromFile({
-	file,
-	output: { template: "general_report" },
-	target: { strategy: "dominant" },
-});
-return { id: report.id, summary: report.summary };
+await mappa.reports.createJob({
+  media: { mediaId: "media_abc123" },
+  output: { template: "general_report" },
+  target: { strategy: "dominant" },
+  webhook: { url: "https://your-app.com/api/webhooks/mappa" },
+})
 ```
 
-### Security checklist
+### Consume
 
-- Keep `MAPPA_API_KEY` server-only
-- Require auth for proxy endpoints
-- Validate input size and type before SDK calls
-- Add rate limits on proxy endpoints
-- Log `requestId` values from SDK errors for traceability
+Verify. Parse. React.
 
-## Install
+```ts
+import { Mappa } from "@mappa-ai/mappa-node"
 
-```bash
-npm install @mappa-ai/mappa-node
-```
+const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! })
 
-## Quickstart
+export async function POST(req: Request): Promise<Response> {
+  const payload = await req.text()
 
-```ts
-import { Mappa } from "@mappa-ai/mappa-node";
+  await mappa.webhooks.verifySignature({
+    payload,
+    headers: Object.fromEntries(req.headers),
+    secret: process.env.MAPPA_WEBHOOK_SECRET!,
+  })
 
-const mappa = new Mappa({
-	apiKey: process.env.MAPPA_API_KEY!,
-});
+  const event = mappa.webhooks.parseEvent(payload)
 
-const media = await mappa.files.upload({
-	file: new Blob(["...binary..."]),
-});
+  if (event.type === "report.completed") {
+    const report = await mappa.reports.get(event.data.reportId)
+    console.log("done", report.id)
+    return new Response("ok", { status: 200 })
+  }
 
-const receipt = await mappa.reports.createJob({
-	media: { mediaId: media.mediaId },
-	output: { template: "general_report" },
-	target: { strategy: "dominant" },
-});
+  if (event.type === "report.failed") {
+    console.error("failed", event.data.jobId, event.data.error.code)
+    return new Response("ok", { status: 200 })
+  }
 
-const report = await receipt.handle?.wait();
-console.log(report?.id);
+  return new Response("ignored", { status: 200 })
+}
 ```
 
-## Node filesystem helpers
+## Polling — when you want to wait
 
-For Node/Bun file-path ergonomics, use the Node adapter subpath.
+Sometimes you need the answer now.
+
+### `wait()`
 
 ```ts
-import { Mappa } from "@mappa-ai/mappa-node";
-import { uploadFromPath, generateReportFromPath } from "@mappa-ai/mappa-node/node";
+import { Mappa } from "@mappa-ai/mappa-node"
 
-const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });
+const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! })
 
-const media = await uploadFromPath(mappa, {
-	path: "./recording.wav",
-});
+const media = await mappa.files.upload({ file: audioBlob })
 
-const report = await generateReportFromPath(mappa, {
-	path: "./recording.wav",
-	output: { template: "general_report" },
-	target: { strategy: "dominant" },
-});
+const job = await mappa.reports.createJob({
+  media: { mediaId: media.mediaId },
+  output: { template: "general_report" },
+  target: { strategy: "dominant" },
+})
+
+const report = await job.handle?.wait()
+console.log(report?.id)
 ```
 
-## Matching analysis
+### `stream()`
 
 ```ts
-const job = await mappa.matchingAnalysis.createJob({
-	entityA: { type: "entity_id", entityId: "entity_a" },
-	entityB: { type: "entity_id", entityId: "entity_b" },
-	context: "Compare communication style",
-	output: { template: "matching_analysis" },
-});
-
-const analysis = await job.handle?.wait();
-console.log(analysis?.id);
+for await (const event of job.handle?.stream() ?? []) {
+  if (event.type === "stage") {
+    console.log(event.stage, event.progress)
+  }
+}
 ```
 
-## Observability and retries
+## Helpers
+
+### `generateFromFile`
+
+Upload, process, return. One call.
 
 ```ts
-const mappa = new Mappa({
-	apiKey: process.env.MAPPA_API_KEY!,
-	timeoutMs: 30000,
-	maxRetries: 2,
-	telemetry: {
-		onRequest: (ctx) => console.log("req", ctx.method, ctx.url, ctx.requestId),
-		onResponse: (ctx) => console.log("res", ctx.status, ctx.durationMs),
-		onError: (ctx) => console.error("err", ctx.requestId, ctx.error),
-	},
-});
+const report = await mappa.reports.generateFromFile({
+  file: audioBlob,
+  output: { template: "general_report" },
+  target: { strategy: "dominant" },
+})
+
+console.log(report.id)
 ```
 
-## Webhooks
+### `generateFromUrl`
+
+Got a URL? We fetch it.
 
 ```ts
-const payload = rawBodyString;
+const report = await mappa.reports.generateFromUrl({
+  url: "https://example.com/recording.wav",
+  output: { template: "general_report" },
+  target: { strategy: "dominant" },
+})
 
-await mappa.webhooks.verifySignature({
-	payload,
-	headers: req.headers,
-	secret: process.env.MAPPA_WEBHOOK_SECRET!,
-});
+console.log(report.id)
+```
 
-const event = mappa.webhooks.parseEvent(payload);
-if (event.type === "report.completed") {
-	console.log(event.data.reportId);
-}
+## Node/Bun file paths
+
+Working with file paths? Use the `/node` subpath.
+
+```ts
+import { Mappa } from "@mappa-ai/mappa-node"
+import { generateReportFromPath, uploadFromPath } from "@mappa-ai/mappa-node/node"
+
+const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! })
+
+const media = await uploadFromPath(mappa, { path: "./recording.wav" })
+
+const report = await generateReportFromPath(mappa, {
+  path: "./recording.wav",
+  output: { template: "general_report" },
+  target: { strategy: "dominant" },
+})
+
+console.log(media.mediaId, report.id)
 ```
 
 ## Error handling
 
+Things break. We tell you why.
+
 ```ts
-import {
-	isInsufficientCreditsError,
-	isMappaError,
-	isStreamError,
-} from "@mappa-ai/mappa-node";
+import { isInsufficientCreditsError, isMappaError, isStreamError } from "@mappa-ai/mappa-node"
 
 try {
-	// ...
+  // ...
 } catch (err) {
-	if (isInsufficientCreditsError(err)) {
-		console.error(err.required, err.available);
-	} else if (isStreamError(err)) {
-		console.error(err.jobId, err.retryCount);
-	} else if (isMappaError(err)) {
-		console.error(err.requestId, err.code, err.message);
-	}
+  if (isInsufficientCreditsError(err)) {
+    console.error(err.required, err.available)
+    return
+  }
+
+  if (isStreamError(err)) {
+    console.error(err.jobId, err.retryCount)
+    return
+  }
+
+  if (isMappaError(err)) {
+    console.error(err.requestId, err.code, err.message)
+  }
 }
 ```
 
 ## Scope
 
-- API-key workflows only
-- Includes: health, files, jobs, reports, matching-analysis, feedback, entities, webhooks
-- Excludes: billing and user-session console endpoints
+API-key workflows. Reports, files, jobs, webhooks, feedback, entities. Billing lives in the dashboard.
 
-## Development
+---
 
-```bash
-bun run build
-bun run check
-bun run type-check
-bun test
-```
+Questions? [api-docs.mappa.ai](https://api-docs.mappa.ai)
 
+For SDK maintenance, see `README_INTERNAL.md`.

package/dist/index.cjs

@@ -4904,7 +4904,7 @@ const reportTemplates = _enum([
 * - `markdown`: Human-readable formatted text
 * - `json`: Structured data for programmatic use
 * - `pdf`: Rendered PDF document (via external service)
-* - `url`: Hosted web report at console.mappa.ai/reports/[id]
+* - `url`: Hosted web report at conduit.mappa.ai/reports/[id]
 */
 const reportOutput = object({
 	template: reportTemplates,