npm package: @oatfi/oatfi-sdk
Description: Official TypeScript SDK for the Oatfi API
Author: Oatfi
Latest version: 1.3.6

# Oatfi SDK

Official TypeScript SDK for the Oatfi API.

## Installation

```bash
npm install @oatfi/oatfi-sdk
```

## Usage

First, initialize the SDK with your API credentials:

```typescript
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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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`)

```typescript
// 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:

```typescript
// 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: 'john@example.com'
  }
});

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

#### 2. Using Resource-Specific Methods

For businesses, use the dedicated file methods:

```typescript
// 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`:
```typescript
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:
```typescript
// 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:

```typescript
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:

```typescript
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:

```typescript
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](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>`