@sencai-space/sdk (TypeScript)

TypeScript/JavaScript klient pro Sencai Platform API (/api/v1/*), generovaný z veřejného OpenAPI specu (sencai.space/openapi/sencai-platform.public.v1.yaml, výstup F4.DEVPORTAL.01).

Balíček zatím není publikovaný na npm registry. Veřejná distribuce je obchodní/release rozhodnutí mimo scope F4.DEVPORTAL (viz PHASE-4-PLAN.md, modul přehled DEVPORTAL). Do doby publikace se instaluje jen z monorepo cesty nebo přímo z gitu.

Co je (ne)generované

Tento adresář je z většiny generovaný (src/, package.json, tsconfig.esm.json, docs/) přes scripts/sdk-generate.sh — jeden vstup (veřejný OpenAPI spec) → openapi-generator-cli (typescript-fetch generátor) → tři jazykové klienty najednou (TS/Python/Go), viz komentář v tom skriptu.

Ručně psané a chráněné přes .openapi-generator-ignore (regenerace je nikdy nepřepíše):

• tento README.md
• CHANGELOG.md
• .env.example
• tsconfig.json (strict: true dle repo konvence + poznámka k noImplicitAny výjimce)

⚠️ Regenerace je dnes nefunkční. scripts/sdk-generate.sh čte spec z sencai.space/openapi/sencai-platform.public.v1.yaml — sencai.space (Strapi) byl ale smazán 2026-07-30, adresář v monorepu vůbec neexistuje. Skript proto skončí hned na úvodní kontrole existence souboru. Committed generovaný kód (src/) zůstává buildovatelný — je jen zamrzlý na posledním stavu specu, dokud nevznikne nový zdroj (typicky vygenerovaný z sencai-backend, Go náhrady Strapi).

Regenerace po změně specu (až bude mít skript kde číst):

cd sencai.space && npm run openapi:generate   # F4.DEVPORTAL.01, pokud se spec změnil
cd .. && ./scripts/sdk-generate.sh

Instalace

npm install @sencai-space/sdk

Z monorepa (vývoj proti rozpracovanému klientovi):

npm install ./packages/sdk-ts

Použití

import { Configuration, CloudInstanceApi, OrganisationApi } from '@sencai-space/sdk';

const config = new Configuration({
  basePath: 'https://api.sencai.space/api/v1', // nebo http://api.sencai.localhost/api/v1 lokálně
  accessToken: async () => myKeycloakAccessToken, // Bearer JWT — nebo budoucí API-key header,
                                                    // viz `security` sekce specu (bearerAuth /
                                                    // apiTokenAuth) — SDK jen umožňuje injection,
                                                    // neřeší, jak token získat
});

const cloudInstances = new CloudInstanceApi(config);
const { data } = await cloudInstances.findCloudInstance();

Configuration.basePath i accessToken jsou vždy konfigurovatelné v konstruktoru — balíček neobsahuje žádnou hardcoded produkční URL.

Build & typecheck

npm install
npm run build       # tsc (CJS → dist/) + tsc -p tsconfig.esm.json (ESM → dist/esm/)
npx tsc --noEmit    # strict typecheck bez emitu

Verzování

Verze balíčku (package.json → version) je odvozená z info.version veřejného OpenAPI specu při každé regeneraci — není bumpovaná ručně. Breaking change v API → nová major verze specu → SDK breaking change, zdokumentovat v CHANGELOG.md s odkazem na doc.sencai.space/dev/api-versioning (SUNSET_DATE konvenci).

Distribuce

Do konzumujících frontend/service projektů dle stejné vendoring konvence jako @sencai/audit (viz packages/README.md), dokud nebude schválená veřejná npm publikace.