Oatfi SDK

Official TypeScript SDK for the Oatfi API.

Installation

npm install @oatfi/oatfi-sdk

Usage

First, initialize the SDK with your API credentials:

import { Oatfi, Environment } from '@oatfi/oatfi-sdk';

// Using environment configuration
const oatfi = new Oatfi({
  environment: Environment.DEV, // Options: Environment.LOCAL, Environment.DEV, Environment.STG
  apiKey: 'your-api-key'
});

// Or using default configuration (will use OATFI_API environment variable)
const oatfi = new Oatfi({
  apiKey: 'your-api-key'
});

Environment Configuration

The SDK supports different environments through the environment parameter or environment variables:

| Environment | Environment Variable | Default URL | |-------------|---------------------|-------------| | Local | OATFI_API_LOCAL | http://localhost:3020/v3 | | Development | OATFI_API_DEV | https://api.dev.oatfi.com/v3 | | Staging | OATFI_API_STG | https://api.stg.oatfi.com/v3 | | Production | OATFI_API | https://api.oatfi.com/v3 |

Available Modules and Methods

Applications Module (oatfi.applications)

// Create a new application
create(data: CreateApplicationDto): Promise<ApplicationDto>

// List applications with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: string;
  kyb_status?: string;
  platform?: string;
}): Promise<PaginatedResponse<ApplicationDto>>

// Get a specific application
findById(id: string, params?: {
  expand?: string[];
}): Promise<ApplicationDto>

// Update an application
update(id: string, data: UpdateApplicationDto): Promise<ApplicationDto>

// Submit an application
submit(id: string): Promise<ApplicationDto>

Auth Module (oatfi.auth)

// Login with API key
login(data: { apiKey: string }): Promise<AuthResponseDto>

// Refresh token
refresh(data: { refreshToken: string }): Promise<AuthResponseDto>

// Get user profile
getProfile(): Promise<ProfileDto>

Businesses Module (oatfi.businesses)

// Create a business
create(data: CreateBusinessDto): Promise<BusinessDto>

// List businesses with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: string;
  platform?: string;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<BusinessDto>>

// Get a specific business
findById(id: string, params?: {
  expand?: string[];
}): Promise<BusinessDto>

// Update a business
update(id: string, data: UpdateBusinessDto): Promise<BusinessDto>

// Search businesses
search(params: {
  q?: string;
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
}): Promise<PaginatedResponse<BusinessDto>>

// Start underwriting process
startUnderwriting(id: string): Promise<void>

// Upload multiple files for a business
uploadFiles(businessId: string, data: {
  files: (File | Buffer)[];
  file_type: FileType;
  description?: string;
  metadata?: Record<string, any>;
}): Promise<PaginatedResponse<FileDto>>

// Upload a single file for a business
uploadFile(businessId: string, data: {
  file: File | Buffer;
  file_type: FileType;
  description?: string;
  metadata?: Record<string, any>;
}): Promise<FileDto>

// List all files for a business
listFiles(businessId: string, params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  file_type?: FileType;
}): Promise<PaginatedResponse<FileDto>>

// Get a specific file for a business
getFile(businessId: string, fileId: string): Promise<FileResponse>

// Delete a file for a business
deleteFile(businessId: string, fileId: string): Promise<FileResponse>

// Get a temporary download URL for a business file
getDownloadUrl(businessId: string, fileId: string): Promise<GetDownloadUrlResponse>

Persons Module (oatfi.persons)

// Create a person
create(data: CreatePersonDto): Promise<PersonDto>

// List persons with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: string;
  business?: string;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<PersonDto>>

// Get a specific person
findById(id: string, params?: {
  expand?: string[];
}): Promise<PersonDto>

// Update a person
update(id: string, data: UpdatePersonDto): Promise<PersonDto>

// Remove a person
remove(id: string): Promise<{ id: string; deleted: boolean; object: string }>

Payment Intents Module (oatfi.paymentIntents)

// Create a payment intent
create(data: CreatePaymentIntentDto): Promise<PaymentIntentDto>

// List payment intents with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: string;
  business?: string;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<PaymentIntentDto>>

// Get a specific payment intent
findById(id: string, params?: {
  expand?: string[];
}): Promise<PaymentIntentDto>

// Update a payment intent
update(id: string, data: UpdatePaymentIntentDto): Promise<PaymentIntentDto>

Platforms Module (oatfi.platforms)

// Create a platform
create(data: CreatePlatformDto): Promise<PlatformDto>

// List platforms with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: string;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<PlatformDto>>

// Get a specific platform
findById(id: string, params?: {
  expand?: string[];
}): Promise<PlatformDto>

// Update a platform
update(id: string, data: UpdatePlatformDto): Promise<PlatformDto>

// Get platform roles
getRoles(id: string): Promise<{ roles: PlatformRole[] }>

// Update platform roles
updateRoles(id: string, data: UpdatePlatformRolesDto): Promise<{ roles: PlatformRole[] }>

Programs Module (oatfi.programs)

// Create a program
create(data: CreateProgramDto): Promise<ProgramDto>

// List programs with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: string;
  platform?: string;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<ProgramDto>>

// Get a specific program
findById(id: string, params?: {
  expand?: string[];
}): Promise<ProgramDto>

// Update a program
update(id: string, data: UpdateProgramDto): Promise<ProgramDto>

Webhook Endpoints Module (oatfi.webhookEndpoints)

// Create a webhook endpoint
create(data: CreateWebhookEndpointDto): Promise<WebhookEndpointDto>

// List webhook endpoints with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: WebhookEndpointStatus;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<WebhookEndpointDto>>

// Get a specific webhook endpoint
findById(id: string, params?: {
  expand?: string[];
}): Promise<WebhookEndpointDto>

// Update a webhook endpoint
update(id: string, data: UpdateWebhookEndpointDto): Promise<WebhookEndpointDto>

// Remove a webhook endpoint
remove(id: string): Promise<{ id: string; deleted: boolean; object: string }>

Embed Module (oatfi.embed)

// Create an embed token
createToken(data: CreateEmbedTokenDto): Promise<EmbedTokenResponseDto>

// Exchange an embed token
exchangeToken(): Promise<EmbedTokenResponseDto>

// List embed tokens with pagination
listTokens(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
}): Promise<PaginatedResponse<EmbedTokenDto>>

// Get a specific embed token
getToken(id: string): Promise<EmbedTokenDto>

// Revoke an embed token
revokeToken(id: string): Promise<{ id: string; deleted: boolean; object: string }>

Originations Module (oatfi.originations)

// Create an origination offer
createOffer(data: CreateOriginationOfferDto): Promise<OriginationDto>

// Accept an origination
acceptOrigination(id: string): Promise<OriginationDto>

// List originations with pagination
findAll(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  expand?: string[];
  status?: OriginationStatus;
  sub_status?: OriginationSubStatus;
  business_id?: string;
  program_id?: string;
  payment_intent_id?: string;
  created_at?: {
    gt?: string;
    gte?: string;
    lt?: string;
    lte?: string;
  };
}): Promise<PaginatedResponse<OriginationDto>>

// Get a specific origination
findById(id: string, params?: {
  expand?: string[];
}): Promise<OriginationDto>

Files Module (oatfi.files)

// Upload multiple files linked to a resource
uploadFiles(data: {
  files: (File | Buffer)[];
  resource_type: FileResourceType;
  resource_id: string;
  file_type: FileType;
  description?: string;
  metadata?: Record<string, any>;
}): Promise<PaginatedResponse<FileDto>>

// Upload a single file (convenience method)
uploadFile(data: {
  file: File | Buffer;
  resource_type: FileResourceType;
  resource_id: string;
  file_type: FileType;
  description?: string;
  metadata?: Record<string, any>;
}): Promise<FileDto>

// Retrieve a file by ID
retrieve(id: string): Promise<FileResponse>

// List all files with optional filters
list(params?: {
  limit?: number;
  starting_after?: string;
  ending_before?: string;
  resource_type?: FileResourceType;
  resource_id?: string;
  file_type?: FileType;
}): Promise<PaginatedResponse<FileDto>>

// Delete a file by ID
deleteFile(id: string): Promise<FileResponse>

// Get a temporary download URL for a file
getDownloadUrl(id: string, expiresIn?: number): Promise<GetDownloadUrlResponse>

// Update file metadata
update(id: string, updates: {
  file_type?: FileType;
  description?: string;
  metadata?: Record<string, any>;
}): Promise<FileResponse>

Common Features

File Management

The SDK provides comprehensive file management capabilities through two approaches:

1. Using the Files Module (Generic Approach)

Upload files linked to any resource type:

// Upload a single file
const file = await oatfi.files.uploadFile({
  file: fileBuffer, // or File object in browser
  resource_type: 'business',
  resource_id: 'business_id',
  file_type: 'bank_statement',
  description: 'Q4 2023 Bank Statement',
  metadata: {
    quarter: 'Q4',
    year: '2023'
  }
});

// Upload multiple files at once
const files = await oatfi.files.uploadFiles({
  files: [file1, file2, file3],
  resource_type: 'business',
  resource_id: 'business_id',
  file_type: 'tax_return',
  description: 'Tax returns for 2021-2023'
});

// List files with filters
const businessFiles = await oatfi.files.list({
  resource_type: 'business',
  resource_id: 'business_id',
  file_type: 'bank_statement',
  limit: 10
});

// Get a temporary download URL
const downloadInfo = await oatfi.files.getDownloadUrl('file_id', 7200); // expires in 2 hours
console.log(downloadInfo.download_url);

// Update file metadata
await oatfi.files.update('file_id', {
  file_type: 'financial_statement',
  description: 'Updated description',
  metadata: {
    reviewed: true,
    reviewer: '[email protected]'
  }
});

// Delete a file
await oatfi.files.deleteFile('file_id');

2. Using Resource-Specific Methods

For businesses, use the dedicated file methods:

// Upload a single file to a business
const file = await oatfi.businesses.uploadFile('business_id', {
  file: fileBuffer,
  file_type: 'business_license',
  description: 'Business License 2024'
});

// Upload multiple files to a business
const files = await oatfi.businesses.uploadFiles('business_id', {
  files: [file1, file2],
  file_type: 'tax_return'
});

// List all files for a business
const businessFiles = await oatfi.businesses.listFiles('business_id', {
  file_type: 'bank_statement',
  limit: 20
});

// Get a specific file
const fileDetails = await oatfi.businesses.getFile('business_id', 'file_id');

// Get download URL
const downloadUrl = await oatfi.businesses.getDownloadUrl('business_id', 'file_id');

// Delete a file
await oatfi.businesses.deleteFile('business_id', 'file_id');

Supported File Types

The SDK supports a wide range of file types:

Business Documents:

• bank_statement, tax_return, business_license, articles_of_incorporation
• ein_letter, financial_statement, corporate_formation_document, certificate_of_good_standing

Identity Documents:

• drivers_license, passport, social_security_card, id_document

Verification Documents:

• utility_bill, bank_account_statement, kyc_qr_code, proof_of_address
• proof_of_income, employment_verification, bank_reference_letter

Legal & Financial:

• contract, terms_of_service, privacy_policy, signed_agreement
• invoice, receipt, payment_proof

Other:

• other - for miscellaneous file types

Supported Resource Types

Files can be linked to the following resource types:

• business - Business entity files
• application - Application-related documents
• person - Person/individual documents
• partner - Partner documents
• user - User files
• payment_intent - Payment-related documents
• origination - Origination documents
• payment - Payment receipts and proofs

Pagination

All list endpoints support cursor-based pagination. You can use it in two ways:

1. Manual pagination using limit, starting_after, and ending_before:

const firstPage = await oatfi.businesses.findAll({ limit: 10 });
const nextPage = await oatfi.businesses.findAll({
  limit: 10,
  starting_after: firstPage.data[firstPage.data.length - 1].id
});

2. Automatic pagination using the async iterator:

// This will automatically fetch all pages
for await (const business of oatfi.businesses.paginate()) {
  console.log(business.name);
}

// With filters
for await (const business of oatfi.businesses.paginate({
  status: 'ACTIVE',
  limit: 20
})) {
  console.log(business.name);
}

Error Handling

The SDK provides consistent error handling through the ApiException class:

import { ApiException } from '@oatfi/oatfi-sdk';

try {
  await oatfi.businesses.create({ /* ... */ });
} catch (error) {
  if (error instanceof ApiException) {
    // Handle API-specific errors
    console.error(`API Error: ${error.code} - ${error.message}`);
    if (error.details) {
      console.error('Error details:', error.details);
    }
  } else {
    // Handle other errors
    console.error('Unexpected error:', error);
  }
}

Metadata

All resources support a metadata field for storing custom key-value pairs:

const business = await oatfi.businesses.create({
  name: 'Business Name',
  // ... other fields ...
  metadata: {
    custom_field_1: 'value1',
    custom_field_2: 'value2',
    internal_id: '12345'
  }
});

Expansion

Many endpoints support expanding related resources using the expand parameter:

const business = await oatfi.businesses.findById('business_id', {
  expand: ['persons', 'applications']
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions for all API responses and request parameters. This includes:

• All DTOs (Data Transfer Objects)
• Enum types for statuses and other fixed values
• Pagination parameters and responses
• Error types and exceptions
• Metadata types for extensibility

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Methods Summary

Applications Module (oatfi.applications)

• create(data: CreateApplicationDto): Promise<ApplicationDto>
• findAll(params?: ListApplicationsParams): Promise<PaginatedResponse<ApplicationDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<ApplicationDto>
• update(id: string, data: UpdateApplicationDto): Promise<ApplicationDto>
• submit(id: string): Promise<ApplicationDto>

Auth Module (oatfi.auth)

• login(data: { apiKey: string }): Promise<AuthResponseDto>
• refresh(data: { refreshToken: string }): Promise<AuthResponseDto>
• getProfile(): Promise<ProfileDto>

Businesses Module (oatfi.businesses)

• create(data: CreateBusinessDto): Promise<BusinessDto>
• findAll(params?: ListBusinessesParams): Promise<PaginatedResponse<BusinessDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<BusinessDto>
• update(id: string, data: UpdateBusinessDto): Promise<BusinessDto>
• search(params: SearchBusinessesParams): Promise<PaginatedResponse<BusinessDto>>
• startUnderwriting(id: string): Promise<void>
• uploadFiles(businessId: string, data: UploadFilesDto): Promise<PaginatedResponse<FileDto>>
• uploadFile(businessId: string, data: { file: File | Buffer; file_type: FileType; description?: string; metadata?: Record<string, any> }): Promise<FileDto>
• listFiles(businessId: string, params?: ListFilesParams): Promise<PaginatedResponse<FileDto>>
• getFile(businessId: string, fileId: string): Promise<FileResponse>
• deleteFile(businessId: string, fileId: string): Promise<FileResponse>
• getDownloadUrl(businessId: string, fileId: string): Promise<GetDownloadUrlResponse>

Persons Module (oatfi.persons)

• create(data: CreatePersonDto): Promise<PersonDto>
• findAll(params?: ListPersonsParams): Promise<PaginatedResponse<PersonDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<PersonDto>
• update(id: string, data: UpdatePersonDto): Promise<PersonDto>
• remove(id: string): Promise<{ id: string; deleted: boolean; object: string }>

Payment Intents Module (oatfi.paymentIntents)

• create(data: CreatePaymentIntentDto): Promise<PaymentIntentDto>
• findAll(params?: ListPaymentIntentsParams): Promise<PaginatedResponse<PaymentIntentDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<PaymentIntentDto>
• update(id: string, data: UpdatePaymentIntentDto): Promise<PaymentIntentDto>

Platforms Module (oatfi.platforms)

• create(data: CreatePlatformDto): Promise<PlatformDto>
• findAll(params?: ListPlatformsParams): Promise<PaginatedResponse<PlatformDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<PlatformDto>
• update(id: string, data: UpdatePlatformDto): Promise<PlatformDto>
• getRoles(id: string): Promise<{ roles: PlatformRole[] }>
• updateRoles(id: string, data: UpdatePlatformRolesDto): Promise<{ roles: PlatformRole[] }>

Programs Module (oatfi.programs)

• create(data: CreateProgramDto): Promise<ProgramDto>
• findAll(params?: ListProgramsParams): Promise<PaginatedResponse<ProgramDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<ProgramDto>
• update(id: string, data: UpdateProgramDto): Promise<ProgramDto>

Webhook Endpoints Module (oatfi.webhookEndpoints)

• create(data: CreateWebhookEndpointDto): Promise<WebhookEndpointDto>
• findAll(params?: ListWebhookEndpointsParams): Promise<PaginatedResponse<WebhookEndpointDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<WebhookEndpointDto>
• update(id: string, data: UpdateWebhookEndpointDto): Promise<WebhookEndpointDto>
• remove(id: string): Promise<{ id: string; deleted: boolean; object: string }>

Embed Module (oatfi.embed)

• createToken(data: CreateEmbedTokenDto): Promise<EmbedTokenResponseDto>
• exchangeToken(): Promise<EmbedTokenResponseDto>
• listTokens(params?: ListEmbedTokensParams): Promise<PaginatedResponse<EmbedTokenDto>>
• getToken(id: string): Promise<EmbedTokenDto>
• revokeToken(id: string): Promise<{ id: string; deleted: boolean; object: string }>

Originations Module (oatfi.originations)

• createOffer(data: CreateOriginationOfferDto): Promise<OriginationDto>
• acceptOrigination(id: string): Promise<OriginationDto>
• findAll(params?: ListOriginationsParams): Promise<PaginatedResponse<OriginationDto>>
• findById(id: string, params?: { expand?: string[] }): Promise<OriginationDto>

Files Module (oatfi.files)

• uploadFiles(data: UploadFilesDto): Promise<PaginatedResponse<FileDto>>
• uploadFile(data: { file: File | Buffer; resource_type: FileResourceType; resource_id: string; file_type: FileType; description?: string; metadata?: Record<string, any> }): Promise<FileDto>
• retrieve(id: string): Promise<FileResponse>
• list(params?: ListFilesParams): Promise<PaginatedResponse<FileDto>>
• deleteFile(id: string): Promise<FileResponse>
• getDownloadUrl(id: string, expiresIn?: number): Promise<GetDownloadUrlResponse>
• update(id: string, updates: { file_type?: FileType; description?: string; metadata?: Record<string, any> }): Promise<FileResponse>