TypeScript client

@sloose/api-client is not on npm yet. npm install @sloose/api-client finds nothing today. Until it is published, call the API directly: every route this client wraps is in the API reference, with the same paths, parameters and bodies described below.

Every path, parameter, body and response comes from the same document that generates the API reference, so the client cannot describe an endpoint the server does not have — and a route that changes shape breaks the build of code still using the old one.

Getting started

import { createClient } from '@sloose/api-client';

const sloose = createClient({
  token: process.env.SLOOSE_TOKEN!,
  environment: 'production',
});

const { templates } = await sloose.get('/orgs/{org}/templates', {
  params: { path: { org } },
});

get, post, put, patch and delete return the response body. Anything that is not a 2xx throws.

For local development, pass an origin instead of an environment:

const sloose = createClient({ baseUrl: 'http://localhost:8787', token });

Handling refusals

Refusals use a closed set of codes, so catching and switching is the intended shape:

import { isApiError } from '@sloose/api-client';

try {
  const run = await sloose.post('/entitlements/runs/authorise', {
    body: { declaredRows: rows.length, templateId: null },
  });
} catch (err) {
  if (!isApiError(err)) throw err;

  if (err.code === 'LIMIT_RUNS' || err.code === 'LIMIT_ROWS_PER_RUN') {
    // err.body carries runsRemaining, or rowsPerRun
    return offerUpgrade();
  }
  throw err;
}

SlooseApiError carries:

status	the HTTP status
code	the machine-readable reason, when there is one
body	the whole parsed body — issues, balance, template, missing
response	the raw Response, for headers
isReason	whether this is a plan or status refusal rather than a bad request

A request that never reached the API throws SlooseNetworkError instead, so a dropped connection is never mistaken for a rejection.

Reason codes as a value

import { REASON_CODES, isReasonCode, type ReasonCode } from '@sloose/api-client';

Exported as an array as well as a type, so you can switch exhaustively and have the compiler tell you when a new one appears.

Escape hatch

sloose.raw is the underlying openapi-fetch client, if you would rather have { data, error } than exceptions, or want to add middleware:

const { data, error, response } = await sloose.raw.GET('/health');

Authentication

A session token and an organisation API token both work on the organisation’s routes, except the ones that take a session only — Authentication lists them, and each is marked Session only in the API reference.