TypeScript SDK

Official TypeScript/JavaScript SDK for Scalix Cloud

Install

bash

npm install @scalix-world/sdk

To update to the latest release: npm install @scalix-world/sdk@latest. Versions follow the platform API line; minor and patch updates are backwards-compatible.

The SDK is generated from the platform's OpenAPI spec (API v1.3.4 — 237 operations across 31 service areas). Every endpoint is an exported, fully-typed function — there is no client class to instantiate, and unused operations tree-shake out of your bundle.

Initialize

Import the operations you need and pass your API key in the options. The base URL defaults to https://api.scalix.world, so authentication is the only required config:

typescript

import { getMe, listFunctions } from "@scalix-world/sdk";
 
const opts = {
  headers: { Authorization: `Bearer ${process.env.SCALIX_API_KEY}` },
};
 
const { data: me, error } = await getMe(opts);
const { data: fns } = await listFunctions(opts);

You can also pass the key as auth: process.env.SCALIX_API_KEY — it's applied as a bearer token per each operation's security scheme — and override baseUrl per call if you're pointing at a different deployment.

Every call resolves to a result envelope — no exceptions by default:

typescript

const { data, error, response } = await getMe(opts);
if (error) {
  console.error(error.code, error.error); // typed ErrorResponse
} else {
  console.log(data.identity.org_id, data.tools);
}

Database

executeSql returns a typed result set:

typescript

import { executeSql } from "@scalix-world/sdk";
 
const { data, error } = await executeSql({
  ...opts,
  body: { query: "SELECT id, email FROM users WHERE active = true" },
});
 
if (data) {
  console.log(data.columns);     // ["id", "email"]
  console.log(data.row_count);   // rows returned
  console.log(data.duration_ms); // server-side execution time
}

The body also accepts params for $1, $2, … placeholders, and batchSql runs multiple statements in one round trip. naturalLanguageToSql, optimizeQuery, and detectAnomalies cover the rest of the database surface.

Functions

typescript

import { invokeFunction, listFunctions } from "@scalix-world/sdk";
 
const { data: fns } = await listFunctions(opts);
 
const { data: result } = await invokeFunction({
  ...opts,
  path: { id: "process-order" }, // function id or name
  body: { order_id: "ord_123" },
});

createFunction, updateFunction, getFunctionLogs, and listFunctionInvocations are also exported.

Storage

Objects are raw bytes (application/octet-stream):

typescript

import { getObject, listBuckets, putObject } from "@scalix-world/sdk";
 
await putObject({
  ...opts,
  path: { bucket: "my-bucket", key: "notes/hello.txt" },
  body: "hello world",
});
 
const { data } = await getObject({
  ...opts,
  path: { bucket: "my-bucket", key: "notes/hello.txt" },
});
 
const { data: buckets } = await listBuckets(opts);

createBucket, deleteObject, headObject, and presignObject (presigned URLs) round out the surface.

AI Chat Completions

The request/response envelope is OpenAI-compatible:

typescript

import { chatCompletion } from "@scalix-world/sdk";
 
const { data, error } = await chatCompletion({
  ...opts,
  body: {
    model: "scalix-lumio-lite",
    messages: [{ role: "user", content: "Hello!" }],
  },
});
 
if (data) {
  console.log(data.model);
  console.log(data.choices); // completion choices (message + finish reason)
  console.log(data.usage);   // prompt/completion/total token counts
}

For streaming, streamChatCompletion posts to /v1/ai/chat/completions/stream and the response is server-sent events — pass parseAs: "stream" in the options to consume the raw stream. The AI surface also exports createEmbeddings, listModels, image generation, speech, transcription, RAG, research, and text utilities.

Vectors

The vectors surface supports collections, single and batch upsert (one multi-row write), and nearest-neighbour search with metadata filtering. Operations are scoped to your database tenant id (UUID):

typescript

import { batchUpsertVectors, searchVectors } from "@scalix-world/sdk";
 
const tenantId = "00000000-0000-0000-0000-000000000000"; // your database tenant UUID
 
// Batch upsert with per-vector metadata
await batchUpsertVectors({
  ...opts,
  path: { tenant_id: tenantId },
  body: {
    collection: "docs",
    entries: [
      { id: "doc-1", embedding: [0.12, 0.51, 0.33], metadata: { lang: "en" } },
    ],
  },
});
 
// Search with a metadata filter
const { data: matches } = await searchVectors({
  ...opts,
  path: { tenant_id: tenantId },
  body: {
    collection: "docs",
    query_vector: [0.10, 0.48, 0.30],
    top_k: 5,
    filter: { lang: "en" },
  },
});

Generate embeddings with createEmbeddings, then upsert them here. upsertVectors and listVectorCollections complete the surface.

KV Store

Values are JSON objects; ttl is optional, in seconds:

typescript

import { kvDel, kvGet, kvSet } from "@scalix-world/sdk";
 
await kvSet({
  ...opts,
  body: { key: "user:123", value: { name: "Alice" }, ttl: 3600 },
});
 
const { data: value } = await kvGet({
  ...opts,
  body: { key: "user:123" },
});
 
await kvDel({ ...opts, body: { keys: ["user:123"] } });

Error Handling

Calls don't throw by default — check the typed error field:

typescript

import { executeSql } from "@scalix-world/sdk";
 
const { data, error } = await executeSql({
  ...opts,
  body: { query: "SELECT * FROM users" },
});
 
if (error) {
  console.error(error.code);       // stable machine-readable code, e.g. "AUTH_FAILED"
  console.error(error.error);      // human-readable message
  console.error(error.request_id); // correlation id for support
}

Prefer exceptions? Pass throwOnError: true — the promise rejects with the error body and the result narrows to { data, request, response }:

typescript

try {
  const { data } = await getMe({ ...opts, throwOnError: true });
  console.log(data.identity.org_id);
} catch (err) {
  // rejected with the error body
}

All request and response types are exported (SqlRequest, SqlResponse, ChatCompletionRequest, VectorSearchRequest, MeResponse, ErrorResponse, …) if you need to type your own wrappers.