Ocriva Logo

Documents

TypeScript

Import and use the full type definitions exported from @ocriva/sdk for a strongly-typed development experience.

sdktypescripttypesgenerics

Published: 4/1/2026

TypeScript

@ocriva/sdk is written in TypeScript and ships its own type declarations. No separate @types/ package is needed. All public types are exported from the package root so you can import them directly alongside the client.

Type Imports

import {
  OcrivaClient,
  // Error classes
  OcrivaError,
  ApiError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  // Types
  type OcrivaClientConfig,
  type PaginationParams,
  type PaginatedResponse,
  type FileType,
  type UploadFileParams,
  type UploadResponse,
  type ResultFormat,
  type ExtractionMode,
  type TemplateDataFile,
  type Template,
  type CreateTemplateParams,
  type UpdateTemplateParams,
  type ListTemplatesParams,
  type Project,
  type ListProjectsParams,
  type ProcessingStatus,
  type ProcessingPriority,
  type ProcessingHistory,
  type ListProcessingHistoryParams,
  type ProcessingHistoryStats,
  type ExportResultParams,
  type BatchStatus,
  type Batch,
  type BatchUploadParams,
  type ListBatchParams,
  type ExportBatchParams,
} from '@ocriva/sdk';

Import only what you need. The type keyword ensures type-only imports are erased at compile time and do not affect your bundle.

Key Types Reference

Configuration

OcrivaClientConfig

Options passed to the OcrivaClient constructor.

interface OcrivaClientConfig {
  apiKey: string;         // required
  baseUrl?: string;       // default: 'https://api.ocriva.com/v1'
  timeout?: number;       // default: 30000 (ms)
  maxRetries?: number;    // default: 3
}

Pagination

PaginationParams

Common query parameters accepted by list methods.

interface PaginationParams {
  page?: number;   // 1-based page number
  limit?: number;  // items per page
}

PaginatedResponse

Wrapper returned by methods that return paginated lists.

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    pages: number;
  };
}

Upload

FileType

Broad category for the uploaded file.

type FileType = 'pdf' | 'image' | 'document';

UploadFileParams

Parameters for client.upload.file().

interface UploadFileParams {
  fileName: string;
  fileType: FileType;
  fileSize: string;          // bytes as a string
  mimeType: string;
  projectId: string;
  templateId?: string;
  uploadType?: string;
  metadata?: Record<string, unknown>;
  batchId?: string;
}

UploadResponse

Return value of client.upload.file().

interface UploadResponse {
  id: string;
  fileName: string;
  fileUrl: string;
  publicUrl: string;
  filePath: string;
  fileSize: string;
  mimeType: string;
  status: 'uploaded' | 'processing' | 'completed' | 'failed';
  templateId?: string;
  projectId: string;
  uploadedAt: string;
  userId: string;
  organizationId?: string;
  bucketName?: string;
}

Templates

ResultFormat

Output format a template can produce.

type ResultFormat = 'json' | 'text' | 'xml' | 'html' | 'csv' | 'pdf' | 'docx' | 'image';

ExtractionMode

Extraction strategy used when resultFormat is 'text'.

type ExtractionMode = 'structured' | 'freeText';

Template

A template record as returned by the API.

interface Template {
  templateId: string;
  name: string;
  description?: string;
  templateSchema?: Record<string, unknown>;
  projectId: string;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
  resultFormat?: ResultFormat;
  extractionMode?: ExtractionMode;
  instructions?: string;
}

CreateTemplateParams / UpdateTemplateParams

interface CreateTemplateParams {
  name: string;
  description: string;
  templateSchema: Record<string, unknown>;
  projectId: string;
  instructions?: string;
}
 
interface UpdateTemplateParams {
  projectId: string;  // required for scoping
  name?: string;
  description?: string;
  templateSchema?: Record<string, unknown>;
  instructions?: string;
}

Projects

Project

interface Project {
  id: string;
  name: string;
  description?: string;
  organizationId: string;
  isActive: boolean;
  createdAt: string;
  updatedAt: string;
}

Processing History

ProcessingStatus

All possible status values for a processing record.

type ProcessingStatus = 'pending' | 'queued' | 'in_progress' | 'completed' | 'failed';

ProcessingPriority

type ProcessingPriority = 'low' | 'medium' | 'high';

ProcessingHistory

A full processing history record.

interface ProcessingHistory {
  id: string;
  uploadId: string;
  projectId: string;
  userId: string;
  fileName: string;
  fileUrl: string;
  filePath: string;
  fileSize: string;
  mimeType: string;
  status: ProcessingStatus;
  templateId?: string;
  templateName?: string;
  resultFormat?: ResultFormat;
  priority: ProcessingPriority;
  processingResult?: Record<string, unknown>;
  errorMessage?: string;
  startedAt?: string;
  completedAt?: string;
  estimatedCompletionTime?: string;
  createdAt: string;
  updatedAt: string;
  metadata?: Record<string, unknown>;
  batchId?: string;
}

ProcessingHistoryStats

interface ProcessingHistoryStats {
  total: number;
  pending: number;
  processing: number;
  completed: number;
  failed: number;
}

Batch

BatchStatus

type BatchStatus = 'uploading' | 'processing' | 'completed' | 'partially_failed' | 'failed';

Batch

interface Batch {
  id: string;
  name: string;
  projectId: string;
  organizationId: string;
  userId: string;
  templateId?: string;
  templateName?: string;
  totalFiles: number;
  completedFiles: number;
  failedFiles: number;
  status: BatchStatus;
  uploadIds: string[];
  processingHistoryIds: string[];
  progress: number;   // 0–100
  metadata?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

BatchUploadParams

interface BatchUploadParams {
  projectId: string;
  templateId?: string;
  name?: string;
  metadata?: Record<string, unknown>;
}

Generics

PaginatedResponse<T> is a generic wrapper. You can annotate variables explicitly or let TypeScript infer the type from the method return:

import type { PaginatedResponse, ProcessingHistory, Batch } from '@ocriva/sdk';
 
// Inferred — TypeScript knows this is PaginatedResponse<ProcessingHistory>
const historyPage = await client.processingHistory.list({
  projectId: 'proj_abc123',
});
 
// Explicit annotation (useful when storing the result for later)
let batchPage: PaginatedResponse<Batch>;
batchPage = await client.batch.list({ projectId: 'proj_abc123' });
 
// Access the generic T[] array
const batches: Batch[] = batchPage.data;
console.log(`Total: ${batchPage.pagination.total}`);

Type Narrowing

ProcessingStatus is a union type, which lets TypeScript enforce exhaustive checks:

import type { ProcessingStatus } from '@ocriva/sdk';
 
function describeStatus(status: ProcessingStatus): string {
  switch (status) {
    case 'pending':
      return 'Waiting to be queued';
    case 'queued':
      return 'In queue for processing';
    case 'in_progress':
      return 'Currently being processed';
    case 'completed':
      return 'Processing finished successfully';
    case 'failed':
      return 'Processing failed';
    default: {
      // TypeScript will error here if a new status is added to the SDK
      // but not handled in this switch statement
      const _exhaustive: never = status;
      return _exhaustive;
    }
  }
}

The same pattern works for BatchStatus, FileType, ResultFormat, and ProcessingPriority.

IDE Support

Because the SDK ships full TypeScript declarations, your editor provides:

  • Autocomplete for all method names, parameter fields, and return type properties
  • Hover documentation — JSDoc comments from the SDK source appear in tooltips
  • Inline type errors — TypeScript reports missing required fields (e.g., forgetting projectId in CreateTemplateParams) before you run the code

No additional configuration is required. Install the package and start typing — the types work out of the box with VSCode, WebStorm, Neovim with LSP, and any other TypeScript-aware editor.