@bara-agency/sisu

Server-side TypeScript SDK for the SISU API.

Install

npm install @bara-agency/sisu

Usage

import { createSisuClient } from "@bara-agency/sisu";

const sisu = createSisuClient({
  auth: {
    type: "apiKey",
    apiKey: process.env.SISU_API_KEY!,
  },
});

You can also use username/password Basic auth when needed:

import { createSisuClient } from "@bara-agency/sisu";

const sisu = createSisuClient({
  auth: {
    type: "basic",
    username: process.env.SISU_API_USERNAME!,
    password: process.env.SISU_API_PASSWORD!,
  },
});

const activities = await sisu.activities.getActivities({
  path: {
    agent_id: 123,
    market_id: 456,
  },
});

The SDK is designed for server-side Node.js usage. Do not call SISU directly from browser code because authorization credentials would be exposed to users.

Request input shape

Prefer explicit channels:

• path — path template values (/v3/contacts/{contact_id})
• query — query-string filters and pagination
• body — typed JSON or multipart field object
• formData — caller-built FormData for uploads (wins over body when both are set)

await sisuV3.contact.getContacts({
  query: { page: 1, per_page: 25 },
});

await sisuV3.tasks.postTask({
  body: {
    name: "Follow up",
    client_id: 42,
    task_type: "task",
    date_type: "absolute",
  },
});

Convenience still supported:

• On GET, values in body are merged into the query string (explicit query wins on key conflicts).
• On POST/PUT/PATCH/DELETE, known OpenAPI query param names found in a plain-object body are lifted into the query string and removed from the JSON body.
• Path params may be supplied via path, or (for plain-object bodies) lifted from matching body fields.
• An explicit empty plain-object body: {} is still sent as {} (it is not dropped).
• Pass uploads via formData; it is sent as-is and is never emptied by lifting.

Multipart uploads

Endpoints marked requestBodyContentType: "multipart" accept either a plain object on body (auto-converted to FormData) or a caller-built FormData on formData:

const form = new FormData();
form.append("files", fileBlob, "doc.pdf");

await sisuV3.documents.postDocuments({
  formData: form,
});

Legacy v1/v2 generated inputs use the same path / query / body / formData channels. v2 docs do not currently extract typed query params, so query remains the open SisuQueryParams bag (GET filters can still be passed via body and are merged into the query string).

SISU v3 API

The v3 API uses a separate client surface and authentication model. Every v3 request requires these headers:

• team-id
• Agent-Authorization

For v3-only usage (smaller import surface), use the dedicated subpath:

import { createSisuV3Client } from "@bara-agency/sisu/v3";

Or import from the main package:

import { createSisuV3Client } from "@bara-agency/sisu";

const sisuV3 = createSisuV3Client({
  auth: {
    teamId: process.env.SISU_V3_TEAM_ID!,
    agentAuthorization: process.env.SISU_V3_AGENT_AUTHORIZATION!,
  },
});

const contacts = await sisuV3.contact.getContacts({
  query: {
    page: 1,
    per_page: 25,
  },
});

Use createSisuClient for legacy v1/v2 endpoints and createSisuV3Client for v3 endpoints. The two clients are intentionally separate because they use different auth contracts.

Migrating to 0.3.0 (breaking)

This release is a breaking change from @bara-agency/[email protected]. Bump your dependency to 0.3.0 (do not republish or pin over 0.2.0).

If you already consume generated v3 input types:

1. Move list/filter fields from body to query for GET endpoints (e.g. getContacts).
2. Expect some previously optional body/query fields to be required when OpenAPI marks them required; method input is required when any path/body/query field is required. Runtime still does not validate required fields — this is a TypeScript-only enforcement.
3. Move caller-built uploads from body: formData to formData: formData. Plain objects for multipart endpoints still go on body.
4. SisuEndpointDefinition now includes queryParams and requestBodyContentType.
5. Empty plain-object bodies (body: {}) are sent as {} instead of omitting the request body.

Regenerating Endpoints

v3 endpoints are extracted from the public SISU PWA API docs (no login required):

npm run extract:docs:v3
npm run generate:v3

Source: sisu-web-api.readme.io

The extractor caches the docs index at data/sisu-v3-llms.txt and per-endpoint markdown under data/sisu-v3-docs-cache/, so re-runs work offline and avoid readme.io rate limits. To refresh the remote index once limits clear:

SISU_V3_REFRESH_LLMS=1 npm run extract:docs:v3

Legacy v1/v2 endpoints still require a logged-in docs session on docs.sisu.co:

npm run auth:docs
SISU_DOCS_STORAGE_STATE=./storage-state.json npm run extract:docs
npm run generate

Development

npm install
npm test
npm run check
npm run build