@mappa-ai/mappa-node 0.1.2 → 1.1.1

package/README.md

@@ -1,6 +1,16 @@
-# Mappa Node SDK
+# Mappa Node SDK [WIP - DO NOT USE YET]
 
-A lightweight JavaScript/TypeScript client 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)
+![license](https://img.shields.io/npm/l/@mappa-ai/mappa-node.svg)
+
+Official JavaScript/TypeScript SDK for the **Mappa API**.
+
+- 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**.
+
+---
 
 ## Installation
 
@@ -9,77 +19,456 @@ npm install @mappa-ai/mappa-node
 # or
 yarn add @mappa-ai/mappa-node
 # or
-pnpm install @mappa-ai/mappa-node
+pnpm add @mappa-ai/mappa-node
 # or
 bun add @mappa-ai/mappa-node
 ```
 
-## Requirements
+---
+
+## Quickstart
+
+Create a report from a remote media URL and wait for completion:
+
+```ts
+import { Mappa } from "@mappa-ai/mappa-node";
+
+const mappa = new Mappa({
+  apiKey: process.env.MAPPA_API_KEY!,
+});
+
+  // 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" },
+  });
+
+
+if (report.output.type === "markdown") {
+  console.log(report.markdown);
+}
+```
 
-- A valid Mappa API key.
+---
 
 ## Authentication
 
-Set the `MAPPA_API_KEY` environment variable or pass the key directly:
+Pass the API key when constructing the client:
+
+```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"
 ```
 
+```ts
+const mappa = new Mappa({ apiKey: process.env.MAPPA_API_KEY! });
+```
+
+---
+
+## Configuration
+
+The client supports per-instance configuration:
+
 ```ts
 import { Mappa } from "@mappa-ai/mappa-node";
 
-const client = new Mappa("your-api-key");
+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",
+  },
+});
 ```
 
-## Usage
+### Request tracing
 
-### Instantiate the client
+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
-import { Mappa } from "@mappa-ai/mappa-node";
+await mappa.reports.createJob({
+  media: { mediaId: "media_..." },
+  output: { type: "markdown", template: "general_report" },
+  idempotencyKey: "report:customer_123:2026-01-14",
+  requestId: "req_customer_123",
+});
+```
+
+### Retries
+
+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.
+
+Create a derived client with overrides:
 
-const mappa = new Mappa(); // Reads MAPPA_API_KEY by default
+```ts
+const mappaNoRetries = mappa.withOptions({ maxRetries: 0 });
 ```
 
-### Generate a behavior profile from a remote URL
+### 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.
 
 ```ts
-await mappa.generateTextReport({
-  inputMedia: {
-    kind: "url",
-    url: "https://example.com/media.mp3",
-  },
-  targetSpeaker: { strategy: "dominant" },
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 10_000);
+
+const receipt = await mappa.reports.createJob({
+  media: { mediaId: "media_..." },
+  output: { type: "markdown" },
 });
+
+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");
+  }
+}
 ```
 
-### Generate a behavior profile from an uploaded file
+Streaming with cancellation:
+
+```ts
+const controller = new AbortController();
+
+const handle = mappa.reports.makeHandle("job_...");
+
+setTimeout(() => controller.abort(), 5_000);
+
+for await (const event of handle.stream({ signal: controller.signal })) {
+  if (event.type === "terminal") break;
+}
+```
+
+---
+
+## 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
+
+Report job creation accepts **already-uploaded** media references:
+
+- `{ 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)
+
+If you already have an uploaded `mediaId`, use `createJob()`:
 
 ```ts
-const file = new File([buffer], "sample.wav", { type: "audio/wav" });
+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",
+});
 
-await mappa.generateTextReport({
-  inputMedia: {
-    kind: "file",
-    file,
+console.log(receipt.jobId);
+```
+
+If you’re starting from a remote URL, use `createJobFromUrl()`:
+
+```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" },
   },
-  targetSpeaker: {
-    strategy: "magic_hint",
-    hint: "the person being interviewed",
+  options: {
+    language: "en",
+    timezone: "UTC",
   },
+  idempotencyKey: "report:customer_123:2026-01-14",
 });
+
+console.log(receiptFromUrl.jobId);
+```
+
+### 2) Wait for completion (polling)
+
+```ts
+const report = await receipt.handle!.wait({
+  timeoutMs: 10 * 60_000,
+  onEvent: (e) => {
+    if (e.type === "stage") {
+      console.log("stage", e.stage, e.progress);
+    }
+  },
+});
+```
+
+### 3) Stream job events
+
+`jobs.stream(jobId)` yields state transitions.
+
+```ts
+if (report.output.type === "json") {
+  for (const section of report.sections) {
+    console.log(section.section_title, section.section_content);
+  }
+}
 ```
 
-The method returns:
+Type narrowing helpers:
 
 ```ts
-{
-  behaviorProfile: string;
-  entityId: string;
+if (report.output.type === "markdown") {
+  console.log(report.markdown);
 }
 ```
 
+---
+
+## 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
+
+```ts
+import {
+  ApiError,
+  AuthError,
+  MappaError,
+  RateLimitError,
+  ValidationError,
+} 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;
+}
+```
+
+---
+
+## 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");
+  },
+);
+```
+
+---
+
+## Telemetry hooks
+
+You can hook into request/response/error events:
+
+```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";
+```
+
+---
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -1 +1 @@
-let e=require(`zod`);var t=class{async generateReport(){return``}};async function n(e,t=3){let n;for(let r=0;r<t;r++)try{return await e()}catch(e){console.warn(`Attempt ${r+1} failed. Retrying...`),n=e}throw n}let r;(function(t){t.availablePresetsSchema=e.z.enum([`base`])})(r||={});let i;(function(t){t.generateReportInputSchema=e.z.object({inputMedia:e.z.discriminatedUnion(`kind`,[e.z.object({kind:e.z.literal(`file`),file:e.z.file().mime([`video/*`,`audio/*`],{message:`Invalid file type, only audio and video files are allowed`}).describe(`The audio file to be processed`)}),e.z.object({kind:e.z.literal(`url`),url:e.z.url().describe(`The URL of the audio or video file to be processed`)})]),targetSpeaker:e.z.discriminatedUnion(`strategy`,[e.z.object({strategy:e.z.literal(`dominant`).describe(`Select the speaker who speaks the most in the audio`)}),e.z.object({strategy:e.z.literal(`magic_hint`).describe(`Use a hint to identify the target speaker`),hint:e.z.string().describe(`A hint to help identify the target speaker, e.g., 'the interviewer', 'the CEO', 'the person being interviewed`)})]).default({strategy:`dominant`}).describe(`Strategy for target extraction, this is useful when there are multiple speakers in the audio`),template:r.availablePresetsSchema}),t.generateReportOutputSchema=e.z.object({outputs:e.z.object({entity_id:e.z.string().describe(`The unique identifier for the analyzed entity`),behavior_profile:e.z.string().describe(`The generated behavior profile report`)}).array().transform(e=>e[0]??null)})})(i||={});var a=class{apiKey;apiBaseUrl=`https://api.mappa.ai`;apiVersion=`v1`;presets=new t;constructor(e){if(!e&&typeof process<`u`&&process.env&&process.env.MAPPA_API_KEY?.trim()!==``&&(this.apiKey=process.env.MAPPA_API_KEY||``),this.apiKey=e||``,this.apiKey.trim()===``)throw Error(`Mappa API key is required`)}async generateTextReport(e){let t;if(e.inputMedia.kind===`file`){let r=new FormData;r.append(`file`,e.inputMedia.file),r.append(`metadata`,JSON.stringify({mode:`sync`,output:`behavior_profile`,target:e.targetSpeaker})),t=await n(()=>fetch(`${this.apiBaseUrl}/${this.apiVersion}/analyze/file`,{method:`POST`,headers:{"Mappa-Api-Key":this.apiKey},body:r}))}else{let r=new URL(e.inputMedia.url);t=await n(()=>fetch(`${this.apiBaseUrl}/${this.apiVersion}/analyze/url`,{method:`POST`,headers:{"Content-Type":`application/json`,"Mappa-Api-Key":this.apiKey},body:JSON.stringify({url:r.href,mode:`sync`,output:`behavior_profile`,target:e.targetSpeaker})}))}if(!t.ok){let e=`Mappa API request failed with status ${t.status}: ${await t.text().catch(()=>`Unable to retrieve error message`)}`;throw console.error(e),Error(e)}let r=await t.json(),a=i.generateReportOutputSchema.parse(r).outputs;if(!a)throw Error(`No outputs found in the response, error occurred during analysis.`);return{behaviorProfile:a.behavior_profile,entityId:a.entity_id}}};exports.Mappa=a;
+let e=require(`@paralleldrive/cuid2`);var t=class extends Error{name=`MappaError`;requestId;code;constructor(e,t){super(e),this.requestId=t?.requestId,this.code=t?.code,this.cause=t?.cause}},n=class extends t{name=`ApiError`;status;details;constructor(e,t){super(e,{requestId:t.requestId,code:t.code}),this.status=t.status,this.details=t.details}},r=class extends n{name=`RateLimitError`;retryAfterMs},i=class extends n{name=`AuthError`},a=class extends n{name=`ValidationError`},o=class extends t{name=`JobFailedError`;jobId;constructor(e,t,n){super(t,n),this.jobId=e}},s=class extends t{name=`JobCanceledError`;jobId;constructor(e,t,n){super(t,n),this.jobId=e}},c=class{constructor(e){this.transport=e}async getBalance(e){return(await this.transport.request({method:`GET`,path:`/v1/credits/balance`,requestId:e?.requestId,signal:e?.signal,retryable:!0})).data}async listTransactions(e){let t={};return e?.limit!==void 0&&(t.limit=String(e.limit)),e?.offset!==void 0&&(t.offset=String(e.offset)),(await this.transport.request({method:`GET`,path:`/v1/credits/transactions`,query:t,requestId:e?.requestId,signal:e?.signal,retryable:!0})).data}async*listAllTransactions(e){let t=0,n=e?.limit??50;for(;;){let r=await this.listTransactions({...e,limit:n,offset:t});for(let e of r.transactions)yield e;if(t+=r.transactions.length,t>=r.pagination.total)break}}async getJobUsage(e,n){if(!e)throw new t(`jobId is required`);return(await this.transport.request({method:`GET`,path:`/v1/credits/usage/${encodeURIComponent(e)}`,requestId:n?.requestId,signal:n?.signal,retryable:!0})).data}async hasEnough(e,t){return(await this.getBalance(t)).available>=e}async getAvailable(e){return(await this.getBalance(e)).available}};const l=/^[a-zA-Z0-9_-]{1,64}$/,u=10;function d(e){if(typeof e!=`string`)throw new t(`Tags must be strings`);if(!l.test(e))throw new t(`Invalid tag "${e}": must be 1-64 characters, alphanumeric with underscores and hyphens only`)}function f(e){if(!Array.isArray(e))throw new t(`tags must be an array`);if(e.length>10)throw new t(`Too many tags: maximum 10 per request`);for(let t of e)d(t)}var p=class{constructor(e){this.transport=e}async get(e,n){if(!e||typeof e!=`string`)throw new t(`entityId must be a non-empty string`);return(await this.transport.request({method:`GET`,path:`/v1/entities/${encodeURIComponent(e)}`,requestId:n?.requestId,signal:n?.signal,retryable:!0})).data}async list(e){let t={};return e?.tags&&(f(e.tags),t.tags=e.tags.join(`,`)),e?.cursor&&(t.cursor=e.cursor),e?.limit!==void 0&&(t.limit=String(e.limit)),(await this.transport.request({method:`GET`,path:`/v1/entities`,query:t,requestId:e?.requestId,signal:e?.signal,retryable:!0})).data}async*listAll(e){let t,n=!0;for(;n;){let r=await this.list({...e,cursor:t});for(let e of r.entities)yield e;t=r.cursor,n=r.hasMore}}async getByTag(e,t){return d(e),this.list({...t,tags:[e]})}async addTags(e,n,r){if(!e||typeof e!=`string`)throw new t(`entityId must be a non-empty string`);if(n.length===0)throw new t(`At least one tag is required`);return f(n),(await this.transport.request({method:`POST`,path:`/v1/entities/${encodeURIComponent(e)}/tags`,body:{tags:n},requestId:r?.requestId,signal:r?.signal,retryable:!0})).data}async removeTags(e,n,r){if(!e||typeof e!=`string`)throw new t(`entityId must be a non-empty string`);if(n.length===0)throw new t(`At least one tag is required`);return f(n),(await this.transport.request({method:`DELETE`,path:`/v1/entities/${encodeURIComponent(e)}/tags`,body:{tags:n},requestId:r?.requestId,signal:r?.signal,retryable:!0})).data}async setTags(e,n,r){if(!e||typeof e!=`string`)throw new t(`entityId must be a non-empty string`);return f(n),(await this.transport.request({method:`PUT`,path:`/v1/entities/${encodeURIComponent(e)}/tags`,body:{tags:n},requestId:r?.requestId,signal:r?.signal,retryable:!0})).data}},m=class{constructor(e){this.transport=e}async create(e){if(!!e.reportId==!!e.jobId)throw new t(`Provide exactly one of reportId or jobId`);return(await this.transport.request({method:`POST`,path:`/v1/feedback`,body:e,idempotencyKey:e.idempotencyKey,requestId:e.requestId,signal:e.signal,retryable:!0})).data}},h=class{constructor(e){this.transport=e}async upload(e){if(typeof FormData>`u`)throw new t(`FormData is not available in this runtime; cannot perform multipart upload`);let n=g(e.file,e.filename),r=e.contentType??n;if(!r)throw new t(`contentType is required when it cannot be inferred from file.type or filename`);let i=e.filename??_(e.file)??`upload`,a=await y(e.file,r),o=new FormData;return o.append(`file`,a,i),o.append(`contentType`,r),e.filename&&o.append(`filename`,e.filename),(await this.transport.request({method:`POST`,path:`/v1/files`,body:o,idempotencyKey:e.idempotencyKey,requestId:e.requestId,signal:e.signal,retryable:!0})).data}async get(e,n){if(!e)throw new t(`mediaId is required`);return(await this.transport.request({method:`GET`,path:`/v1/files/${encodeURIComponent(e)}`,requestId:n?.requestId,signal:n?.signal,retryable:!0})).data}async list(e){let t={};return e?.limit!==void 0&&(t.limit=String(e.limit)),e?.cursor&&(t.cursor=e.cursor),e?.includeDeleted!==void 0&&(t.includeDeleted=String(e.includeDeleted)),(await this.transport.request({method:`GET`,path:`/v1/files`,query:t,requestId:e?.requestId,signal:e?.signal,retryable:!0})).data}async*listAll(e){let t,n=!0;for(;n;){let r=await this.list({...e,cursor:t});for(let e of r.files)yield e;t=r.cursor,n=r.hasMore}}async setRetentionLock(e,n,r){if(!e)throw new t(`mediaId is required`);return(await this.transport.request({method:`PATCH`,path:`/v1/files/${encodeURIComponent(e)}/retention`,body:{lock:n},requestId:r?.requestId,signal:r?.signal,retryable:!0})).data}async delete(e,n){if(!e)throw new t(`mediaId is required`);return(await this.transport.request({method:`DELETE`,path:`/v1/files/${encodeURIComponent(e)}`,idempotencyKey:n?.idempotencyKey,requestId:n?.requestId,signal:n?.signal,retryable:!0})).data}};function g(e,t){if(typeof Blob<`u`&&e instanceof Blob&&e.type)return e.type;if(t)return v(t)}function _(e){if(typeof Blob<`u`&&e instanceof Blob){let t=e;if(typeof t.name==`string`&&t.name)return t.name}}function v(e){let t=e.lastIndexOf(`.`);if(!(t<0))switch(e.slice(t+1).toLowerCase()){case`mp4`:return`video/mp4`;case`mov`:return`video/quicktime`;case`webm`:return`video/webm`;case`mp3`:return`audio/mpeg`;case`wav`:return`audio/wav`;case`m4a`:return`audio/mp4`;case`png`:return`image/png`;case`jpg`:case`jpeg`:return`image/jpeg`;case`gif`:return`image/gif`;case`webp`:return`image/webp`;case`pdf`:return`application/pdf`;case`json`:return`application/json`;case`txt`:return`text/plain`;default:return}}async function y(e,n){if(typeof Blob<`u`&&e instanceof Blob){if(e.type===n)return e;let t=e;return typeof t.slice==`function`?t.slice(0,e.size,n):e}if(e instanceof ArrayBuffer||e instanceof Uint8Array)return new Blob([e],{type:n});if(typeof ReadableStream<`u`&&e instanceof ReadableStream){if(typeof Response>`u`)throw new t(`ReadableStream upload requires Response to convert stream to Blob`);let r=await new Response(e).blob();return r.slice(0,r.size,n)}throw new t(`Unsupported file type for upload()`)}var b=class{constructor(e){this.transport=e}async ping(){return(await this.transport.request({method:`GET`,path:`/v1/health/ping`,retryable:!0})).data}};const x=(0,e.init)({length:32});function S(e,t){let n=e.get(t);return n===null?void 0:n}function C(e){let t=.8+Math.random()*.4;return Math.floor(e*t)}function w(e,t,n){let r=t*2**Math.max(0,e-1);return Math.min(r,n)}function T(){return Date.now()}function E(e){return!!e&&typeof e.aborted==`boolean`}function D(){let e=Error(`The operation was aborted`);return e.name=`AbortError`,e}function O(e=`req`){return`${e}_${x()}`}var k=class{constructor(e){this.transport=e}async get(e,t){return(await this.transport.request({method:`GET`,path:`/v1/jobs/${encodeURIComponent(e)}`,requestId:t?.requestId,signal:t?.signal,retryable:!0})).data}async cancel(e,t){return(await this.transport.request({method:`POST`,path:`/v1/jobs/${encodeURIComponent(e)}/cancel`,idempotencyKey:t?.idempotencyKey,requestId:t?.requestId,signal:t?.signal,retryable:!0})).data}async wait(e,t){let n=t?.timeoutMs??5*6e4,r=t?.pollIntervalMs??1e3,i=t?.maxPollIntervalMs??1e4,a=T(),c=0,l,u;for(;;){if(t?.signal?.aborted)throw D();let d=await this.get(e,{signal:t?.signal});if(d.status!==u&&(u=d.status,t?.onEvent?.({type:`status`,job:d})),d.stage&&d.stage!==l&&(l=d.stage,t?.onEvent?.({type:`stage`,stage:d.stage,progress:d.progress,job:d})),d.status===`succeeded`)return t?.onEvent?.({type:`terminal`,job:d}),d;if(d.status===`failed`)throw t?.onEvent?.({type:`terminal`,job:d}),new o(e,d.error?.message??`Job failed`,{requestId:d.requestId,code:d.error?.code,cause:d.error});if(d.status===`canceled`)throw t?.onEvent?.({type:`terminal`,job:d}),new s(e,`Job canceled`,{requestId:d.requestId,cause:d.error});if(T()-a>n)throw new o(e,`Timed out waiting for job ${e} after ${n}ms`,{cause:{jobId:e,timeoutMs:n}});c+=1;let f=C(w(c,r,i));await new Promise(e=>setTimeout(e,f))}}async*stream(e,t){let n,r;for(;;){if(t?.signal?.aborted)return;let i=await this.get(e,{signal:t?.signal});if(i.status!==r){r=i.status;let e={type:`status`,job:i};t?.onEvent?.(e),yield e}if(i.stage&&i.stage!==n){n=i.stage;let e={type:`stage`,stage:i.stage,progress:i.progress,job:i};t?.onEvent?.(e),yield e}if(i.status===`succeeded`||i.status===`failed`||i.status===`canceled`){let e={type:`terminal`,job:i};t?.onEvent?.(e),yield e;return}await new Promise(e=>setTimeout(e,1e3))}}};function A(e){let n=e;if(!(e=>typeof e==`object`&&!!e)(n))throw new t(`media must be an object`);if(n.url!==void 0)throw new t(`media.url is not supported; pass { mediaId } or use createJobFromUrl()`);let r=n.mediaId;if(typeof r!=`string`||!r)throw new t(`media.mediaId must be a non-empty string`)}var j=class{constructor(e,t,n,r){this.transport=e,this.jobs=t,this.files=n,this.fetchImpl=r}async createJob(e){A(e.media);let t=e.idempotencyKey??this.defaultIdempotencyKey(e),n=await this.transport.request({method:`POST`,path:`/v1/reports/jobs`,body:this.normalizeJobRequest(e),idempotencyKey:t,requestId:e.requestId,retryable:!0}),r={...n.data,requestId:n.requestId??n.data.requestId};return r.handle=this.makeHandle(r.jobId),r}async createJobFromFile(e){let{file:t,contentType:n,filename:r,idempotencyKey:i,requestId:a,signal:o,...s}=e,c=await this.files.upload({file:t,contentType:n,filename:r,idempotencyKey:i,requestId:a,signal:o});return this.createJob({...s,media:{mediaId:c.mediaId},idempotencyKey:i,requestId:a})}async createJobFromUrl(e){let{url:n,contentType:r,filename:i,idempotencyKey:a,requestId:o,signal:s,...c}=e,l;try{l=new URL(n)}catch{throw new t(`url must be a valid URL`)}if(l.protocol!==`http:`&&l.protocol!==`https:`)throw new t(`url must use http: or https:`);let u=await this.fetchImpl(l.toString(),{signal:s});if(!u.ok)throw new t(`Failed to download url (status ${u.status})`);let d=u.headers.get(`content-type`)??void 0,f=r??d;if(!f)throw new t(`contentType is required when it cannot be inferred from the download response`);if(typeof Blob>`u`)throw new t(`Blob is not available in this runtime; cannot download and upload from url`);let p=await u.blob(),m=await this.files.upload({file:p,contentType:f,filename:i,idempotencyKey:a,requestId:o,signal:s});return this.createJob({...c,media:{mediaId:m.mediaId},idempotencyKey:a,requestId:o})}async get(e,t){return(await this.transport.request({method:`GET`,path:`/v1/reports/${encodeURIComponent(e)}`,requestId:t?.requestId,signal:t?.signal,retryable:!0})).data}async getByJob(e,t){return(await this.transport.request({method:`GET`,path:`/v1/reports/by-job/${encodeURIComponent(e)}`,requestId:t?.requestId,signal:t?.signal,retryable:!0})).data}async generate(e,n){let r=await this.createJob(e);if(!r.handle)throw new t(`Job receipt is missing handle`);return r.handle.wait(n?.wait)}async generateFromFile(e,n){let r=await this.createJobFromFile(e);if(!r.handle)throw new t(`Job receipt is missing handle`);return r.handle.wait(n?.wait)}async generateFromUrl(e,n){let r=await this.createJobFromUrl(e);if(!r.handle)throw new t(`Job receipt is missing handle`);return r.handle.wait(n?.wait)}makeHandle(e){let n=this;return{jobId:e,stream:t=>n.jobs.stream(e,t),async wait(r){let i=await n.jobs.wait(e,r);if(!i.reportId)throw new t(`Job ${e} succeeded but no reportId was returned`);return n.get(i.reportId)},cancel:()=>n.jobs.cancel(e),job:()=>n.jobs.get(e),report:()=>n.getByJob(e)}}defaultIdempotencyKey(e){return O(`idem`)}normalizeJobRequest(e){let t=e.target;if(!t)return e;let n={strategy:t.strategy};switch(t.onMiss&&(n.on_miss=t.onMiss),t.tags&&t.tags.length>0&&(n.tags=t.tags),t.excludeTags&&t.excludeTags.length>0&&(n.exclude_tags=t.excludeTags),t.strategy){case`dominant`:return{...e,target:n};case`timerange`:{let r=t.timeRange??{};return{...e,target:{...n,timerange:{start_seconds:r.startSeconds??null,end_seconds:r.endSeconds??null}}}}case`entity_id`:return{...e,target:{...n,entity_id:t.entityId}};case`magic_hint`:return{...e,target:{...n,hint:t.hint}};default:return e}}};function M(e,t,n){let r=new URL(t.replace(/^\//,``),e.endsWith(`/`)?e:`${e}/`);if(n)for(let[e,t]of Object.entries(n))t!==void 0&&r.searchParams.set(e,String(t));return r.toString()}async function N(e){let t=await e.text();if(!t)return{parsed:null,text:``};try{return{parsed:JSON.parse(t),text:t}}catch{return{parsed:t,text:t}}}function P(e,t){let o=e.headers.get(`x-request-id`)??void 0,s,c=`Request failed with status ${e.status}`,l=t;if(typeof t==`string`)c=t;else if(t&&typeof t==`object`){let e=t,n=e.error??e;if(n&&typeof n==`object`){let e=n;typeof e.message==`string`&&(c=e.message),typeof e.code==`string`&&(s=e.code),`details`in e&&(l=e.details)}}if(e.status===401||e.status===403)return new i(c,{status:e.status,requestId:o,code:s,details:l});if(e.status===422)return new a(c,{status:e.status,requestId:o,code:s,details:l});if(e.status===429){let t=new r(c,{status:e.status,requestId:o,code:s,details:l}),n=e.headers.get(`retry-after`);if(n){let e=Number(n);Number.isFinite(e)&&e>=0&&(t.retryAfterMs=e*1e3)}return t}return new n(c,{status:e.status,requestId:o,code:s,details:l})}function F(e,t){return e.retryable?t instanceof r?{retry:!0,retryAfterMs:t.retryAfterMs}:t instanceof n?{retry:t.status>=500&&t.status<=599}:t instanceof TypeError?{retry:!0}:{retry:!1}:{retry:!1}}var I=class{fetchImpl;constructor(e){this.opts=e,this.fetchImpl=e.fetch??fetch}async request(e){let t=M(this.opts.baseUrl,e.path,e.query),n=e.requestId??O(`req`),r={"Mappa-Api-Key":this.opts.apiKey,"X-Request-Id":n,...this.opts.userAgent?{"User-Agent":this.opts.userAgent}:{},...this.opts.defaultHeaders??{}};if(e.idempotencyKey&&(r[`Idempotency-Key`]=e.idempotencyKey),e.headers)for(let[t,n]of Object.entries(e.headers))n!==void 0&&(r[t]=n);let i=typeof FormData<`u`&&e.body instanceof FormData;e.body!==void 0&&!i&&(r[`Content-Type`]=`application/json`);let a=e.body===void 0?void 0:i?e.body:JSON.stringify(e.body),o=Math.max(0,this.opts.maxRetries),s=Date.now();for(let i=1;i<=1+o;i++){let c=new AbortController,l=setTimeout(()=>c.abort(D()),this.opts.timeoutMs);if(E(e.signal)){let t=e.signal;if(!t)throw clearTimeout(l),Error(`Unexpected: abort signal missing`);if(t.aborted)throw clearTimeout(l),D();t.addEventListener(`abort`,()=>c.abort(D()),{once:!0})}this.opts.telemetry?.onRequest?.({method:e.method,url:t,requestId:n});try{let l=await this.fetchImpl(t,{method:e.method,headers:r,body:a,signal:c.signal}),u=Date.now()-s,d=S(l.headers,`x-request-id`)??n;if(!l.ok){let{parsed:n}=await N(l),r=P(l,n);this.opts.telemetry?.onError?.({url:t,requestId:d,error:r});let a=F(e,r);if(i<=o+1&&a.retry&&i<=o){let e=a.retryAfterMs??C(w(i,500,4e3));await new Promise(t=>setTimeout(t,e));continue}throw r}let f=l.headers.get(`content-type`)??``,p;return p=f.includes(`application/json`)?await l.json():await l.text(),this.opts.telemetry?.onResponse?.({status:l.status,url:t,requestId:d,durationMs:u}),{data:p,status:l.status,requestId:d,headers:l.headers}}catch(r){this.opts.telemetry?.onError?.({url:t,requestId:n,error:r});let a=F(e,r);if(i<=o&&a.retry){let e=a.retryAfterMs??C(w(i,500,4e3));await new Promise(t=>setTimeout(t,e));continue}throw r}finally{clearTimeout(l)}}throw Error(`Unexpected transport exit`)}};function L(e){return typeof e==`object`&&!!e}var R=class{async verifySignature(e){let t=e.toleranceSec??300,n=z(e.headers,`mappa-signature`);if(!n)throw Error(`Missing mappa-signature header`);let r=B(n),i=Number(r.t);if(!Number.isFinite(i))throw Error(`Invalid signature timestamp`);let a=Math.floor(Date.now()/1e3);if(Math.abs(a-i)>t)throw Error(`Signature timestamp outside tolerance`);let o=`${r.t}.${e.payload}`;if(!U(await V(e.secret,o),r.v1))throw Error(`Invalid signature`);return{ok:!0}}parseEvent(e){let t=JSON.parse(e);if(!L(t))throw Error(`Invalid webhook payload: not an object`);let n=t,r=n.id,i=n.type,a=n.createdAt;if(typeof r!=`string`)throw Error(`Invalid webhook payload: id must be a string`);if(typeof i!=`string`)throw Error(`Invalid webhook payload: type must be a string`);if(typeof a!=`string`)throw Error(`Invalid webhook payload: createdAt must be a string`);return{id:r,type:i,createdAt:a,data:`data`in n?n.data:void 0}}};function z(e,t){let n=Object.keys(e).find(e=>e.toLowerCase()===t.toLowerCase()),r=n?e[n]:void 0;if(r)return Array.isArray(r)?r[0]:r}function B(e){let t={};for(let n of e.split(`,`)){let[e,r]=n.split(`=`);e&&r&&(t[e.trim()]=r.trim())}if(!t.t||!t.v1)throw Error(`Invalid signature format`);return{t:t.t,v1:t.v1}}async function V(e,t){let n=new TextEncoder,r=await crypto.subtle.importKey(`raw`,n.encode(e),{name:`HMAC`,hash:`SHA-256`},!1,[`sign`]);return H(await crypto.subtle.sign(`HMAC`,r,n.encode(t)))}function H(e){let t=new Uint8Array(e),n=``;for(let e of t)n+=e.toString(16).padStart(2,`0`);return n}function U(e,t){if(e.length!==t.length)return!1;let n=0;for(let r=0;r<e.length;r++)n|=e.charCodeAt(r)^t.charCodeAt(r);return n===0}var W=class e{files;jobs;reports;feedback;credits;entities;webhooks;health;transport;opts;constructor(e){if(!e.apiKey)throw new t(`apiKey is required`);let n=e.baseUrl??`https://api.mappa.ai`,r=e.timeoutMs??3e4,i=e.maxRetries??2;this.opts={...e,apiKey:e.apiKey,baseUrl:n,timeoutMs:r,maxRetries:i},this.transport=new I({apiKey:e.apiKey,baseUrl:n,timeoutMs:r,maxRetries:i,defaultHeaders:e.defaultHeaders,fetch:e.fetch,telemetry:e.telemetry,userAgent:e.userAgent}),this.files=new h(this.transport),this.jobs=new k(this.transport),this.reports=new j(this.transport,this.jobs,this.files,this.opts.fetch??fetch),this.feedback=new m(this.transport),this.credits=new c(this.transport),this.entities=new p(this.transport),this.webhooks=new R,this.health=new b(this.transport)}withOptions(t){return new e({...this.opts,...t,apiKey:t.apiKey??this.opts.apiKey})}close(){}};function G(e){return e.output.type===`markdown`}function K(e){return e.output.type===`json`}function q(e){return e.output.type===`pdf`}function J(e){return e.output.type===`url`}function Y(e){return e.entity!==void 0&&e.entity!==null}function X(e){return e instanceof t}exports.ApiError=n,exports.AuthError=i,exports.JobCanceledError=s,exports.JobFailedError=o,exports.Mappa=W,exports.MappaError=t,exports.RateLimitError=r,exports.ValidationError=a,exports.hasEntity=Y,exports.isJsonReport=K,exports.isMappaError=X,exports.isMarkdownReport=G,exports.isPdfReport=q,exports.isUrlReport=J;