TypeScript SDK

The official TypeScript SDK provides a type-safe and convenient way to interact with the Financeable Aggregation API from Node.js applications. The SDK is built using Speakeasy and provides full TypeScript support.

Installation

Install the SDK using your preferred package manager:

npm add @financeable/aggregation

pnpm add @financeable/aggregation

yarn add @financeable/aggregation

bun add @financeable/aggregation

Quick Start

import { Financeable } from "@financeable/aggregation";

const financeable = new Financeable({
  serverURL: "https://your-tenant.api.financeable.com.au",
});

async function run() {
  // Obtain an OAuth token
  const tokenRequest = await financeable.oauthToken.get({
    grantType: 'client_credentials',
    clientId: process.env["CLIENT_ID"],
    clientSecret: process.env["CLIENT_SECRET"],
    scope: 'application:read application:write',
  });

  // Use the token to make authenticated requests
  const result = await financeable.applications.list({
    fetchOptions: {
      headers: {
        authorization: `Bearer ${tokenRequest.accessToken}`,
      },
    },
  });

  console.log(result);
}

run();

Configuration

Basic Configuration

The SDK can be initialized with the following options:

import { Financeable } from "@financeable/aggregation";

const financeable = new Financeable({
  // Required: Your tenant's server URL
  serverURL: "https://your-tenant.api.financeable.com.au",

  // Optional: Custom retry configuration
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },

  // Optional: Custom timeout in milliseconds
  timeoutMs: 30000,

  // Optional: Enable debug logging
  debugLogger: console,
});

Environment Variables

Store your OAuth credentials in environment variables:

CLIENT_ID=your_client_id_here
CLIENT_SECRET=your_client_secret_here
FINANCEABLE_DEBUG=true  # Enable debug logging

Authentication

The SDK uses OAuth 2.0 client credentials flow for authentication. You can obtain an access token using the oauthToken resource:

const tokenRequest = await financeable.oauthToken.get({
  grantType: 'client_credentials',
  clientId: process.env["CLIENT_ID"],
  clientSecret: process.env["CLIENT_SECRET"],
  scope: 'application:read application:write',
});

// Use the token in subsequent requests
const result = await financeable.applications.create({
  data: { /* ... */ }
}, {
  fetchOptions: {
    headers: {
      authorization: `Bearer ${tokenRequest.accessToken}`,
    },
  },
});

Available Resources

The SDK provides access to the following resources:

Applications

Create, list, and retrieve loan applications:

// First, obtain an OAuth token
const tokenRequest = await financeable.oauthToken.get({
  grantType: 'client_credentials',
  clientId: process.env["CLIENT_ID"],
  clientSecret: process.env["CLIENT_SECRET"],
  scope: 'application:read application:write',
});

const authHeader = {
  fetchOptions: {
    headers: {
      authorization: `Bearer ${tokenRequest.accessToken}`,
    },
  },
};

// List all applications
const applications = await financeable.applications.list(authHeader);

// Get a specific application
const application = await financeable.applications.get("application-id", authHeader);

// Create a new application
const newApplication = await financeable.applications.create({
  data: {
    type: "consumer-secured-applications",
    attributes: {
      applicationType: "consumerSecured",
      associatedBrokerEmail: "broker@example.com",
    },
    relationships: {
      customers: {
        data: [
          {
            type: "customers",
            attributes: {
              title: "Mr",
              firstName: "John",
              lastName: "Smith",
              dateOfBirth: "1985-06-15",
              idExpiryDate: "2030-12-31",
            },
            relationships: {
              addresses: {
                data: [
                  {
                    type: "addresses",
                    attributes: {
                      addressType: "residential",
                      fullAddress: "42 Wallaby Way, Sydney NSW 2000",
                      city: "Sydney",
                      postCode: "2000",
                      streetAddress: "42 Wallaby Way",
                      streetNumber: "42",
                      streetType: "Way",
                      street: "Wallaby",
                      state: "NSW",
                      country: "Australia",
                      status: "current",
                      monthsAt: 24,
                      yearsAt: 2,
                    },
                  },
                ],
              },
            },
          },
        ],
      },
      asset: {
        data: {
          type: "assets",
          attributes: {
            assetType: "MOTOR_VEHICLE",
            ageOfAsset: 3,
            ageOfAssetAtEnd: 8,
            condition: "USED",
            assetValue: "35000.00",
            make: "Toyota",
            assetModel: "Camry",
            registrationNumber: "ABC123",
            registrationState: "VIC",
            vin: "1HGCM82633A123456",
          },
        },
      },
    },
  },
}, authHeader);

OAuth Token

Obtain OAuth access tokens:

const token = await financeable.oauthToken.get({
  grantType: "client_credentials",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  scope: "application:read application:write",
});

Supporting Documents

Create supporting document records and get pre-signed upload URLs:

const document = await financeable.supportingDocuments.create({
  // Document creation parameters
}, {
  fetchOptions: {
    headers: {
      authorization: `Bearer ${tokenRequest.accessToken}`,
    },
  },
});

Error Handling

The SDK provides structured error handling using the FinanceableError base class:

import { Financeable } from "@financeable/aggregation";
import * as errors from "@financeable/aggregation/models/errors";

const financeable = new Financeable({
  serverURL: "https://your-tenant.api.financeable.com.au",
});

async function run() {
  // Obtain an OAuth token
  const tokenRequest = await financeable.oauthToken.get({
    grantType: 'client_credentials',
    clientId: process.env["CLIENT_ID"],
    clientSecret: process.env["CLIENT_SECRET"],
    scope: 'application:read application:write',
  });

  try {
    const result = await financeable.applications.get("invalid-id", {
      fetchOptions: {
        headers: {
          authorization: `Bearer ${tokenRequest.accessToken}`,
        },
      },
    });
    console.log(result);
  } catch (error) {
    if (error instanceof errors.FinanceableError) {
      console.error("Error message:", error.message);
      console.error("Status code:", error.statusCode);
      console.error("Response body:", error.body);
      console.error("Response headers:", error.headers);
    } else if (error instanceof errors.SDKValidationError) {
      // Schema validation error
      console.error(error.pretty());
    } else {
      // Other errors (network, timeout, etc.)
      throw error;
    }
  }
}

run();

Error Classes

Primary error:

FinanceableError: Base class for HTTP error responses with statusCode, message, body, and headers properties

Network errors:

ConnectionError: HTTP client unable to connect to server
RequestTimeoutError: Request timed out
RequestAbortedError: Request was aborted
InvalidRequestError: Invalid input used to create request
UnexpectedClientError: Unrecognized error

Validation errors:

ResponseValidationError: Type mismatch between server response and SDK schema (use error.pretty() for formatted output)

Retries

The SDK supports configurable retry strategies for failed requests:

// Configure retries globally
const financeable = new Financeable({
  serverURL: "https://your-tenant.api.financeable.com.au",
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

// Or configure per-request
const result = await financeable.applications.create({
  data: { /* ... */ }
}, {
  fetchOptions: {
    headers: {
      authorization: `Bearer ${tokenRequest.accessToken}`,
    },
  },
  retries: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

Standalone Functions

All SDK methods are available as standalone functions for use in environments where bundle size is critical (e.g., browsers, serverless):

import { applicationsList } from "@financeable/aggregation/funcs/applicationsList";
import { oauthTokenGet } from "@financeable/aggregation/funcs/oauthTokenGet";

// Obtain token
const tokenRequest = await oauthTokenGet({
  grantType: 'client_credentials',
  clientId: process.env["CLIENT_ID"],
  clientSecret: process.env["CLIENT_SECRET"],
  scope: 'application:read application:write',
});

// Use with authentication
const applications = await applicationsList({
  fetchOptions: {
    headers: {
      authorization: `Bearer ${tokenRequest.accessToken}`,
    },
  },
});

For more details, see FUNCTIONS.md in the SDK repository.

Custom HTTP Client

You can provide a custom HTTP client for advanced use cases like adding custom headers or hooks:

import { Financeable } from "@financeable/aggregation";
import { HTTPClient } from "@financeable/aggregation/lib/http";

const httpClient = new HTTPClient({
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });
  nextRequest.headers.set("x-custom-header", "custom value");
  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.error(`Request Error: ${error}`);
  console.error(`Endpoint: ${request.method} ${request.url}`);
});

const sdk = new Financeable({
  serverURL: "https://your-tenant.api.financeable.com.au",
  httpClient,
});

Debugging

Enable debug logging to see HTTP request and response details:

const financeable = new Financeable({
  serverURL: "https://your-tenant.api.financeable.com.au",
  debugLogger: console,
});

Or set the FINANCEABLE_DEBUG environment variable to true.

Warning: Debug logging will reveal sensitive information like API tokens in headers. Only use during local development.

TypeScript Support

The SDK is written in TypeScript and provides full type definitions for all API resources and operations. Your IDE will provide autocomplete and type checking out of the box.