@reqvet-sdk/sdk 2.2.0

package/src/index.d.ts

@@ -0,0 +1,261 @@
+// @reqvet/sdk — Type definitions
+
+export interface ReqVetOptions {
+  baseUrl?: string;
+  pollInterval?: number;
+  timeout?: number;
+}
+
+export interface UploadResult {
+  /** Canonical path to the uploaded audio in ReqVet storage */
+  audio_file: string;
+  /** Alias for audio_file (for DX / backward compatibility) */
+  path: string;
+  size_bytes: number;
+  content_type: string;
+}
+
+export interface JobResult {
+  job_id: string;
+  status: 'pending' | 'transcribing' | 'generating' | 'completed' | 'failed' | 'amending';
+}
+
+// ─── Field Extraction Types ─────────────────────────────────
+
+/** Supported field types for structured extraction */
+export type FieldType = 'string' | 'text' | 'number' | 'boolean' | 'array' | 'html';
+
+/** A single field definition in an organization's field_schema */
+export interface FieldDefinition {
+  /** Unique key in snake_case (e.g. "espece", "poids", "traitements") */
+  key: string;
+  /** Human-readable label (e.g. "Espèce", "Poids (kg)") */
+  label: string;
+  /** Data type for this field */
+  type: FieldType;
+}
+
+/**
+ * Extracted fields from a generation.
+ * Keys match the field_schema definitions on the organization.
+ * Values are typed according to the field type, or null if not mentioned.
+ */
+export type ExtractedFields = Record<string, string | number | boolean | string[] | null>;
+
+// ─── Report & Job Types ─────────────────────────────────────
+
+export interface ReqVetReport {
+  jobId: string;
+  html: string;
+  /** Structured fields extracted from the transcription (null if org has no field_schema) */
+  fields: ExtractedFields | null;
+  transcription: string;
+  animalName: string;
+  cost: {
+    transcription_usd: number;
+    generation_usd: number;
+    total_usd: number;
+  };
+  metadata: Record<string, unknown>;
+}
+
+export interface Template {
+  id: string;
+  org_id: string | null;
+  name: string;
+  description: string;
+  content: string;
+  is_default: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+// ─── Params ──────────────────────────────────────────────────
+
+export interface GenerateReportParams {
+  audio: Blob | Buffer | File;
+  animalName: string;
+  templateId: string;
+  fileName?: string;
+  /**
+   * Optional webhook URL.
+   * If provided, ReqVet will POST the final result to this endpoint when ready.
+   */
+  callbackUrl?: string;
+  metadata?: Record<string, unknown>;
+  /** Optional: extra instructions injected into the generation prompt (kept separate from metadata) */
+  extraInstructions?: string;
+  /**
+   * When true, generateReport() will poll until completion and return the final report.
+   * When false (default), it returns immediately after creating the job.
+   */
+  waitForResult?: boolean;
+  /** Called on each poll with current status (only when waitForResult=true). */
+  onStatus?: (status: string) => void;
+}
+
+export interface CreateJobParams {
+  audioFile: string;
+  animalName: string;
+  templateId: string;
+  /** Optional webhook URL (falls back to the org default webhook_url server-side if omitted). */
+  callbackUrl?: string;
+  metadata?: Record<string, unknown>;
+  extraInstructions?: string; // 👈 add
+}
+
+export interface CreateTemplateParams {
+  name: string;
+  content: string;
+  description?: string;
+  is_default?: boolean;
+}
+
+export interface ListJobsOptions {
+  limit?: number;
+  offset?: number;
+  status?: 'pending' | 'transcribing' | 'generating' | 'completed' | 'failed' | 'amending';
+  sort?: 'created_at' | 'updated_at';
+  order?: 'asc' | 'desc';
+}
+
+export interface JobSummary {
+  id: string;
+  status: 'pending' | 'transcribing' | 'generating' | 'completed' | 'failed' | 'amending';
+  animal_name: string;
+  template_id: string;
+  metadata: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+  error_message?: string | null;
+}
+
+export interface ListJobsResult {
+  jobs: JobSummary[];
+  pagination: {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+  };
+}
+
+export interface RegenerateOptions {
+  extraInstructions?: string;
+  templateId?: string;
+}
+
+export interface RegenerateResult {
+  job_id: string;
+  status: string;
+  result: {
+    html: string;
+    fields?: ExtractedFields;
+  };
+}
+
+export type ReformulationPurpose =
+  | 'owner'
+  | 'referral'
+  | 'summary'
+  | 'custom'
+  | 'diagnostic_hypothesis';
+
+export interface ReformulateParams {
+  purpose: ReformulationPurpose;
+  customInstructions?: string;
+}
+
+export interface ReqVetReformulation {
+  id: string;
+  job_id: string;
+  purpose: ReformulationPurpose;
+  html: string;
+  custom_instructions?: string;
+  cost: {
+    model: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    cost_usd: number;
+  };
+  created_at: string;
+}
+
+// ─── Client ──────────────────────────────────────────────────
+
+export declare class ReqVetError extends Error {
+  status: number;
+  body: unknown;
+  constructor(message: string, status: number, body: unknown);
+}
+
+export declare class ReqVet {
+  constructor(apiKey: string, options?: ReqVetOptions);
+
+  /**
+   * Convenience helper.
+   * - Default: upload → create job → return {job_id, status}
+   * - If waitForResult=true: upload → create job → poll → return final report
+   */
+  generateReport(params: GenerateReportParams & { waitForResult: true }): Promise<ReqVetReport>;
+  generateReport(params: GenerateReportParams & { waitForResult?: false }): Promise<JobResult>;
+  generateReport(params: GenerateReportParams): Promise<JobResult | ReqVetReport>;
+
+  /** Upload an audio file */
+  uploadAudio(audio: Blob | Buffer | File, fileName?: string): Promise<UploadResult>;
+
+  /** Create a generation job */
+  createJob(params: CreateJobParams): Promise<JobResult>;
+
+  /** List jobs with optional pagination and filtering */
+  listJobs(options?: ListJobsOptions): Promise<ListJobsResult>;
+
+  /** Get job status */
+  getJob(jobId: string): Promise<Record<string, unknown>>;
+
+  /** Wait for a job to finish */
+  waitForJob(jobId: string, onStatus?: (status: string) => void): Promise<ReqVetReport>;
+
+  /** Regenerate a completed report */
+  regenerateJob(jobId: string, options?: RegenerateOptions): Promise<RegenerateResult>;
+
+  /** Add an audio complement to a completed job */
+  amendJob(
+    jobId: string,
+    params: { audioFile: string; templateId?: string },
+  ): Promise<{
+    job_id: string;
+    status: 'amending';
+    amendment_number: number;
+    message: string;
+  }>;
+
+  /** Reformulate a completed report for a specific audience */
+  reformulateReport(jobId: string, params: ReformulateParams): Promise<ReqVetReformulation>;
+
+  /** List all reformulations for a job */
+  listReformulations(jobId: string): Promise<{ reformulations: ReqVetReformulation[] }>;
+
+  /** List templates */
+  listTemplates(): Promise<{ custom: Template[]; system: Template[] }>;
+
+  /** Get a template */
+  getTemplate(templateId: string): Promise<Template>;
+
+  /** Create a template */
+  createTemplate(params: CreateTemplateParams): Promise<Template>;
+
+  /** Update a template */
+  updateTemplate(
+    templateId: string,
+    updates: Partial<Pick<CreateTemplateParams, 'name' | 'content' | 'description' | 'is_default'>>,
+  ): Promise<Template>;
+
+  /** Delete a template */
+  deleteTemplate(templateId: string): Promise<{ success: boolean }>;
+
+  /** Health check */
+  health(): Promise<{ status: string; services: Record<string, string> }>;
+}
+
+export default ReqVet;

package/src/index.js

@@ -0,0 +1,444 @@
+// @reqvet/sdk — Official JavaScript SDK
+// Zero dependencies. Works in Node.js 18+ and modern browsers.
+
+class ReqVetError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'ReqVetError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function mimeFromFileName(fileName) {
+  const name = (fileName || '').toLowerCase();
+  const ext = name.split('.').pop();
+  switch (ext) {
+    case 'mp3':
+      return 'audio/mpeg';
+    case 'wav':
+      return 'audio/wav';
+    case 'webm':
+      return 'audio/webm';
+    case 'ogg':
+      return 'audio/ogg';
+    case 'm4a':
+      return 'audio/mp4';
+    case 'aac':
+      return 'audio/aac';
+    case 'flac':
+      return 'audio/flac';
+    default:
+      return '';
+  }
+}
+
+class ReqVet {
+  /**
+   * Create a ReqVet client.
+   *
+   * @param {string} apiKey - Your API key (rqv_live_...)
+   * @param {Object} [options]
+   * @param {string} [options.baseUrl] - API base URL (default: https://api.reqvet.com)
+   * @param {number} [options.pollInterval] - Polling interval in ms (default: 5000)
+   * @param {number} [options.timeout] - Max wait time in ms (default: 300000 = 5 min)
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey?.startsWith('rqv_')) {
+      throw new Error('Invalid API key. Must start with "rqv_".');
+    }
+
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || 'https://api.reqvet.com').replace(/\/$/, '');
+    this.pollInterval = options.pollInterval || 5000;
+    this.timeout = options.timeout || 300_000;
+  }
+
+  // ─── Core: Generate a report (upload + job + poll) ─────────
+
+  /**
+   * Generate a veterinary report from an audio file.
+   * Handles the full flow: upload → create job → wait for result.
+   *
+   * @param {Object} params
+   * @param {Blob|Buffer|File} params.audio - Audio file
+   * @param {string} params.animalName - Name of the animal
+   * @param {string} params.templateId - Template UUID
+   * @param {string} [params.fileName] - File name (default: audio.webm)
+   * @param {string} [params.callbackUrl] - Webhook URL for result
+   * @param {Object} [params.metadata] - Custom data passed through
+   * @param {Function} [params.onStatus] - Called on each poll with current status
+   * @returns {Promise<ReqVetReport>}
+   */
+  async generateReport({
+    audio,
+    animalName,
+    templateId,
+    fileName,
+    callbackUrl,
+    metadata,
+    extraInstructions,
+    onStatus,
+    waitForResult = false,
+  }) {
+    // Convenience helper.
+    // - Default: webhook-first (returns immediately after job creation). If callbackUrl is provided,
+    //   ReqVet will POST the final result to that URL when ready.
+    // - Optional: polling mode (waitForResult=true) which returns the final report.
+
+    // Step 1: Upload
+    const upload = await this.uploadAudio(audio, fileName);
+
+    // Step 2: Create job (pipeline starts server-side)
+    const job = await this.createJob({
+      audioFile: upload.audio_file,
+      animalName,
+      templateId,
+      callbackUrl,
+      metadata, // 👈 ne touche pas metadata
+      extraInstructions, // 👈 passe le param séparé
+    });
+
+    // Step 3: Either return immediately, or poll until completion.
+    if (waitForResult) {
+      return this.waitForJob(job.job_id, onStatus);
+    }
+    return job;
+  }
+
+  // ─── Upload ────────────────────────────────────────────────
+
+  /**
+   * Upload an audio file to ReqVet storage.
+   *
+   * @param {Blob|Buffer|File} audio - The audio file
+   * @param {string} [fileName] - File name
+   * @returns {Promise<{audio_file: string, size_bytes: number}>}
+   */
+  async uploadAudio(audio, fileName) {
+    const form = new FormData();
+
+    if (typeof Blob !== 'undefined' && audio instanceof Blob) {
+      form.append('file', audio, fileName || 'audio.webm');
+    } else if (Buffer.isBuffer(audio)) {
+      // Node.js Buffer → Blob
+      const finalName = fileName || 'audio.webm';
+      const mime = mimeFromFileName(finalName);
+      const blob = mime ? new Blob([audio], { type: mime }) : new Blob([audio]);
+      form.append('file', blob, finalName);
+    } else {
+      throw new ReqVetError('audio must be a Blob, File, or Buffer', 0, null);
+    }
+
+    const res = await this._fetch('POST', '/api/v1/upload', null, form);
+    // DX: provide a stable alias `path` for consumers.
+    if (res && typeof res === 'object' && res.audio_file && !res.path) {
+      return { ...res, path: res.audio_file };
+    }
+    return res;
+  }
+
+  // ─── Jobs ──────────────────────────────────────────────────
+
+  /**
+   * Create a new CR generation job.
+   *
+   * @param {Object} params
+   * @param {string} params.audioFile - Path from upload
+   * @param {string} params.animalName
+   * @param {string} params.templateId
+   * @param {string} [params.callbackUrl]
+   * @param {Object} [params.metadata]
+   * @returns {Promise<{job_id: string, status: string}>}
+   */
+  async createJob({ audioFile, animalName, templateId, callbackUrl, metadata, extraInstructions }) {
+    return this._fetch('POST', '/api/v1/jobs', {
+      audio_file: audioFile,
+      animal_name: animalName,
+      template_id: templateId,
+      callback_url: callbackUrl,
+      metadata,
+      extra_instructions: extraInstructions,
+    });
+  }
+
+  /**
+   * Get the status and result of a job.
+   *
+   * @param {string} jobId
+   * @returns {Promise<ReqVetJob>}
+   */
+  async getJob(jobId) {
+    return this._fetch('GET', `/api/v1/jobs/${jobId}`);
+  }
+
+  /**
+   * List jobs with optional pagination and filtering.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.limit] - Number of jobs to return (1-100, default 20)
+   * @param {number} [options.offset] - Pagination offset (default 0)
+   * @param {string} [options.status] - Filter by status (pending|transcribing|generating|completed|failed|amending)
+   * @param {string} [options.sort] - Sort field: 'created_at' (default) or 'updated_at'
+   * @param {string} [options.order] - Sort direction: 'desc' (default) or 'asc'
+   * @returns {Promise<{jobs: Object[], pagination: {total: number, limit: number, offset: number, has_more: boolean}}>}
+   */
+  async listJobs({ limit, offset, status, sort, order } = {}) {
+    const params = new URLSearchParams();
+    if (limit != null) params.set('limit', String(limit));
+    if (offset != null) params.set('offset', String(offset));
+    if (status != null) params.set('status', status);
+    if (sort != null) params.set('sort', sort);
+    if (order != null) params.set('order', order);
+    const qs = params.toString();
+    return this._fetch('GET', `/api/v1/jobs${qs ? `?${qs}` : ''}`);
+  }
+
+  /**
+   * Wait for a job to complete by polling.
+   *
+   * @param {string} jobId
+   * @param {Function} [onStatus] - Called on each poll
+   * @returns {Promise<ReqVetReport>}
+   */
+  async waitForJob(jobId, onStatus) {
+    const deadline = Date.now() + this.timeout;
+
+    while (Date.now() < deadline) {
+      await this._sleep(this.pollInterval);
+
+      const job = await this.getJob(jobId);
+
+      if (onStatus) onStatus(job.status);
+
+      if (job.status === 'completed') {
+        return {
+          jobId: job.job_id,
+          html: job.result?.html || '',
+          fields: job.result?.fields || null,
+          transcription: job.transcription || '',
+          animalName: job.animal_name,
+          cost: job.cost || {},
+          metadata: job.metadata || {},
+        };
+      }
+
+      if (job.status === 'failed') {
+        throw new ReqVetError(`Job failed: ${job.error || 'Unknown error'}`, 0, job);
+      }
+    }
+
+    throw new ReqVetError('Timeout waiting for job to complete', 0, { jobId });
+  }
+
+  /**
+   * Regenerate a completed report with new instructions.
+   *
+   * @param {string} jobId
+   * @param {Object} [options]
+   * @param {string} [options.extraInstructions]
+   * @param {string} [options.templateId]
+   * @returns {Promise<{job_id: string, html: string}>}
+   */
+  async regenerateJob(jobId, options = {}) {
+    return this._fetch('POST', `/api/v1/jobs/${jobId}/regenerate`, {
+      extra_instructions: options.extraInstructions,
+      template_id: options.templateId,
+    });
+  }
+
+  // ─── Amendments (audio complements) ────────────────────────
+
+  /**
+   * Add an audio complement to a completed job.
+   *
+   * The new audio is transcribed and merged with the existing
+   * transcription(s). The CR is then regenerated with the full context.
+   * Supports multiple amendments — each one appends.
+   *
+   * @param {string} jobId - The completed job ID
+   * @param {Object} params
+   * @param {string} params.audioFile - Path from signed upload
+   * @param {string} [params.templateId] - Optional: switch to a different template
+   * @returns {Promise<{job_id: string, status: string, amendment_number: number}>}
+   *
+   * @example
+   * // Upload the complement audio first
+   * const { audio_file } = await reqvet.uploadAudio(newAudioBlob, 'complement.webm');
+   *
+   * // Submit the amendment
+   * const amend = await reqvet.amendJob(jobId, { audioFile: audio_file });
+   * // amend.status === 'amending'
+   *
+   * // Poll for completion (same as initial job)
+   * const updated = await reqvet.waitForJob(jobId);
+   * // updated.html now includes the complement info
+   */
+  async amendJob(jobId, { audioFile, templateId } = {}) {
+    if (!audioFile) throw new Error('audioFile is required for amendJob');
+    return this._fetch('POST', `/api/v1/jobs/${jobId}/amend`, {
+      audio_file: audioFile,
+      template_id: templateId,
+    });
+  }
+
+  // ─── Reformulations ─────────────────────────────────────────
+
+  /**
+   * Generate a reformulation of a completed report.
+   *
+   * Produces an alternative version of the CR adapted to a specific audience.
+   *
+   * @param {string} jobId - The completed job ID
+   * @param {Object} params
+   * @param {string} params.purpose - 'owner' | 'referral' | 'summary' | 'custom'
+   * @param {string} [params.customInstructions] - Required when purpose is 'custom'
+   * @returns {Promise<ReqVetReformulation>}
+   *
+   * @example
+   * // Simplified version for the pet owner
+   * const ownerVersion = await reqvet.reformulateReport(jobId, { purpose: 'owner' });
+   *
+   * // Clinical summary for specialist referral
+   * const referral = await reqvet.reformulateReport(jobId, { purpose: 'referral' });
+   *
+   * // Short internal summary
+   * const summary = await reqvet.reformulateReport(jobId, { purpose: 'summary' });
+   *
+   * // Custom reformulation
+   * const custom = await reqvet.reformulateReport(jobId, {
+   *   purpose: 'custom',
+   *   customInstructions: 'Reformule en insistant sur le pronostic et le suivi nutritionnel',
+   * });
+   */
+  async reformulateReport(jobId, { purpose, customInstructions } = {}) {
+    if (!purpose) {
+      throw new ReqVetError(
+        'purpose is required. Must be one of: owner, referral, summary, custom, diagnostic_hypothesis',
+        0,
+        null,
+      );
+    }
+    return this._fetch('POST', `/api/v1/jobs/${jobId}/reformulate`, {
+      purpose,
+      custom_instructions: customInstructions,
+    });
+  }
+
+  /**
+   * List all reformulations for a completed job.
+   *
+   * @param {string} jobId
+   * @returns {Promise<{reformulations: ReqVetReformulation[]}>}
+   */
+  async listReformulations(jobId) {
+    return this._fetch('GET', `/api/v1/jobs/${jobId}/reformulate`);
+  }
+
+  // ─── Templates ─────────────────────────────────────────────
+
+  /**
+   * List all accessible templates.
+   * @returns {Promise<{custom: Template[], system: Template[]}>}
+   */
+  async listTemplates() {
+    return this._fetch('GET', '/api/v1/templates');
+  }
+
+  /**
+   * Get a template by ID.
+   * @param {string} templateId
+   */
+  async getTemplate(templateId) {
+    return this._fetch('GET', `/api/v1/templates/${templateId}`);
+  }
+
+  /**
+   * Create a new template.
+   * @param {Object} params
+   * @param {string} params.name
+   * @param {string} params.content - The prompt instructions
+   * @param {string} [params.description]
+   */
+  async createTemplate({ name, content, description }) {
+    return this._fetch('POST', '/api/v1/templates', {
+      name,
+      content,
+      description,
+    });
+  }
+
+  /**
+   * Update a template.
+   * @param {string} templateId
+   * @param {Object} updates
+   * @param {string} [updates.name]
+   * @param {string} [updates.content]
+   * @param {string} [updates.description]
+   */
+  async updateTemplate(templateId, updates) {
+    return this._fetch('PUT', `/api/v1/templates/${templateId}`, updates);
+  }
+
+  /**
+   * Delete a template.
+   * @param {string} templateId
+   */
+  async deleteTemplate(templateId) {
+    return this._fetch('DELETE', `/api/v1/templates/${templateId}`);
+  }
+
+  // ─── Health ────────────────────────────────────────────────
+
+  /**
+   * Check API health.
+   * @returns {Promise<{status: string, services: Object}>}
+   */
+  async health() {
+    return this._fetch('GET', '/api/v1/health');
+  }
+
+  // ─── Internal ──────────────────────────────────────────────
+
+  async _fetch(method, path, body, formData) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = { Authorization: `Bearer ${this.apiKey}` };
+    const opts = { method, headers };
+
+    const isRealFormData =
+      typeof FormData !== 'undefined' && formData && formData instanceof FormData;
+
+    if (isRealFormData) {
+      opts.body = formData;
+    } else if (body) {
+      headers['Content-Type'] = 'application/json';
+      // Strip null/undefined values to keep payloads clean
+      const cleaned = Object.fromEntries(
+        Object.entries(body).filter(([, v]) => v !== null && v !== undefined),
+      );
+      opts.body = JSON.stringify(cleaned);
+    }
+
+    const response = await fetch(url, opts);
+
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      throw new ReqVetError(`Non-JSON response from ${path}`, response.status, null);
+    }
+
+    if (!response.ok) {
+      throw new ReqVetError(data?.error || `HTTP ${response.status}`, response.status, data);
+    }
+
+    return data;
+  }
+
+  _sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+  }
+}
+
+export { ReqVet, ReqVetError };
+export default ReqVet;