Typescript SDK

What is @apploitech/apploi-client?

The official TypeScript client for Apploi’s Partner API. It wraps the generated Fern SDK with a developer-friendly layer that adds native TypeScript types, input validation, and a consistent error model. This means faster integration, fewer runtime surprises, and a cleaner DX from local development to production.

Features

✅ Native TypeScript Types - Use number, Date, and enums instead of strings ✅ Input Validation - Catch errors before making API calls ✅ Strongly-Typed Responses - Full TypeScript interfaces with IDE autocomplete ✅ Better Error Handling - Custom exception hierarchy with detailed error information ✅ Bundled SDK - Includes the Fern-generated SDK, no additional dependencies needed ✅ Developer-Friendly - Intuitive API that follows TypeScript best practices

Installation

npm install @apploitech/apploi-client

or with yarn:

yarn add @apploitech/apploi-client

Quick Start

import { ApploiClient } from '@apploitech/apploi-client';

// Initialize the client
const client = new ApploiClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://partners.apploi.com' // Optional, this is the default
});

// Get job applications with native types
const applications = await client.getJobApplications({
  jobId: 12345,                        // number, not string!
  limit: 50,                           // number, not string!
  updatedAfter: new Date('2024-01-01') // Date object, not string!
});

// Strongly-typed response
console.log(applications.applicants[0].name);     // Full TypeScript support
console.log(applications.pagination.total);       // IDE autocomplete works
console.log(applications.pagination.hasMore);     // Know exactly what fields exist

💡 See examples.ts for comprehensive usage examples including pagination, error handling, and advanced features.

API Reference

Client Initialization

import { ApploiClient, ApploiClientConfig } from '@apploitech/apploi-client';

const config: ApploiClientConfig = {
  apiKey: 'your-api-key',              // Required - API key for authentication
  authorization: 'your-auth-token',    // Optional - not required by the API
  baseUrl: 'https://api.example.com',  // Optional - uses default if not provided
  timeout: 30000,                      // Optional - timeout in milliseconds
  customHeaders: {                     // Optional - additional headers
    'X-Custom-Header': 'value'
  }
};

const client = new ApploiClient(config);

// Or use minimal configuration (recommended):
const client = new ApploiClient({
  apiKey: 'your-api-key'
});

Getting Job Applications

import { GetJobApplicationsParams, ApplicationStatus } from '@apploitech/apploi-client';

const params: GetJobApplicationsParams = {
  // All parameters are optional and strongly-typed
  jobId: 12345,                          // number or string
  teamId: 67890,                         // number or string
  status: ApplicationStatus.SCREENING,   // Enum value
  updatedAfter: new Date('2024-01-01'),  // Date object
  updatedBefore: new Date('2024-12-31'), // Date object
  limit: 50,                             // number (1-1000)
  offset: 0,                             // number (>= 0)
  includeArchived: false                 // boolean
};

try {
  const result = await client.getJobApplications(params);

  // Access strongly-typed response
  for (const applicant of result.applicants) {
    console.log(`${applicant.name} - ${applicant.status}`);
    console.log(`Applied: ${applicant.createdAt}`);
    console.log(`Email: ${applicant.email}`);
  }

  // Pagination information
  console.log(`Total: ${result.pagination.total}`);
  console.log(`Has more: ${result.pagination.hasMore}`);
} catch (error) {
  // Handle errors (see Error Handling section)
}

Working with Application Status

import { ApplicationStatus } from '@apploitech/apploi-client';

// Use the enum for type safety
const status = ApplicationStatus.HIRED;

// Available statuses:
// - ApplicationStatus.APPLIED
// - ApplicationStatus.SCREENING
// - ApplicationStatus.INTERVIEWING
// - ApplicationStatus.REFERENCE_CHECK
// - ApplicationStatus.OFFER_EXTENDED
// - ApplicationStatus.HIRED
// - ApplicationStatus.REJECTED
// - ApplicationStatus.WITHDRAWN
// - ApplicationStatus.ON_HOLD
// - ApplicationStatus.UNKNOWN (fallback for unrecognized values)

Error Handling

The adapter provides a custom exception hierarchy for better error handling:

import {
  ApploiValidationError,
  ApploiAuthenticationError,
  ApploiAPIError,
  ApploiResponseParseError
} from '@apploitech/apploi-client';

try {
  const result = await client.getJobApplications({ limit: 2000 }); // Invalid!
} catch (error) {
  if (error instanceof ApploiValidationError) {
    // Parameter validation failed
    console.error(`Field ${error.field} is invalid:`, error.message);
    console.error('Provided value:', error.value);
  } else if (error instanceof ApploiAuthenticationError) {
    // 401 or 403 status code
    console.error('Auth failed:', error.statusCode, error.message);
  } else if (error instanceof ApploiAPIError) {
    // Other API errors
    console.error('API error:', error.statusCode, error.message);
    console.error('Response:', error.response);
  } else if (error instanceof ApploiResponseParseError) {
    // Failed to parse API response
    console.error('Parse error:', error.message);
    console.error('Raw response:', error.rawResponse);
  }
}

Type Definitions

JobApplication

interface JobApplication {
  id: string;
  jobId: string;
  teamId?: string;
  status?: ApplicationStatus;
  firstName?: string;
  lastName?: string;
  name: string;
  email?: string;
  phone?: string;
  createdAt?: Date;
  updatedAt?: Date;
  source?: string;
  address?: Address;
  resume?: Attachment;
  coverLetter?: Attachment;
  attachments?: Attachment[];
  notes?: string;
  tags?: string[];
  score?: number;
  isPriority?: boolean;
  // ... and more fields
}

ApplicantsList

interface ApplicantsList {
  applicants: JobApplication[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
}

Validation Rules

The adapter validates all inputs before making API calls:

limit: Must be between 1 and 1000
offset: Must be >= 0
IDs: Can be numbers or strings, automatically converted
Dates: Accept Date objects or ISO strings, converted to YYYY-MM-DD format
Status: Must be a valid ApplicationStatus enum value

Advanced Usage

Access the Underlying SDK

If you need to access the raw Fern SDK for any reason:

const sdkClient = client.getSdkClient();
// Use raw SDK methods if needed

Custom Validators

You can also use the validators directly:

import { validateLimit, validateId, validateAndConvertDate } from '@apploitech/apploi-client';

// Validate parameters before use
const limit = validateLimit(50);        // Returns "50"
const id = validateId(12345, 'jobId');  // Returns "12345"
const date = validateAndConvertDate(new Date(), 'startDate'); // Returns "YYYY-MM-DD"

Building the Project

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run linter
npm run lint

# Format code
npm run format