@mappa-ai/mappa-node 1.2.3 → 2.0.8

package/dist/Mappa-BTrlzSaB.d.cts

@@ -0,0 +1,621 @@
+//#region src/types.d.ts
+type JsonValue = string | number | boolean | null | {
+  [k: string]: JsonValue;
+} | JsonValue[];
+type ReportTemplateId = "sales_playbook" | "general_report" | "hiring_report" | "profile_alignment";
+type ReportOutputType = "markdown" | "json" | "pdf" | "url";
+type ReportOutput = {
+  template: ReportTemplateId;
+  templateParams?: Record<string, unknown>;
+};
+type TargetSelector = {
+  strategy: "dominant";
+  onMiss?: "fallback_dominant" | "error";
+} | {
+  strategy: "timerange";
+  onMiss?: "fallback_dominant" | "error";
+  timeRange?: {
+    startSeconds?: number;
+    endSeconds?: number;
+  };
+} | {
+  strategy: "entity_id";
+  onMiss?: "fallback_dominant" | "error";
+  entityId: string;
+} | {
+  strategy: "magic_hint";
+  onMiss?: "fallback_dominant" | "error";
+  hint: string;
+};
+type WebhookConfig = {
+  url: string;
+  headers?: Record<string, string>;
+};
+type ReportCreateJobRequest = {
+  media: {
+    mediaId: string;
+  };
+  output: ReportOutput;
+  target: TargetSelector;
+  label?: string;
+  entityLabel?: string;
+  webhook?: WebhookConfig;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type JobStage = "uploaded" | "queued" | "transcoding" | "extracting" | "scoring" | "rendering" | "finalizing";
+type JobStatus = "queued" | "running" | "succeeded" | "failed" | "canceled";
+type Usage = {
+  creditsUsed: number;
+  creditsDiscounted?: number;
+  creditsNetUsed: number;
+  durationMs?: number;
+  modelVersion?: string;
+};
+type JobCreditReservation = {
+  reservedCredits: number | null;
+  reservationStatus: "active" | "released" | "applied" | null;
+};
+type Job = {
+  id: string;
+  type: "report.generate";
+  status: JobStatus;
+  stage?: JobStage;
+  progress?: number;
+  createdAt: string;
+  updatedAt: string;
+  reportId?: string;
+  usage?: Usage;
+  credits?: JobCreditReservation;
+  releasedCredits?: number | null;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+    retryable?: boolean;
+  };
+  requestId?: string;
+};
+type JobEvent = {
+  type: "status";
+  job: Job;
+} | {
+  type: "stage";
+  stage: JobStage;
+  progress?: number;
+  job: Job;
+} | {
+  type: "terminal";
+  job: Job;
+};
+type WaitOptions = {
+  timeoutMs?: number;
+  onEvent?: (event: JobEvent) => void;
+  signal?: AbortSignal;
+};
+type Report = {
+  id: string;
+  createdAt: string;
+  jobId?: string;
+  label?: string;
+  summary?: string;
+  media: {
+    url?: string;
+    mediaId?: string;
+  };
+  output: {
+    template: ReportTemplateId;
+  };
+  entity?: {
+    id: string;
+    label: string | null;
+  };
+  markdown?: string | null;
+  sections?: Array<{
+    section_title: string;
+    section_content: unknown;
+  }> | null;
+  metrics?: Record<string, unknown> | null;
+  raw?: unknown;
+  pdfUrl?: string;
+  reportUrl?: string;
+};
+type ReportForOutputType = Report;
+type ReportRunHandle = {
+  jobId: string;
+  stream(opts?: {
+    signal?: AbortSignal;
+    onEvent?: (e: JobEvent) => void;
+  }): AsyncIterable<JobEvent>;
+  wait(opts?: WaitOptions): Promise<ReportForOutputType>;
+  cancel(): Promise<Job>;
+  job(): Promise<Job>;
+  report(): Promise<ReportForOutputType | null>;
+};
+type MatchingAnalysisOutputType = "markdown" | "json" | "pdf" | "url";
+type MatchingAnalysisOutput = {
+  template: "matching_analysis";
+  templateParams?: Record<string, unknown>;
+};
+type MatchingAnalysisEntitySource = {
+  type: "entity_id";
+  entityId: string;
+} | {
+  type: "media_target";
+  mediaId: string;
+  target: TargetSelector;
+};
+type MatchingAnalysisCreateJobRequest = {
+  entityA: MatchingAnalysisEntitySource;
+  entityB: MatchingAnalysisEntitySource;
+  context: string;
+  output: MatchingAnalysisOutput;
+  label?: string;
+  entityALabel?: string;
+  entityBLabel?: string;
+  webhook?: WebhookConfig;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type MatchingAnalysisResponse = {
+  id: string;
+  createdAt: string;
+  jobId?: string;
+  label?: string;
+  context: string;
+  output: {
+    template: "matching_analysis";
+  };
+  entityA?: {
+    id: string;
+    label: string | null;
+  };
+  entityB?: {
+    id: string;
+    label: string | null;
+  };
+  markdown?: string | null;
+  sections?: Array<{
+    section_title: string;
+    section_content: unknown;
+  }> | null;
+  metrics?: Record<string, unknown> | null;
+  raw?: unknown;
+  pdfUrl?: string;
+  reportUrl?: string;
+};
+type MatchingAnalysisForOutputType = MatchingAnalysisResponse;
+type MatchingAnalysisRunHandle = {
+  jobId: string;
+  stream(opts?: {
+    signal?: AbortSignal;
+    onEvent?: (e: JobEvent) => void;
+  }): AsyncIterable<JobEvent>;
+  wait(opts?: WaitOptions): Promise<MatchingAnalysisForOutputType>;
+  cancel(): Promise<Job>;
+  job(): Promise<Job>;
+  analysis(): Promise<MatchingAnalysisForOutputType | null>;
+};
+type MatchingAnalysisJobReceipt = {
+  jobId: string;
+  status: "queued" | "running";
+  stage?: string;
+  estimatedWaitSec?: number;
+  requestId?: string;
+  handle?: MatchingAnalysisRunHandle;
+};
+type ReportJobReceipt = {
+  jobId: string;
+  status: "queued" | "running";
+  stage?: string;
+  estimatedWaitSec?: number;
+  requestId?: string;
+  handle?: ReportRunHandle;
+};
+type FeedbackCreateRequest = {
+  reportId?: string;
+  jobId?: string;
+  matchingAnalysisId?: string;
+  rating: "thumbs_up" | "thumbs_down";
+  comment?: string;
+  corrections?: Array<{
+    path: string;
+    expected?: unknown;
+    observed?: unknown;
+  }>;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type FeedbackReceipt = {
+  id: string;
+  createdAt: string;
+  target: {
+    reportId?: string;
+    jobId?: string;
+    matchingAnalysisId?: string;
+  };
+  rating: "thumbs_up" | "thumbs_down";
+  comment?: string;
+  credits: {
+    eligible: boolean;
+    reason?: string;
+    discountApplied: number;
+    netUsed: number;
+  };
+};
+type MediaObject = {
+  mediaId: string;
+  createdAt: string;
+  contentType: string;
+  label?: string | null;
+  sizeBytes?: number | null;
+  durationSeconds?: number | null;
+};
+type MediaRetention = {
+  expiresAt: string | null;
+  daysRemaining: number | null;
+  locked: boolean;
+};
+type MediaFile = {
+  mediaId: string;
+  createdAt: string;
+  contentType: string;
+  label?: string | null;
+  sizeBytes?: number | null;
+  durationSeconds?: number | null;
+  processingStatus: "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
+  lastUsedAt: string | null;
+  retention: MediaRetention;
+};
+type FileDeleteReceipt = {
+  mediaId: string;
+  deleted: true;
+};
+type RetentionLockResult = {
+  mediaId: string;
+  retentionLock: boolean;
+  message: string;
+};
+type ListFilesResponse = {
+  files: MediaFile[];
+  nextCursor: string | null;
+  hasMore: boolean;
+};
+type Entity = {
+  id: string;
+  label: string | null;
+  createdAt: string;
+  mediaCount: number;
+  lastSeenAt: string | null;
+};
+type ListEntitiesResponse = {
+  entities: Entity[];
+  cursor: string | null;
+  hasMore: boolean;
+};
+declare function hasEntity(report: Report): report is Report & {
+  entity: {
+    id: string;
+    label: string | null;
+  };
+};
+//#endregion
+//#region src/resources/transport.d.ts
+type SSEStreamOptions = {
+  signal?: AbortSignal;
+  lastEventId?: string;
+};
+type SSEEvent<T = unknown> = {
+  id?: string;
+  event: string;
+  data: T;
+};
+type Telemetry = {
+  onRequest?: (ctx: {
+    method: string;
+    url: string;
+    requestId?: string;
+  }) => void;
+  onResponse?: (ctx: {
+    status: number;
+    url: string;
+    requestId?: string;
+    durationMs: number;
+  }) => void;
+  onError?: (ctx: {
+    url: string;
+    requestId?: string;
+    error: unknown;
+    context?: Record<string, unknown>;
+  }) => void;
+};
+type TransportOptions = {
+  apiKey: string;
+  baseUrl: string;
+  timeoutMs: number;
+  maxRetries: number;
+  defaultHeaders?: Record<string, string>;
+  fetch?: typeof fetch;
+  telemetry?: Telemetry;
+  userAgent?: string;
+};
+type RequestOptions = {
+  method: "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  headers?: Record<string, string | undefined>;
+  body?: unknown;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+  retryable?: boolean;
+};
+type TransportResponse<T> = {
+  data: T;
+  status: number;
+  requestId?: string;
+  headers: Headers;
+};
+declare class Transport {
+  private readonly opts;
+  private readonly fetchImpl;
+  constructor(opts: TransportOptions);
+  streamSSE<T>(path: string, opts?: SSEStreamOptions): AsyncGenerator<SSEEvent<T>>;
+  private parseSSEStream;
+  private parseSSEEvent;
+  request<T>(req: RequestOptions): Promise<TransportResponse<T>>;
+}
+//#endregion
+//#region src/resources/entities.d.ts
+type ListEntitiesOptions = {
+  limit?: number;
+  cursor?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+declare class EntitiesResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  get(entityId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Entity>;
+  list(opts?: ListEntitiesOptions): Promise<ListEntitiesResponse>;
+  listAll(opts?: Omit<ListEntitiesOptions, "cursor">): AsyncIterable<Entity>;
+  update(entityId: string, body: {
+    label?: string | null;
+  }, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Entity>;
+}
+//#endregion
+//#region src/resources/feedback.d.ts
+declare class FeedbackResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  create(req: FeedbackCreateRequest): Promise<FeedbackReceipt>;
+}
+//#endregion
+//#region src/resources/files.d.ts
+type UploadRequest = {
+  file: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
+  label?: string;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type ListFilesOptions = {
+  limit?: number;
+  cursor?: string;
+  includeDeleted?: boolean;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+declare class FilesResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  upload(req: UploadRequest): Promise<MediaObject>;
+  get(mediaId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<MediaFile>;
+  list(opts?: ListFilesOptions): Promise<ListFilesResponse>;
+  listAll(opts?: Omit<ListFilesOptions, "cursor">): AsyncIterable<MediaFile>;
+  setRetentionLock(mediaId: string, locked: boolean, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<RetentionLockResult>;
+  delete(mediaId: string, opts?: {
+    idempotencyKey?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<FileDeleteReceipt>;
+}
+//#endregion
+//#region src/resources/health.d.ts
+declare class HealthResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  ping(): Promise<{
+    ok: true;
+    time: string;
+  }>;
+}
+//#endregion
+//#region src/resources/jobs.d.ts
+declare class JobsResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  get(jobId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Job>;
+  cancel(jobId: string, opts?: {
+    idempotencyKey?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Job>;
+  wait(jobId: string, opts?: WaitOptions): Promise<Job>;
+  stream(jobId: string, opts?: {
+    signal?: AbortSignal;
+    onEvent?: (e: JobEvent) => void;
+  }): AsyncIterable<JobEvent>;
+  private mapSSEToJobEvent;
+  private backoff;
+}
+//#endregion
+//#region src/resources/matching-analysis.d.ts
+declare class MatchingAnalysisResource {
+  private readonly transport;
+  private readonly jobs;
+  constructor(transport: Transport, jobs: JobsResource);
+  createJob(req: MatchingAnalysisCreateJobRequest): Promise<MatchingAnalysisJobReceipt>;
+  get(matchingAnalysisId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<MatchingAnalysisResponse>;
+  getByJob(jobId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<MatchingAnalysisResponse | null>;
+  generate(req: MatchingAnalysisCreateJobRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<MatchingAnalysisForOutputType>;
+  makeHandle(jobId: string): MatchingAnalysisRunHandle;
+  private normalizeBody;
+  private normalizeEntitySource;
+  private normalizeTarget;
+}
+//#endregion
+//#region src/resources/reports.d.ts
+type ReportCreateJobFromFileRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "label"> & {
+  label?: string;
+  idempotencyKey?: string;
+  requestId?: string;
+};
+type ReportCreateJobFromUrlRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & {
+  url: string;
+  label?: string;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+declare class ReportsResource {
+  private readonly transport;
+  private readonly jobs;
+  private readonly files;
+  private readonly fetchImpl;
+  constructor(transport: Transport, jobs: JobsResource, files: {
+    upload: (req: UploadRequest) => Promise<{
+      mediaId: string;
+    }>;
+  }, fetchImpl: typeof fetch);
+  createJob(req: ReportCreateJobRequest): Promise<ReportJobReceipt>;
+  createJobFromFile(req: ReportCreateJobFromFileRequest): Promise<ReportJobReceipt>;
+  createJobFromUrl(req: ReportCreateJobFromUrlRequest): Promise<ReportJobReceipt>;
+  get(reportId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Report>;
+  getByJob(jobId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Report | null>;
+  generate(req: ReportCreateJobRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<ReportForOutputType>;
+  generateFromFile(req: ReportCreateJobFromFileRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<ReportForOutputType>;
+  generateFromUrl(req: ReportCreateJobFromUrlRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<ReportForOutputType>;
+  makeHandle(jobId: string): ReportRunHandle;
+  private defaultIdempotencyKey;
+  private normalizeJobRequest;
+}
+//#endregion
+//#region src/resources/webhooks.d.ts
+type WebhookEventType = "report.completed" | "report.failed";
+interface WebhookEvent<T = unknown> {
+  type: string;
+  timestamp: string;
+  data: T;
+}
+interface ReportCompletedData {
+  jobId: string;
+  reportId: string;
+  status: "succeeded";
+}
+interface ReportFailedData {
+  jobId: string;
+  status: "failed";
+  error: {
+    code: string;
+    message: string;
+  };
+}
+type ReportCompletedEvent = WebhookEvent<ReportCompletedData> & {
+  type: "report.completed";
+};
+type ReportFailedEvent = WebhookEvent<ReportFailedData> & {
+  type: "report.failed";
+};
+declare class WebhooksResource {
+  verifySignature(params: {
+    payload: string;
+    headers: Record<string, string | string[] | undefined>;
+    secret: string;
+    toleranceSec?: number;
+  }): Promise<{
+    ok: true;
+  }>;
+  parseEvent<T = unknown>(payload: string): WebhookEvent<T>;
+  parseEvent(payload: string): ReportCompletedEvent | ReportFailedEvent | WebhookEvent<unknown>;
+}
+//#endregion
+//#region src/Mappa.d.ts
+type MappaClientOptions = {
+  /** API key used for Mappa authenticated requests. */apiKey: string; /** Base API URL. Defaults to https://api.mappa.ai. */
+  baseUrl?: string; /** Per-request timeout in milliseconds. Defaults to 30000. */
+  timeoutMs?: number; /** Number of retry attempts for retryable requests. Defaults to 2. */
+  maxRetries?: number; /** Headers included on every request. */
+  defaultHeaders?: Record<string, string>; /** Custom fetch implementation. */
+  fetch?: typeof fetch; /** User-Agent header value sent on requests. */
+  userAgent?: string; /** Request/response/error instrumentation hooks. */
+  telemetry?: Telemetry;
+  /**
+   * Allow use from browser-like runtimes.
+   *
+   * This is unsafe for secret API keys and should only be used when
+   * credentials are intentionally exposed.
+   */
+  dangerouslyAllowBrowser?: boolean;
+};
+/**
+ * Mappa API client for server and worker runtimes.
+ */
+declare class Mappa {
+  readonly files: FilesResource;
+  readonly jobs: JobsResource;
+  readonly reports: ReportsResource;
+  readonly matchingAnalysis: MatchingAnalysisResource;
+  readonly feedback: FeedbackResource;
+  readonly entities: EntitiesResource;
+  readonly webhooks: WebhooksResource;
+  readonly health: HealthResource;
+  private readonly transport;
+  private readonly opts;
+  /** Create a new client instance. */
+  constructor(options: MappaClientOptions);
+  /** Clone the client with option overrides. */
+  withOptions(overrides: Partial<MappaClientOptions>): Mappa;
+  close(): void;
+}
+//#endregion
+export { MediaRetention as A, TargetSelector as B, MatchingAnalysisJobReceipt as C, MatchingAnalysisRunHandle as D, MatchingAnalysisResponse as E, ReportOutput as F, WaitOptions as H, ReportOutputType as I, ReportRunHandle as L, ReportCreateJobRequest as M, ReportForOutputType as N, MediaFile as O, ReportJobReceipt as P, ReportTemplateId as R, MatchingAnalysisForOutputType as S, MatchingAnalysisOutputType as T, WebhookConfig as U, Usage as V, hasEntity as W, JsonValue as _, ReportFailedEvent as a, MatchingAnalysisCreateJobRequest as b, Entity as c, FileDeleteReceipt as d, Job as f, JobStatus as g, JobStage as h, ReportFailedData as i, Report as j, MediaObject as k, FeedbackCreateRequest as l, JobEvent as m, ReportCompletedData as n, WebhookEvent as o, JobCreditReservation as p, ReportCompletedEvent as r, WebhookEventType as s, Mappa as t, FeedbackReceipt as u, ListEntitiesResponse as v, MatchingAnalysisOutput as w, MatchingAnalysisEntitySource as x, ListFilesResponse as y, RetentionLockResult as z };
+//# sourceMappingURL=Mappa-BTrlzSaB.d.cts.map