Maintainers Guide

Ten dokument zbiera informacje operacyjne dla utrzymania repozytorium. README pozostaje zwięzły i skupiony na użytkowniku SDK.

Wymagania

Node.js >= 20
npm
lokalne repo ksef-api (do kontroli zgodności OpenAPI) albo pobrany open-api.json

Instalacja:

npm ci

Kontrola jakości:

npm run lint
npm run typecheck
npm run test:coverage

Uwaga: CI wymaga 100% coverage (statement/branch/function/line).

Aktualny target kompatybilności repo: KSeF API 2.7.0.

Źródło kontraktu: CIRFMF/ksef-api (open-api.json) lub live TEST: https://api-test.ksef.mf.gov.pl/docs/v2/openapi.json.

Regeneracja modeli:

npm run generate:openapi-models -- --openapi ../ksef-api/open-api.json --output src/types/openapi.generated.ts

Kontrola pokrycia endpointów:

npm run check:openapi-coverage -- --openapi ../ksef-api/open-api.json --src src/api

CI (.github/workflows/ci.yml) - lint, typecheck, testy i coverage.
E2E Auth Flows (.github/workflows/e2e-token.yml) - scenariusze token/XAdES dla TEST i DEMO.
Validate API Compliance (.github/workflows/validate-openapi.yml) - kontrola pokrycia endpointów.
Validate OpenAPI Models (.github/workflows/validate-models.yml) - pobranie OpenAPI, regeneracja modeli i diff.
Release Please (.github/workflows/release-please.yml) - automatyzacja wersjonowania i changeloga.
Publish to npm (.github/workflows/publish-npm.yml) - publikacja paczki po opublikowaniu GitHub Release.
Publish to GitHub Packages (.github/workflows/publish-github-packages.yml) - publikacja scoped package po opublikowaniu GitHub Release.
Release Published Validation (.github/workflows/release-published.yml) - walidacja opublikowanego release.

Używaj Conventional Commits (feat:, fix:, chore: itd.).
Release Please aktualizuje wersję i CHANGELOG.md automatycznie.
Po publikacji GitHub Release workflowy publish-npm.yml i publish-github-packages.yml publikują odpowiednio do npm i GitHub Packages.
npm publish musi odbywać się z publish-npm.yml, bo to ten workflow jest powiązany z npm Trusted Publishing.
Przed merge release PR upewnij się, że main zawiera wszystkie wymagane commity funkcjonalne.