@visionfi/server-sdk/dist/types/index.d.ts

Server-side SDK for VisionFI API access using Google Service Account authentication

/**
 * Configuration options for initializing the VisionFi client.
 * @aimodels This interface defines how to configure the VisionFi client.
 */
export interface VisionFiConfig {
    /**
     * Path to the Google service account JSON file
     * @example './service-account.json'
     */
    serviceAccountPath?: string;
    /**
     * Pre-loaded Google service account JSON object
     * @example { "type": "service_account", "project_id": "...", ... }
     */
    serviceAccountJson?: object;
    /**
     * Custom API base URL (optional)
     * @default 'https://platform.visionfi.ai/api/v1'
     */
    apiBaseUrl?: string;
}
/**
 * Options for document analysis requests.
 * @aimodels This interface defines the payload for document analysis.
 */
export interface AnalyzeDocumentOptions {
    /**
     * The name of the file being analyzed
     * @example 'loan_document.pdf'
     */
    fileName: string;
    /**
     * The type of analysis to perform on the document
     * @example 'auto_loan_abstract'
     */
    analysisType: string;
}
/**
 * Response from a document analysis request.
 * @aimodels This represents the initial job created when submitting a document.
 */
export interface AnalysisJob {
    /**
     * Unique identifier for the analysis job
     * Used for retrieving results later
     */
    uuid: string;
    /** Optional message about the job status */
    message?: string;
}
/**
 * Response from a getAnalysisResults request.
 * Contains either results or information that the job is still processing.
 * @aimodels This represents the possible states of an analysis job result.
 */
export interface AnalysisResult {
    /**
     * Status of the analysis job - only present when results are found
     * 'processed' = successful completion
     * 'error' = job failed with an error
     */
    status?: 'processed' | 'error';
    /**
     * Analysis results data - structure varies by analysis type
     * Only present when status is 'processed' or 'error'
     */
    results?: any;
    /**
     * Indicates if results were found for this job
     * false = job still processing or doesn't exist
     */
    found?: boolean;
    /**
     * Message describing the current state
     * @example "No analysis results found"
     */
    message?: string;
}
/**
 * Response from authentication verification.
 * @aimodels This represents the authentication verification response.
 */
export interface AuthVerificationResult {
    /**
     * True if authentication is valid, false otherwise
     */
    data: boolean;
}
/**
 * Authentication token result.
 * @aimodels This represents the JWT token response.
 */
export interface AuthTokenResult {
    /**
     * The JWT token string that can be used for authentication
     */
    token: string;
}
/**
 * Client information data structure returned from getClientInfo endpoint.
 * Uses Record type for flexibility with future API changes while ensuring
 * critical fields are properly typed.
 * @aimodels This represents a client's configuration and account details.
 */
export type ClientInfo = Record<string, unknown> & {
    /** Unique identifier for the client */
    id: string;
    /** Client name */
    name: string;
    /** Current status of the client account */
    status: 'active' | 'inactive' | 'suspended' | 'pending';
    /** Type of tenant */
    tenantType: string;
    /** Unique tenant key identifier */
    tenantKey: string;
    /** Primary contact email */
    contactEmail: string;
    /** Creation timestamp */
    createdAt: string | Date;
    /** Last update timestamp */
    updatedAt: string | Date;
};
/**
 * Response from the getClientInfo endpoint.
 * @aimodels This represents the full response structure from the client info endpoint.
 */
export interface ClientInfoResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Client information data, only present when success is true */
    data?: ClientInfo;
    /** Optional message, typically present when success is false */
    message?: string;
}
/**
 * Information about an available workflow.
 * @aimodels This represents a single workflow available to the client.
 */
export interface WorkflowInfo {
    /**
     * Unique identifier key for the workflow
     * @example 'auto_loan_abstract'
     */
    workflow_key: string;
    /**
     * Description of what the workflow does
     * @example 'Workflow for auto loan abstracts'
     */
    description: string;
}
/**
 * Response from the getAvailableWorkflows endpoint.
 * @aimodels This represents the full response structure from the workflows endpoint.
 */
export interface WorkflowsResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Array of available workflows, only present when success is true */
    data?: WorkflowInfo[];
    /** Optional message, typically present when success is false */
    message?: string;
}
/**
 * Options for creating a new package.
 * @aimodels This interface defines the payload for package creation.
 */
export interface CreatePackageOptions {
    /**
     * Optional description of the package
     * @example 'Test vehicle loan application package'
     */
    description?: string;
    /**
     * The product type for this package
     * @example 'consumer_loan_vehicle_installment'
     */
    productType: string;
    /**
     * Optional external reference IDs for package organization
     * @example ['APP-2024-001', 'LOCAL-ID-12345']
     */
    externalReferenceIds?: string[];
    /**
     * Individual reference field for exact matching (1 of 5)
     * @example 'INV-2024-Q1'
     */
    externalReference1?: string;
    /**
     * Individual reference field for exact matching (2 of 5)
     * @example 'BATCH-001'
     */
    externalReference2?: string;
    /**
     * Individual reference field for exact matching (3 of 5)
     * @example 'PRIORITY-HIGH'
     */
    externalReference3?: string;
    /**
     * Individual reference field for exact matching (4 of 5)
     * @example 'DEPT-FINANCE'
     */
    externalReference4?: string;
    /**
     * Individual reference field for exact matching (5 of 5)
     * @example 'REGION-WEST'
     */
    externalReference5?: string;
    /**
     * Semantic categorization field for structured filtering
     * @example 'invoices'
     */
    externalCategory?: string;
    /**
     * Ownership/department field for organizational filtering
     * @example 'accounting-dept'
     */
    externalOwner?: string;
}
/**
 * Response from package creation.
 * @aimodels This represents the response when creating a new package.
 */
export interface CreatePackageResponse {
    /** Unique identifier for the created package */
    packageId: string;
    /** Confirmation message */
    message: string;
}
/**
 * Document information within a package.
 * @aimodels This represents detailed information about a document in a package.
 */
export interface DocumentInfo {
    /** Name of the file */
    fileName: string;
    /** Type of file (e.g., 'pdf') */
    fileType: string;
    /** Path to file in storage */
    filePath: string;
    /** Unique identifier for the document */
    uuid: string;
    /** Number of pages in the document */
    pageCount: number | null;
    /** Status of the file (e.g., 'ACTIVE', 'SOFT_DELETED') */
    fileStatus: string;
    /** Type of document (e.g., 'unknown', 'driver_license', etc.) */
    documentType: string;
    /** Document creation timestamp */
    createdAt: string;
    /** Document last update timestamp */
    updatedAt: string;
    /** Date when document was deleted (null if not deleted) */
    deleteDate: string | null;
}
/**
 * Available processing option for a package.
 * @aimodels This represents a processing configuration available for a package.
 */
export interface ProcessingOption {
    /** Configuration ID for the processing option */
    configId: string;
    /** Description of what this processing option does */
    description: string;
}
/**
 * Package information structure.
 * @aimodels This represents detailed information about a package.
 */
export interface PackageInfo {
    /** Unique identifier for the package */
    packageId: string;
    /** Optional description of the package */
    description?: string;
    /** Product type for this package */
    productType: string;
    /** Current status of the package */
    status: string;
    /** External reference IDs associated with the package */
    externalReferenceIds: string[];
    /** Total number of files in the package */
    totalFiles: number;
    /** List of documents in the package */
    documentList: DocumentInfo[];
    /** Available processing options for this package */
    availableProcessingOptions: ProcessingOption[];
    /** Package creation timestamp */
    createdAt: string;
    /** Package last update timestamp */
    updatedAt: string;
    /** Individual reference field (1 of 5) */
    externalReference1?: string;
    /** Individual reference field (2 of 5) */
    externalReference2?: string;
    /** Individual reference field (3 of 5) */
    externalReference3?: string;
    /** Individual reference field (4 of 5) */
    externalReference4?: string;
    /** Individual reference field (5 of 5) */
    externalReference5?: string;
    /** Semantic categorization field */
    externalCategory?: string;
    /** Ownership/department field */
    externalOwner?: string;
}
/**
 * Options for filtering packages when listing.
 * @aimodels This interface defines the query parameters for package filtering.
 */
export interface ListPackagesOptions {
    /**
     * Comma-separated external reference IDs (OR logic)
     * @example 'APP-2024-001,LOCAL-ID-12345'
     * @deprecated Use 'tags' parameter instead for better clarity
     */
    externalReferences?: string;
    /**
     * Comma-separated product types (OR logic)
     * @example 'consumer_loan_vehicle_installment'
     */
    productTypes?: string;
    /**
     * ISO 8601 datetime or simple date (YYYY-MM-DD)
     * @example '2024-01-15T10:30:00Z' or '2024-01-15'
     */
    createdAfter?: string;
    /**
     * Comma-separated tags for OR filtering (maps to externalReferences array field)
     * @example 'urgent,q1-2024,priority'
     */
    tags?: string;
    /**
     * Exact match for externalReference1 field
     * @example 'INV-2024-Q1'
     */
    ref1?: string;
    /**
     * Exact match for externalReference2 field
     * @example 'BATCH-001'
     */
    ref2?: string;
    /**
     * Exact match for externalReference3 field
     * @example 'PRIORITY-HIGH'
     */
    ref3?: string;
    /**
     * Exact match for externalReference4 field
     * @example 'DEPT-FINANCE'
     */
    ref4?: string;
    /**
     * Exact match for externalReference5 field
     * @example 'REGION-WEST'
     */
    ref5?: string;
    /**
     * Exact match for externalCategory field
     * @example 'invoices'
     */
    category?: string;
    /**
     * Exact match for externalOwner field
     * @example 'accounting-dept'
     */
    owner?: string;
}
/**
 * Response from listing packages.
 * @aimodels This represents the response when listing packages.
 */
export interface ListPackagesResponse {
    /** Array of package information */
    packages: PackageInfo[];
    /** Total number of packages */
    total: number;
}
/**
 * Audit action types for package operations.
 * @aimodels This enum represents all possible audit actions that can be tracked.
 */
export type AuditAction = 'PACKAGE_CREATED' | 'DOCUMENT_ADDED' | 'DOCUMENT_REMOVED' | 'DOCUMENT_STATUS_CHANGED' | 'PACKAGE_STATUS_CHANGED' | 'ACTION_ADDED' | 'EXTERNAL_REFERENCE_ADDED' | 'EXTERNAL_REFERENCE_REMOVED' | 'WORKFLOW_EXECUTED' | 'PACKAGE_PROCESSED' | 'ERROR_OCCURRED';
/**
 * Audit history entry for a package.
 * @aimodels This represents a single audit entry in the package audit history.
 */
export interface AuditHistoryEntry {
    /** Unique identifier for this audit entry */
    auditId: string;
    /** Reference to parent package */
    packageId: string;
    /** Client identifier for security isolation */
    clientId: string;
    /** ISO 8601 timestamp of when the action occurred */
    timestamp: string;
    /** Standardized action type */
    action: AuditAction;
    /** Human-readable description of the action */
    description: string;
    /** Action-specific structured details */
    details?: Record<string, any>;
    /** Optional user identifier who initiated the action */
    userId?: string;
    /** Whether the action was automated or user-initiated */
    systemGenerated: boolean;
    /** Optional IP address of the request origin */
    originatingIp?: string;
    /** Optional user agent of the request */
    userAgent?: string;
}
/**
 * Response from getting package audit history.
 * @aimodels This represents the response when getting package audit history.
 */
export interface PackageAuditHistoryResponse {
    /** The unique identifier of the package */
    packageId: string;
    /** Array of audit entries ordered by timestamp (newest first) */
    auditHistory: AuditHistoryEntry[];
    /** Total number of audit entries returned */
    total: number;
    /** Indicates if there are more entries beyond the limit */
    hasMore: boolean;
}
/**
 * File information for adding to a package.
 * @aimodels This represents a file to be added to a package.
 */
export interface PackageFile {
    /** Name of the file */
    fileName: string;
    /** Base64 encoded file content */
    fileBase64: string;
}
/**
 * Options for adding documents to a package.
 * @aimodels This interface defines the payload for adding documents to a package.
 */
export interface AddDocumentsOptions {
    /** Array of files to add to the package */
    files: PackageFile[];
}
/**
 * Response from adding documents to a package.
 * @aimodels This represents the response when adding documents to a package.
 */
export interface AddDocumentsResponse {
    /** The package ID that documents were added to */
    packageId: string;
    /** Number of files added in this request */
    filesAdded: number;
    /** Total number of files in the package after this operation */
    totalFiles: number;
    /** Confirmation message */
    message: string;
}
/**
 * Response from deleting a document from a package.
 * @aimodels This represents the response when deleting a document from a package.
 */
export interface DeleteDocumentResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Confirmation message */
    message?: string;
    /** Response data */
    data?: any;
}
/**
 * Options for managing external references.
 * @aimodels This interface defines the payload for adding/removing external references.
 */
export interface ExternalReferencesOptions {
    /** Array of reference IDs to add or remove */
    referenceIds: string[];
}
/**
 * Response from external reference operations.
 * @aimodels This represents the response when managing external references.
 */
export interface ExternalReferencesResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Confirmation message */
    message?: string;
    /** Response data */
    data?: any;
}
/**
 * Options for executing prompt processing on a package.
 * @aimodels This interface defines the payload for executing prompt processing.
 */
export interface ExecuteProcessingOptions {
    /** Configuration ID for the prompt to execute */
    configId: string;
    /** Optional array of specific document UUIDs to process */
    documentUuids?: string[];
}
/**
 * Response from executing prompt processing.
 * @aimodels This represents the response when executing prompt processing.
 */
export interface ExecuteProcessingResponse {
    /** Unique identifier for tracking this processing request */
    processingId: string;
    /** Current status (always 'queued' initially) */
    status: string;
    /** Echo of the requested configuration ID */
    configId: string;
    /** Number of documents that will be processed */
    documentCount: number;
    /** Confirmation message */
    message: string;
}
/**
 * Processing history entry information.
 * @aimodels This represents a processing history entry for a package.
 */
export interface ProcessingHistoryEntry {
    /** Unique identifier for this processing attempt */
    processingId: string;
    /** The prompt configuration that was executed */
    configId: string;
    /** Documents processed (empty array if all documents were processed) */
    documentUuids: string[];
    /** Current status of the processing */
    status: 'queued' | 'processing' | 'completed' | 'failed';
    /** When the processing request was created */
    createdAt: string;
    /** When processing actually began (null if still queued) */
    startedAt?: string | null;
    /** When processing finished (null if not completed) */
    completedAt?: string | null;
    /** Processing results (when includeResults=true and status is completed) */
    result?: {
        /** Extracted/processed data from AI analysis */
        data: any;
        /** Confidence score (if available) */
        confidence?: number;
    };
}
/**
 * Response from getting processing history.
 * @aimodels This represents the response when getting processing history for a package.
 */
export interface ProcessingHistoryResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Processing history data */
    data?: {
        /** The package ID */
        packageId: string;
        /** Array of processing history entries ordered by creation time (newest first) */
        processingHistory: ProcessingHistoryEntry[];
        /** Total number of processing entries */
        total: number;
    };
    /** Optional message */
    message?: string;
}
/**
 * Options for retrieving processing history.
 * @aimodels This interface defines options for the getProcessingHistory method.
 */
export interface ProcessingHistoryOptions {
    /**
     * Whether to include processing results in the response.
     * When true, result field will be populated for completed processing entries.
     * @default false
     */
    includeResults?: boolean;
}
/**
 * Processing result information.
 * @aimodels This represents detailed processing result data.
 */
export interface ProcessingResult {
    /** Unique processing identifier */
    processingId: string;
    /** Associated package ID */
    packageId: string;
    /** Client identifier */
    clientId: string;
    /** Prompt configuration used */
    configId: string;
    /** Prompt/workflow collection ID (if available) */
    configCollectionId?: string;
    /** Prompt/workflow version ID (if available) */
    configVersionId?: string;
    /** Boolean indicating if views are available (defaults to false if undefined) */
    hasViews?: boolean;
    /** Documents processed (if specific documents were targeted) */
    documentUuids?: string[];
    /** Current status (queued, processing, completed, failed) */
    status: 'queued' | 'processing' | 'completed' | 'failed';
    /** Processing results (when status is completed) */
    result?: {
        /** Extracted/processed data from AI analysis */
        data: any;
        /** Confidence score (if available) */
        confidence?: number;
    };
    /** Error details (when status is failed) */
    error?: any;
    /** When processing was queued */
    createdAt: string;
    /** When processing began (if started) */
    startedAt?: string;
    /** When processing finished (if completed) */
    completedAt?: string;
}
/**
 * Response from getting processing results.
 * @aimodels This represents the response when getting processing results.
 */
export interface ProcessingResultResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Processing result data (if found) */
    data?: ProcessingResult;
    /** Optional message */
    message?: string;
}
/**
 * Options for retrieving processing view.
 * @aimodels This interface defines options for the getProcessingView method.
 */
export interface ProcessingViewOptions {
    /**
     * Optional template name to use for rendering.
     * If not provided, uses the default template.
     */
    viewName?: string;
}
/**
 * Response from getting processing view.
 * @aimodels This represents the response when getting a rendered processing view.
 */
export interface ProcessingViewResponse {
    /** Whether the request was successful */
    success: boolean;
    /** Base64-encoded rendered HTML string */
    view?: string;
    /** Error message if unsuccessful */
    message?: string;
}
/**
 * Product type information.
 * @aimodels This represents information about a product type.
 */
export interface ProductType {
    /** Product type identifier */
    type: string;
}
/**
 * Response from getting product types.
 * @aimodels This represents the response when getting available product types.
 */
export interface ProductTypesResponse {
    /** Array of available product types */
    productTypes: ProductType[];
}
export declare class VisionFiError extends Error {
    statusCode?: number;
    code?: string;
    constructor(message: string, statusCode?: number, code?: string);
}