@mappa-ai/mappa-node 1.2.4 → 2.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +156 -391
- package/dist/Mappa-BTrlzSaB.d.cts +621 -0
- package/dist/Mappa-BjTJceWa.d.mts +621 -0
- package/dist/index.cjs +5184 -1036
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -1397
- package/dist/index.d.mts +3 -1397
- package/dist/index.mjs +5184 -1034
- package/dist/index.mjs.map +1 -1
- package/dist/node.cjs +37 -0
- package/dist/node.cjs.map +1 -0
- package/dist/node.d.cts +26 -0
- package/dist/node.d.mts +26 -0
- package/dist/node.mjs +34 -0
- package/dist/node.mjs.map +1 -0
- package/package.json +39 -28
- package/LICENSE +0 -21
package/dist/index.d.mts
CHANGED
|
@@ -1,15 +1,7 @@
|
|
|
1
|
+
import { A as MediaRetention, B as TargetSelector, C as MatchingAnalysisJobReceipt, D as MatchingAnalysisRunHandle, E as MatchingAnalysisResponse, F as ReportOutput, H as WaitOptions, I as ReportOutputType, L as ReportRunHandle, M as ReportCreateJobRequest, N as ReportForOutputType, O as MediaFile, P as ReportJobReceipt, R as ReportTemplateId, S as MatchingAnalysisForOutputType, T as MatchingAnalysisOutputType, U as WebhookConfig, V as Usage, W as hasEntity, _ as JsonValue, a as ReportFailedEvent, b as MatchingAnalysisCreateJobRequest, c as Entity, d as FileDeleteReceipt, f as Job, g as JobStatus, h as JobStage, i as ReportFailedData, j as Report, k as MediaObject, l as FeedbackCreateRequest, m as JobEvent, n as ReportCompletedData, o as WebhookEvent, p as JobCreditReservation, r as ReportCompletedEvent, s as WebhookEventType, t as Mappa, u as FeedbackReceipt, v as ListEntitiesResponse, w as MatchingAnalysisOutput, x as MatchingAnalysisEntitySource, y as ListFilesResponse, z as RetentionLockResult } from "./Mappa-BjTJceWa.mjs";
|
|
2
|
+
|
|
1
3
|
//#region src/errors.d.ts
|
|
2
|
-
/**
|
|
3
|
-
* Symbol for custom Node.js inspect formatting.
|
|
4
|
-
* Ensures errors display nicely in console.log, REPL, and debuggers.
|
|
5
|
-
*/
|
|
6
4
|
declare const customInspect: unique symbol;
|
|
7
|
-
/**
|
|
8
|
-
* Base error type for all SDK-raised errors.
|
|
9
|
-
*
|
|
10
|
-
* When available, {@link MappaError.requestId} can be used to correlate a failure
|
|
11
|
-
* with server logs/support.
|
|
12
|
-
*/
|
|
13
5
|
declare class MappaError extends Error {
|
|
14
6
|
name: string;
|
|
15
7
|
requestId?: string;
|
|
@@ -22,9 +14,6 @@ declare class MappaError extends Error {
|
|
|
22
14
|
toString(): string;
|
|
23
15
|
[customInspect](): string;
|
|
24
16
|
}
|
|
25
|
-
/**
|
|
26
|
-
* Error returned when the API responds with a non-2xx status.
|
|
27
|
-
*/
|
|
28
17
|
declare class ApiError extends MappaError {
|
|
29
18
|
name: string;
|
|
30
19
|
status: number;
|
|
@@ -37,51 +26,19 @@ declare class ApiError extends MappaError {
|
|
|
37
26
|
});
|
|
38
27
|
toString(): string;
|
|
39
28
|
}
|
|
40
|
-
/**
|
|
41
|
-
* Error returned for HTTP 429 responses.
|
|
42
|
-
*
|
|
43
|
-
* If provided by the server, {@link RateLimitError.retryAfterMs} indicates when
|
|
44
|
-
* it is safe to retry.
|
|
45
|
-
*/
|
|
46
29
|
declare class RateLimitError extends ApiError {
|
|
47
30
|
name: string;
|
|
48
31
|
retryAfterMs?: number;
|
|
49
|
-
toString(): string;
|
|
50
32
|
}
|
|
51
|
-
/**
|
|
52
|
-
* Error returned for authentication/authorization failures (typically 401/403).
|
|
53
|
-
*/
|
|
54
33
|
declare class AuthError extends ApiError {
|
|
55
34
|
name: string;
|
|
56
35
|
}
|
|
57
|
-
/**
|
|
58
|
-
* Error returned when the server rejects a request as invalid (typically 422).
|
|
59
|
-
*/
|
|
60
36
|
declare class ValidationError extends ApiError {
|
|
61
37
|
name: string;
|
|
62
38
|
}
|
|
63
|
-
/**
|
|
64
|
-
* Error returned when the account lacks sufficient credits (HTTP 402).
|
|
65
|
-
*
|
|
66
|
-
* Use {@link InsufficientCreditsError.required} and {@link InsufficientCreditsError.available}
|
|
67
|
-
* to inform users how many credits are needed.
|
|
68
|
-
*
|
|
69
|
-
* @example
|
|
70
|
-
* ```typescript
|
|
71
|
-
* try {
|
|
72
|
-
* await mappa.reports.createJob({ ... });
|
|
73
|
-
* } catch (err) {
|
|
74
|
-
* if (err instanceof InsufficientCreditsError) {
|
|
75
|
-
* console.log(`Need ${err.required} credits, have ${err.available}`);
|
|
76
|
-
* }
|
|
77
|
-
* }
|
|
78
|
-
* ```
|
|
79
|
-
*/
|
|
80
39
|
declare class InsufficientCreditsError extends ApiError {
|
|
81
40
|
name: string;
|
|
82
|
-
/** Credits required for the operation */
|
|
83
41
|
required: number;
|
|
84
|
-
/** Credits currently available */
|
|
85
42
|
available: number;
|
|
86
43
|
constructor(message: string, opts: {
|
|
87
44
|
status: number;
|
|
@@ -92,11 +49,7 @@ declare class InsufficientCreditsError extends ApiError {
|
|
|
92
49
|
available?: number;
|
|
93
50
|
};
|
|
94
51
|
});
|
|
95
|
-
toString(): string;
|
|
96
52
|
}
|
|
97
|
-
/**
|
|
98
|
-
* Error thrown by polling helpers when a job reaches the "failed" terminal state.
|
|
99
|
-
*/
|
|
100
53
|
declare class JobFailedError extends MappaError {
|
|
101
54
|
name: string;
|
|
102
55
|
jobId: string;
|
|
@@ -105,11 +58,7 @@ declare class JobFailedError extends MappaError {
|
|
|
105
58
|
code?: string;
|
|
106
59
|
cause?: unknown;
|
|
107
60
|
});
|
|
108
|
-
toString(): string;
|
|
109
61
|
}
|
|
110
|
-
/**
|
|
111
|
-
* Error thrown by polling helpers when a job reaches the "canceled" terminal state.
|
|
112
|
-
*/
|
|
113
62
|
declare class JobCanceledError extends MappaError {
|
|
114
63
|
name: string;
|
|
115
64
|
jobId: string;
|
|
@@ -117,30 +66,7 @@ declare class JobCanceledError extends MappaError {
|
|
|
117
66
|
requestId?: string;
|
|
118
67
|
cause?: unknown;
|
|
119
68
|
});
|
|
120
|
-
toString(): string;
|
|
121
69
|
}
|
|
122
|
-
/**
|
|
123
|
-
* Error thrown when SSE streaming fails after all retries.
|
|
124
|
-
*
|
|
125
|
-
* Includes recovery metadata to allow callers to resume or retry:
|
|
126
|
-
* - `jobId`: The job being streamed (when known)
|
|
127
|
-
* - `lastEventId`: Last successfully received event ID for resumption
|
|
128
|
-
* - `url`: The stream URL that failed
|
|
129
|
-
* - `retryCount`: Number of retries attempted
|
|
130
|
-
*
|
|
131
|
-
* @example
|
|
132
|
-
* ```typescript
|
|
133
|
-
* try {
|
|
134
|
-
* for await (const event of mappa.jobs.stream(jobId)) { ... }
|
|
135
|
-
* } catch (err) {
|
|
136
|
-
* if (err instanceof StreamError) {
|
|
137
|
-
* console.log(`Stream failed for job ${err.jobId}`);
|
|
138
|
-
* console.log(`Last event ID: ${err.lastEventId}`);
|
|
139
|
-
* // Can retry with: mappa.jobs.stream(err.jobId)
|
|
140
|
-
* }
|
|
141
|
-
* }
|
|
142
|
-
* ```
|
|
143
|
-
*/
|
|
144
70
|
declare class StreamError extends MappaError {
|
|
145
71
|
name: string;
|
|
146
72
|
jobId?: string;
|
|
@@ -155,1332 +81,12 @@ declare class StreamError extends MappaError {
|
|
|
155
81
|
requestId?: string;
|
|
156
82
|
cause?: unknown;
|
|
157
83
|
});
|
|
158
|
-
toString(): string;
|
|
159
|
-
}
|
|
160
|
-
//#endregion
|
|
161
|
-
//#region src/resources/transport.d.ts
|
|
162
|
-
/**
|
|
163
|
-
* Options for SSE streaming.
|
|
164
|
-
*/
|
|
165
|
-
type SSEStreamOptions = {
|
|
166
|
-
signal?: AbortSignal;
|
|
167
|
-
lastEventId?: string;
|
|
168
|
-
};
|
|
169
|
-
/**
|
|
170
|
-
* A parsed SSE event.
|
|
171
|
-
*/
|
|
172
|
-
type SSEEvent<T = unknown> = {
|
|
173
|
-
id?: string;
|
|
174
|
-
event: string;
|
|
175
|
-
data: T;
|
|
176
|
-
};
|
|
177
|
-
type Telemetry = {
|
|
178
|
-
onRequest?: (ctx: {
|
|
179
|
-
method: string;
|
|
180
|
-
url: string;
|
|
181
|
-
requestId?: string;
|
|
182
|
-
}) => void;
|
|
183
|
-
onResponse?: (ctx: {
|
|
184
|
-
status: number;
|
|
185
|
-
url: string;
|
|
186
|
-
requestId?: string;
|
|
187
|
-
durationMs: number;
|
|
188
|
-
}) => void;
|
|
189
|
-
onError?: (ctx: {
|
|
190
|
-
url: string;
|
|
191
|
-
requestId?: string;
|
|
192
|
-
error: unknown;
|
|
193
|
-
/** Additional context for SSE streaming errors. */
|
|
194
|
-
context?: Record<string, unknown>;
|
|
195
|
-
}) => void;
|
|
196
|
-
};
|
|
197
|
-
type TransportOptions = {
|
|
198
|
-
apiKey: string;
|
|
199
|
-
baseUrl: string;
|
|
200
|
-
timeoutMs: number;
|
|
201
|
-
maxRetries: number;
|
|
202
|
-
defaultHeaders?: Record<string, string>;
|
|
203
|
-
fetch?: typeof fetch;
|
|
204
|
-
telemetry?: Telemetry;
|
|
205
|
-
userAgent?: string;
|
|
206
|
-
};
|
|
207
|
-
type RequestOptions = {
|
|
208
|
-
method: "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
|
|
209
|
-
path: string;
|
|
210
|
-
query?: Record<string, string | number | boolean | undefined>;
|
|
211
|
-
headers?: Record<string, string | undefined>;
|
|
212
|
-
body?: unknown;
|
|
213
|
-
idempotencyKey?: string;
|
|
214
|
-
requestId?: string;
|
|
215
|
-
signal?: AbortSignal;
|
|
216
|
-
retryable?: boolean;
|
|
217
|
-
};
|
|
218
|
-
type TransportResponse<T> = {
|
|
219
|
-
data: T;
|
|
220
|
-
status: number;
|
|
221
|
-
requestId?: string;
|
|
222
|
-
headers: Headers;
|
|
223
|
-
};
|
|
224
|
-
declare class Transport {
|
|
225
|
-
private readonly opts;
|
|
226
|
-
private readonly fetchImpl;
|
|
227
|
-
constructor(opts: TransportOptions);
|
|
228
|
-
/**
|
|
229
|
-
* Stream SSE events from a given path.
|
|
230
|
-
*
|
|
231
|
-
* Uses native `fetch` with streaming response body (not browser-only `EventSource`).
|
|
232
|
-
* Parses SSE format manually from the `ReadableStream`.
|
|
233
|
-
*
|
|
234
|
-
* Automatically retries on network failures (socket errors, DNS failures, etc.)
|
|
235
|
-
* up to `maxRetries` times with exponential backoff.
|
|
236
|
-
*/
|
|
237
|
-
streamSSE<T>(path: string, opts?: SSEStreamOptions): AsyncGenerator<SSEEvent<T>>;
|
|
238
|
-
/**
|
|
239
|
-
* Parse SSE events from a ReadableStream.
|
|
240
|
-
*
|
|
241
|
-
* SSE format:
|
|
242
|
-
* ```
|
|
243
|
-
* id: <id>
|
|
244
|
-
* event: <type>
|
|
245
|
-
* data: <json>
|
|
246
|
-
*
|
|
247
|
-
* ```
|
|
248
|
-
* Each event is terminated by an empty line.
|
|
249
|
-
*/
|
|
250
|
-
private parseSSEStream;
|
|
251
|
-
/**
|
|
252
|
-
* Parse a single SSE event from text.
|
|
253
|
-
*/
|
|
254
|
-
private parseSSEEvent;
|
|
255
|
-
request<T>(req: RequestOptions): Promise<TransportResponse<T>>;
|
|
256
|
-
}
|
|
257
|
-
//#endregion
|
|
258
|
-
//#region src/types.d.ts
|
|
259
|
-
/**
|
|
260
|
-
* JSON-serializable value.
|
|
261
|
-
*
|
|
262
|
-
* Used throughout the SDK for message payloads, webhook data, and server-provided
|
|
263
|
-
* metadata where the exact shape is not known at compile time.
|
|
264
|
-
*/
|
|
265
|
-
type JsonValue = string | number | boolean | null | {
|
|
266
|
-
[k: string]: JsonValue;
|
|
267
|
-
} | JsonValue[];
|
|
268
|
-
type MediaRef = {
|
|
269
|
-
url: string;
|
|
270
|
-
contentType?: string;
|
|
271
|
-
filename?: string;
|
|
272
|
-
} | {
|
|
273
|
-
mediaId: string;
|
|
274
|
-
};
|
|
275
|
-
/**
|
|
276
|
-
* A reference to an already-uploaded media object.
|
|
277
|
-
*/
|
|
278
|
-
type MediaIdRef = {
|
|
279
|
-
mediaId: string;
|
|
280
|
-
};
|
|
281
|
-
type ReportTemplateId = "sales_playbook" | "general_report" | "hiring_report" | "profile_alignment";
|
|
282
|
-
type ReportTemplateParamsMap = {
|
|
283
|
-
sales_playbook: Record<string, never>;
|
|
284
|
-
general_report: Record<string, never>;
|
|
285
|
-
hiring_report: {
|
|
286
|
-
roleTitle: string;
|
|
287
|
-
roleDescription: string;
|
|
288
|
-
companyCulture: string;
|
|
289
|
-
};
|
|
290
|
-
profile_alignment: {
|
|
291
|
-
idealProfile: string;
|
|
292
|
-
};
|
|
293
|
-
};
|
|
294
|
-
type ReportOutputType = "markdown" | "json" | "pdf" | "url";
|
|
295
|
-
type ReportOutputEntry<OutputType extends ReportOutputType, Template extends ReportTemplateId> = ReportTemplateParamsMap[Template] extends Record<string, never> ? {
|
|
296
|
-
type: OutputType;
|
|
297
|
-
template: Template;
|
|
298
|
-
templateParams?: ReportTemplateParamsMap[Template];
|
|
299
|
-
} : {
|
|
300
|
-
type: OutputType;
|
|
301
|
-
template: Template;
|
|
302
|
-
templateParams: ReportTemplateParamsMap[Template];
|
|
303
|
-
};
|
|
304
|
-
type ReportOutputForType<OutputType extends ReportOutputType> = ReportOutputEntry<OutputType, "sales_playbook"> | ReportOutputEntry<OutputType, "general_report"> | ReportOutputEntry<OutputType, "hiring_report"> | ReportOutputEntry<OutputType, "profile_alignment">;
|
|
305
|
-
type ReportOutput = ReportOutputForType<"markdown"> | ReportOutputForType<"json"> | ReportOutputForType<"pdf"> | ReportOutputForType<"url">;
|
|
306
|
-
/**
|
|
307
|
-
* Report output configuration constrained to a specific output type.
|
|
308
|
-
* When T is a specific literal like "markdown", only markdown output configs are allowed.
|
|
309
|
-
* When T is the full union (ReportOutputType), all output configs are allowed.
|
|
310
|
-
*
|
|
311
|
-
* @example
|
|
312
|
-
* ```typescript
|
|
313
|
-
* type MarkdownOutput = ReportOutputFor<"markdown">; // Only markdown configs
|
|
314
|
-
* type AnyOutput = ReportOutputFor<ReportOutputType>; // All configs (same as ReportOutput)
|
|
315
|
-
* ```
|
|
316
|
-
*/
|
|
317
|
-
type ReportOutputFor<T extends ReportOutputType> = T extends "markdown" ? ReportOutputForType<"markdown"> : T extends "json" ? ReportOutputForType<"json"> : T extends "pdf" ? ReportOutputForType<"pdf"> : T extends "url" ? ReportOutputForType<"url"> : ReportOutput;
|
|
318
|
-
type TargetStrategy = "dominant" | "timerange" | "entity_id" | "magic_hint";
|
|
319
|
-
type TargetOnMiss = "fallback_dominant" | "error";
|
|
320
|
-
type TargetTimeRange = {
|
|
321
|
-
/**
|
|
322
|
-
* Start time in seconds.
|
|
323
|
-
* When omitted, starts from the beginning.
|
|
324
|
-
*/
|
|
325
|
-
startSeconds?: number;
|
|
326
|
-
/**
|
|
327
|
-
* End time in seconds.
|
|
328
|
-
* When omitted, goes until the end.
|
|
329
|
-
*/
|
|
330
|
-
endSeconds?: number;
|
|
331
|
-
};
|
|
332
|
-
type TargetBase = {
|
|
333
|
-
/**
|
|
334
|
-
* Behavior when the entity is not found.
|
|
335
|
-
*/
|
|
336
|
-
onMiss?: TargetOnMiss;
|
|
337
|
-
/**
|
|
338
|
-
* Tags to apply to the selected entity after job completion.
|
|
339
|
-
*
|
|
340
|
-
* Tags must be 1-64 characters, alphanumeric with underscores and hyphens only.
|
|
341
|
-
* Maximum 10 tags per request.
|
|
342
|
-
*
|
|
343
|
-
* @example ["interviewer", "sales-rep", "round-1"]
|
|
344
|
-
*/
|
|
345
|
-
tags?: string[];
|
|
346
|
-
/**
|
|
347
|
-
* Exclude speakers whose entities have ANY of these tags from selection.
|
|
348
|
-
*
|
|
349
|
-
* Useful for filtering out known interviewers, hosts, etc.
|
|
350
|
-
*
|
|
351
|
-
* @example ["interviewer", "host"]
|
|
352
|
-
*/
|
|
353
|
-
excludeTags?: string[];
|
|
354
|
-
};
|
|
355
|
-
type TargetDominant = TargetBase & {
|
|
356
|
-
strategy: "dominant";
|
|
357
|
-
};
|
|
358
|
-
type TargetTimeRangeStrategy = TargetBase & {
|
|
359
|
-
strategy: "timerange";
|
|
360
|
-
timeRange: TargetTimeRange;
|
|
361
|
-
};
|
|
362
|
-
type TargetEntityId = TargetBase & {
|
|
363
|
-
strategy: "entity_id";
|
|
364
|
-
entityId: string;
|
|
365
|
-
};
|
|
366
|
-
type TargetMagicHint = TargetBase & {
|
|
367
|
-
strategy: "magic_hint";
|
|
368
|
-
hint: string;
|
|
369
|
-
};
|
|
370
|
-
type TargetSelector = TargetDominant | TargetTimeRangeStrategy | TargetEntityId | TargetMagicHint;
|
|
371
|
-
type TargetStrategyMap = {
|
|
372
|
-
dominant: TargetDominant;
|
|
373
|
-
timerange: TargetTimeRangeStrategy;
|
|
374
|
-
entity_id: TargetEntityId;
|
|
375
|
-
magic_hint: TargetMagicHint;
|
|
376
|
-
};
|
|
377
|
-
type TargetFor<Strategy extends TargetStrategy> = TargetStrategyMap[Strategy];
|
|
378
|
-
type Usage = {
|
|
379
|
-
creditsUsed: number;
|
|
380
|
-
creditsDiscounted?: number;
|
|
381
|
-
creditsNetUsed: number;
|
|
382
|
-
durationMs?: number;
|
|
383
|
-
modelVersion?: string;
|
|
384
|
-
};
|
|
385
|
-
type JobStage = "uploaded" | "queued" | "transcoding" | "extracting" | "scoring" | "rendering" | "finalizing";
|
|
386
|
-
type JobStatus = "queued" | "running" | "succeeded" | "failed" | "canceled";
|
|
387
|
-
type JobCreditReservation = {
|
|
388
|
-
reservedCredits: number | null;
|
|
389
|
-
reservationStatus: "active" | "released" | "applied" | null;
|
|
390
|
-
};
|
|
391
|
-
type Job = {
|
|
392
|
-
id: string;
|
|
393
|
-
type: "report.generate";
|
|
394
|
-
status: JobStatus;
|
|
395
|
-
stage?: JobStage;
|
|
396
|
-
progress?: number;
|
|
397
|
-
createdAt: string;
|
|
398
|
-
updatedAt: string;
|
|
399
|
-
reportId?: string;
|
|
400
|
-
usage?: Usage;
|
|
401
|
-
credits?: JobCreditReservation;
|
|
402
|
-
releasedCredits?: number | null;
|
|
403
|
-
error?: {
|
|
404
|
-
code: string;
|
|
405
|
-
message: string;
|
|
406
|
-
details?: JsonValue;
|
|
407
|
-
retryable?: boolean;
|
|
408
|
-
};
|
|
409
|
-
requestId?: string;
|
|
410
|
-
};
|
|
411
|
-
type JobEvent = {
|
|
412
|
-
type: "status";
|
|
413
|
-
job: Job;
|
|
414
|
-
} | {
|
|
415
|
-
type: "stage";
|
|
416
|
-
stage: JobStage;
|
|
417
|
-
progress?: number;
|
|
418
|
-
job: Job;
|
|
419
|
-
} | {
|
|
420
|
-
type: "log";
|
|
421
|
-
message: string;
|
|
422
|
-
ts: string;
|
|
423
|
-
} | {
|
|
424
|
-
type: "terminal";
|
|
425
|
-
job: Job;
|
|
426
|
-
};
|
|
427
|
-
type Subject = {
|
|
428
|
-
id?: string;
|
|
429
|
-
externalRef?: string;
|
|
430
|
-
metadata?: Record<string, JsonValue>;
|
|
431
|
-
};
|
|
432
|
-
type WebhookConfig = {
|
|
433
|
-
url: string;
|
|
434
|
-
headers?: Record<string, string>;
|
|
435
|
-
};
|
|
436
|
-
type ReportCreateJobRequest<T extends ReportOutputType = ReportOutputType> = {
|
|
437
|
-
subject?: Subject;
|
|
438
|
-
/**
|
|
439
|
-
* Reference to already-uploaded media.
|
|
440
|
-
*
|
|
441
|
-
* Note: Report job creation requires a `mediaId`. To start from a remote URL or local bytes,
|
|
442
|
-
* use helper methods like `reports.createJobFromUrl()` / `reports.createJobFromFile()`.
|
|
443
|
-
*/
|
|
444
|
-
media: MediaIdRef;
|
|
445
|
-
output: ReportOutputFor<T>;
|
|
446
|
-
/**
|
|
447
|
-
* Select the target entity for analysis.
|
|
448
|
-
*
|
|
449
|
-
* @defaultValue `{ strategy: "dominant" }` - analyzes the dominant speaker
|
|
450
|
-
*/
|
|
451
|
-
target?: TargetSelector;
|
|
452
|
-
options?: {
|
|
453
|
-
language?: string;
|
|
454
|
-
timezone?: string;
|
|
455
|
-
includeMetrics?: boolean;
|
|
456
|
-
includeRawModelOutput?: boolean;
|
|
457
|
-
};
|
|
458
|
-
/**
|
|
459
|
-
* Webhook to call when the job completes or fails.
|
|
460
|
-
*
|
|
461
|
-
* @example
|
|
462
|
-
* webhook: {
|
|
463
|
-
* url: "https://example.com/webhooks/mappa",
|
|
464
|
-
* headers: { "X-Custom-Header": "value" }
|
|
465
|
-
* }
|
|
466
|
-
*/
|
|
467
|
-
webhook?: WebhookConfig;
|
|
468
|
-
idempotencyKey?: string;
|
|
469
|
-
requestId?: string;
|
|
470
|
-
};
|
|
471
|
-
type ReportBase = {
|
|
472
|
-
id: string;
|
|
473
|
-
createdAt: string;
|
|
474
|
-
jobId?: string;
|
|
475
|
-
subject?: Subject;
|
|
476
|
-
media: {
|
|
477
|
-
url?: string;
|
|
478
|
-
mediaId?: string;
|
|
479
|
-
};
|
|
480
|
-
entity: {
|
|
481
|
-
id: string;
|
|
482
|
-
tags: string[];
|
|
483
|
-
};
|
|
484
|
-
usage?: Usage;
|
|
485
|
-
metrics?: Record<string, JsonValue>;
|
|
486
|
-
raw?: JsonValue;
|
|
487
|
-
};
|
|
488
|
-
type MarkdownReport = ReportBase & {
|
|
489
|
-
output: {
|
|
490
|
-
type: "markdown";
|
|
491
|
-
template: ReportTemplateId;
|
|
492
|
-
};
|
|
493
|
-
markdown: string;
|
|
494
|
-
};
|
|
495
|
-
type JsonReport = ReportBase & {
|
|
496
|
-
output: {
|
|
497
|
-
type: "json";
|
|
498
|
-
template: ReportTemplateId;
|
|
499
|
-
};
|
|
500
|
-
sections: Array<{
|
|
501
|
-
section_title: string;
|
|
502
|
-
section_content: JsonValue;
|
|
503
|
-
}>;
|
|
504
|
-
};
|
|
505
|
-
type PdfReport = ReportBase & {
|
|
506
|
-
output: {
|
|
507
|
-
type: "pdf";
|
|
508
|
-
template: ReportTemplateId;
|
|
509
|
-
};
|
|
510
|
-
markdown: string;
|
|
511
|
-
pdfUrl: string;
|
|
512
|
-
};
|
|
513
|
-
type UrlReport = ReportBase & {
|
|
514
|
-
output: {
|
|
515
|
-
type: "url";
|
|
516
|
-
template: ReportTemplateId;
|
|
517
|
-
};
|
|
518
|
-
markdown: string;
|
|
519
|
-
sections: Array<{
|
|
520
|
-
section_title: string;
|
|
521
|
-
section_content: JsonValue;
|
|
522
|
-
}>;
|
|
523
|
-
reportUrl: string;
|
|
524
|
-
};
|
|
525
|
-
type Report = MarkdownReport | JsonReport | PdfReport | UrlReport;
|
|
526
|
-
/**
|
|
527
|
-
* Maps an output type to its corresponding report type.
|
|
528
|
-
* Used for type-safe inference in generate methods.
|
|
529
|
-
*
|
|
530
|
-
* @example
|
|
531
|
-
* ```typescript
|
|
532
|
-
* type R = ReportForOutputType<"markdown">; // MarkdownReport
|
|
533
|
-
* type R = ReportForOutputType<"json">; // JsonReport
|
|
534
|
-
* type R = ReportForOutputType<ReportOutputType>; // Report (union)
|
|
535
|
-
* ```
|
|
536
|
-
*/
|
|
537
|
-
type ReportForOutputType<T extends ReportOutputType> = T extends "markdown" ? MarkdownReport : T extends "json" ? JsonReport : T extends "pdf" ? PdfReport : T extends "url" ? UrlReport : Report;
|
|
538
|
-
type ReportJobReceipt<T extends ReportOutputType = ReportOutputType> = {
|
|
539
|
-
jobId: string;
|
|
540
|
-
status: "queued" | "running";
|
|
541
|
-
stage?: JobStage;
|
|
542
|
-
estimatedWaitSec?: number;
|
|
543
|
-
requestId?: string;
|
|
544
|
-
handle?: ReportRunHandle<T>;
|
|
545
|
-
};
|
|
546
|
-
type FeedbackReceipt = {
|
|
547
|
-
id: string;
|
|
548
|
-
createdAt: string;
|
|
549
|
-
target: {
|
|
550
|
-
reportId?: string;
|
|
551
|
-
jobId?: string;
|
|
552
|
-
};
|
|
553
|
-
rating: "thumbs_up" | "thumbs_down" | "1" | "2" | "3" | "4" | "5";
|
|
554
|
-
tags?: string[];
|
|
555
|
-
comment?: string;
|
|
556
|
-
credits: {
|
|
557
|
-
eligible: boolean;
|
|
558
|
-
reason?: string;
|
|
559
|
-
discountApplied: number;
|
|
560
|
-
netUsed: number;
|
|
561
|
-
};
|
|
562
|
-
};
|
|
563
|
-
type MediaObject = {
|
|
564
|
-
mediaId: string;
|
|
565
|
-
createdAt: string;
|
|
566
|
-
contentType: string;
|
|
567
|
-
filename?: string;
|
|
568
|
-
sizeBytes?: number;
|
|
569
|
-
};
|
|
570
|
-
type MediaProcessingStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
|
|
571
|
-
type MediaRetention = {
|
|
572
|
-
expiresAt: string | null;
|
|
573
|
-
daysRemaining: number | null;
|
|
574
|
-
locked: boolean;
|
|
575
|
-
};
|
|
576
|
-
type MediaFile = {
|
|
577
|
-
mediaId: string;
|
|
578
|
-
createdAt: string;
|
|
579
|
-
contentType: string;
|
|
580
|
-
filename: string | null;
|
|
581
|
-
sizeBytes: number | null;
|
|
582
|
-
durationSeconds: number | null;
|
|
583
|
-
processingStatus: MediaProcessingStatus;
|
|
584
|
-
lastUsedAt: string | null;
|
|
585
|
-
retention: MediaRetention;
|
|
586
|
-
};
|
|
587
|
-
type FileDeleteReceipt = {
|
|
588
|
-
mediaId: string;
|
|
589
|
-
deleted: true;
|
|
590
|
-
};
|
|
591
|
-
type RetentionLockResult = {
|
|
592
|
-
mediaId: string;
|
|
593
|
-
retentionLock: boolean;
|
|
594
|
-
message: string;
|
|
595
|
-
};
|
|
596
|
-
type CursorPaginationParams = {
|
|
597
|
-
limit?: number;
|
|
598
|
-
cursor?: string;
|
|
599
|
-
};
|
|
600
|
-
type OffsetPaginationParams = {
|
|
601
|
-
limit?: number;
|
|
602
|
-
offset?: number;
|
|
603
|
-
};
|
|
604
|
-
type CursorPage<T> = {
|
|
605
|
-
data: T[];
|
|
606
|
-
cursor?: string;
|
|
607
|
-
hasMore: boolean;
|
|
608
|
-
};
|
|
609
|
-
type OffsetPage<T> = {
|
|
610
|
-
data: T[];
|
|
611
|
-
pagination: {
|
|
612
|
-
limit: number;
|
|
613
|
-
offset: number;
|
|
614
|
-
total: number;
|
|
615
|
-
};
|
|
616
|
-
};
|
|
617
|
-
type CreditBalance = {
|
|
618
|
-
balance: number;
|
|
619
|
-
reserved: number;
|
|
620
|
-
available: number;
|
|
621
|
-
};
|
|
622
|
-
type CreditTransactionType = "PURCHASE" | "SUBSCRIPTION_GRANT" | "PROMO_GRANT" | "USAGE" | "REFUND" | "FEEDBACK_DISCOUNT" | "ADJUSTMENT" | "EXPIRATION";
|
|
623
|
-
type CreditTransaction = {
|
|
624
|
-
id: string;
|
|
625
|
-
type: CreditTransactionType;
|
|
626
|
-
amount: number;
|
|
627
|
-
createdAt: string;
|
|
628
|
-
effectiveAt: string;
|
|
629
|
-
expiresAt: string | null;
|
|
630
|
-
jobId: string | null;
|
|
631
|
-
job?: {
|
|
632
|
-
id: string;
|
|
633
|
-
status: string;
|
|
634
|
-
createdAt: string;
|
|
635
|
-
};
|
|
636
|
-
};
|
|
637
|
-
type CreditUsage = {
|
|
638
|
-
jobId: string;
|
|
639
|
-
creditsUsed: number;
|
|
640
|
-
creditsDiscounted?: number;
|
|
641
|
-
creditsNetUsed: number;
|
|
642
|
-
durationMs?: number;
|
|
643
|
-
modelVersion?: string;
|
|
644
|
-
};
|
|
645
|
-
/**
|
|
646
|
-
* Options for waiting on job completion.
|
|
647
|
-
*/
|
|
648
|
-
type WaitOptions = {
|
|
649
|
-
/**
|
|
650
|
-
* Maximum time to wait before failing.
|
|
651
|
-
*
|
|
652
|
-
* @defaultValue 300000
|
|
653
|
-
*/
|
|
654
|
-
timeoutMs?: number;
|
|
655
|
-
/**
|
|
656
|
-
* Optional callback invoked on meaningful job state transitions.
|
|
657
|
-
*/
|
|
658
|
-
onEvent?: (event: JobEvent) => void;
|
|
659
|
-
/**
|
|
660
|
-
* Abort signal used to cancel waiting.
|
|
661
|
-
*/
|
|
662
|
-
signal?: AbortSignal;
|
|
663
|
-
};
|
|
664
|
-
type ReportRunHandle<T extends ReportOutputType = ReportOutputType> = {
|
|
665
|
-
jobId: string;
|
|
666
|
-
stream(opts?: {
|
|
667
|
-
signal?: AbortSignal;
|
|
668
|
-
onEvent?: (e: JobEvent) => void;
|
|
669
|
-
}): AsyncIterable<JobEvent>;
|
|
670
|
-
wait(opts?: WaitOptions): Promise<ReportForOutputType<T>>;
|
|
671
|
-
cancel(): Promise<Job>;
|
|
672
|
-
job(): Promise<Job>;
|
|
673
|
-
report(): Promise<ReportForOutputType<T> | null>;
|
|
674
|
-
};
|
|
675
|
-
/**
|
|
676
|
-
* Type guard for MarkdownReport.
|
|
677
|
-
*/
|
|
678
|
-
declare function isMarkdownReport(report: Report): report is MarkdownReport;
|
|
679
|
-
/**
|
|
680
|
-
* Type guard for JsonReport.
|
|
681
|
-
*/
|
|
682
|
-
declare function isJsonReport(report: Report): report is JsonReport;
|
|
683
|
-
/**
|
|
684
|
-
* Type guard for PdfReport.
|
|
685
|
-
*/
|
|
686
|
-
declare function isPdfReport(report: Report): report is PdfReport;
|
|
687
|
-
/**
|
|
688
|
-
* Type guard for UrlReport.
|
|
689
|
-
*/
|
|
690
|
-
declare function isUrlReport(report: Report): report is UrlReport;
|
|
691
|
-
type Entity = {
|
|
692
|
-
id: string;
|
|
693
|
-
tags: string[];
|
|
694
|
-
createdAt: string;
|
|
695
|
-
mediaCount: number;
|
|
696
|
-
lastSeenAt: string | null;
|
|
697
|
-
};
|
|
698
|
-
type EntityTagsResult = {
|
|
699
|
-
entityId: string;
|
|
700
|
-
tags: string[];
|
|
701
|
-
};
|
|
702
|
-
type ListEntitiesOptions = CursorPaginationParams & {
|
|
703
|
-
/**
|
|
704
|
-
* Filter entities by tags.
|
|
705
|
-
* Entities must have ALL specified tags (AND logic).
|
|
706
|
-
*/
|
|
707
|
-
tags?: string[];
|
|
708
|
-
};
|
|
709
|
-
type ListEntitiesResponse = {
|
|
710
|
-
entities: Entity[];
|
|
711
|
-
cursor?: string;
|
|
712
|
-
hasMore: boolean;
|
|
713
|
-
};
|
|
714
|
-
/**
|
|
715
|
-
* Type guard to check if a report has entity information.
|
|
716
|
-
* Always returns true since entity is always present in reports.
|
|
717
|
-
*/
|
|
718
|
-
declare function hasEntity(report: Report): report is Report & {
|
|
719
|
-
entity: {
|
|
720
|
-
id: string;
|
|
721
|
-
tags: string[];
|
|
722
|
-
};
|
|
723
|
-
};
|
|
724
|
-
//#endregion
|
|
725
|
-
//#region src/resources/credits.d.ts
|
|
726
|
-
type ListTransactionsOptions = {
|
|
727
|
-
/** Max transactions per page (1-100, default 50) */
|
|
728
|
-
limit?: number;
|
|
729
|
-
/** Offset for pagination (default 0) */
|
|
730
|
-
offset?: number;
|
|
731
|
-
requestId?: string;
|
|
732
|
-
signal?: AbortSignal;
|
|
733
|
-
};
|
|
734
|
-
type ListTransactionsResponse = {
|
|
735
|
-
transactions: CreditTransaction[];
|
|
736
|
-
pagination: {
|
|
737
|
-
limit: number;
|
|
738
|
-
offset: number;
|
|
739
|
-
total: number;
|
|
740
|
-
};
|
|
741
|
-
};
|
|
742
|
-
/**
|
|
743
|
-
* Credits API resource.
|
|
744
|
-
*
|
|
745
|
-
* Provides methods to manage and query credit balances, transaction history,
|
|
746
|
-
* and job-specific credit usage.
|
|
747
|
-
*/
|
|
748
|
-
declare class CreditsResource {
|
|
749
|
-
private readonly transport;
|
|
750
|
-
constructor(transport: Transport);
|
|
751
|
-
/**
|
|
752
|
-
* Get the current credit balance for your team.
|
|
753
|
-
*
|
|
754
|
-
* @example
|
|
755
|
-
* const balance = await mappa.credits.getBalance();
|
|
756
|
-
* console.log(`Available: ${balance.available} credits`);
|
|
757
|
-
*/
|
|
758
|
-
getBalance(opts?: {
|
|
759
|
-
requestId?: string;
|
|
760
|
-
signal?: AbortSignal;
|
|
761
|
-
}): Promise<CreditBalance>;
|
|
762
|
-
/**
|
|
763
|
-
* List credit transactions with offset pagination.
|
|
764
|
-
*
|
|
765
|
-
* @example
|
|
766
|
-
* const { transactions, pagination } = await mappa.credits.listTransactions({ limit: 25 });
|
|
767
|
-
* console.log(`Showing ${transactions.length} of ${pagination.total}`);
|
|
768
|
-
*/
|
|
769
|
-
listTransactions(opts?: ListTransactionsOptions): Promise<ListTransactionsResponse>;
|
|
770
|
-
/**
|
|
771
|
-
* Iterate over all transactions, automatically handling pagination.
|
|
772
|
-
*
|
|
773
|
-
* @example
|
|
774
|
-
* for await (const tx of mappa.credits.listAllTransactions()) {
|
|
775
|
-
* console.log(`${tx.type}: ${tx.amount}`);
|
|
776
|
-
* }
|
|
777
|
-
*/
|
|
778
|
-
listAllTransactions(opts?: Omit<ListTransactionsOptions, "offset">): AsyncIterable<CreditTransaction>;
|
|
779
|
-
/**
|
|
780
|
-
* Get credit usage details for a completed job.
|
|
781
|
-
*
|
|
782
|
-
* @example
|
|
783
|
-
* const usage = await mappa.credits.getJobUsage("job_xyz");
|
|
784
|
-
* console.log(`Net credits used: ${usage.creditsNetUsed}`);
|
|
785
|
-
*/
|
|
786
|
-
getJobUsage(jobId: string, opts?: {
|
|
787
|
-
requestId?: string;
|
|
788
|
-
signal?: AbortSignal;
|
|
789
|
-
}): Promise<CreditUsage>;
|
|
790
|
-
/**
|
|
791
|
-
* Check if the team has enough available credits for an operation.
|
|
792
|
-
*
|
|
793
|
-
* @example
|
|
794
|
-
* if (await mappa.credits.hasEnough(100)) {
|
|
795
|
-
* await mappa.reports.createJob(...);
|
|
796
|
-
* }
|
|
797
|
-
*/
|
|
798
|
-
hasEnough(credits: number, opts?: {
|
|
799
|
-
requestId?: string;
|
|
800
|
-
signal?: AbortSignal;
|
|
801
|
-
}): Promise<boolean>;
|
|
802
|
-
/**
|
|
803
|
-
* Get the number of available credits (balance - reserved).
|
|
804
|
-
*
|
|
805
|
-
* @example
|
|
806
|
-
* const available = await mappa.credits.getAvailable();
|
|
807
|
-
* console.log(`You can spend ${available} credits`);
|
|
808
|
-
*/
|
|
809
|
-
getAvailable(opts?: {
|
|
810
|
-
requestId?: string;
|
|
811
|
-
signal?: AbortSignal;
|
|
812
|
-
}): Promise<number>;
|
|
813
|
-
}
|
|
814
|
-
//#endregion
|
|
815
|
-
//#region src/resources/entities.d.ts
|
|
816
|
-
/**
|
|
817
|
-
* Entities API resource.
|
|
818
|
-
*
|
|
819
|
-
* Responsibilities:
|
|
820
|
-
* - List entities with optional tag filtering (`GET /v1/entities`)
|
|
821
|
-
* - Get single entity details (`GET /v1/entities/:entityId`)
|
|
822
|
-
* - Add tags to entities (`POST /v1/entities/:entityId/tags`)
|
|
823
|
-
* - Remove tags from entities (`DELETE /v1/entities/:entityId/tags`)
|
|
824
|
-
* - Replace all entity tags (`PUT /v1/entities/:entityId/tags`)
|
|
825
|
-
*
|
|
826
|
-
* Entities represent analyzed speakers identified by voice fingerprints.
|
|
827
|
-
* Tags allow you to label entities (e.g., "interviewer", "sales-rep") for easier
|
|
828
|
-
* filtering and identification across multiple reports.
|
|
829
|
-
*/
|
|
830
|
-
declare class EntitiesResource {
|
|
831
|
-
private readonly transport;
|
|
832
|
-
constructor(transport: Transport);
|
|
833
|
-
/**
|
|
834
|
-
* Get a single entity by ID.
|
|
835
|
-
*
|
|
836
|
-
* Returns entity metadata including tags, creation time, and usage statistics.
|
|
837
|
-
*
|
|
838
|
-
* @param entityId - The entity ID to retrieve
|
|
839
|
-
* @param opts - Optional request options (requestId, signal)
|
|
840
|
-
* @returns Entity details with tags and metadata
|
|
841
|
-
*
|
|
842
|
-
* @example
|
|
843
|
-
* ```typescript
|
|
844
|
-
* const entity = await mappa.entities.get("entity_abc123");
|
|
845
|
-
* console.log(entity.tags); // ["interviewer", "john"]
|
|
846
|
-
* ```
|
|
847
|
-
*/
|
|
848
|
-
get(entityId: string, opts?: {
|
|
849
|
-
requestId?: string;
|
|
850
|
-
signal?: AbortSignal;
|
|
851
|
-
}): Promise<Entity>;
|
|
852
|
-
/**
|
|
853
|
-
* List entities with optional tag filtering.
|
|
854
|
-
*
|
|
855
|
-
* Supports cursor-based pagination. Use the returned `cursor` for fetching
|
|
856
|
-
* subsequent pages, or use {@link listAll} for automatic pagination.
|
|
857
|
-
*
|
|
858
|
-
* When `tags` is provided, only entities with ALL specified tags are returned (AND logic).
|
|
859
|
-
*
|
|
860
|
-
* @param opts - List options: tags filter, cursor, limit
|
|
861
|
-
* @returns Paginated list of entities
|
|
862
|
-
*
|
|
863
|
-
* @example
|
|
864
|
-
* ```typescript
|
|
865
|
-
* // List all entities
|
|
866
|
-
* const page1 = await mappa.entities.list({ limit: 20 });
|
|
867
|
-
*
|
|
868
|
-
* // Filter by tags (must have both "interviewer" AND "sales")
|
|
869
|
-
* const filtered = await mappa.entities.list({
|
|
870
|
-
* tags: ["interviewer", "sales"],
|
|
871
|
-
* limit: 50
|
|
872
|
-
* });
|
|
873
|
-
*
|
|
874
|
-
* // Pagination
|
|
875
|
-
* const page2 = await mappa.entities.list({
|
|
876
|
-
* cursor: page1.cursor,
|
|
877
|
-
* limit: 20
|
|
878
|
-
* });
|
|
879
|
-
* ```
|
|
880
|
-
*/
|
|
881
|
-
list(opts?: ListEntitiesOptions & {
|
|
882
|
-
requestId?: string;
|
|
883
|
-
signal?: AbortSignal;
|
|
884
|
-
}): Promise<ListEntitiesResponse>;
|
|
885
|
-
/**
|
|
886
|
-
* Async iterator that automatically paginates through all entities.
|
|
887
|
-
*
|
|
888
|
-
* Useful for processing large entity sets without manual pagination management.
|
|
889
|
-
*
|
|
890
|
-
* @param opts - List options: tags filter, limit per page
|
|
891
|
-
* @yields Individual entities
|
|
892
|
-
*
|
|
893
|
-
* @example
|
|
894
|
-
* ```typescript
|
|
895
|
-
* // Process all entities with "interviewer" tag
|
|
896
|
-
* for await (const entity of mappa.entities.listAll({ tags: ["interviewer"] })) {
|
|
897
|
-
* console.log(`${entity.id}: ${entity.tags.join(", ")}`);
|
|
898
|
-
* }
|
|
899
|
-
* ```
|
|
900
|
-
*/
|
|
901
|
-
listAll(opts?: Omit<ListEntitiesOptions, "cursor"> & {
|
|
902
|
-
requestId?: string;
|
|
903
|
-
signal?: AbortSignal;
|
|
904
|
-
}): AsyncIterable<Entity>;
|
|
905
|
-
/**
|
|
906
|
-
* Get all entities with a specific tag.
|
|
907
|
-
*
|
|
908
|
-
* Convenience wrapper around {@link list} for single-tag filtering.
|
|
909
|
-
*
|
|
910
|
-
* @param tag - The tag to filter by
|
|
911
|
-
* @param opts - Optional pagination and request options
|
|
912
|
-
* @returns Paginated list of entities with the specified tag
|
|
913
|
-
*
|
|
914
|
-
* @example
|
|
915
|
-
* ```typescript
|
|
916
|
-
* const interviewers = await mappa.entities.getByTag("interviewer");
|
|
917
|
-
* ```
|
|
918
|
-
*/
|
|
919
|
-
getByTag(tag: string, opts?: Omit<ListEntitiesOptions, "tags"> & {
|
|
920
|
-
requestId?: string;
|
|
921
|
-
signal?: AbortSignal;
|
|
922
|
-
}): Promise<ListEntitiesResponse>;
|
|
923
|
-
/**
|
|
924
|
-
* Add tags to an entity.
|
|
925
|
-
*
|
|
926
|
-
* Idempotent: existing tags are preserved, duplicates are ignored.
|
|
927
|
-
*
|
|
928
|
-
* @param entityId - The entity ID to tag
|
|
929
|
-
* @param tags - Array of tags to add (1-10 tags, each 1-64 chars)
|
|
930
|
-
* @param opts - Optional request options
|
|
931
|
-
* @returns Updated tags for the entity
|
|
932
|
-
*
|
|
933
|
-
* @example
|
|
934
|
-
* ```typescript
|
|
935
|
-
* await mappa.entities.addTags("entity_abc123", ["interviewer", "john"]);
|
|
936
|
-
* ```
|
|
937
|
-
*/
|
|
938
|
-
addTags(entityId: string, tags: string[], opts?: {
|
|
939
|
-
requestId?: string;
|
|
940
|
-
signal?: AbortSignal;
|
|
941
|
-
}): Promise<EntityTagsResult>;
|
|
942
|
-
/**
|
|
943
|
-
* Remove tags from an entity.
|
|
944
|
-
*
|
|
945
|
-
* Idempotent: missing tags are silently ignored.
|
|
946
|
-
*
|
|
947
|
-
* @param entityId - The entity ID to update
|
|
948
|
-
* @param tags - Array of tags to remove
|
|
949
|
-
* @param opts - Optional request options
|
|
950
|
-
* @returns Updated tags for the entity
|
|
951
|
-
*
|
|
952
|
-
* @example
|
|
953
|
-
* ```typescript
|
|
954
|
-
* await mappa.entities.removeTags("entity_abc123", ["interviewer"]);
|
|
955
|
-
* ```
|
|
956
|
-
*/
|
|
957
|
-
removeTags(entityId: string, tags: string[], opts?: {
|
|
958
|
-
requestId?: string;
|
|
959
|
-
signal?: AbortSignal;
|
|
960
|
-
}): Promise<EntityTagsResult>;
|
|
961
|
-
/**
|
|
962
|
-
* Replace all tags on an entity.
|
|
963
|
-
*
|
|
964
|
-
* Sets the complete tag list, removing any tags not in the provided array.
|
|
965
|
-
* Pass an empty array to remove all tags.
|
|
966
|
-
*
|
|
967
|
-
* @param entityId - The entity ID to update
|
|
968
|
-
* @param tags - New complete tag list (0-10 tags)
|
|
969
|
-
* @param opts - Optional request options
|
|
970
|
-
* @returns Updated tags for the entity
|
|
971
|
-
*
|
|
972
|
-
* @example
|
|
973
|
-
* ```typescript
|
|
974
|
-
* // Replace all tags
|
|
975
|
-
* await mappa.entities.setTags("entity_abc123", ["sales-rep", "john"]);
|
|
976
|
-
*
|
|
977
|
-
* // Remove all tags
|
|
978
|
-
* await mappa.entities.setTags("entity_abc123", []);
|
|
979
|
-
* ```
|
|
980
|
-
*/
|
|
981
|
-
setTags(entityId: string, tags: string[], opts?: {
|
|
982
|
-
requestId?: string;
|
|
983
|
-
signal?: AbortSignal;
|
|
984
|
-
}): Promise<EntityTagsResult>;
|
|
985
|
-
}
|
|
986
|
-
//#endregion
|
|
987
|
-
//#region src/resources/feedback.d.ts
|
|
988
|
-
type FeedbackCreateRequest = {
|
|
989
|
-
reportId?: string;
|
|
990
|
-
jobId?: string;
|
|
991
|
-
rating: "thumbs_up" | "thumbs_down" | "1" | "2" | "3" | "4" | "5";
|
|
992
|
-
tags?: string[];
|
|
993
|
-
comment?: string;
|
|
994
|
-
corrections?: Array<{
|
|
995
|
-
path: string;
|
|
996
|
-
expected?: unknown;
|
|
997
|
-
observed?: unknown;
|
|
998
|
-
}>;
|
|
999
|
-
idempotencyKey?: string;
|
|
1000
|
-
requestId?: string;
|
|
1001
|
-
signal?: AbortSignal;
|
|
1002
|
-
};
|
|
1003
|
-
declare class FeedbackResource {
|
|
1004
|
-
private readonly transport;
|
|
1005
|
-
constructor(transport: Transport);
|
|
1006
|
-
/**
|
|
1007
|
-
* Create feedback for a report or job. Provide exactly one of `reportId` or `jobId`.
|
|
1008
|
-
*/
|
|
1009
|
-
create(req: FeedbackCreateRequest): Promise<FeedbackReceipt>;
|
|
1010
|
-
}
|
|
1011
|
-
//#endregion
|
|
1012
|
-
//#region src/resources/files.d.ts
|
|
1013
|
-
type UploadRequest = {
|
|
1014
|
-
file: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
|
|
1015
|
-
/**
|
|
1016
|
-
* Optional override.
|
|
1017
|
-
* If omitted, the SDK will try to infer it from `file.type` (Blob) and then from `filename`.
|
|
1018
|
-
*/
|
|
1019
|
-
contentType?: string;
|
|
1020
|
-
filename?: string;
|
|
1021
|
-
idempotencyKey?: string;
|
|
1022
|
-
requestId?: string;
|
|
1023
|
-
signal?: AbortSignal;
|
|
1024
|
-
};
|
|
1025
|
-
type ListFilesOptions = {
|
|
1026
|
-
/** Max files per page (1-100, default 20) */
|
|
1027
|
-
limit?: number;
|
|
1028
|
-
/** Pagination cursor from previous response */
|
|
1029
|
-
cursor?: string;
|
|
1030
|
-
/** Include soft-deleted files (default false) */
|
|
1031
|
-
includeDeleted?: boolean;
|
|
1032
|
-
requestId?: string;
|
|
1033
|
-
signal?: AbortSignal;
|
|
1034
|
-
};
|
|
1035
|
-
type ListFilesResponse = {
|
|
1036
|
-
files: MediaFile[];
|
|
1037
|
-
cursor?: string;
|
|
1038
|
-
hasMore: boolean;
|
|
1039
|
-
};
|
|
1040
|
-
/**
|
|
1041
|
-
* Uses multipart/form-data for uploads.
|
|
1042
|
-
*
|
|
1043
|
-
* If you need resumable uploads, add a dedicated resumable protocol.
|
|
1044
|
-
*/
|
|
1045
|
-
declare class FilesResource {
|
|
1046
|
-
private readonly transport;
|
|
1047
|
-
constructor(transport: Transport);
|
|
1048
|
-
upload(req: UploadRequest): Promise<MediaObject>;
|
|
1049
|
-
/**
|
|
1050
|
-
* Retrieve metadata for a single uploaded file.
|
|
1051
|
-
*
|
|
1052
|
-
* @example
|
|
1053
|
-
* const file = await mappa.files.get("media_abc123");
|
|
1054
|
-
* console.log(file.processingStatus); // "COMPLETED"
|
|
1055
|
-
*/
|
|
1056
|
-
get(mediaId: string, opts?: {
|
|
1057
|
-
requestId?: string;
|
|
1058
|
-
signal?: AbortSignal;
|
|
1059
|
-
}): Promise<MediaFile>;
|
|
1060
|
-
/**
|
|
1061
|
-
* List uploaded files with cursor pagination.
|
|
1062
|
-
*
|
|
1063
|
-
* @example
|
|
1064
|
-
* const page1 = await mappa.files.list({ limit: 10 });
|
|
1065
|
-
* if (page1.hasMore) {
|
|
1066
|
-
* const page2 = await mappa.files.list({ limit: 10, cursor: page1.cursor });
|
|
1067
|
-
* }
|
|
1068
|
-
*/
|
|
1069
|
-
list(opts?: ListFilesOptions): Promise<ListFilesResponse>;
|
|
1070
|
-
/**
|
|
1071
|
-
* Iterate over all files, automatically handling pagination.
|
|
1072
|
-
*
|
|
1073
|
-
* @example
|
|
1074
|
-
* for await (const file of mappa.files.listAll()) {
|
|
1075
|
-
* console.log(file.mediaId);
|
|
1076
|
-
* }
|
|
1077
|
-
*
|
|
1078
|
-
* // Or collect all
|
|
1079
|
-
* const allFiles = [];
|
|
1080
|
-
* for await (const file of mappa.files.listAll({ limit: 50 })) {
|
|
1081
|
-
* allFiles.push(file);
|
|
1082
|
-
* }
|
|
1083
|
-
*/
|
|
1084
|
-
listAll(opts?: Omit<ListFilesOptions, "cursor">): AsyncIterable<MediaFile>;
|
|
1085
|
-
/**
|
|
1086
|
-
* Lock or unlock a file's retention to prevent/allow automatic deletion.
|
|
1087
|
-
*
|
|
1088
|
-
* @example
|
|
1089
|
-
* // Prevent automatic deletion
|
|
1090
|
-
* await mappa.files.setRetentionLock("media_abc", true);
|
|
1091
|
-
*
|
|
1092
|
-
* // Allow automatic deletion
|
|
1093
|
-
* await mappa.files.setRetentionLock("media_abc", false);
|
|
1094
|
-
*/
|
|
1095
|
-
setRetentionLock(mediaId: string, locked: boolean, opts?: {
|
|
1096
|
-
requestId?: string;
|
|
1097
|
-
signal?: AbortSignal;
|
|
1098
|
-
}): Promise<RetentionLockResult>;
|
|
1099
|
-
delete(mediaId: string, opts?: {
|
|
1100
|
-
idempotencyKey?: string;
|
|
1101
|
-
requestId?: string;
|
|
1102
|
-
signal?: AbortSignal;
|
|
1103
|
-
}): Promise<FileDeleteReceipt>;
|
|
1104
|
-
}
|
|
1105
|
-
//#endregion
|
|
1106
|
-
//#region src/resources/health.d.ts
|
|
1107
|
-
declare class HealthResource {
|
|
1108
|
-
private readonly transport;
|
|
1109
|
-
constructor(transport: Transport);
|
|
1110
|
-
ping(): Promise<{
|
|
1111
|
-
ok: true;
|
|
1112
|
-
time: string;
|
|
1113
|
-
}>;
|
|
1114
|
-
}
|
|
1115
|
-
//#endregion
|
|
1116
|
-
//#region src/resources/jobs.d.ts
|
|
1117
|
-
declare class JobsResource {
|
|
1118
|
-
private readonly transport;
|
|
1119
|
-
constructor(transport: Transport);
|
|
1120
|
-
get(jobId: string, opts?: {
|
|
1121
|
-
requestId?: string;
|
|
1122
|
-
signal?: AbortSignal;
|
|
1123
|
-
}): Promise<Job>;
|
|
1124
|
-
cancel(jobId: string, opts?: {
|
|
1125
|
-
idempotencyKey?: string;
|
|
1126
|
-
requestId?: string;
|
|
1127
|
-
signal?: AbortSignal;
|
|
1128
|
-
}): Promise<Job>;
|
|
1129
|
-
/**
|
|
1130
|
-
* Wait for a job to reach a terminal state.
|
|
1131
|
-
*
|
|
1132
|
-
* Uses SSE streaming internally for efficient real-time updates.
|
|
1133
|
-
*/
|
|
1134
|
-
wait(jobId: string, opts?: WaitOptions): Promise<Job>;
|
|
1135
|
-
/**
|
|
1136
|
-
* Stream job events via SSE.
|
|
1137
|
-
*
|
|
1138
|
-
* Yields events as they arrive from the server. Use `AbortSignal` to cancel streaming.
|
|
1139
|
-
* Automatically handles reconnection with `Last-Event-ID` for up to 3 retries.
|
|
1140
|
-
*/
|
|
1141
|
-
stream(jobId: string, opts?: {
|
|
1142
|
-
signal?: AbortSignal;
|
|
1143
|
-
onEvent?: (e: JobEvent) => void;
|
|
1144
|
-
}): AsyncIterable<JobEvent>;
|
|
1145
|
-
/**
|
|
1146
|
-
* Map an SSE event to a JobEvent.
|
|
1147
|
-
*/
|
|
1148
|
-
private mapSSEToJobEvent;
|
|
1149
|
-
/**
|
|
1150
|
-
* Exponential backoff with jitter for reconnection.
|
|
1151
|
-
*/
|
|
1152
|
-
private backoff;
|
|
1153
|
-
}
|
|
1154
|
-
//#endregion
|
|
1155
|
-
//#region src/resources/reports.d.ts
|
|
1156
|
-
/**
|
|
1157
|
-
* Request shape for {@link ReportsResource.createJobFromFile}.
|
|
1158
|
-
*
|
|
1159
|
-
* This helper performs two API calls as one logical operation:
|
|
1160
|
-
* 1) Upload bytes via `files.upload()` (multipart)
|
|
1161
|
-
* 2) Create a report job via {@link ReportsResource.createJob} using the returned `{ mediaId }`
|
|
1162
|
-
*
|
|
1163
|
-
* Differences vs {@link ReportCreateJobRequest}:
|
|
1164
|
-
* - `media` is derived from the upload result and therefore omitted.
|
|
1165
|
-
* - `idempotencyKey` applies to the *whole* upload + create-job sequence.
|
|
1166
|
-
* - `requestId` is forwarded to both requests for end-to-end correlation.
|
|
1167
|
-
*
|
|
1168
|
-
* Abort behavior:
|
|
1169
|
-
* - `signal` (from {@link UploadRequest}) is applied to the upload request.
|
|
1170
|
-
* Job creation only runs after a successful upload.
|
|
1171
|
-
*/
|
|
1172
|
-
type ReportCreateJobFromFileRequest<T extends ReportOutputType = ReportOutputType> = Omit<ReportCreateJobRequest<T>, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "filename"> & {
|
|
1173
|
-
/**
|
|
1174
|
-
* Optional filename to attach to the upload.
|
|
1175
|
-
*
|
|
1176
|
-
* When omitted, the upload layer may infer it (e.g. from a `File` object).
|
|
1177
|
-
*/
|
|
1178
|
-
filename?: string;
|
|
1179
|
-
/**
|
|
1180
|
-
* Idempotency for the upload + job creation sequence.
|
|
1181
|
-
*/
|
|
1182
|
-
idempotencyKey?: string;
|
|
1183
|
-
/**
|
|
1184
|
-
* Optional request correlation ID forwarded to both the upload and the job creation call.
|
|
1185
|
-
*/
|
|
1186
|
-
requestId?: string;
|
|
1187
|
-
};
|
|
1188
|
-
/**
|
|
1189
|
-
* Request shape for {@link ReportsResource.createJobFromUrl}.
|
|
1190
|
-
*
|
|
1191
|
-
* This helper performs two API calls as one logical operation:
|
|
1192
|
-
* 1) Download bytes from a remote URL using `fetch()`
|
|
1193
|
-
* 2) Upload bytes via `files.upload()` and then create a report job via {@link ReportsResource.createJob}
|
|
1194
|
-
*
|
|
1195
|
-
* Differences vs {@link ReportCreateJobRequest}:
|
|
1196
|
-
* - `media` is derived from the upload result and therefore omitted.
|
|
1197
|
-
* - `idempotencyKey` applies to the *whole* download + upload + create-job sequence.
|
|
1198
|
-
* - `requestId` is forwarded to both upload and job creation calls.
|
|
1199
|
-
*/
|
|
1200
|
-
type ReportCreateJobFromUrlRequest<T extends ReportOutputType = ReportOutputType> = Omit<ReportCreateJobRequest<T>, "media" | "idempotencyKey" | "requestId"> & {
|
|
1201
|
-
url: string;
|
|
1202
|
-
contentType?: string;
|
|
1203
|
-
filename?: string;
|
|
1204
|
-
idempotencyKey?: string;
|
|
1205
|
-
requestId?: string;
|
|
1206
|
-
signal?: AbortSignal;
|
|
1207
|
-
};
|
|
1208
|
-
/**
|
|
1209
|
-
* Reports API resource.
|
|
1210
|
-
*
|
|
1211
|
-
* Responsibilities:
|
|
1212
|
-
* - Create report jobs (`POST /v1/reports/jobs`).
|
|
1213
|
-
* - Fetch reports by report ID (`GET /v1/reports/:reportId`).
|
|
1214
|
-
* - Fetch reports by job ID (`GET /v1/reports/by-job/:jobId`).
|
|
1215
|
-
*
|
|
1216
|
-
* Convenience helpers:
|
|
1217
|
-
* - {@link ReportsResource.createJobFromFile} orchestrates `files.upload()` + {@link ReportsResource.createJob}.
|
|
1218
|
-
* - {@link ReportsResource.createJobFromUrl} downloads a remote URL, uploads it, then calls {@link ReportsResource.createJob}.
|
|
1219
|
-
* - {@link ReportsResource.generate} / {@link ReportsResource.generateFromFile} are script-friendly wrappers that
|
|
1220
|
-
* create a job, wait for completion, and then fetch the final report.
|
|
1221
|
-
*
|
|
1222
|
-
* For production systems, prefer `createJob*()` plus webhooks or streaming job events rather than blocking waits.
|
|
1223
|
-
*/
|
|
1224
|
-
declare class ReportsResource {
|
|
1225
|
-
private readonly transport;
|
|
1226
|
-
private readonly jobs;
|
|
1227
|
-
private readonly files;
|
|
1228
|
-
private readonly fetchImpl;
|
|
1229
|
-
constructor(transport: Transport, jobs: JobsResource, files: {
|
|
1230
|
-
upload: (req: UploadRequest) => Promise<MediaObject>;
|
|
1231
|
-
}, fetchImpl: typeof fetch);
|
|
1232
|
-
/**
|
|
1233
|
-
* Create a new report job.
|
|
1234
|
-
*
|
|
1235
|
-
* Behavior:
|
|
1236
|
-
* - Validates {@link MediaIdRef} at runtime (must provide `{ mediaId }`).
|
|
1237
|
-
* - Defaults to `{ strategy: "dominant" }` when `target` is omitted.
|
|
1238
|
-
* - Applies an idempotency key: uses `req.idempotencyKey` when provided; otherwise generates a best-effort default.
|
|
1239
|
-
* - Forwards `req.requestId` to the transport for end-to-end correlation.
|
|
1240
|
-
*
|
|
1241
|
-
* The returned receipt includes a {@link ReportRunHandle} (`receipt.handle`) which can be used to:
|
|
1242
|
-
* - stream job events
|
|
1243
|
-
* - wait for completion and fetch the final report
|
|
1244
|
-
* - cancel the job, or fetch job/report metadata
|
|
1245
|
-
*/
|
|
1246
|
-
createJob<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobRequest<T>): Promise<ReportJobReceipt<T>>;
|
|
1247
|
-
/**
|
|
1248
|
-
* Upload a file and create a report job in one call.
|
|
1249
|
-
*
|
|
1250
|
-
* Keeps `createJob()` strict about `media: { mediaId }` while offering a
|
|
1251
|
-
* convenient helper when you start from raw bytes.
|
|
1252
|
-
*/
|
|
1253
|
-
createJobFromFile<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromFileRequest<T>): Promise<ReportJobReceipt<T>>;
|
|
1254
|
-
/**
|
|
1255
|
-
* Download a file from a URL, upload it, and create a report job.
|
|
1256
|
-
*
|
|
1257
|
-
* Recommended when starting from a remote URL because report job creation
|
|
1258
|
-
* only accepts `media: { mediaId }`.
|
|
1259
|
-
*
|
|
1260
|
-
* Workflow:
|
|
1261
|
-
* 1) `fetch(url)`
|
|
1262
|
-
* 2) Validate the response (2xx) and derive `contentType`
|
|
1263
|
-
* 3) `files.upload({ file: Blob, ... })`
|
|
1264
|
-
* 4) `createJob({ media: { mediaId }, ... })`
|
|
1265
|
-
*
|
|
1266
|
-
* Verification / safety:
|
|
1267
|
-
* - Only allows `http:` and `https:` URLs.
|
|
1268
|
-
* - Requires a resolvable `contentType` (from `req.contentType` or response header).
|
|
1269
|
-
*/
|
|
1270
|
-
createJobFromUrl<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromUrlRequest<T>): Promise<ReportJobReceipt<T>>;
|
|
1271
|
-
get(reportId: string, opts?: {
|
|
1272
|
-
requestId?: string;
|
|
1273
|
-
signal?: AbortSignal;
|
|
1274
|
-
}): Promise<Report>;
|
|
1275
|
-
getByJob(jobId: string, opts?: {
|
|
1276
|
-
requestId?: string;
|
|
1277
|
-
signal?: AbortSignal;
|
|
1278
|
-
}): Promise<Report | null>;
|
|
1279
|
-
/**
|
|
1280
|
-
* Convenience wrapper: createJob + wait + get
|
|
1281
|
-
* Use for scripts; for production prefer createJob + webhooks/stream.
|
|
1282
|
-
*/
|
|
1283
|
-
generate<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobRequest<T>, opts?: {
|
|
1284
|
-
wait?: WaitOptions;
|
|
1285
|
-
}): Promise<ReportForOutputType<T>>;
|
|
1286
|
-
/**
|
|
1287
|
-
* Convenience wrapper: createJobFromFile + wait + get.
|
|
1288
|
-
* Use for scripts; for production prefer createJobFromFile + webhooks/stream.
|
|
1289
|
-
*/
|
|
1290
|
-
generateFromFile<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromFileRequest<T>, opts?: {
|
|
1291
|
-
wait?: WaitOptions;
|
|
1292
|
-
}): Promise<ReportForOutputType<T>>;
|
|
1293
|
-
/**
|
|
1294
|
-
* Convenience wrapper: createJobFromUrl + wait + get.
|
|
1295
|
-
* Use for scripts; for production prefer createJobFromUrl + webhooks/stream.
|
|
1296
|
-
*/
|
|
1297
|
-
generateFromUrl<T extends ReportOutputType = ReportOutputType>(req: ReportCreateJobFromUrlRequest<T>, opts?: {
|
|
1298
|
-
wait?: WaitOptions;
|
|
1299
|
-
}): Promise<ReportForOutputType<T>>;
|
|
1300
|
-
makeHandle<T extends ReportOutputType = ReportOutputType>(jobId: string): ReportRunHandle<T>;
|
|
1301
|
-
private defaultIdempotencyKey;
|
|
1302
|
-
private normalizeJobRequest;
|
|
1303
|
-
}
|
|
1304
|
-
//#endregion
|
|
1305
|
-
//#region src/resources/webhooks.d.ts
|
|
1306
|
-
/**
|
|
1307
|
-
* Webhook event types supported by the API.
|
|
1308
|
-
*/
|
|
1309
|
-
type WebhookEventType = "report.completed" | "report.failed";
|
|
1310
|
-
/**
|
|
1311
|
-
* Base webhook event structure.
|
|
1312
|
-
*/
|
|
1313
|
-
interface WebhookEvent<T = unknown> {
|
|
1314
|
-
type: string;
|
|
1315
|
-
timestamp: string;
|
|
1316
|
-
data: T;
|
|
1317
|
-
}
|
|
1318
|
-
/**
|
|
1319
|
-
* Payload for successful report completion.
|
|
1320
|
-
*/
|
|
1321
|
-
interface ReportCompletedData {
|
|
1322
|
-
jobId: string;
|
|
1323
|
-
reportId: string;
|
|
1324
|
-
status: "succeeded";
|
|
1325
|
-
}
|
|
1326
|
-
/**
|
|
1327
|
-
* Payload for failed report processing.
|
|
1328
|
-
*/
|
|
1329
|
-
interface ReportFailedData {
|
|
1330
|
-
jobId: string;
|
|
1331
|
-
status: "failed";
|
|
1332
|
-
error: {
|
|
1333
|
-
code: string;
|
|
1334
|
-
message: string;
|
|
1335
|
-
};
|
|
1336
|
-
}
|
|
1337
|
-
/**
|
|
1338
|
-
* Event emitted when a report completes successfully.
|
|
1339
|
-
*/
|
|
1340
|
-
type ReportCompletedEvent = WebhookEvent<ReportCompletedData> & {
|
|
1341
|
-
type: "report.completed";
|
|
1342
|
-
};
|
|
1343
|
-
/**
|
|
1344
|
-
* Event emitted when a report fails.
|
|
1345
|
-
*/
|
|
1346
|
-
type ReportFailedEvent = WebhookEvent<ReportFailedData> & {
|
|
1347
|
-
type: "report.failed";
|
|
1348
|
-
};
|
|
1349
|
-
/**
|
|
1350
|
-
* Async signature verification using WebCrypto (works in modern Node and browsers).
|
|
1351
|
-
* Signature scheme:
|
|
1352
|
-
* headers["mappa-signature"] = "t=1700000000,v1=<hex_hmac_sha256>"
|
|
1353
|
-
* Signed payload: `${t}.${rawBody}`
|
|
1354
|
-
*/
|
|
1355
|
-
declare class WebhooksResource {
|
|
1356
|
-
verifySignature(params: {
|
|
1357
|
-
payload: string;
|
|
1358
|
-
headers: Record<string, string | string[] | undefined>;
|
|
1359
|
-
secret: string;
|
|
1360
|
-
toleranceSec?: number;
|
|
1361
|
-
}): Promise<{
|
|
1362
|
-
ok: true;
|
|
1363
|
-
}>;
|
|
1364
|
-
/**
|
|
1365
|
-
* Parse and validate a webhook event payload.
|
|
1366
|
-
*
|
|
1367
|
-
* @param payload - Raw JSON string from the webhook request body
|
|
1368
|
-
* @returns Parsed and validated webhook event
|
|
1369
|
-
* @throws Error if payload is invalid or missing required fields
|
|
1370
|
-
*/
|
|
1371
|
-
parseEvent<T = unknown>(payload: string): WebhookEvent<T>;
|
|
1372
|
-
}
|
|
1373
|
-
//#endregion
|
|
1374
|
-
//#region src/Mappa.d.ts
|
|
1375
|
-
/**
|
|
1376
|
-
* Options for constructing a {@link Mappa} client.
|
|
1377
|
-
*/
|
|
1378
|
-
type MappaClientOptions = {
|
|
1379
|
-
/**
|
|
1380
|
-
* API key used for authenticating requests.
|
|
1381
|
-
*/
|
|
1382
|
-
apiKey: string;
|
|
1383
|
-
/**
|
|
1384
|
-
* Base URL for the Mappa API.
|
|
1385
|
-
*
|
|
1386
|
-
* @defaultValue "https://api.mappa.ai"
|
|
1387
|
-
*/
|
|
1388
|
-
baseUrl?: string;
|
|
1389
|
-
/**
|
|
1390
|
-
* Per-request timeout, in milliseconds.
|
|
1391
|
-
*
|
|
1392
|
-
* Note: this timeout applies to individual HTTP attempts (including retries).
|
|
1393
|
-
* Long-running workflows should use {@link JobsResource.wait} through
|
|
1394
|
-
* {@link ReportsResource.makeHandle} instead.
|
|
1395
|
-
*
|
|
1396
|
-
* @defaultValue 30000
|
|
1397
|
-
*/
|
|
1398
|
-
timeoutMs?: number;
|
|
1399
|
-
/**
|
|
1400
|
-
* Maximum number of retries performed by the transport for retryable requests.
|
|
1401
|
-
*
|
|
1402
|
-
* @defaultValue 2
|
|
1403
|
-
*/
|
|
1404
|
-
maxRetries?: number;
|
|
1405
|
-
/**
|
|
1406
|
-
* Headers that will be sent with every request.
|
|
1407
|
-
*/
|
|
1408
|
-
defaultHeaders?: Record<string, string>;
|
|
1409
|
-
/**
|
|
1410
|
-
* Custom fetch implementation (useful for polyfills, instrumentation, or tests).
|
|
1411
|
-
*/
|
|
1412
|
-
fetch?: typeof fetch;
|
|
1413
|
-
/**
|
|
1414
|
-
* Overrides the User-Agent header.
|
|
1415
|
-
*/
|
|
1416
|
-
userAgent?: string;
|
|
1417
|
-
/**
|
|
1418
|
-
* Telemetry hooks called on request/response/error.
|
|
1419
|
-
*/
|
|
1420
|
-
telemetry?: Telemetry;
|
|
1421
|
-
};
|
|
1422
|
-
/**
|
|
1423
|
-
* Main SDK client.
|
|
1424
|
-
*
|
|
1425
|
-
* Exposes resource namespaces ({@link Mappa.files}, {@link Mappa.reports}, etc.)
|
|
1426
|
-
* and configures a shared HTTP transport.
|
|
1427
|
-
*/
|
|
1428
|
-
declare class Mappa {
|
|
1429
|
-
readonly files: FilesResource;
|
|
1430
|
-
readonly jobs: JobsResource;
|
|
1431
|
-
readonly reports: ReportsResource;
|
|
1432
|
-
readonly feedback: FeedbackResource;
|
|
1433
|
-
readonly credits: CreditsResource;
|
|
1434
|
-
readonly entities: EntitiesResource;
|
|
1435
|
-
readonly webhooks: WebhooksResource;
|
|
1436
|
-
readonly health: HealthResource;
|
|
1437
|
-
private readonly transport;
|
|
1438
|
-
private readonly opts;
|
|
1439
|
-
constructor(options: MappaClientOptions);
|
|
1440
|
-
withOptions(overrides: Partial<MappaClientOptions>): Mappa;
|
|
1441
|
-
close(): void;
|
|
1442
84
|
}
|
|
1443
85
|
//#endregion
|
|
1444
86
|
//#region src/index.d.ts
|
|
1445
|
-
/**
|
|
1446
|
-
* Type guard for catching SDK errors.
|
|
1447
|
-
*/
|
|
1448
87
|
declare function isMappaError(err: unknown): err is MappaError;
|
|
1449
|
-
/**
|
|
1450
|
-
* Type guard for insufficient credits errors.
|
|
1451
|
-
*
|
|
1452
|
-
* @example
|
|
1453
|
-
* ```typescript
|
|
1454
|
-
* try {
|
|
1455
|
-
* await mappa.reports.createJob({ ... });
|
|
1456
|
-
* } catch (err) {
|
|
1457
|
-
* if (isInsufficientCreditsError(err)) {
|
|
1458
|
-
* console.log(`Need ${err.required} credits, have ${err.available}`);
|
|
1459
|
-
* }
|
|
1460
|
-
* }
|
|
1461
|
-
* ```
|
|
1462
|
-
*/
|
|
1463
88
|
declare function isInsufficientCreditsError(err: unknown): err is InsufficientCreditsError;
|
|
1464
|
-
/**
|
|
1465
|
-
* Type guard for stream connection errors.
|
|
1466
|
-
*
|
|
1467
|
-
* Use this to detect streaming failures and access recovery metadata
|
|
1468
|
-
* like `jobId`, `lastEventId`, and `retryCount`.
|
|
1469
|
-
*
|
|
1470
|
-
* @example
|
|
1471
|
-
* ```typescript
|
|
1472
|
-
* try {
|
|
1473
|
-
* await mappa.reports.generate({ ... });
|
|
1474
|
-
* } catch (err) {
|
|
1475
|
-
* if (isStreamError(err)) {
|
|
1476
|
-
* console.log(`Stream failed for job ${err.jobId}`);
|
|
1477
|
-
* console.log(`Last event ID: ${err.lastEventId}`);
|
|
1478
|
-
* console.log(`Retries attempted: ${err.retryCount}`);
|
|
1479
|
-
* }
|
|
1480
|
-
* }
|
|
1481
|
-
* ```
|
|
1482
|
-
*/
|
|
1483
89
|
declare function isStreamError(err: unknown): err is StreamError;
|
|
1484
90
|
//#endregion
|
|
1485
|
-
export { ApiError, AuthError,
|
|
91
|
+
export { ApiError, AuthError, Entity, FeedbackCreateRequest, FeedbackReceipt, FileDeleteReceipt, InsufficientCreditsError, Job, JobCanceledError, JobCreditReservation, JobEvent, JobFailedError, JobStage, JobStatus, JsonValue, ListEntitiesResponse, ListFilesResponse, Mappa, MappaError, MatchingAnalysisCreateJobRequest, MatchingAnalysisEntitySource, MatchingAnalysisForOutputType, MatchingAnalysisJobReceipt, MatchingAnalysisOutput, MatchingAnalysisOutputType, MatchingAnalysisResponse, MatchingAnalysisRunHandle, MediaFile, MediaObject, MediaRetention, RateLimitError, Report, type ReportCompletedData, type ReportCompletedEvent, ReportCreateJobRequest, type ReportFailedData, type ReportFailedEvent, ReportForOutputType, ReportJobReceipt, ReportOutput, ReportOutputType, ReportRunHandle, ReportTemplateId, RetentionLockResult, StreamError, TargetSelector, Usage, ValidationError, WaitOptions, WebhookConfig, type WebhookEvent, type WebhookEventType, hasEntity, isInsufficientCreditsError, isMappaError, isStreamError };
|
|
1486
92
|
//# sourceMappingURL=index.d.mts.map
|