TypeScript SDK

The @apso/sdk is a TypeScript client for interacting with APSO services via their OpenAPI-compliant CRUD API. It provides both a fluent query builder and a low-level HTTP interface, with full compatibility with NestJS CRUD query syntax out of the box.

Key Features

Fluent Query Builder — Chain .where(), .orderBy(), .limit(), and more to construct queries without string manipulation
NestJS CRUD Compatible — Generates query strings that work directly with @nestjsx/crud and @dataui/crud backends
Dual HTTP Client — Choose between fetch (default, zero-dependency) or axios for the transport layer
Singleton Factory — ApsoClientFactory ensures one client instance per configuration, preventing resource leaks
Built-in Retry — Configurable retry with exponential backoff for transient failures (408, 429, 5xx)
Request Caching — Optional in-memory cache with configurable TTL for GET requests
TypeScript First — Written in TypeScript with full type definitions included

Quick Start


import { ApsoClientFactory } from '@apso/sdk';
 
const client = ApsoClientFactory.getClient({
  baseURL: 'https://your-service.apso.cloud',
  apiKey: 'your-api-key',
});
 
// Fluent query builder
const activeUsers = await client.entity('Users')
  .where({ status: { $eq: 'Active' } })
  .orderBy({ created_at: 'DESC' })
  .limit(10)
  .findMany();
 
// Create a record
const newUser = await client.entity('Users')
  .create({ name: 'Jane Doe', email: 'jane@example.com', status: 'Active' });
 
// Update a record by ID
const updated = await client.entity('Users')
  .where({ id: 'user-123' })
  .update({ status: 'Inactive' });
 
// Delete a record by ID
await client.entity('Users')
  .where({ id: 'user-123' })
  .remove();

How It Works

The SDK translates your fluent method calls into NestJS CRUD-compatible query strings. For example:


client.entity('WorkspaceServices')
  .where({ status: { $eq: 'Active' }, build_status: { $eq: 'Ready' } })
  .orderBy({ created_at: 'DESC' })
  .limit(10)
  .page(1)
  .cache(true)
  .findMany();

Produces the following HTTP request:


GET /WorkspaceServices?filter=status||$eq||Active&filter=build_status||$eq||Ready&sort=created_at,DESC&limit=10&page=1&cache=0

This format is directly understood by any backend built with the APSO CLI, which uses @dataui/crud under the hood.

Two API Styles

The SDK provides two ways to interact with your backend.

Fluent Entity API (Recommended)

The entity API provides a chainable query builder with semantic CRUD methods:


// Read
const items = await client.entity('Products').where({ category: { $eq: 'Electronics' } }).findMany();
const item  = await client.entity('Products').where({ id: 'prod-1' }).findOne();
 
// Write
const created = await client.entity('Products').create({ name: 'Widget', price: 29.99 });
const updated = await client.entity('Products').where({ id: 'prod-1' }).update({ price: 24.99 });
await client.entity('Products').where({ id: 'prod-1' }).remove();

Low-Level HTTP API

For cases where you need direct control over the request:


// GET with query parameters
const response = await client.get('/Products', {
  filter: { category: { $eq: 'Electronics' } },
  sort: { created_at: 'DESC' },
  limit: 10,
  page: 1,
});
 
// POST
const created = await client.post('/Products', { name: 'Widget', price: 29.99 });
 
// PUT
const updated = await client.put('/Products/prod-1', { price: 24.99 });
 
// DELETE
await client.delete('/Products/prod-1');

SDK Sections

Installation — Install the package and verify your setup
Configuration — Client options, authentication, retry, and caching
CRUD Operations — Create, read, update, and delete with the entity API
Query Building — Filtering, sorting, pagination, joins, and field selection

Compatibility

Requirement	Version
Node.js	18+
TypeScript	5.0+ (recommended)
Backend	Any `@dataui/crud` / `@nestjsx/crud` compatible API

The SDK is published on npm as @apso/sdk under the MIT license.