TypeScript SDK — Začínáme

@sencai/sdk je TypeScript/JavaScript klient pro Sencai Platform API (/api/v1/*), generovaný z veřejného OpenAPI specu (openapi-generator-cli, šablona typescript-fetch — F4.DEVPORTAL.02). Žije v monorepu na packages/sdk-ts/.

Instalace

@sencai/sdk zatím není publikovaný na npm — veřejná distribuce balíčku je samostatné obchodní/release rozhodnutí, mimo scope samotné práce na generování SDK. Do té doby instalovat z monorepo cesty nebo přímo z gitu:

# Uvnitř monorepa (npm workspace)
npm install ./packages/sdk-ts

# Mimo monorepo, přes git
npm install git+https://github.com/sencai-space/packages.git#path:sdk-ts

Inicializace klienta

import { Configuration, OrganisationApi } from "@sencai/sdk";

const config = new Configuration({
  // Lokální vývoj: http://api.sencai.localhost/api/v1 nebo http://localhost:1337/api/v1
  // Produkce: https://api.sencai.space/api/v1
  basePath: process.env.SENCAI_API_BASE_URL,
  // Bearer JWT (dnes Keycloak access token) — nebo budoucí API-key hlavička.
  // Klient jen umožňuje injection, sám token nezískává ani neobnovuje.
  accessToken: async () => process.env.SENCAI_ACCESS_TOKEN!,
});

const organisations = new OrganisationApi(config);

basePath i accessToken jsou vždy konstruktorové parametry — balíček nikdy neobsahuje hardcoded produkční URL.

Kompletní příklad: seznam organizací, pozvání člena

Ověřeno proti lokálnímu stacku run-local-dev.sh (profily backend, backend-db, auth).

import { Configuration, OrganisationApi } from "@sencai/sdk";

async function main() {
  const config = new Configuration({
    basePath: process.env.SENCAI_API_BASE_URL,
    accessToken: async () => process.env.SENCAI_ACCESS_TOKEN!,
  });
  const organisations = new OrganisationApi(config);

  // Seznam organizací, jejichž je volající členem.
  const list = await organisations.findOrganisation({ paginationPageSize: 10 });
  console.log(list.data.map((org) => org.name));
  // -> [ "QA Admin Workspace", "e2e-org-d18a54e2", "e2e-org-d9e67836" ]

  const targetOrg = list.data[0];
  if (!targetOrg?.documentId) return;

  // Pozvání existujícího Strapi uživatele do dané organizace. `POST
  // /organisations/{id}/invite` vyžaduje, aby zvaný email už měl
  // registrovaný účet (viz sekce Zpracování chyb níže, co se stane jinak)
  // a aby volající měl v organizaci roli admin+.
  const invite = await organisations.organisationInviteMember({
    id: targetOrg.documentId,
    organisationInviteMemberRequest: {
      email: "new-member@example.com",
      role: "viewer",
    },
  });
  console.log(invite.data);
  // -> { id: 1266, attributes: { email: "new-member@example.com", role: "viewer",
  //      invitedBy: "you@example.com", invitedAt: "2026-07-05T12:02:45.279Z", status: "pending" } }
}

main();

Zpracování chyb

Každá non-2xx odpověď vyhodí ResponseError (exportovaný z @sencai/sdk, re-exportovaný z jeho runtime modulu), který nese syrový Response objekt — typovaná metoda nikdy při chybě nevrátí částečně platný výsledek. Tělo chyby má standardní Strapi obálku: { error: { status, name, message, details } }.

import { ResponseError } from "@sencai/sdk";

try {
  await organisations.organisationInviteMember({
    id: targetOrg.documentId!,
    organisationInviteMemberRequest: { email: "new-member@example.com", role: "viewer" },
  });
} catch (err) {
  if (err instanceof ResponseError) {
    const body = await err.response.json();
    console.error(err.response.status, body.error.name, body.error.message);
    // Reálný, běžně narazitelný příklad — limit počtu členů z tarifu organizace:
    // 402 PaymentRequired "Member limit reached (3/3). Upgrade your plan."
    // body.error.details -> { limit: 3, current: 3, limit_source: "organisation_plan", ... }
  } else {
    throw err;
  }
}

Další stavové kódy, které lze u tohoto konkrétního endpointu očekávat: 400 (chybějící/neplatný email/role, nebo žádný Strapi uživatel s daným emailem — tento endpoint nezve ještě neregistrované emaily), 401 (chybějící/expirovaný token), 403 (volající nemá v organizaci roli admin+), 409 (daný uživatel je již členem).

Verzování SDK a breaking changes

Verze balíčku (package.json → version) je při každé regeneraci odvozená z info.version OpenAPI specu — nikdy se nebumpuje ručně. Breaking change API se vydá jako nová major verze specu, což přeregeneruje toto SDK také jako novou major verzi. Co se počítá jako breaking, migrační cestu /api/v1/ → /api/v2/ a konvenci deprecation hlavičky SUNSET_DATE viz Verzování API — tato stránka danou politiku neopakuje, jen popisuje, jak se projevuje v generovaném klientovi.

Kompletní generovanou referenci každé operace, kterou tento klient pokrývá, najdeš v API Reference.