@mappa-ai/mappa-node 0.1.2 → 1.1.1

package/dist/index.d.cts

@@ -1,67 +1,1248 @@
-import { z } from "zod";
-
-//#region src/presets.d.ts
-declare class Presets {
-  generateReport(): Promise<string>;
+//#region src/errors.d.ts
+/**
+ * Base error type for all SDK-raised errors.
+ *
+ * When available, {@link MappaError.requestId} can be used to correlate a failure
+ * with server logs/support.
+ */
+declare class MappaError extends Error {
+  name: string;
+  requestId?: string;
+  code?: string;
+  constructor(message: string, opts?: {
+    requestId?: string;
+    code?: string;
+    cause?: unknown;
+  });
+}
+/**
+ * Error returned when the API responds with a non-2xx status.
+ */
+declare class ApiError extends MappaError {
+  name: string;
+  status: number;
+  details?: unknown;
+  constructor(message: string, opts: {
+    status: number;
+    requestId?: string;
+    code?: string;
+    details?: unknown;
+  });
+}
+/**
+ * Error returned for HTTP 429 responses.
+ *
+ * If provided by the server, {@link RateLimitError.retryAfterMs} indicates when
+ * it is safe to retry.
+ */
+declare class RateLimitError extends ApiError {
+  name: string;
+  retryAfterMs?: number;
+}
+/**
+ * Error returned for authentication/authorization failures (typically 401/403).
+ */
+declare class AuthError extends ApiError {
+  name: string;
+}
+/**
+ * Error returned when the server rejects a request as invalid (typically 422).
+ */
+declare class ValidationError extends ApiError {
+  name: string;
+}
+/**
+ * Error thrown by polling helpers when a job reaches the "failed" terminal state.
+ */
+declare class JobFailedError extends MappaError {
+  name: string;
+  jobId: string;
+  constructor(jobId: string, message: string, opts?: {
+    requestId?: string;
+    code?: string;
+    cause?: unknown;
+  });
+}
+/**
+ * Error thrown by polling helpers when a job reaches the "canceled" terminal state.
+ */
+declare class JobCanceledError extends MappaError {
+  name: string;
+  jobId: string;
+  constructor(jobId: string, message: string, opts?: {
+    requestId?: string;
+    cause?: unknown;
+  });
 }
 //#endregion
-//#region src/mappa/model.d.ts
-declare namespace MappaModel {
-  const generateReportInputSchema: z.ZodObject<{
-    inputMedia: z.ZodDiscriminatedUnion<[z.ZodObject<{
-      kind: z.ZodLiteral<"file">;
-      file: z.ZodFile;
-    }, z.core.$strip>, z.ZodObject<{
-      kind: z.ZodLiteral<"url">;
-      url: z.ZodURL;
-    }, z.core.$strip>], "kind">;
-    targetSpeaker: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
-      strategy: z.ZodLiteral<"dominant">;
-    }, z.core.$strip>, z.ZodObject<{
-      strategy: z.ZodLiteral<"magic_hint">;
-      hint: z.ZodString;
-    }, z.core.$strip>], "strategy">>;
-    template: z.ZodEnum<{
-      base: "base";
-    }>;
-  }, z.core.$strip>;
-  type GenerateReportInput = z.infer<typeof generateReportInputSchema>;
-  const generateReportOutputSchema: z.ZodObject<{
-    outputs: z.ZodPipe<z.ZodArray<z.ZodObject<{
-      entity_id: z.ZodString;
-      behavior_profile: z.ZodString;
-    }, z.core.$strip>>, z.ZodTransform<{
-      entity_id: string;
-      behavior_profile: string;
-    } | null, {
-      entity_id: string;
-      behavior_profile: string;
-    }[]>>;
-  }, z.core.$strip>;
-  type GenerateReportOutput = z.infer<typeof generateReportOutputSchema>;
+//#region src/resources/transport.d.ts
+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;
+  }) => 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);
+  request<T>(req: RequestOptions): Promise<TransportResponse<T>>;
 }
 //#endregion
-//#region src/mappa/index.d.ts
+//#region src/types.d.ts
 /**
- * Client for the Mappa API that provides access to presets and can generate a synchronous behavior profile report
- * from either an uploaded media file or a remote media URL.
+ * JSON-serializable value.
+ *
+ * Used throughout the SDK for message payloads, webhook data, and server-provided
+ * metadata where the exact shape is not known at compile time.
  */
-declare class Mappa {
-  private readonly apiKey;
-  private readonly apiBaseUrl;
-  private readonly apiVersion;
-  readonly presets: Presets;
+type JsonValue = string | number | boolean | null | {
+  [k: string]: JsonValue;
+} | JsonValue[];
+type MediaRef = {
+  url: string;
+  contentType?: string;
+  filename?: string;
+} | {
+  mediaId: string;
+};
+/**
+ * A reference to an already-uploaded media object.
+ */
+type MediaIdRef = {
+  mediaId: string;
+};
+type ReportTemplateId = "sales_playbook" | "general_report" | "hiring_report" | "profile_alignment";
+type ReportTemplateParamsMap = {
+  sales_playbook: Record<string, never>;
+  general_report: Record<string, never>;
+  hiring_report: {
+    roleTitle: string;
+    roleDescription: string;
+    companyCulture: string;
+  };
+  profile_alignment: {
+    idealProfile: string;
+  };
+};
+type ReportOutputType = "markdown" | "json" | "pdf" | "url";
+type ReportOutputEntry<OutputType extends ReportOutputType, Template extends ReportTemplateId> = ReportTemplateParamsMap[Template] extends Record<string, never> ? {
+  type: OutputType;
+  template: Template;
+  templateParams?: ReportTemplateParamsMap[Template];
+} : {
+  type: OutputType;
+  template: Template;
+  templateParams: ReportTemplateParamsMap[Template];
+};
+type ReportOutputForType<OutputType extends ReportOutputType> = ReportOutputEntry<OutputType, "sales_playbook"> | ReportOutputEntry<OutputType, "general_report"> | ReportOutputEntry<OutputType, "hiring_report"> | ReportOutputEntry<OutputType, "profile_alignment">;
+type ReportOutput = ReportOutputForType<"markdown"> | ReportOutputForType<"json"> | ReportOutputForType<"pdf"> | ReportOutputForType<"url">;
+type TargetStrategy = "dominant" | "timerange" | "entity_id" | "magic_hint";
+type TargetOnMiss = "fallback_dominant" | "error";
+type TargetTimeRange = {
+  /**
+   * Start time in seconds.
+   * When omitted, starts from the beginning.
+   */
+  startSeconds?: number;
+  /**
+   * End time in seconds.
+   * When omitted, goes until the end.
+   */
+  endSeconds?: number;
+};
+type TargetBase = {
+  /**
+   * Behavior when the entity is not found.
+   */
+  onMiss?: TargetOnMiss;
+  /**
+   * Tags to apply to the selected entity after job completion.
+   *
+   * Tags must be 1-64 characters, alphanumeric with underscores and hyphens only.
+   * Maximum 10 tags per request.
+   *
+   * @example ["interviewer", "sales-rep", "round-1"]
+   */
+  tags?: string[];
+  /**
+   * Exclude speakers whose entities have ANY of these tags from selection.
+   *
+   * Useful for filtering out known interviewers, hosts, etc.
+   *
+   * @example ["interviewer", "host"]
+   */
+  excludeTags?: string[];
+};
+type TargetDominant = TargetBase & {
+  strategy: "dominant";
+};
+type TargetTimeRangeStrategy = TargetBase & {
+  strategy: "timerange";
+  timeRange: TargetTimeRange;
+};
+type TargetEntityId = TargetBase & {
+  strategy: "entity_id";
+  entityId: string;
+};
+type TargetMagicHint = TargetBase & {
+  strategy: "magic_hint";
+  hint: string;
+};
+type TargetSelector = TargetDominant | TargetTimeRangeStrategy | TargetEntityId | TargetMagicHint;
+type TargetStrategyMap = {
+  dominant: TargetDominant;
+  timerange: TargetTimeRangeStrategy;
+  entity_id: TargetEntityId;
+  magic_hint: TargetMagicHint;
+};
+type TargetFor<Strategy extends TargetStrategy> = TargetStrategyMap[Strategy];
+type Usage = {
+  creditsUsed: number;
+  creditsDiscounted?: number;
+  creditsNetUsed: number;
+  durationMs?: number;
+  modelVersion?: string;
+};
+type JobStage = "uploaded" | "queued" | "transcoding" | "extracting" | "scoring" | "rendering" | "finalizing";
+type JobStatus = "queued" | "running" | "succeeded" | "failed" | "canceled";
+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?: JsonValue;
+    retryable?: boolean;
+  };
+  requestId?: string;
+};
+type JobEvent = {
+  type: "status";
+  job: Job;
+} | {
+  type: "stage";
+  stage: JobStage;
+  progress?: number;
+  job: Job;
+} | {
+  type: "log";
+  message: string;
+  ts: string;
+} | {
+  type: "terminal";
+  job: Job;
+};
+type Subject = {
+  id?: string;
+  externalRef?: string;
+  metadata?: Record<string, JsonValue>;
+};
+type WebhookConfig = {
+  url: string;
+  headers?: Record<string, string>;
+};
+type ReportCreateJobRequest = {
+  subject?: Subject;
+  /**
+   * Reference to already-uploaded media.
+   *
+   * Note: Report job creation requires a `mediaId`. To start from a remote URL or local bytes,
+   * use helper methods like `reports.createJobFromUrl()` / `reports.createJobFromFile()`.
+   */
+  media: MediaIdRef;
+  output: ReportOutput;
+  /**
+   * Select the target entity for analysis.
+   *
+   * When omitted, the API defaults to the dominant speaker.
+   */
+  target?: TargetSelector;
+  options?: {
+    language?: string;
+    timezone?: string;
+    includeMetrics?: boolean;
+    includeRawModelOutput?: boolean;
+  };
+  /**
+   * Webhook to call when the job completes or fails.
+   *
+   * @example
+   * webhook: {
+   *   url: "https://example.com/webhooks/mappa",
+   *   headers: { "X-Custom-Header": "value" }
+   * }
+   */
+  webhook?: WebhookConfig;
+  idempotencyKey?: string;
+  requestId?: string;
+};
+type ReportBase = {
+  id: string;
+  createdAt: string;
+  subject?: Subject;
+  media: {
+    url?: string;
+    mediaId?: string;
+  };
+  entity: {
+    id: string;
+    tags: string[];
+  };
+  usage?: Usage;
+  metrics?: Record<string, JsonValue>;
+  raw?: JsonValue;
+};
+type MarkdownReport = ReportBase & {
+  output: {
+    type: "markdown";
+  };
+  markdown: string;
+};
+type JsonReport = ReportBase & {
+  output: {
+    type: "json";
+  };
+  sections: Array<{
+    section_title: string;
+    section_content: JsonValue;
+  }>;
+};
+type PdfReport = ReportBase & {
+  output: {
+    type: "pdf";
+    template: string;
+  };
+  markdown: string;
+  pdfUrl: string;
+};
+type UrlReport = ReportBase & {
+  output: {
+    type: "url";
+    template: string;
+  };
+  markdown?: string;
+  sections?: Array<{
+    section_title: string;
+    section_content: JsonValue;
+  }>;
+  reportUrl: string;
+};
+type Report = MarkdownReport | JsonReport | PdfReport | UrlReport;
+type ReportJobReceipt = {
+  jobId: string;
+  status: "queued" | "running";
+  stage?: JobStage;
+  estimatedWaitSec?: number;
+  requestId?: string;
+  handle?: ReportRunHandle;
+};
+type FeedbackReceipt = {
+  id: string;
+  createdAt: string;
+  target: {
+    reportId?: string;
+    jobId?: string;
+  };
+  rating: "thumbs_up" | "thumbs_down" | "1" | "2" | "3" | "4" | "5";
+  tags?: string[];
+  comment?: string;
+  credits: {
+    eligible: boolean;
+    reason?: string;
+    discountApplied: number;
+    netUsed: number;
+  };
+};
+type MediaObject = {
+  mediaId: string;
+  createdAt: string;
+  contentType: string;
+  filename?: string;
+  sizeBytes?: number;
+};
+type MediaProcessingStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
+type MediaRetention = {
+  expiresAt: string | null;
+  daysRemaining: number | null;
+  locked: boolean;
+};
+type MediaFile = {
+  mediaId: string;
+  createdAt: string;
+  contentType: string;
+  filename: string | null;
+  sizeBytes: number | null;
+  durationSeconds: number | null;
+  processingStatus: MediaProcessingStatus;
+  lastUsedAt: string | null;
+  retention: MediaRetention;
+};
+type FileDeleteReceipt = {
+  mediaId: string;
+  deleted: true;
+};
+type RetentionLockResult = {
+  mediaId: string;
+  retentionLock: boolean;
+  message: string;
+};
+type CursorPaginationParams = {
+  limit?: number;
+  cursor?: string;
+};
+type OffsetPaginationParams = {
+  limit?: number;
+  offset?: number;
+};
+type CursorPage<T> = {
+  data: T[];
+  cursor?: string;
+  hasMore: boolean;
+};
+type OffsetPage<T> = {
+  data: T[];
+  pagination: {
+    limit: number;
+    offset: number;
+    total: number;
+  };
+};
+type CreditBalance = {
+  balance: number;
+  reserved: number;
+  available: number;
+};
+type CreditTransactionType = "PURCHASE" | "SUBSCRIPTION_GRANT" | "PROMO_GRANT" | "USAGE" | "REFUND" | "FEEDBACK_DISCOUNT" | "ADJUSTMENT" | "EXPIRATION";
+type CreditTransaction = {
+  id: string;
+  type: CreditTransactionType;
+  amount: number;
+  createdAt: string;
+  effectiveAt: string;
+  expiresAt: string | null;
+  jobId: string | null;
+  job?: {
+    id: string;
+    status: string;
+    createdAt: string;
+  };
+};
+type CreditUsage = {
+  jobId: string;
+  creditsUsed: number;
+  creditsDiscounted?: number;
+  creditsNetUsed: number;
+  durationMs?: number;
+  modelVersion?: string;
+};
+/**
+ * Options for long-polling job completion.
+ */
+type WaitOptions = {
+  /**
+   * Maximum time to wait before failing.
+   *
+   * @defaultValue 300000
+   */
+  timeoutMs?: number;
+  /**
+   * Initial polling interval.
+   *
+   * @defaultValue 1000
+   */
+  pollIntervalMs?: number;
+  /**
+   * Maximum polling interval used with exponential backoff.
+   *
+   * @defaultValue 10000
+   */
+  maxPollIntervalMs?: number;
+  /**
+   * Optional callback invoked on meaningful job state transitions.
+   */
+  onEvent?: (event: JobEvent) => void;
+  /**
+   * Abort signal used to cancel waiting.
+   */
+  signal?: AbortSignal;
+};
+type ReportRunHandle = {
+  jobId: string;
+  stream(opts?: {
+    signal?: AbortSignal;
+    onEvent?: (e: JobEvent) => void;
+  }): AsyncIterable<JobEvent>;
+  wait(opts?: WaitOptions): Promise<Report>;
+  cancel(): Promise<Job>;
+  job(): Promise<Job>;
+  report(): Promise<Report | null>;
+};
+/**
+ * Type guard for MarkdownReport.
+ */
+declare function isMarkdownReport(report: Report): report is MarkdownReport;
+/**
+ * Type guard for JsonReport.
+ */
+declare function isJsonReport(report: Report): report is JsonReport;
+/**
+ * Type guard for PdfReport.
+ */
+declare function isPdfReport(report: Report): report is PdfReport;
+/**
+ * Type guard for UrlReport.
+ */
+declare function isUrlReport(report: Report): report is UrlReport;
+type Entity = {
+  id: string;
+  tags: string[];
+  createdAt: string;
+  mediaCount: number;
+  lastSeenAt: string | null;
+};
+type EntityTagsResult = {
+  entityId: string;
+  tags: string[];
+};
+type ListEntitiesOptions = CursorPaginationParams & {
+  /**
+   * Filter entities by tags.
+   * Entities must have ALL specified tags (AND logic).
+   */
+  tags?: string[];
+};
+type ListEntitiesResponse = {
+  entities: Entity[];
+  cursor?: string;
+  hasMore: boolean;
+};
+/**
+ * Type guard to check if a report has entity information.
+ * Always returns true since entity is always present in reports.
+ */
+declare function hasEntity(report: Report): report is Report & {
+  entity: {
+    id: string;
+    tags: string[];
+  };
+};
+//#endregion
+//#region src/resources/credits.d.ts
+type ListTransactionsOptions = {
+  /** Max transactions per page (1-100, default 50) */
+  limit?: number;
+  /** Offset for pagination (default 0) */
+  offset?: number;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type ListTransactionsResponse = {
+  transactions: CreditTransaction[];
+  pagination: {
+    limit: number;
+    offset: number;
+    total: number;
+  };
+};
+/**
+ * Credits API resource.
+ *
+ * Provides methods to manage and query credit balances, transaction history,
+ * and job-specific credit usage.
+ */
+declare class CreditsResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  /**
+   * Get the current credit balance for your team.
+   *
+   * @example
+   * const balance = await mappa.credits.getBalance();
+   * console.log(`Available: ${balance.available} credits`);
+   */
+  getBalance(opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<CreditBalance>;
+  /**
+   * List credit transactions with offset pagination.
+   *
+   * @example
+   * const { transactions, pagination } = await mappa.credits.listTransactions({ limit: 25 });
+   * console.log(`Showing ${transactions.length} of ${pagination.total}`);
+   */
+  listTransactions(opts?: ListTransactionsOptions): Promise<ListTransactionsResponse>;
+  /**
+   * Iterate over all transactions, automatically handling pagination.
+   *
+   * @example
+   * for await (const tx of mappa.credits.listAllTransactions()) {
+   *   console.log(`${tx.type}: ${tx.amount}`);
+   * }
+   */
+  listAllTransactions(opts?: Omit<ListTransactionsOptions, "offset">): AsyncIterable<CreditTransaction>;
+  /**
+   * Get credit usage details for a completed job.
+   *
+   * @example
+   * const usage = await mappa.credits.getJobUsage("job_xyz");
+   * console.log(`Net credits used: ${usage.creditsNetUsed}`);
+   */
+  getJobUsage(jobId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<CreditUsage>;
+  /**
+   * Check if the team has enough available credits for an operation.
+   *
+   * @example
+   * if (await mappa.credits.hasEnough(100)) {
+   *   await mappa.reports.createJob(...);
+   * }
+   */
+  hasEnough(credits: number, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<boolean>;
+  /**
+   * Get the number of available credits (balance - reserved).
+   *
+   * @example
+   * const available = await mappa.credits.getAvailable();
+   * console.log(`You can spend ${available} credits`);
+   */
+  getAvailable(opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<number>;
+}
+//#endregion
+//#region src/resources/entities.d.ts
+/**
+ * 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.
+ */
+declare class EntitiesResource {
+  private readonly transport;
+  constructor(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"]
+   * ```
+   */
+  get(entityId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<Entity>;
+  /**
+   * 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
+   * });
+   * ```
+   */
+  list(opts?: ListEntitiesOptions & {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<ListEntitiesResponse>;
   /**
-   * Initializes the client with an API key sourced from arguments or the environment.
+   * 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(", ")}`);
+   * }
+   * ```
    */
-  constructor(apiKey?: string);
+  listAll(opts?: Omit<ListEntitiesOptions, "cursor"> & {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): AsyncIterable<Entity>;
   /**
-   * Generates a synchronous behavior profile report from either an uploaded media file or a remote media URL.
+   * 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");
+   * ```
    */
-  generateTextReport(body: MappaModel.GenerateReportInput): Promise<{
-    behaviorProfile: string;
-    entityId: string;
+  getByTag(tag: string, opts?: Omit<ListEntitiesOptions, "tags"> & {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<ListEntitiesResponse>;
+  /**
+   * 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"]);
+   * ```
+   */
+  addTags(entityId: string, tags: string[], opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<EntityTagsResult>;
+  /**
+   * 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"]);
+   * ```
+   */
+  removeTags(entityId: string, tags: string[], opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<EntityTagsResult>;
+  /**
+   * 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", []);
+   * ```
+   */
+  setTags(entityId: string, tags: string[], opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<EntityTagsResult>;
+}
+//#endregion
+//#region src/resources/feedback.d.ts
+type FeedbackCreateRequest = {
+  reportId?: string;
+  jobId?: string;
+  rating: "thumbs_up" | "thumbs_down" | "1" | "2" | "3" | "4" | "5";
+  tags?: string[];
+  comment?: string;
+  corrections?: Array<{
+    path: string;
+    expected?: unknown;
+    observed?: unknown;
+  }>;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+declare class FeedbackResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  /**
+   * Create feedback for a report or job. Provide exactly one of `reportId` or `jobId`.
+   */
+  create(req: FeedbackCreateRequest): Promise<FeedbackReceipt>;
+}
+//#endregion
+//#region src/resources/files.d.ts
+type UploadRequest = {
+  file: Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
+  /**
+   * Optional override.
+   * If omitted, the SDK will try to infer it from `file.type` (Blob) and then from `filename`.
+   */
+  contentType?: string;
+  filename?: string;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type ListFilesOptions = {
+  /** Max files per page (1-100, default 20) */
+  limit?: number;
+  /** Pagination cursor from previous response */
+  cursor?: string;
+  /** Include soft-deleted files (default false) */
+  includeDeleted?: boolean;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type ListFilesResponse = {
+  files: MediaFile[];
+  cursor?: string;
+  hasMore: boolean;
+};
+/**
+ * Uses multipart/form-data for uploads.
+ *
+ * If you need resumable uploads, add a dedicated resumable protocol.
+ */
+declare class FilesResource {
+  private readonly transport;
+  constructor(transport: Transport);
+  upload(req: UploadRequest): Promise<MediaObject>;
+  /**
+   * Retrieve metadata for a single uploaded file.
+   *
+   * @example
+   * const file = await mappa.files.get("media_abc123");
+   * console.log(file.processingStatus); // "COMPLETED"
+   */
+  get(mediaId: string, opts?: {
+    requestId?: string;
+    signal?: AbortSignal;
+  }): Promise<MediaFile>;
+  /**
+   * 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 });
+   * }
+   */
+  list(opts?: ListFilesOptions): Promise<ListFilesResponse>;
+  /**
+   * 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);
+   * }
+   */
+  listAll(opts?: Omit<ListFilesOptions, "cursor">): AsyncIterable<MediaFile>;
+  /**
+   * 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);
+   */
+  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>;
+  /**
+   * Public stream API.
+   * If you add SSE later, keep this signature and switch implementation internally.
+   * For now, it yields events based on polling. Use `AbortSignal` to cancel streaming.
+   */
+  stream(jobId: string, opts?: {
+    signal?: AbortSignal;
+    onEvent?: (e: JobEvent) => void;
+  }): AsyncIterable<JobEvent>;
+}
+//#endregion
+//#region src/resources/reports.d.ts
+/**
+ * Request shape for {@link ReportsResource.createJobFromFile}.
+ *
+ * This helper performs two API calls as one logical operation:
+ * 1) Upload bytes via `files.upload()` (multipart)
+ * 2) Create a report job via {@link ReportsResource.createJob} using the returned `{ mediaId }`
+ *
+ * Differences vs {@link ReportCreateJobRequest}:
+ * - `media` is derived from the upload result and therefore omitted.
+ * - `idempotencyKey` applies to the *whole* upload + create-job sequence.
+ * - `requestId` is forwarded to both requests for end-to-end correlation.
+ *
+ * Abort behavior:
+ * - `signal` (from {@link UploadRequest}) is applied to the upload request.
+ *   Job creation only runs after a successful upload.
+ */
+type ReportCreateJobFromFileRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & Omit<UploadRequest, "filename"> & {
+  /**
+   * Optional filename to attach to the upload.
+   *
+   * When omitted, the upload layer may infer it (e.g. from a `File` object).
+   */
+  filename?: string;
+  /**
+   * Idempotency for the upload + job creation sequence.
+   */
+  idempotencyKey?: string;
+  /**
+   * Optional request correlation ID forwarded to both the upload and the job creation call.
+   */
+  requestId?: string;
+};
+/**
+ * Request shape for {@link ReportsResource.createJobFromUrl}.
+ *
+ * This helper performs two API calls as one logical operation:
+ * 1) Download bytes from a remote URL using `fetch()`
+ * 2) Upload bytes via `files.upload()` and then create a report job via {@link ReportsResource.createJob}
+ *
+ * Differences vs {@link ReportCreateJobRequest}:
+ * - `media` is derived from the upload result and therefore omitted.
+ * - `idempotencyKey` applies to the *whole* download + upload + create-job sequence.
+ * - `requestId` is forwarded to both upload and job creation calls.
+ */
+type ReportCreateJobFromUrlRequest = Omit<ReportCreateJobRequest, "media" | "idempotencyKey" | "requestId"> & {
+  url: string;
+  contentType?: string;
+  filename?: string;
+  idempotencyKey?: string;
+  requestId?: string;
+  signal?: AbortSignal;
+};
+/**
+ * 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.
+ */
+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<MediaObject>;
+  }, fetchImpl: typeof fetch);
+  /**
+   * Create a new report job.
+   *
+   * Behavior:
+   * - Validates {@link MediaIdRef} at runtime (must provide `{ mediaId }`).
+   * - 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
+   */
+  createJob(req: ReportCreateJobRequest): Promise<ReportJobReceipt>;
+  /**
+   * 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.
+   */
+  createJobFromFile(req: ReportCreateJobFromFileRequest): Promise<ReportJobReceipt>;
+  /**
+   * 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).
+   */
+  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>;
+  /**
+   * Convenience wrapper: createJob + wait + get
+   * Use for scripts; for production prefer createJob + webhooks/stream.
+   */
+  generate(req: ReportCreateJobRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<Report>;
+  /**
+   * Convenience wrapper: createJobFromFile + wait + get.
+   * Use for scripts; for production prefer createJobFromFile + webhooks/stream.
+   */
+  generateFromFile(req: ReportCreateJobFromFileRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<Report>;
+  /**
+   * Convenience wrapper: createJobFromUrl + wait + get.
+   * Use for scripts; for production prefer createJobFromUrl + webhooks/stream.
+   */
+  generateFromUrl(req: ReportCreateJobFromUrlRequest, opts?: {
+    wait?: WaitOptions;
+  }): Promise<Report>;
+  makeHandle(jobId: string): ReportRunHandle;
+  private defaultIdempotencyKey;
+  private normalizeJobRequest;
+}
+//#endregion
+//#region src/resources/webhooks.d.ts
+/**
+ * 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}`
+ */
+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): {
+    id: string;
+    type: string;
+    createdAt: string;
+    data: T;
+  };
+}
+//#endregion
+//#region src/Mappa.d.ts
+/**
+ * Options for constructing a {@link Mappa} client.
+ */
+type MappaClientOptions = {
+  /**
+   * API key used for authenticating requests.
+   */
+  apiKey: string;
+  /**
+   * Base URL for the Mappa API.
+   *
+   * @defaultValue "https://api.mappa.ai"
+   */
+  baseUrl?: string;
+  /**
+   * Per-request timeout, in milliseconds.
+   *
+   * Note: this timeout applies to individual HTTP attempts (including retries).
+   * Long-running workflows should use {@link JobsResource.wait} through
+   * {@link ReportsResource.makeHandle} instead.
+   *
+   * @defaultValue 30000
+   */
+  timeoutMs?: number;
+  /**
+   * Maximum number of retries performed by the transport for retryable requests.
+   *
+   * @defaultValue 2
+   */
+  maxRetries?: number;
+  /**
+   * Headers that will be sent with every request.
+   */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Custom fetch implementation (useful for polyfills, instrumentation, or tests).
+   */
+  fetch?: typeof fetch;
+  /**
+   * Overrides the User-Agent header.
+   */
+  userAgent?: string;
+  /**
+   * Telemetry hooks called on request/response/error.
+   */
+  telemetry?: Telemetry;
+};
+/**
+ * Main SDK client.
+ *
+ * Exposes resource namespaces ({@link Mappa.files}, {@link Mappa.reports}, etc.)
+ * and configures a shared HTTP transport.
+ */
+declare class Mappa {
+  readonly files: FilesResource;
+  readonly jobs: JobsResource;
+  readonly reports: ReportsResource;
+  readonly feedback: FeedbackResource;
+  readonly credits: CreditsResource;
+  readonly entities: EntitiesResource;
+  readonly webhooks: WebhooksResource;
+  readonly health: HealthResource;
+  private readonly transport;
+  private readonly opts;
+  constructor(options: MappaClientOptions);
+  withOptions(overrides: Partial<MappaClientOptions>): Mappa;
+  close(): void;
 }
 //#endregion
-export { Mappa };
+//#region src/index.d.ts
+/**
+ * Type guard for catching SDK errors.
+ */
+declare function isMappaError(err: unknown): err is MappaError;
+//#endregion
+export { ApiError, AuthError, CreditBalance, CreditTransaction, CreditTransactionType, CreditUsage, CursorPage, CursorPaginationParams, Entity, EntityTagsResult, FeedbackReceipt, FileDeleteReceipt, Job, JobCanceledError, JobCreditReservation, JobEvent, JobFailedError, JobStage, JobStatus, JsonReport, JsonValue, ListEntitiesOptions, ListEntitiesResponse, Mappa, MappaError, MarkdownReport, MediaFile, MediaIdRef, MediaObject, MediaProcessingStatus, MediaRef, MediaRetention, OffsetPage, OffsetPaginationParams, PdfReport, RateLimitError, Report, ReportBase, ReportCreateJobRequest, ReportJobReceipt, ReportOutput, ReportOutputType, ReportRunHandle, ReportTemplateId, ReportTemplateParamsMap, RetentionLockResult, Subject, TargetDominant, TargetEntityId, TargetFor, TargetMagicHint, TargetOnMiss, TargetSelector, TargetStrategy, TargetStrategyMap, TargetTimeRange, TargetTimeRangeStrategy, UrlReport, Usage, ValidationError, WaitOptions, WebhookConfig, hasEntity, isJsonReport, isMappaError, isMarkdownReport, isPdfReport, isUrlReport };