Installation

Install the @apso/sdk package in your JavaScript or TypeScript project.

Requirements

• Node.js 18.0 or higher
• TypeScript 5.0+ (recommended for full type inference)

Install via npm

npm install @apso/sdk

Install via yarn

yarn add @apso/sdk

Install via pnpm

pnpm add @apso/sdk

TypeScript Support

The SDK is written in TypeScript and ships with type definitions (dist/index.d.ts). No additional @types packages are needed.

Dependencies

The SDK installs the following runtime dependencies:

Note: When using the default fetch transport, axios is still installed as a dependency but is not loaded at runtime unless you explicitly set client: 'axios' in your configuration.

Verify Installation

Create a quick test to confirm the SDK is installed correctly:

import { ApsoClientFactory } from '@apso/sdk';
 
const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
});
 
async function verify() {
  try {
    const result = await client.entity('Health').findMany();
    console.log('SDK connected successfully:', result);
  } catch (error) {
    console.error('Connection failed:', error);
  }
}
 
verify();

Basic Setup

Create a shared client module that you import throughout your application:

import { ApsoClientFactory } from '@apso/sdk';
 
export const apso = ApsoClientFactory.getClient({
  baseURL: process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
});

Then use it in your application code:

import { apso } from '../lib/apso';
 
export async function getActiveUsers() {
  return apso.entity('Users')
    .where({ status: { $eq: 'Active' } })
    .orderBy({ created_at: 'DESC' })
    .findMany();
}

Framework-Specific Setup

Next.js

For Next.js applications, configure the client in a shared module. Use the APSO_API_URL environment variable (server-only) or NEXT_PUBLIC_APSO_API_URL if you need client-side access:

import { ApsoClientFactory } from '@apso/sdk';
 
export const apso = ApsoClientFactory.getClient({
  baseURL: process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
});

Node.js / Express

import { ApsoClientFactory } from '@apso/sdk';
 
export const apso = ApsoClientFactory.getClient({
  baseURL: process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
  client: 'axios',  // Use axios for Node.js environments
  timeout: 10000,
});

Testing Setup

For tests, install axios-mock-adapter as a dev dependency to mock HTTP requests:

npm install --save-dev axios-mock-adapter @types/axios-mock-adapter

See the Operations page for complete testing examples.

Updating the SDK

npm update @apso/sdk

Check the current installed version:

npm list @apso/sdk

Troubleshooting

”Cannot find module ‘@apso/sdk’”

Make sure the package is installed in your project (not globally):

npm install @apso/sdk

TypeScript Compilation Errors

Ensure your tsconfig.json includes the following settings:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "target": "ES2018"
  }
}

Network / Connection Errors

If you see ECONNREFUSED or timeout errors:

1. Verify your baseURL is correct and the service is running
2. Check that your apiKey is valid
3. Confirm that no firewall or proxy is blocking the connection
4. Try increasing the timeout value in your configuration

Next Steps

• Configure the client
• Learn about queries