@mappa-ai/mappa-node 1.1.1 → 1.2.1

package/dist/index.cjs

@@ -1 +1,1732 @@
-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;
+let _paralleldrive_cuid2 = require("@paralleldrive/cuid2");
+
+//#region src/errors.ts
+/**
+* Symbol for custom Node.js inspect formatting.
+* Ensures errors display nicely in console.log, REPL, and debuggers.
+*/
+const customInspect = Symbol.for("nodejs.util.inspect.custom");
+/**
+* Formats error details for display.
+*/
+function formatDetails(details, indent = "  ") {
+	if (details === void 0 || details === null) return "";
+	try {
+		return JSON.stringify(details, null, 2).split("\n").join(`\n${indent}`);
+	} catch {
+		return String(details);
+	}
+}
+/**
+* Base error type for all SDK-raised errors.
+*
+* When available, {@link MappaError.requestId} can be used to correlate a failure
+* with server logs/support.
+*/
+var MappaError = class extends Error {
+	name = "MappaError";
+	requestId;
+	code;
+	constructor(message, opts) {
+		super(message);
+		this.requestId = opts?.requestId;
+		this.code = opts?.code;
+		this.cause = opts?.cause;
+	}
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		if (this.code) lines.push(`  Code: ${this.code}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		return lines.join("\n");
+	}
+	[customInspect]() {
+		return this.toString();
+	}
+};
+/**
+* Error returned when the API responds with a non-2xx status.
+*/
+var ApiError = class extends MappaError {
+	name = "ApiError";
+	status;
+	details;
+	constructor(message, opts) {
+		super(message, {
+			requestId: opts.requestId,
+			code: opts.code
+		});
+		this.status = opts.status;
+		this.details = opts.details;
+	}
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		lines.push(`  Status: ${this.status}`);
+		if (this.code) lines.push(`  Code: ${this.code}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		if (this.details !== void 0 && this.details !== null) lines.push(`  Details: ${formatDetails(this.details)}`);
+		return lines.join("\n");
+	}
+};
+/**
+* Error returned for HTTP 429 responses.
+*
+* If provided by the server, {@link RateLimitError.retryAfterMs} indicates when
+* it is safe to retry.
+*/
+var RateLimitError = class extends ApiError {
+	name = "RateLimitError";
+	retryAfterMs;
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		lines.push(`  Status: ${this.status}`);
+		if (this.retryAfterMs !== void 0) lines.push(`  Retry After: ${this.retryAfterMs}ms`);
+		if (this.code) lines.push(`  Code: ${this.code}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		return lines.join("\n");
+	}
+};
+/**
+* Error returned for authentication/authorization failures (typically 401/403).
+*/
+var AuthError = class extends ApiError {
+	name = "AuthError";
+};
+/**
+* Error returned when the server rejects a request as invalid (typically 422).
+*/
+var ValidationError = class extends ApiError {
+	name = "ValidationError";
+};
+/**
+* Error returned when the account lacks sufficient credits (HTTP 402).
+*
+* Use {@link InsufficientCreditsError.required} and {@link InsufficientCreditsError.available}
+* to inform users how many credits are needed.
+*
+* @example
+* ```typescript
+* try {
+*   await mappa.reports.createJob({ ... });
+* } catch (err) {
+*   if (err instanceof InsufficientCreditsError) {
+*     console.log(`Need ${err.required} credits, have ${err.available}`);
+*   }
+* }
+* ```
+*/
+var InsufficientCreditsError = class extends ApiError {
+	name = "InsufficientCreditsError";
+	/** Credits required for the operation */
+	required;
+	/** Credits currently available */
+	available;
+	constructor(message, opts) {
+		super(message, opts);
+		this.required = opts.details?.required ?? 0;
+		this.available = opts.details?.available ?? 0;
+	}
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		lines.push(`  Status: ${this.status}`);
+		lines.push(`  Required: ${this.required} credits`);
+		lines.push(`  Available: ${this.available} credits`);
+		if (this.code) lines.push(`  Code: ${this.code}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		return lines.join("\n");
+	}
+};
+/**
+* Error thrown by polling helpers when a job reaches the "failed" terminal state.
+*/
+var JobFailedError = class extends MappaError {
+	name = "JobFailedError";
+	jobId;
+	constructor(jobId, message, opts) {
+		super(message, opts);
+		this.jobId = jobId;
+	}
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		lines.push(`  Job ID: ${this.jobId}`);
+		if (this.code) lines.push(`  Code: ${this.code}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		return lines.join("\n");
+	}
+};
+/**
+* Error thrown by polling helpers when a job reaches the "canceled" terminal state.
+*/
+var JobCanceledError = class extends MappaError {
+	name = "JobCanceledError";
+	jobId;
+	constructor(jobId, message, opts) {
+		super(message, opts);
+		this.jobId = jobId;
+	}
+	toString() {
+		const lines = [`${this.name}: ${this.message}`];
+		lines.push(`  Job ID: ${this.jobId}`);
+		if (this.requestId) lines.push(`  Request ID: ${this.requestId}`);
+		return lines.join("\n");
+	}
+};
+
+//#endregion
+//#region src/resources/credits.ts
+/**
+* Credits API resource.
+*
+* Provides methods to manage and query credit balances, transaction history,
+* and job-specific credit usage.
+*/
+var CreditsResource = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/**
+	* Get the current credit balance for your team.
+	*
+	* @example
+	* const balance = await mappa.credits.getBalance();
+	* console.log(`Available: ${balance.available} credits`);
+	*/
+	async getBalance(opts) {
+		return (await this.transport.request({
+			method: "GET",
+			path: "/v1/credits/balance",
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* List credit transactions with offset pagination.
+	*
+	* @example
+	* const { transactions, pagination } = await mappa.credits.listTransactions({ limit: 25 });
+	* console.log(`Showing ${transactions.length} of ${pagination.total}`);
+	*/
+	async listTransactions(opts) {
+		const query = {};
+		if (opts?.limit !== void 0) query.limit = String(opts.limit);
+		if (opts?.offset !== void 0) query.offset = String(opts.offset);
+		return (await this.transport.request({
+			method: "GET",
+			path: "/v1/credits/transactions",
+			query,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Iterate over all transactions, automatically handling pagination.
+	*
+	* @example
+	* for await (const tx of mappa.credits.listAllTransactions()) {
+	*   console.log(`${tx.type}: ${tx.amount}`);
+	* }
+	*/
+	async *listAllTransactions(opts) {
+		let offset = 0;
+		const limit = opts?.limit ?? 50;
+		while (true) {
+			const page = await this.listTransactions({
+				...opts,
+				limit,
+				offset
+			});
+			for (const tx of page.transactions) yield tx;
+			offset += page.transactions.length;
+			if (offset >= page.pagination.total) break;
+		}
+	}
+	/**
+	* Get credit usage details for a completed job.
+	*
+	* @example
+	* const usage = await mappa.credits.getJobUsage("job_xyz");
+	* console.log(`Net credits used: ${usage.creditsNetUsed}`);
+	*/
+	async getJobUsage(jobId, opts) {
+		if (!jobId) throw new MappaError("jobId is required");
+		return (await this.transport.request({
+			method: "GET",
+			path: `/v1/credits/usage/${encodeURIComponent(jobId)}`,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Check if the team has enough available credits for an operation.
+	*
+	* @example
+	* if (await mappa.credits.hasEnough(100)) {
+	*   await mappa.reports.createJob(...);
+	* }
+	*/
+	async hasEnough(credits, opts) {
+		return (await this.getBalance(opts)).available >= credits;
+	}
+	/**
+	* Get the number of available credits (balance - reserved).
+	*
+	* @example
+	* const available = await mappa.credits.getAvailable();
+	* console.log(`You can spend ${available} credits`);
+	*/
+	async getAvailable(opts) {
+		return (await this.getBalance(opts)).available;
+	}
+};
+
+//#endregion
+//#region src/resources/entities.ts
+/**
+* Tag validation regex: 1-64 chars, alphanumeric with underscores and hyphens.
+*/
+const TAG_REGEX = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+* Maximum number of tags per request.
+*/
+const MAX_TAGS_PER_REQUEST = 10;
+/**
+* Validates a single tag.
+* @throws {MappaError} if validation fails
+*/
+function validateTag(tag) {
+	if (typeof tag !== "string") throw new MappaError("Tags must be strings");
+	if (!TAG_REGEX.test(tag)) throw new MappaError(`Invalid tag "${tag}": must be 1-64 characters, alphanumeric with underscores and hyphens only`);
+}
+/**
+* Validates an array of tags.
+* @throws {MappaError} if validation fails
+*/
+function validateTags(tags) {
+	if (!Array.isArray(tags)) throw new MappaError("tags must be an array");
+	if (tags.length > MAX_TAGS_PER_REQUEST) throw new MappaError(`Too many tags: maximum ${MAX_TAGS_PER_REQUEST} per request`);
+	for (const tag of tags) validateTag(tag);
+}
+/**
+* Entities API resource.
+*
+* Responsibilities:
+* - List entities with optional tag filtering (`GET /v1/entities`)
+* - Get single entity details (`GET /v1/entities/:entityId`)
+* - Add tags to entities (`POST /v1/entities/:entityId/tags`)
+* - Remove tags from entities (`DELETE /v1/entities/:entityId/tags`)
+* - Replace all entity tags (`PUT /v1/entities/:entityId/tags`)
+*
+* Entities represent analyzed speakers identified by voice fingerprints.
+* Tags allow you to label entities (e.g., "interviewer", "sales-rep") for easier
+* filtering and identification across multiple reports.
+*/
+var EntitiesResource = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/**
+	* Get a single entity by ID.
+	*
+	* Returns entity metadata including tags, creation time, and usage statistics.
+	*
+	* @param entityId - The entity ID to retrieve
+	* @param opts - Optional request options (requestId, signal)
+	* @returns Entity details with tags and metadata
+	*
+	* @example
+	* ```typescript
+	* const entity = await mappa.entities.get("entity_abc123");
+	* console.log(entity.tags); // ["interviewer", "john"]
+	* ```
+	*/
+	async get(entityId, opts) {
+		if (!entityId || typeof entityId !== "string") throw new MappaError("entityId must be a non-empty string");
+		return (await this.transport.request({
+			method: "GET",
+			path: `/v1/entities/${encodeURIComponent(entityId)}`,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* List entities with optional tag filtering.
+	*
+	* Supports cursor-based pagination. Use the returned `cursor` for fetching
+	* subsequent pages, or use {@link listAll} for automatic pagination.
+	*
+	* When `tags` is provided, only entities with ALL specified tags are returned (AND logic).
+	*
+	* @param opts - List options: tags filter, cursor, limit
+	* @returns Paginated list of entities
+	*
+	* @example
+	* ```typescript
+	* // List all entities
+	* const page1 = await mappa.entities.list({ limit: 20 });
+	*
+	* // Filter by tags (must have both "interviewer" AND "sales")
+	* const filtered = await mappa.entities.list({
+	*   tags: ["interviewer", "sales"],
+	*   limit: 50
+	* });
+	*
+	* // Pagination
+	* const page2 = await mappa.entities.list({
+	*   cursor: page1.cursor,
+	*   limit: 20
+	* });
+	* ```
+	*/
+	async list(opts) {
+		const query = {};
+		if (opts?.tags) {
+			validateTags(opts.tags);
+			query.tags = opts.tags.join(",");
+		}
+		if (opts?.cursor) query.cursor = opts.cursor;
+		if (opts?.limit !== void 0) query.limit = String(opts.limit);
+		return (await this.transport.request({
+			method: "GET",
+			path: "/v1/entities",
+			query,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Async iterator that automatically paginates through all entities.
+	*
+	* Useful for processing large entity sets without manual pagination management.
+	*
+	* @param opts - List options: tags filter, limit per page
+	* @yields Individual entities
+	*
+	* @example
+	* ```typescript
+	* // Process all entities with "interviewer" tag
+	* for await (const entity of mappa.entities.listAll({ tags: ["interviewer"] })) {
+	*   console.log(`${entity.id}: ${entity.tags.join(", ")}`);
+	* }
+	* ```
+	*/
+	async *listAll(opts) {
+		let cursor;
+		let hasMore = true;
+		while (hasMore) {
+			const page = await this.list({
+				...opts,
+				cursor
+			});
+			for (const entity of page.entities) yield entity;
+			cursor = page.cursor;
+			hasMore = page.hasMore;
+		}
+	}
+	/**
+	* Get all entities with a specific tag.
+	*
+	* Convenience wrapper around {@link list} for single-tag filtering.
+	*
+	* @param tag - The tag to filter by
+	* @param opts - Optional pagination and request options
+	* @returns Paginated list of entities with the specified tag
+	*
+	* @example
+	* ```typescript
+	* const interviewers = await mappa.entities.getByTag("interviewer");
+	* ```
+	*/
+	async getByTag(tag, opts) {
+		validateTag(tag);
+		return this.list({
+			...opts,
+			tags: [tag]
+		});
+	}
+	/**
+	* Add tags to an entity.
+	*
+	* Idempotent: existing tags are preserved, duplicates are ignored.
+	*
+	* @param entityId - The entity ID to tag
+	* @param tags - Array of tags to add (1-10 tags, each 1-64 chars)
+	* @param opts - Optional request options
+	* @returns Updated tags for the entity
+	*
+	* @example
+	* ```typescript
+	* await mappa.entities.addTags("entity_abc123", ["interviewer", "john"]);
+	* ```
+	*/
+	async addTags(entityId, tags, opts) {
+		if (!entityId || typeof entityId !== "string") throw new MappaError("entityId must be a non-empty string");
+		if (tags.length === 0) throw new MappaError("At least one tag is required");
+		validateTags(tags);
+		return (await this.transport.request({
+			method: "POST",
+			path: `/v1/entities/${encodeURIComponent(entityId)}/tags`,
+			body: { tags },
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Remove tags from an entity.
+	*
+	* Idempotent: missing tags are silently ignored.
+	*
+	* @param entityId - The entity ID to update
+	* @param tags - Array of tags to remove
+	* @param opts - Optional request options
+	* @returns Updated tags for the entity
+	*
+	* @example
+	* ```typescript
+	* await mappa.entities.removeTags("entity_abc123", ["interviewer"]);
+	* ```
+	*/
+	async removeTags(entityId, tags, opts) {
+		if (!entityId || typeof entityId !== "string") throw new MappaError("entityId must be a non-empty string");
+		if (tags.length === 0) throw new MappaError("At least one tag is required");
+		validateTags(tags);
+		return (await this.transport.request({
+			method: "DELETE",
+			path: `/v1/entities/${encodeURIComponent(entityId)}/tags`,
+			body: { tags },
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Replace all tags on an entity.
+	*
+	* Sets the complete tag list, removing any tags not in the provided array.
+	* Pass an empty array to remove all tags.
+	*
+	* @param entityId - The entity ID to update
+	* @param tags - New complete tag list (0-10 tags)
+	* @param opts - Optional request options
+	* @returns Updated tags for the entity
+	*
+	* @example
+	* ```typescript
+	* // Replace all tags
+	* await mappa.entities.setTags("entity_abc123", ["sales-rep", "john"]);
+	*
+	* // Remove all tags
+	* await mappa.entities.setTags("entity_abc123", []);
+	* ```
+	*/
+	async setTags(entityId, tags, opts) {
+		if (!entityId || typeof entityId !== "string") throw new MappaError("entityId must be a non-empty string");
+		validateTags(tags);
+		return (await this.transport.request({
+			method: "PUT",
+			path: `/v1/entities/${encodeURIComponent(entityId)}/tags`,
+			body: { tags },
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+};
+
+//#endregion
+//#region src/resources/feedback.ts
+var FeedbackResource = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/**
+	* Create feedback for a report or job. Provide exactly one of `reportId` or `jobId`.
+	*/
+	async create(req) {
+		if (!!req.reportId === !!req.jobId) throw new MappaError("Provide exactly one of reportId or jobId");
+		return (await this.transport.request({
+			method: "POST",
+			path: "/v1/feedback",
+			body: req,
+			idempotencyKey: req.idempotencyKey,
+			requestId: req.requestId,
+			signal: req.signal,
+			retryable: true
+		})).data;
+	}
+};
+
+//#endregion
+//#region src/resources/files.ts
+/**
+* Uses multipart/form-data for uploads.
+*
+* If you need resumable uploads, add a dedicated resumable protocol.
+*/
+var FilesResource = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	async upload(req) {
+		if (typeof FormData === "undefined") throw new MappaError("FormData is not available in this runtime; cannot perform multipart upload");
+		const derivedContentType = inferContentType(req.file, req.filename);
+		const contentType = req.contentType ?? derivedContentType;
+		if (!contentType) throw new MappaError("contentType is required when it cannot be inferred from file.type or filename");
+		const filename = req.filename ?? inferFilename(req.file) ?? "upload";
+		const filePart = await toFormDataPart(req.file, contentType);
+		const form = new FormData();
+		form.append("file", filePart, filename);
+		form.append("contentType", contentType);
+		if (req.filename) form.append("filename", req.filename);
+		return (await this.transport.request({
+			method: "POST",
+			path: "/v1/files",
+			body: form,
+			idempotencyKey: req.idempotencyKey,
+			requestId: req.requestId,
+			signal: req.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Retrieve metadata for a single uploaded file.
+	*
+	* @example
+	* const file = await mappa.files.get("media_abc123");
+	* console.log(file.processingStatus); // "COMPLETED"
+	*/
+	async get(mediaId, opts) {
+		if (!mediaId) throw new MappaError("mediaId is required");
+		return (await this.transport.request({
+			method: "GET",
+			path: `/v1/files/${encodeURIComponent(mediaId)}`,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* List uploaded files with cursor pagination.
+	*
+	* @example
+	* const page1 = await mappa.files.list({ limit: 10 });
+	* if (page1.hasMore) {
+	*   const page2 = await mappa.files.list({ limit: 10, cursor: page1.cursor });
+	* }
+	*/
+	async list(opts) {
+		const query = {};
+		if (opts?.limit !== void 0) query.limit = String(opts.limit);
+		if (opts?.cursor) query.cursor = opts.cursor;
+		if (opts?.includeDeleted !== void 0) query.includeDeleted = String(opts.includeDeleted);
+		return (await this.transport.request({
+			method: "GET",
+			path: "/v1/files",
+			query,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Iterate over all files, automatically handling pagination.
+	*
+	* @example
+	* for await (const file of mappa.files.listAll()) {
+	*   console.log(file.mediaId);
+	* }
+	*
+	* // Or collect all
+	* const allFiles = [];
+	* for await (const file of mappa.files.listAll({ limit: 50 })) {
+	*   allFiles.push(file);
+	* }
+	*/
+	async *listAll(opts) {
+		let cursor;
+		let hasMore = true;
+		while (hasMore) {
+			const page = await this.list({
+				...opts,
+				cursor
+			});
+			for (const file of page.files) yield file;
+			cursor = page.cursor;
+			hasMore = page.hasMore;
+		}
+	}
+	/**
+	* Lock or unlock a file's retention to prevent/allow automatic deletion.
+	*
+	* @example
+	* // Prevent automatic deletion
+	* await mappa.files.setRetentionLock("media_abc", true);
+	*
+	* // Allow automatic deletion
+	* await mappa.files.setRetentionLock("media_abc", false);
+	*/
+	async setRetentionLock(mediaId, locked, opts) {
+		if (!mediaId) throw new MappaError("mediaId is required");
+		return (await this.transport.request({
+			method: "PATCH",
+			path: `/v1/files/${encodeURIComponent(mediaId)}/retention`,
+			body: { lock: locked },
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	async delete(mediaId, opts) {
+		if (!mediaId) throw new MappaError("mediaId is required");
+		return (await this.transport.request({
+			method: "DELETE",
+			path: `/v1/files/${encodeURIComponent(mediaId)}`,
+			idempotencyKey: opts?.idempotencyKey,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+};
+function inferContentType(file, filename) {
+	if (typeof Blob !== "undefined" && file instanceof Blob) {
+		if (file.type) return file.type;
+	}
+	if (filename) return contentTypeFromFilename(filename);
+}
+function inferFilename(file) {
+	if (typeof Blob !== "undefined" && file instanceof Blob) {
+		const anyBlob = file;
+		if (typeof anyBlob.name === "string" && anyBlob.name) return anyBlob.name;
+	}
+}
+function contentTypeFromFilename(filename) {
+	const i = filename.lastIndexOf(".");
+	if (i < 0) return void 0;
+	switch (filename.slice(i + 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 toFormDataPart(file, contentType) {
+	if (typeof Blob !== "undefined" && file instanceof Blob) {
+		if (file.type === contentType) return file;
+		const slicer = file;
+		if (typeof slicer.slice === "function") return slicer.slice(0, file.size, contentType);
+		return file;
+	}
+	if (file instanceof ArrayBuffer) return new Blob([file], { type: contentType });
+	if (file instanceof Uint8Array) return new Blob([file], { type: contentType });
+	if (typeof ReadableStream !== "undefined" && file instanceof ReadableStream) {
+		if (typeof Response === "undefined") throw new MappaError("ReadableStream upload requires Response to convert stream to Blob");
+		const blob = await new Response(file).blob();
+		return blob.slice(0, blob.size, contentType);
+	}
+	throw new MappaError("Unsupported file type for upload()");
+}
+
+//#endregion
+//#region src/resources/health.ts
+var HealthResource = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	async ping() {
+		return (await this.transport.request({
+			method: "GET",
+			path: "/v1/health/ping",
+			retryable: true
+		})).data;
+	}
+};
+
+//#endregion
+//#region src/utils/index.ts
+const createId = (0, _paralleldrive_cuid2.init)({ length: 32 });
+function getHeader(headers, name) {
+	const v = headers.get(name);
+	return v === null ? void 0 : v;
+}
+function jitter(ms) {
+	const r = .8 + Math.random() * .4;
+	return Math.floor(ms * r);
+}
+function backoffMs(attempt, baseMs, maxMs) {
+	const ms = baseMs * 2 ** Math.max(0, attempt - 1);
+	return Math.min(ms, maxMs);
+}
+function hasAbortSignal(signal) {
+	return !!signal && typeof signal.aborted === "boolean";
+}
+function makeAbortError() {
+	const e = /* @__PURE__ */ new Error("The operation was aborted");
+	e.name = "AbortError";
+	return e;
+}
+function randomId(prefix = "req") {
+	return `${prefix}_${createId()}`;
+}
+
+//#endregion
+//#region src/resources/jobs.ts
+var JobsResource = class {
+	constructor(transport) {
+		this.transport = transport;
+	}
+	async get(jobId, opts) {
+		return (await this.transport.request({
+			method: "GET",
+			path: `/v1/jobs/${encodeURIComponent(jobId)}`,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	async cancel(jobId, opts) {
+		return (await this.transport.request({
+			method: "POST",
+			path: `/v1/jobs/${encodeURIComponent(jobId)}/cancel`,
+			idempotencyKey: opts?.idempotencyKey,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Wait for a job to reach a terminal state.
+	*
+	* Uses SSE streaming internally for efficient real-time updates.
+	*/
+	async wait(jobId, opts) {
+		const timeoutMs = opts?.timeoutMs ?? 5 * 6e4;
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+		if (opts?.signal) {
+			if (opts.signal.aborted) {
+				clearTimeout(timeoutId);
+				throw makeAbortError();
+			}
+			opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+		}
+		try {
+			for await (const event of this.stream(jobId, {
+				signal: controller.signal,
+				onEvent: opts?.onEvent
+			})) if (event.type === "terminal") {
+				const job = event.job;
+				if (job.status === "succeeded") return job;
+				if (job.status === "failed") throw new JobFailedError(jobId, job.error?.message ?? "Job failed", {
+					requestId: job.requestId,
+					code: job.error?.code,
+					cause: job.error
+				});
+				if (job.status === "canceled") throw new JobCanceledError(jobId, "Job canceled", {
+					requestId: job.requestId,
+					cause: job.error
+				});
+			}
+			throw new JobFailedError(jobId, `Timed out waiting for job ${jobId} after ${timeoutMs}ms`, { cause: {
+				jobId,
+				timeoutMs
+			} });
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+	/**
+	* Stream job events via SSE.
+	*
+	* Yields events as they arrive from the server. Use `AbortSignal` to cancel streaming.
+	* Automatically handles reconnection with `Last-Event-ID` for up to 3 retries.
+	*/
+	async *stream(jobId, opts) {
+		const maxRetries = 3;
+		let lastEventId;
+		let retries = 0;
+		while (retries < maxRetries) try {
+			const sseStream = this.transport.streamSSE(`/v1/jobs/${encodeURIComponent(jobId)}/stream`, {
+				signal: opts?.signal,
+				lastEventId
+			});
+			for await (const sseEvent of sseStream) {
+				lastEventId = sseEvent.id;
+				if (sseEvent.event === "error") {
+					const errorData = sseEvent.data;
+					throw new MappaError(errorData.error?.message ?? "Unknown SSE error", { code: errorData.error?.code });
+				}
+				if (sseEvent.event === "heartbeat") continue;
+				const jobEvent = this.mapSSEToJobEvent(sseEvent);
+				if (jobEvent) {
+					opts?.onEvent?.(jobEvent);
+					yield jobEvent;
+					if (sseEvent.event === "terminal") return;
+				}
+				retries = 0;
+			}
+			retries++;
+			if (retries < maxRetries) await this.backoff(retries);
+		} catch (error) {
+			if (opts?.signal?.aborted) throw error;
+			retries++;
+			if (retries >= maxRetries) throw error;
+			await this.backoff(retries);
+		}
+		throw new MappaError(`Failed to get status for job ${jobId} after ${maxRetries} retries`);
+	}
+	/**
+	* Map an SSE event to a JobEvent.
+	*/
+	mapSSEToJobEvent(sseEvent) {
+		const data = sseEvent.data;
+		switch (sseEvent.event) {
+			case "status": return {
+				type: "status",
+				job: data.job
+			};
+			case "stage": return {
+				type: "stage",
+				stage: data.stage,
+				progress: data.progress,
+				job: data.job
+			};
+			case "terminal": return {
+				type: "terminal",
+				job: data.job
+			};
+			default: return {
+				type: "status",
+				job: data.job
+			};
+		}
+	}
+	/**
+	* Exponential backoff with jitter for reconnection.
+	*/
+	async backoff(attempt) {
+		const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+		const jitter$1 = delay * .5 * Math.random();
+		await new Promise((r) => setTimeout(r, delay + jitter$1));
+	}
+};
+
+//#endregion
+//#region src/resources/reports.ts
+/**
+* Runtime validation for the internal `MediaIdRef` requirement.
+*
+* The public API server expects a `mediaId` when creating a report job.
+* Use helpers like `createJobFromFile` / `createJobFromUrl` to start from bytes or a URL.
+*/
+function validateMedia(media) {
+	const m = media;
+	const isObj = (v) => v !== null && typeof v === "object";
+	if (!isObj(m)) throw new MappaError("media must be an object");
+	if (m.url !== void 0) throw new MappaError("media.url is not supported; pass { mediaId } or use createJobFromUrl()");
+	const mediaId = m.mediaId;
+	if (typeof mediaId !== "string" || !mediaId) throw new MappaError("media.mediaId must be a non-empty string");
+}
+/**
+* Reports API resource.
+*
+* Responsibilities:
+* - Create report jobs (`POST /v1/reports/jobs`).
+* - Fetch reports by report ID (`GET /v1/reports/:reportId`).
+* - Fetch reports by job ID (`GET /v1/reports/by-job/:jobId`).
+*
+* Convenience helpers:
+* - {@link ReportsResource.createJobFromFile} orchestrates `files.upload()` + {@link ReportsResource.createJob}.
+* - {@link ReportsResource.createJobFromUrl} downloads a remote URL, uploads it, then calls {@link ReportsResource.createJob}.
+* - {@link ReportsResource.generate} / {@link ReportsResource.generateFromFile} are script-friendly wrappers that
+*   create a job, wait for completion, and then fetch the final report.
+*
+* For production systems, prefer `createJob*()` plus webhooks or streaming job events rather than blocking waits.
+*/
+var ReportsResource = class {
+	constructor(transport, jobs, files, fetchImpl) {
+		this.transport = transport;
+		this.jobs = jobs;
+		this.files = files;
+		this.fetchImpl = fetchImpl;
+	}
+	/**
+	* Create a new report job.
+	*
+	* Behavior:
+	* - Validates {@link MediaIdRef} at runtime (must provide `{ mediaId }`).
+	* - Defaults to `{ strategy: "dominant" }` when `target` is omitted.
+	* - Applies an idempotency key: uses `req.idempotencyKey` when provided; otherwise generates a best-effort default.
+	* - Forwards `req.requestId` to the transport for end-to-end correlation.
+	*
+	* The returned receipt includes a {@link ReportRunHandle} (`receipt.handle`) which can be used to:
+	* - stream job events
+	* - wait for completion and fetch the final report
+	* - cancel the job, or fetch job/report metadata
+	*/
+	async createJob(req) {
+		validateMedia(req.media);
+		const idempotencyKey = req.idempotencyKey ?? this.defaultIdempotencyKey(req);
+		const res = await this.transport.request({
+			method: "POST",
+			path: "/v1/reports/jobs",
+			body: this.normalizeJobRequest(req),
+			idempotencyKey,
+			requestId: req.requestId,
+			retryable: true
+		});
+		const receipt = {
+			...res.data,
+			requestId: res.requestId ?? res.data.requestId
+		};
+		receipt.handle = this.makeHandle(receipt.jobId);
+		return receipt;
+	}
+	/**
+	* Upload a file and create a report job in one call.
+	*
+	* Keeps `createJob()` strict about `media: { mediaId }` while offering a
+	* convenient helper when you start from raw bytes.
+	*/
+	async createJobFromFile(req) {
+		const { file, contentType, filename, idempotencyKey, requestId, signal, ...rest } = req;
+		const upload = await this.files.upload({
+			file,
+			contentType,
+			filename,
+			idempotencyKey,
+			requestId,
+			signal
+		});
+		return this.createJob({
+			...rest,
+			media: { mediaId: upload.mediaId },
+			idempotencyKey,
+			requestId
+		});
+	}
+	/**
+	* Download a file from a URL, upload it, and create a report job.
+	*
+	* Recommended when starting from a remote URL because report job creation
+	* only accepts `media: { mediaId }`.
+	*
+	* Workflow:
+	* 1) `fetch(url)`
+	* 2) Validate the response (2xx) and derive `contentType`
+	* 3) `files.upload({ file: Blob, ... })`
+	* 4) `createJob({ media: { mediaId }, ... })`
+	*
+	* Verification / safety:
+	* - Only allows `http:` and `https:` URLs.
+	* - Requires a resolvable `contentType` (from `req.contentType` or response header).
+	*/
+	async createJobFromUrl(req) {
+		const { url, contentType: contentTypeOverride, filename, idempotencyKey, requestId, signal, ...rest } = req;
+		let parsed;
+		try {
+			parsed = new URL(url);
+		} catch {
+			throw new MappaError("url must be a valid URL");
+		}
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new MappaError("url must use http: or https:");
+		const res = await this.fetchImpl(parsed.toString(), { signal });
+		if (!res.ok) throw new MappaError(`Failed to download url (status ${res.status})`);
+		const derivedContentType = res.headers.get("content-type") ?? void 0;
+		const contentType = contentTypeOverride ?? derivedContentType;
+		if (!contentType) throw new MappaError("contentType is required when it cannot be inferred from the download response");
+		if (typeof Blob === "undefined") throw new MappaError("Blob is not available in this runtime; cannot download and upload from url");
+		const blob = await res.blob();
+		const upload = await this.files.upload({
+			file: blob,
+			contentType,
+			filename,
+			idempotencyKey,
+			requestId,
+			signal
+		});
+		return this.createJob({
+			...rest,
+			media: { mediaId: upload.mediaId },
+			idempotencyKey,
+			requestId
+		});
+	}
+	async get(reportId, opts) {
+		return (await this.transport.request({
+			method: "GET",
+			path: `/v1/reports/${encodeURIComponent(reportId)}`,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	async getByJob(jobId, opts) {
+		return (await this.transport.request({
+			method: "GET",
+			path: `/v1/reports/by-job/${encodeURIComponent(jobId)}`,
+			requestId: opts?.requestId,
+			signal: opts?.signal,
+			retryable: true
+		})).data;
+	}
+	/**
+	* Convenience wrapper: createJob + wait + get
+	* Use for scripts; for production prefer createJob + webhooks/stream.
+	*/
+	async generate(req, opts) {
+		const receipt = await this.createJob(req);
+		if (!receipt.handle) throw new MappaError("Job receipt is missing handle");
+		return receipt.handle.wait(opts?.wait);
+	}
+	/**
+	* Convenience wrapper: createJobFromFile + wait + get.
+	* Use for scripts; for production prefer createJobFromFile + webhooks/stream.
+	*/
+	async generateFromFile(req, opts) {
+		const receipt = await this.createJobFromFile(req);
+		if (!receipt.handle) throw new MappaError("Job receipt is missing handle");
+		return receipt.handle.wait(opts?.wait);
+	}
+	/**
+	* Convenience wrapper: createJobFromUrl + wait + get.
+	* Use for scripts; for production prefer createJobFromUrl + webhooks/stream.
+	*/
+	async generateFromUrl(req, opts) {
+		const receipt = await this.createJobFromUrl(req);
+		if (!receipt.handle) throw new MappaError("Job receipt is missing handle");
+		return receipt.handle.wait(opts?.wait);
+	}
+	makeHandle(jobId) {
+		const self = this;
+		return {
+			jobId,
+			stream: (opts) => self.jobs.stream(jobId, opts),
+			async wait(opts) {
+				const terminal = await self.jobs.wait(jobId, opts);
+				if (!terminal.reportId) throw new MappaError(`Job ${jobId} succeeded but no reportId was returned`);
+				return self.get(terminal.reportId);
+			},
+			cancel: () => self.jobs.cancel(jobId),
+			job: () => self.jobs.get(jobId),
+			report: () => self.getByJob(jobId)
+		};
+	}
+	defaultIdempotencyKey(_req) {
+		return randomId("idem");
+	}
+	normalizeJobRequest(req) {
+		const target = req.target;
+		if (!target) return {
+			...req,
+			target: { strategy: "dominant" }
+		};
+		const baseTarget = { strategy: target.strategy };
+		if (target.onMiss) baseTarget.on_miss = target.onMiss;
+		if (target.tags && target.tags.length > 0) baseTarget.tags = target.tags;
+		if (target.excludeTags && target.excludeTags.length > 0) baseTarget.exclude_tags = target.excludeTags;
+		switch (target.strategy) {
+			case "dominant": return {
+				...req,
+				target: baseTarget
+			};
+			case "timerange": {
+				const timeRange = target.timeRange ?? {};
+				return {
+					...req,
+					target: {
+						...baseTarget,
+						timerange: {
+							start_seconds: timeRange.startSeconds ?? null,
+							end_seconds: timeRange.endSeconds ?? null
+						}
+					}
+				};
+			}
+			case "entity_id": return {
+				...req,
+				target: {
+					...baseTarget,
+					entity_id: target.entityId
+				}
+			};
+			case "magic_hint": return {
+				...req,
+				target: {
+					...baseTarget,
+					hint: target.hint
+				}
+			};
+			default: return req;
+		}
+	}
+};
+
+//#endregion
+//#region src/resources/transport.ts
+function buildUrl(baseUrl, path, query) {
+	const u = new URL(path.replace(/^\//, ""), baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+	if (query) for (const [k, v] of Object.entries(query)) {
+		if (v === void 0) continue;
+		u.searchParams.set(k, String(v));
+	}
+	return u.toString();
+}
+async function readBody(res) {
+	const text = await res.text();
+	if (!text) return {
+		parsed: null,
+		text: ""
+	};
+	try {
+		return {
+			parsed: JSON.parse(text),
+			text
+		};
+	} catch {
+		return {
+			parsed: text,
+			text
+		};
+	}
+}
+function coerceApiError(res, parsed) {
+	const requestId = res.headers.get("x-request-id") ?? void 0;
+	let code;
+	let message = `Request failed with status ${res.status}`;
+	let details = parsed;
+	if (typeof parsed === "string") message = parsed;
+	else if (parsed && typeof parsed === "object") {
+		const p = parsed;
+		const err = p.error ?? p;
+		if (err && typeof err === "object") {
+			const e = err;
+			if (typeof e.message === "string") message = e.message;
+			if (typeof e.code === "string") code = e.code;
+			if ("details" in e) details = e.details;
+		}
+	}
+	if (res.status === 401 || res.status === 403) return new AuthError(message, {
+		status: res.status,
+		requestId,
+		code,
+		details
+	});
+	if (res.status === 422) return new ValidationError(message, {
+		status: res.status,
+		requestId,
+		code,
+		details
+	});
+	if (res.status === 402 && code === "insufficient_credits") return new InsufficientCreditsError(message, {
+		status: res.status,
+		requestId,
+		code,
+		details
+	});
+	if (res.status === 429) {
+		const e = new RateLimitError(message, {
+			status: res.status,
+			requestId,
+			code,
+			details
+		});
+		const ra = res.headers.get("retry-after");
+		if (ra) {
+			const sec = Number(ra);
+			if (Number.isFinite(sec) && sec >= 0) e.retryAfterMs = sec * 1e3;
+		}
+		return e;
+	}
+	return new ApiError(message, {
+		status: res.status,
+		requestId,
+		code,
+		details
+	});
+}
+function shouldRetry(opts, err) {
+	if (!opts.retryable) return { retry: false };
+	if (err instanceof RateLimitError) return {
+		retry: true,
+		retryAfterMs: err.retryAfterMs
+	};
+	if (err instanceof ApiError) return { retry: err.status >= 500 && err.status <= 599 };
+	if (err instanceof TypeError) return { retry: true };
+	return { retry: false };
+}
+var Transport = class {
+	fetchImpl;
+	constructor(opts) {
+		this.opts = opts;
+		this.fetchImpl = opts.fetch ?? fetch;
+	}
+	/**
+	* Stream SSE events from a given path.
+	*
+	* Uses native `fetch` with streaming response body (not browser-only `EventSource`).
+	* Parses SSE format manually from the `ReadableStream`.
+	*/
+	async *streamSSE(path, opts) {
+		const url = buildUrl(this.opts.baseUrl, path);
+		const requestId = randomId("req");
+		const headers = {
+			Accept: "text/event-stream",
+			"Cache-Control": "no-cache",
+			"Mappa-Api-Key": this.opts.apiKey,
+			"X-Request-Id": requestId,
+			...this.opts.userAgent ? { "User-Agent": this.opts.userAgent } : {},
+			...this.opts.defaultHeaders ?? {}
+		};
+		if (opts?.lastEventId) headers["Last-Event-ID"] = opts.lastEventId;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(makeAbortError()), this.opts.timeoutMs);
+		if (hasAbortSignal(opts?.signal)) {
+			const signal = opts?.signal;
+			if (signal?.aborted) {
+				clearTimeout(timeout);
+				throw makeAbortError();
+			}
+			signal?.addEventListener("abort", () => controller.abort(makeAbortError()), { once: true });
+		}
+		this.opts.telemetry?.onRequest?.({
+			method: "GET",
+			url,
+			requestId
+		});
+		let res;
+		try {
+			res = await this.fetchImpl(url, {
+				method: "GET",
+				headers,
+				signal: controller.signal
+			});
+		} catch (err) {
+			clearTimeout(timeout);
+			this.opts.telemetry?.onError?.({
+				url,
+				requestId,
+				error: err
+			});
+			throw err;
+		}
+		if (!res.ok) {
+			clearTimeout(timeout);
+			const { parsed } = await readBody(res);
+			const apiErr = coerceApiError(res, parsed);
+			this.opts.telemetry?.onError?.({
+				url,
+				requestId,
+				error: apiErr
+			});
+			throw apiErr;
+		}
+		if (!res.body) {
+			clearTimeout(timeout);
+			throw new MappaError("SSE response has no body");
+		}
+		try {
+			yield* this.parseSSEStream(res.body);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	/**
+	* Parse SSE events from a ReadableStream.
+	*
+	* SSE format:
+	* ```
+	* id: <id>
+	* event: <type>
+	* data: <json>
+	*
+	* ```
+	* Each event is terminated by an empty line.
+	*/
+	async *parseSSEStream(body) {
+		const decoder = new TextDecoder();
+		const reader = body.getReader();
+		let buffer = "";
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				const events = buffer.split("\n\n");
+				buffer = events.pop() ?? "";
+				for (const eventText of events) {
+					if (!eventText.trim()) continue;
+					const event = this.parseSSEEvent(eventText);
+					if (event) yield event;
+				}
+			}
+			if (buffer.trim()) {
+				const event = this.parseSSEEvent(buffer);
+				if (event) yield event;
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	/**
+	* Parse a single SSE event from text.
+	*/
+	parseSSEEvent(text) {
+		const lines = text.split("\n");
+		let id;
+		let event = "message";
+		let data = "";
+		for (const line of lines) if (line.startsWith("id:")) id = line.slice(3).trim();
+		else if (line.startsWith("event:")) event = line.slice(6).trim();
+		else if (line.startsWith("data:")) {
+			if (data) data += "\n";
+			data += line.slice(5).trim();
+		}
+		if (!data) return null;
+		let parsedData;
+		try {
+			parsedData = JSON.parse(data);
+		} catch {
+			parsedData = data;
+		}
+		return {
+			id,
+			event,
+			data: parsedData
+		};
+	}
+	async request(req) {
+		const url = buildUrl(this.opts.baseUrl, req.path, req.query);
+		const requestId = req.requestId ?? randomId("req");
+		const headers = {
+			"Mappa-Api-Key": this.opts.apiKey,
+			"X-Request-Id": requestId,
+			...this.opts.userAgent ? { "User-Agent": this.opts.userAgent } : {},
+			...this.opts.defaultHeaders ?? {}
+		};
+		if (req.idempotencyKey) headers["Idempotency-Key"] = req.idempotencyKey;
+		if (req.headers) {
+			for (const [k, v] of Object.entries(req.headers)) if (v !== void 0) headers[k] = v;
+		}
+		const isFormData = typeof FormData !== "undefined" && req.body instanceof FormData;
+		if (req.body !== void 0 && !isFormData) headers["Content-Type"] = "application/json";
+		const body = req.body === void 0 ? void 0 : isFormData ? req.body : JSON.stringify(req.body);
+		const maxRetries = Math.max(0, this.opts.maxRetries);
+		const startedAt = Date.now();
+		for (let attempt = 1; attempt <= 1 + maxRetries; attempt++) {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(makeAbortError()), this.opts.timeoutMs);
+			if (hasAbortSignal(req.signal)) {
+				const signal = req.signal;
+				if (!signal) {
+					clearTimeout(timeout);
+					throw new Error("Unexpected: abort signal missing");
+				}
+				if (signal.aborted) {
+					clearTimeout(timeout);
+					throw makeAbortError();
+				}
+				signal.addEventListener("abort", () => controller.abort(makeAbortError()), { once: true });
+			}
+			this.opts.telemetry?.onRequest?.({
+				method: req.method,
+				url,
+				requestId
+			});
+			try {
+				const res = await this.fetchImpl(url, {
+					method: req.method,
+					headers,
+					body,
+					signal: controller.signal
+				});
+				const durationMs = Date.now() - startedAt;
+				const serverRequestId = getHeader(res.headers, "x-request-id") ?? requestId;
+				if (!res.ok) {
+					const { parsed } = await readBody(res);
+					const apiErr = coerceApiError(res, parsed);
+					this.opts.telemetry?.onError?.({
+						url,
+						requestId: serverRequestId,
+						error: apiErr
+					});
+					const decision = shouldRetry(req, apiErr);
+					if (attempt <= maxRetries + 1 && decision.retry && attempt <= maxRetries) {
+						const base = decision.retryAfterMs ?? jitter(backoffMs(attempt, 500, 4e3));
+						await new Promise((r) => setTimeout(r, base));
+						continue;
+					}
+					throw apiErr;
+				}
+				const ct = res.headers.get("content-type") ?? "";
+				let data;
+				if (ct.includes("application/json")) data = await res.json();
+				else data = await res.text();
+				this.opts.telemetry?.onResponse?.({
+					status: res.status,
+					url,
+					requestId: serverRequestId,
+					durationMs
+				});
+				return {
+					data,
+					status: res.status,
+					requestId: serverRequestId,
+					headers: res.headers
+				};
+			} catch (err) {
+				this.opts.telemetry?.onError?.({
+					url,
+					requestId,
+					error: err
+				});
+				const decision = shouldRetry(req, err);
+				if (attempt <= maxRetries && decision.retry) {
+					const sleep = decision.retryAfterMs ?? jitter(backoffMs(attempt, 500, 4e3));
+					await new Promise((r) => setTimeout(r, sleep));
+					continue;
+				}
+				throw err;
+			} finally {
+				clearTimeout(timeout);
+			}
+		}
+		throw new Error("Unexpected transport exit");
+	}
+};
+
+//#endregion
+//#region src/resources/webhooks.ts
+function isObject(v) {
+	return v !== null && typeof v === "object";
+}
+/**
+* Async signature verification using WebCrypto (works in modern Node and browsers).
+* Signature scheme placeholder:
+*   headers["mappa-signature"] = "t=1700000000,v1=<hex_hmac_sha256>"
+* Signed payload: `${t}.${rawBody}`
+*/
+var WebhooksResource = class {
+	async verifySignature(params) {
+		const tolerance = params.toleranceSec ?? 300;
+		const sigHeader = headerValue(params.headers, "mappa-signature");
+		if (!sigHeader) throw new Error("Missing mappa-signature header");
+		const parts = parseSig(sigHeader);
+		const ts = Number(parts.t);
+		if (!Number.isFinite(ts)) throw new Error("Invalid signature timestamp");
+		const nowSec = Math.floor(Date.now() / 1e3);
+		if (Math.abs(nowSec - ts) > tolerance) throw new Error("Signature timestamp outside tolerance");
+		const signed = `${parts.t}.${params.payload}`;
+		if (!timingSafeEqualHex(await hmacHex(params.secret, signed), parts.v1)) throw new Error("Invalid signature");
+		return { ok: true };
+	}
+	parseEvent(payload) {
+		const raw = JSON.parse(payload);
+		if (!isObject(raw)) throw new Error("Invalid webhook payload: not an object");
+		const obj = raw;
+		const id = obj.id;
+		const type = obj.type;
+		const createdAt = obj.createdAt;
+		if (typeof id !== "string") throw new Error("Invalid webhook payload: id must be a string");
+		if (typeof type !== "string") throw new Error("Invalid webhook payload: type must be a string");
+		if (typeof createdAt !== "string") throw new Error("Invalid webhook payload: createdAt must be a string");
+		return {
+			id,
+			type,
+			createdAt,
+			data: "data" in obj ? obj.data : void 0
+		};
+	}
+};
+function headerValue(headers, name) {
+	const key = Object.keys(headers).find((k) => k.toLowerCase() === name.toLowerCase());
+	const v = key ? headers[key] : void 0;
+	if (!v) return void 0;
+	return Array.isArray(v) ? v[0] : v;
+}
+function parseSig(h) {
+	const out = {};
+	for (const part of h.split(",")) {
+		const [k, v] = part.split("=");
+		if (k && v) out[k.trim()] = v.trim();
+	}
+	if (!out.t || !out.v1) throw new Error("Invalid signature format");
+	return {
+		t: out.t,
+		v1: out.v1
+	};
+}
+async function hmacHex(secret, message) {
+	const enc = new TextEncoder();
+	const key = await crypto.subtle.importKey("raw", enc.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return bufToHex(await crypto.subtle.sign("HMAC", key, enc.encode(message)));
+}
+function bufToHex(buf) {
+	const b = new Uint8Array(buf);
+	let s = "";
+	for (const x of b) s += x.toString(16).padStart(2, "0");
+	return s;
+}
+function timingSafeEqualHex(a, b) {
+	if (a.length !== b.length) return false;
+	let r = 0;
+	for (let i = 0; i < a.length; i++) r |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return r === 0;
+}
+
+//#endregion
+//#region src/Mappa.ts
+/**
+* Main SDK client.
+*
+* Exposes resource namespaces ({@link Mappa.files}, {@link Mappa.reports}, etc.)
+* and configures a shared HTTP transport.
+*/
+var Mappa = class Mappa {
+	files;
+	jobs;
+	reports;
+	feedback;
+	credits;
+	entities;
+	webhooks;
+	health;
+	transport;
+	opts;
+	constructor(options) {
+		if (!options.apiKey) throw new MappaError("apiKey is required");
+		const baseUrl = options.baseUrl ?? "https://api.mappa.ai";
+		const timeoutMs = options.timeoutMs ?? 3e4;
+		const maxRetries = options.maxRetries ?? 2;
+		this.opts = {
+			...options,
+			apiKey: options.apiKey,
+			baseUrl,
+			timeoutMs,
+			maxRetries
+		};
+		this.transport = new Transport({
+			apiKey: options.apiKey,
+			baseUrl,
+			timeoutMs,
+			maxRetries,
+			defaultHeaders: options.defaultHeaders,
+			fetch: options.fetch,
+			telemetry: options.telemetry,
+			userAgent: options.userAgent
+		});
+		this.files = new FilesResource(this.transport);
+		this.jobs = new JobsResource(this.transport);
+		this.reports = new ReportsResource(this.transport, this.jobs, this.files, this.opts.fetch ?? fetch);
+		this.feedback = new FeedbackResource(this.transport);
+		this.credits = new CreditsResource(this.transport);
+		this.entities = new EntitiesResource(this.transport);
+		this.webhooks = new WebhooksResource();
+		this.health = new HealthResource(this.transport);
+	}
+	withOptions(overrides) {
+		return new Mappa({
+			...this.opts,
+			...overrides,
+			apiKey: overrides.apiKey ?? this.opts.apiKey
+		});
+	}
+	close() {}
+};
+
+//#endregion
+//#region src/types.ts
+/**
+* Type guard for MarkdownReport.
+*/
+function isMarkdownReport(report) {
+	return report.output.type === "markdown";
+}
+/**
+* Type guard for JsonReport.
+*/
+function isJsonReport(report) {
+	return report.output.type === "json";
+}
+/**
+* Type guard for PdfReport.
+*/
+function isPdfReport(report) {
+	return report.output.type === "pdf";
+}
+/**
+* Type guard for UrlReport.
+*/
+function isUrlReport(report) {
+	return report.output.type === "url";
+}
+/**
+* Type guard to check if a report has entity information.
+* Always returns true since entity is always present in reports.
+*/
+function hasEntity(report) {
+	return report.entity !== void 0 && report.entity !== null;
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Type guard for catching SDK errors.
+*/
+function isMappaError(err) {
+	return err instanceof MappaError;
+}
+/**
+* Type guard for insufficient credits errors.
+*
+* @example
+* ```typescript
+* try {
+*   await mappa.reports.createJob({ ... });
+* } catch (err) {
+*   if (isInsufficientCreditsError(err)) {
+*     console.log(`Need ${err.required} credits, have ${err.available}`);
+*   }
+* }
+* ```
+*/
+function isInsufficientCreditsError(err) {
+	return err instanceof InsufficientCreditsError;
+}
+
+//#endregion
+exports.ApiError = ApiError;
+exports.AuthError = AuthError;
+exports.InsufficientCreditsError = InsufficientCreditsError;
+exports.JobCanceledError = JobCanceledError;
+exports.JobFailedError = JobFailedError;
+exports.Mappa = Mappa;
+exports.MappaError = MappaError;
+exports.RateLimitError = RateLimitError;
+exports.ValidationError = ValidationError;
+exports.hasEntity = hasEntity;
+exports.isInsufficientCreditsError = isInsufficientCreditsError;
+exports.isJsonReport = isJsonReport;
+exports.isMappaError = isMappaError;
+exports.isMarkdownReport = isMarkdownReport;
+exports.isPdfReport = isPdfReport;
+exports.isUrlReport = isUrlReport;
+//# sourceMappingURL=index.cjs.map