@mappa-ai/mappa-node 1.2.4 → 2.0.9

package/README.md

@@ -1,474 +1,239 @@
-# Mappa Node SDK [WIP - DO NOT USE YET]
+# @mappa-ai/mappa-node
 
-[![npm version](https://img.shields.io/npm/v/@mappa-ai/mappa-node.svg)](https://www.npmjs.com/package/@mappa-ai/mappa-node)
-![license](https://img.shields.io/npm/l/@mappa-ai/mappa-node.svg)
+Official TypeScript SDK for the Mappa API.
 
-Official JavaScript/TypeScript SDK for the **Mappa API**.
+Built for server and worker runtimes. Primary targets are Node.js and Bun.
 
-- Works in **Node.js 18+** (and modern runtimes with `fetch`, `crypto`, `AbortController`).
-- **Typed** end-to-end (requests, replies, errors).
-- Built-in **retries**, **idempotency**, and **job helpers** (polling + streaming).
-- Simple **webhook signature verification**.
+## Agent + Dev Quickstart
 
----
+- 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`
 
-## Installation
+## Runtime support
 
-```bash
-npm install @mappa-ai/mappa-node
-# or
-yarn add @mappa-ai/mappa-node
-# or
-pnpm add @mappa-ai/mappa-node
-# or
-bun add @mappa-ai/mappa-node
-```
-
----
-
-## Quickstart
-
-Create a report from a remote media URL and wait for completion:
-
-```ts
-import { Mappa } from "@mappa-ai/mappa-node";
+- Primary: Node.js, Bun
+- Compatible: Deno, Cloudflare Workers, other fetch-compatible server/edge runtimes
+- Browser: blocked by default to protect secret API keys
 
-const mappa = new Mappa({
-  apiKey: process.env.MAPPA_API_KEY!,
-});
+## Security model
 
-  // One-liner for remote URLs: download -> upload -> create job -> wait -> fetch report
-  const report = await mappa.reports.generateFromUrl({
-    url: "https://example.com/media.mp3",
-    output: { type: "markdown", template: "general_report" },
-  });
+This SDK is designed for secret API keys.
 
+- 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`
 
-if (report.output.type === "markdown") {
-  console.log(report.markdown);
-}
-```
+## Server proxy pattern
 
----
+Use your backend as a trust boundary:
 
-## Authentication
+- Browser uploads/calls your endpoint
+- Your endpoint uses this SDK with `MAPPA_API_KEY`
+- Your endpoint returns only safe response fields
 
-Pass the API key when constructing the client:
+### Next.js App Router example
 
 ```ts
-import { Mappa } from "@mappa-ai/mappa-node";
-
-const mappa = new Mappa({ apiKey: "YOUR_MAPPA_API_KEY" });
-```
-
-Recommended: load the key from environment variables:
-
-```bash
-export MAPPA_API_KEY="your-api-key"
-```
+// app/api/mappa/report/route.ts
+import { NextResponse } from "next/server";
+import { Mappa, isMappaError } from "@mappa-ai/mappa-node";
 
-```ts
 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 });
+	}
+}
+```
 
-## Configuration
+For advanced flow control, prefer `createJob` + `handle.wait()` or `handle.stream()`.
 
-The client supports per-instance configuration:
+### Framework-agnostic pattern
 
 ```ts
-import { Mappa } from "@mappa-ai/mappa-node";
-
-const mappa = new Mappa({
-  apiKey: process.env.MAPPA_API_KEY!,
-  baseUrl: "https://api.mappa.ai", // default
-  timeoutMs: 30_000, // default; per HTTP attempt
-  maxRetries: 2, // default
-  defaultHeaders: {
-    "X-My-App": "my-service",
-  },
-});
+// POST /api/report
+// 1) Validate auth and input
+// 2) Call Mappa on the server
+// 3) Return sanitized output
 ```
 
-### Request tracing
-
-The SDK sets `X-Request-Id` on every request. You can supply your own `requestId`
-per call to correlate logs across your system and Mappa support.
-
-### Idempotency
-
-Most write APIs accept `idempotencyKey`. If you do not provide one, the SDK
-generates a best-effort key per request. For long-running workflows, it is best
-practice to supply a stable key per logical operation.
-
-Example:
-
 ```ts
-await mappa.reports.createJob({
-  media: { mediaId: "media_..." },
-  output: { type: "markdown", template: "general_report" },
-  idempotencyKey: "report:customer_123:2026-01-14",
-  requestId: "req_customer_123",
+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 };
 ```
 
-### Retries
+### Security checklist
 
-Retries are enabled for retryable requests (GETs and idempotent writes). Use
-`maxRetries: 0` to disable retries globally, or pass your own `idempotencyKey`
-to make POST retries safe.
+- 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
 
-Create a derived client with overrides:
+## Install
 
-```ts
-const mappaNoRetries = mappa.withOptions({ maxRetries: 0 });
+```bash
+npm install @mappa-ai/mappa-node
 ```
 
-### Timeouts vs long-running jobs
-
-`timeoutMs` is a **per-request** timeout (including each retry attempt).
-For long-running work, create a job and use `jobs.wait(...)` or `reports.makeHandle(jobId)`.
-
-### Cancelling waits
-
-Use `AbortController` to cancel polling or streaming when your app shuts down
-or the user navigates away.
+## Quickstart
 
 ```ts
-const controller = new AbortController();
-
-setTimeout(() => controller.abort(), 10_000);
+import { Mappa } from "@mappa-ai/mappa-node";
 
-const receipt = await mappa.reports.createJob({
-  media: { mediaId: "media_..." },
-  output: { type: "markdown" },
+const mappa = new Mappa({
+	apiKey: process.env.MAPPA_API_KEY!,
 });
 
-try {
-  const report = await receipt.handle!.wait({
-    signal: controller.signal,
-  });
-  console.log(report.id);
-} catch (err) {
-  if (err instanceof Error && err.name === "AbortError") {
-    console.log("wait canceled");
-  }
-}
-```
-
-Streaming with cancellation:
-
-```ts
-const controller = new AbortController();
-
-const handle = mappa.reports.makeHandle("job_...");
+const media = await mappa.files.upload({
+	file: new Blob(["...binary..."]),
+});
 
-setTimeout(() => controller.abort(), 5_000);
+const receipt = await mappa.reports.createJob({
+	media: { mediaId: media.mediaId },
+	output: { template: "general_report" },
+	target: { strategy: "dominant" },
+});
 
-for await (const event of handle.stream({ signal: controller.signal })) {
-  if (event.type === "terminal") break;
-}
+const report = await receipt.handle?.wait();
+console.log(report?.id);
 ```
 
----
-
-## Core concepts
-
-### Reports are asynchronous
-
-In the underlying architecture we do a series of transformations and
-ML inference, which can take time.
-To accommodate this, creating a report returns a **job receipt**. You can:
-
-- **Wait** (poll) until completion.
-- **Stream** job events.
-- **Use webhooks** so your server is notified when work is done.
-
-### Media input
+## Node filesystem helpers
 
-Report job creation accepts **already-uploaded** media references:
+For Node/Bun file-path ergonomics, use the Node adapter subpath.
 
-- `{ mediaId: string }`
-
-If you want a one-liner starting from something else:
-
-- Remote URLs: `reports.createJobFromUrl()` / `reports.generateFromUrl()` (download client-side → upload → create job)
-- Local bytes: `reports.createJobFromFile()` / `reports.generateFromFile()` (upload → create job)
-
----
-
-## Creating reports
-
-### 1) Create a job (recommended for production)
+```ts
+import { Mappa } from "@mappa-ai/mappa-node";
+import { uploadFromPath, generateReportFromPath } from "@mappa-ai/mappa-node/node";
 
-If you already have an uploaded `mediaId`, use `createJob()`:
+const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });
 
-```ts
-const receipt = await mappa.reports.createJob({
-  media: { mediaId: "media_..." },
-  output: { type: "markdown", template: "general_report" },
-  subject: {
-    externalRef: "customer_123",
-    metadata: { plan: "pro" },
-  },
-  options: {
-    language: "en",
-    timezone: "UTC",
-  },
-  // Optional: provide your own idempotency key for safe retries.
-  idempotencyKey: "report:customer_123:2026-01-14",
+const media = await uploadFromPath(mappa, {
+	path: "./recording.wav",
 });
 
-console.log(receipt.jobId);
+const report = await generateReportFromPath(mappa, {
+	path: "./recording.wav",
+	output: { template: "general_report" },
+	target: { strategy: "dominant" },
+});
 ```
 
-If you’re starting from a remote URL, use `createJobFromUrl()`:
+## Matching analysis
 
 ```ts
-const receiptFromUrl = await mappa.reports.createJobFromUrl({
-  url: "https://example.com/media.mp3",
-  output: { type: "markdown", template: "general_report" },
-  subject: {
-    externalRef: "customer_123",
-    metadata: { plan: "pro" },
-  },
-  options: {
-    language: "en",
-    timezone: "UTC",
-  },
-  idempotencyKey: "report:customer_123:2026-01-14",
+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" },
 });
 
-console.log(receiptFromUrl.jobId);
+const analysis = await job.handle?.wait();
+console.log(analysis?.id);
 ```
 
-### 2) Wait for completion (polling)
+## Observability and retries
 
 ```ts
-const report = await receipt.handle!.wait({
-  timeoutMs: 10 * 60_000,
-  onEvent: (e) => {
-    if (e.type === "stage") {
-      console.log("stage", e.stage, e.progress);
-    }
-  },
+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),
+	},
 });
 ```
 
-### 3) Stream job events
-
-`jobs.stream(jobId)` yields state transitions.
+## Webhooks
 
 ```ts
-if (report.output.type === "json") {
-  for (const section of report.sections) {
-    console.log(section.section_title, section.section_content);
-  }
-}
-```
+const payload = rawBodyString;
 
-Type narrowing helpers:
+await mappa.webhooks.verifySignature({
+	payload,
+	headers: req.headers,
+	secret: process.env.MAPPA_WEBHOOK_SECRET!,
+});
 
-```ts
-if (report.output.type === "markdown") {
-  console.log(report.markdown);
+const event = mappa.webhooks.parseEvent(payload);
+if (event.type === "report.completed") {
+	console.log(event.data.reportId);
 }
 ```
 
----
-
-## Feedback
-
-Use `mappa.feedback.create()` to share ratings or corrections. Provide exactly
-one of `reportId` or `jobId`.
-
-```ts
-await mappa.feedback.create({
-  reportId: "report_...",
-  rating: "thumbs_up",
-  tags: ["quality"],
-  comment: "Accurate summary",
-});
-```
-
----
-
-## Errors
-
-
-The SDK throws typed errors:
-
-- `ApiError` for non-2xx responses
-- `AuthError` for 401/403
-- `ValidationError` for 422
-- `RateLimitError` for 429 (may include `retryAfterMs`)
-- `JobFailedError` / `JobCanceledError` from polling helpers
-- `MappaError` for client-side validation or runtime constraints
+## Error handling
 
 ```ts
 import {
-  ApiError,
-  AuthError,
-  MappaError,
-  RateLimitError,
-  ValidationError,
+	isInsufficientCreditsError,
+	isMappaError,
+	isStreamError,
 } from "@mappa-ai/mappa-node";
 
 try {
-  await mappa.reports.generateFromUrl({
-    url: "https://example.com/media.mp3",
-    output: { type: "markdown", template: "general_report" },
-  });
-
-  await mappa.reports.generateFromUrl({
-    url: "https://example.com/interview.mp3",
-    output: {
-      type: "markdown",
-      template: "hiring_report",
-      templateParams: {
-        roleTitle: "Customer Success Manager",
-        roleDescription: "Own onboarding and renewal conversations.",
-        companyCulture: "Curious, candid, customer-obsessed.",
-      },
-    },
-  });
+	// ...
 } catch (err) {
-  if (err instanceof AuthError) {
-    console.error("Auth error", err.requestId);
-    throw err;
-  }
-
-  if (err instanceof RateLimitError) {
-    console.error("Rate limited; retry after", err.retryAfterMs);
-    throw err;
-  }
-
-  if (err instanceof ValidationError) {
-    console.error("Invalid request", err.details);
-    throw err;
-  }
-
-  if (err instanceof ApiError) {
-    console.error("API error", err.status, err.code, err.requestId);
-    throw err;
-  }
-
-  if (err instanceof MappaError) {
-    console.error("Client error", err.message);
-    throw err;
-  }
-
-  throw 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);
+	}
 }
 ```
 
----
-
-## Webhooks
-
-Use `mappa.webhooks.verifySignature()` to verify incoming webhook events.
-
-Tips for raw body handling:
-- Express: `express.text({ type: "*/*" })`
-- Fastify: use `rawBody` (enable `bodyLimit` and `rawBody`)
-- Next.js (App Router): read `await req.text()` before parsing
-- Node 18+ or modern runtimes are required for WebCrypto
-
-The SDK expects a header shaped like:
-
-```http
-mappa-signature: t=1700000000,v1=<hex>
-```
-
-And verifies the HMAC-SHA256 signature of:
-
-```ts
-${t}.${rawBody}
-```
-
-Example (Express):
-
-```ts
-import express from "express";
-import { Mappa } from "@mappa-ai/mappa-node";
-
-const app = express();
-
-// IMPORTANT: you must keep the raw body for signature verification.
-app.post(
-  "/webhooks/mappa",
-  express.text({ type: "*/*" }),
-  async (req, res) => {
-    const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });
-
-    await mappa.webhooks.verifySignature({
-      payload: req.body,
-      headers: req.headers as Record<string, string | string[] | undefined>,
-      secret: process.env.MAPPA_WEBHOOK_SECRET!,
-      toleranceSec: 300,
-    });
-
-    const event = mappa.webhooks.parseEvent(req.body);
-
-    // Example: handle event types.
-    switch (event.type) {
-      case "report.completed":
-        // event.data contains the payload from Mappa.
-        break;
-      default:
-        break;
-    }
-
-    res.status(200).send("ok");
-  },
-);
-```
-
----
+## Scope
 
-## Telemetry hooks
+- API-key workflows only
+- Includes: health, files, jobs, reports, matching-analysis, feedback, entities, webhooks
+- Excludes: billing and user-session console endpoints
 
-You can hook into request/response/error events:
+## Development
 
-```ts
-import { Mappa } from "@mappa-ai/mappa-node";
-
-const mappa = new Mappa({
-  apiKey: process.env.MAPPA_API_KEY!,
-  telemetry: {
-    onRequest: ({ method, url, requestId }) => {
-      console.log("request", method, url, requestId);
-    },
-    onResponse: ({ status, url, durationMs, requestId }) => {
-      console.log("response", status, url, durationMs, requestId);
-    },
-    onError: ({ url, requestId, error }) => {
-      console.log("error", url, requestId, error);
-    },
-  },
-});
-```
-
----
-
-## TypeScript
-
-Everything is typed. Common types are exported and `Report` is a discriminated
-union on `report.output.type`.
-
-```ts
-import type {
-  Report,
-  Job,
-  ReportCreateJobRequest,
-  ReportOutput,
-  WaitOptions,
-} from "@mappa-ai/mappa-node";
+```bash
+bun run build
+bun run check
+bun run type-check
+bun test
 ```
 
----
-
-## License
-
-MIT