includio-cms 0.21.0 → 0.23.0

package/API.md

@@ -1,4 +1,4 @@
-# includio-cms — Public API v0.21.0
+# includio-cms — Public API v0.23.0
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
@@ -13,19 +13,19 @@ Tags:
 
 ### `includio-cms`
 
-- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS instance and a user.
+- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS
 - `getAuth(): <inferred>` — Returns the underlying `better-auth` instance from the initialized CMS.
-- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
-- `interface ResolvedMedia`
-- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()`
+- `interface ResolvedMedia` — Resolved media file plus its image styles + blur placeholder. Returned by
+- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins or
 
 ### `includio-cms/core`
 
-- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS instance and a user.
+- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS
 - `getAuth(): <inferred>` — Returns the underlying `better-auth` instance from the initialized CMS.
-- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
-- `interface ResolvedMedia`
-- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()`
+- `interface ResolvedMedia` — Resolved media file plus its image styles + blur placeholder. Returned by
+- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins or
 
 ### `includio-cms/types`
 
@@ -239,11 +239,11 @@ Tags:
 ### `includio-cms/sveltekit`
 
 - `const CmsProvider: LegacyComponentType`
-- `defineCollection(config: CollectionInput): CollectionConfig` — Defines a collection (multi-entry content type).
+- `defineCollection(config: CollectionInput): CollectionConfig` — Defines a collection (multi-entry content type, e.g. blog posts, products).
 - `defineConfig(config: CMSConfig): CMSConfig` — Defines the root CMS configuration. Pass to `includioCMS()` in `hooks.server.ts`.
-- `defineForm(config: FormConfig): FormConfig` — Defines a public form (submitted via `/api/forms/[slug]/submit`).
-- `defineObject(config: Omit<ObjectField, 'type'>): ObjectField` — Defines a reusable object field (nested record). Use inside `fields[]`.
-- `defineSingle(config: SingleInput): SingleConfig` — Defines a singleton (single-entry content type, e.g. site settings).
+- `defineForm(config: FormConfig): FormConfig` — Defines a public form (submitted via `POST /api/forms/[slug]/submit`).
+- `defineObject(config: Omit<ObjectField, 'type'>): ObjectField` — Defines a reusable object field (nested record). Use inline inside `fields[]`
+- `defineSingle(config: SingleInput): SingleConfig` — Defines a singleton (single-entry content type, e.g. site settings, homepage).
 - `enableHybridEditing(): <inferred>` — Call in a layout/component script to enable data-hybrid-path rendering for all descendant HybridTarget/Image/Video.
 - `extractBlocks(doc: StructuredContentDoc, type?: string): SCNode[]` — Extract block-level nodes, optionally filtered by type.
 - `extractInlineBlocks(doc: StructuredContentDoc, blockType?: string): SCInlineBlockAttrs[]` — Extract inline block nodes, optionally filtered by blockType.
@@ -267,16 +267,16 @@ Tags:
 
 ### `includio-cms/sveltekit/server`
 
-- `cmsLayoutLoad(event: RequestEvent): <inferred>` — Returns `cmsContext` from `event.locals` for use in a SvelteKit layout `load`. Drop into your `+layout.server.ts`.
-- `countEntries(opts: CountEntriesOptions): Promise<number>` — Count entries matching the same filters as `resolveEntries`, without populating.
+- `cmsLayoutLoad(event: RequestEvent): <inferred>` — Returns `cmsContext` from `event.locals` for use in a SvelteKit layout
+- `countEntries(opts: CountEntriesOptions): Promise<number>` — Count entries matching the same filters as `resolveEntries`, without
 - `type CountEntriesOptions = Omit< ResolveEntriesOptions, 'limit' | 'offset' | 'populate' | 'orderBy' | 'dataOrderBy' >`
 - `const createConsentLog: <inferred>`
 - `const createFormSubmission: <inferred>`
-- `createRestApiHandler(): <inferred>` — REST API handler factory. Returns `{ GET, POST, PUT, DELETE }` `RequestHandler`s authenticated via `x-api-key` header. Mount in `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+- `createRestApiHandler(): <inferred>` — REST API handler factory. Returns `{ GET, POST, PUT, DELETE }`
 - `generateApiKey(): string` — Generate a cryptographically random API key (32 bytes, base64url-encoded).
-- `getPreviewEntry(event: RequestEvent, options: { language: string }): Promise<Entry | null>` — Resolves the preview entry from a `?preview=<versionId>` query param. Requires an authenticated session — throws `Unauthorized` otherwise.
-- `includioCMS(cmsConfig: CMSConfig): Handle[]` — SvelteKit `Handle[]` array that initializes the CMS, generates runtime artifacts, wires auth/admin guards, and exposes `event.locals.cmsContext`. Compose with `sequence()` in `hooks.server.ts`.
-- `parseFormDataForSubmission(formData: FormData, fields: FormField[]): Promise<Record<string, unknown>>` — Parses multipart `FormData` into a typed record of field values, handling file uploads via the configured files adapter.
+- `getPreviewEntry(event: RequestEvent, options: { language: string }): Promise<Entry | null>` — Resolves the preview entry from a `?preview=<versionId>` query param.
+- `includioCMS(cmsConfig: CMSConfig): Handle[]` — SvelteKit `Handle[]` array that initializes the CMS, generates runtime
+- `parseFormDataForSubmission(formData: FormData, fields: FormField[]): Promise<Record<string, unknown>>` — Parses multipart `FormData` into a typed record of field values, handling
 - `type PopulateConfig = { /** Hard cap on relation depth. Default 5. Use `0` to keep all relations as raw IDs. */ maxDept...` — Recursion + per-field opt-out config for relation population.
 - `resolveEntries(opts: ResolveEntriesOptions): Promise<Entry[]>` — Fetch a list of populated Entries from a collection (or singleton with multiple instances).
 - `interface ResolveEntriesOptions`
@@ -387,7 +387,7 @@ Tags:
 ### `includio-cms/files-local`
 
 - `const fullDir: <inferred>`
-- `local(config?: LocalFilesConfig): FilesAdapter` — Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or `/data/uploads` (prod).
+- `local(config?: LocalFilesConfig): FilesAdapter` — Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or
 - `interface LocalFilesConfig`
 
 ### `includio-cms/email-nodemailer`

package/CHANGELOG.md

@@ -3,6 +3,117 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.23.0 — 2026-04-30
+
+Faza 10 — Documentation Pass. DOCS.md uzupełniony (REST cURL + error codes, Entries error handling + transaction patterns, Admin UI a11y guide, Adapter Contracts z interfaces + peer deps + lazy import, Shop retry-payment lifecycle, edge cases dla number/boolean/date/datetime). Nowe sekcje: Stability Promise (semver, @public/@experimental/@internal, deprecation timeline) i Security Model (CSRF, CSP, rate-limit, API keys, link do KNOWN-RISKS.md). Migration Guide rozszerzony o master cheatsheet 0.x → 1.0 (agregat 0.16-0.22). ROADMAP cleanup: pre-v1.0 historia → ROADMAP-ARCHIVE.md.
+
+### Added
+- `docs/stability-promise/` — nowa strona: SemVer 2.0, JSDoc tagi (@public semver-protected, @experimental opt-in to change, @internal poza kontraktem), deprecation timeline (1 minor cycle z @deprecated → remove w MAJOR), reference do `API.md` jako single source of truth public surface.
+- `docs/security/` — nowa strona: threat model in/out of scope, CSRF (Origin/Referer guard na `/admin/api/*`), CSP (`default-src self`, `unsafe-inline` na script/style + uzasadnienie TipTap/Paraglide), rate limiting (200/60s admin, 5/h forms, env override), API keys (opt-in `expiresAt`, audit `rotatedAt`, `generateApiKey()`), Sharp 30s timeout, link do `KNOWN-RISKS.md` (5 zaakceptowanych ryzyk).
+- `docs/migration/` — sekcja "Migrating from 0.x to 1.0 — master cheatsheet": global find-replace (getEntry → resolveEntry, language → locale), per-version blocks dla 0.16.0, 0.18.0, 0.19.0, 0.20.0, 0.21.0, 0.22.0 z migration steps + code examples, suggested upgrade path (pnpm + check + db:push + test).
+- `docs/adapters/` — sekcja "Adapter contracts": tabela 4 interfaces (DatabaseAdapter 38 metod, FilesAdapter 5+3 optional, EmailAdapter 1+config, AIAdapter 1) z source paths, peer deps required vs optional, lazy import pattern (przykład `email-nodemailer`), error contracts, best practices (timeouts, retry, partial state).
+- `docs/api/` — REST cURL examples (GET/POST/PUT/DELETE, upload), tabela error responses (HTTP × `CmsError.code`: UNAUTHORIZED, ENTRY_NOT_FOUND, INVALID_DATA, MISSING_REQUIRED_PARAM, RATE_LIMITED, etc.), authentication (Bearer header), opt-in `expiresAt` w API keys. Remote Functions section zaktualizowana na `resolveEntry/resolveEntries/countEntries`.
+- `docs/entries/` — sekcja "Error handling" (CmsError instanceof + stable codes), sekcja "Transaction patterns" (last-write-wins versioning, custom Drizzle tx z `cms.db.driver`, plugin hooks vs partial failure). Querying przepisany na `resolveEntry/resolveEntries/countEntries` (status enum: published/draft/scheduled, archived = ops nie status).
+- `docs/admin-ui/` — sekcja "Accessibility": WCAG 2.1 AA targets per surface (color contrast, keyboard nav, focus management, skip-link, heading hierarchy, ARIA roles, reduced motion), pattern dla custom plugin panels.
+- `docs/shop/retry-payment/` — pełen lifecycle (5 kroków + ASCII diagram), server endpoint scaffold, headless SDK + `createOrderState`, error responses (400/401/404/409/429/502 z `CmsError.code`), constraints (same totals, token-gated, rate-limited, idempotent gateway, no auto-retry), admin override.
+- `docs/fields/{number,boolean,date,datetime}/` — sekcje "Edge cases": number (NaN/Infinity rejection, floating-point precision, integer-only via step:1, parseFloat guards), boolean (null vs false, no string coercion, defaultValue vs runtime backfill), date (no timezone, ISO-8601 calendar string, null handling, edge years), datetime (UTC storage + local render, DST traps, ISO datetime validation).
+- `ROADMAP-ARCHIVE.md` (root) — pełna historia 0.0.69 → 0.16.0 wycięta z `ROADMAP.md`. `ROADMAP.md` zawiera od teraz wyłącznie v1.0+ (header + legenda + v1.0 + v1.x + Security + Backlog), z linkiem do archive.
+- `_config/nav.ts` + `scripts/compile-docs.ts` — zsynchronizowane: dodane "Stability Promise" w Guides, "Security Model" w "Authentication & Security" (renamed z "Authentication"). Brakujący "InPost Carrier" w nav.ts dodany dla parity z compile-docs.
+
+### Notes
+
+Brak code changes — only docs + ROADMAP cleanup. DOCS.md regeneruje się przez `pnpm docs:compile` (część `prepublishOnly`). Po publikacji pełen TOC widoczny w DOCS.md z 10 zaktualizowanymi/nowymi sekcjami. Dla user-facing changes — żadnych. Dla devów customizujących admin UI lub piszących adaptery — pełny stable contract w jednym miejscu.
+
+## 0.22.0 — 2026-04-30
+
+Faza 9 — DX & config validation pass. `defineConfig()` waliduje config strict Zodem z czytelnymi błędami (path + hint), resolvery / operacje throwują typowane `CmsError` z `code` + `context`, CLI ma `--help` per subcommand i `--version`, README przepisany pod nowych userów (system requirements + 5-min quickstart), `.env.example` rozszerzony o wszystkie `INCLUDIO_*` envy, JSDoc na każdym `@public` symbolu (opis + `@param` + `@returns` + `@example`).
+
+### Added
+- `defineConfig()` (`includio-cms/sveltekit`) — runtime Zod validation z agregacją wszystkich błędów. Invalid config → `ConfigValidationError` (extends `CmsError`) z `issues[]` (path + message + hint), bullet-list message ready-to-paste do PR. `superRefine`: unique slugs (collections/singles/forms), default locale ≤ 1, relation targets w deklarowanych kolekcjach, `apiKeys[].permissions` referuje istniejące collection slugs.
+- `CmsError` + `ConfigValidationError` (`includio-cms` → `core/errors`) — bazowa klasa z `code` (SCREAMING_SNAKE_CASE), `context: Record<string, unknown>`, `cause?`. Stabilne kody: `ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`, `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`. `toString()` = `[CODE] message (k=v, k=v)`.
+- `formatZodDataIssues(error)` helper — render Zod errora z entry/form data jako lista `path: message`. Używany w `createEntryVersion`, `updateEntryVersion`, `createFormSubmission`.
+- CLI: `includio --help`, `includio scaffold admin --help`, `includio install-peers --help`, `includio create-user --help` — exit 0 + Usage/Options/Example block. `includio --version` / `-v` z `package.json`. Unknown command → exit 1 + top-level help.
+- `.env.example` rozszerzony — 11 envów z komentarzami i sekcjami (Required / Media & Uploads / Security & Rate Limits). Demo vars usunięte (były tylko dla `src/lib/demo/` skasowanego w Fazie 1).
+- README rebuild: TOC, sekcja **System requirements** (Node 18+, PG 14+, ffmpeg optional), 5-step **Quick start** (install → .env → config → scaffold → create-user → dev), poprawiony link do `DOCS.md`, dodana tabelka adapterów, sekcja CLI z subcommandami.
+- JSDoc bodies (opis + `@param` + `@returns` + `@example`) na każdym `@public` symbolu — `defineConfig`, `defineCollection`, `defineSingle`, `defineForm`, `defineObject`, `getCMS`, `resolveEntry`, `resolveEntries`, `countEntries`, `createFormSubmission`, `parseFormDataForSubmission`, `createConsentLog`, `resolveMediaWithStyles`, `createEntityAPI`, `createRestApiHandler`, `generateApiKey`, `getAuth`, `includioCMS`, `getPreviewEntry`, `cmsLayoutLoad`, factory adapterów (`pg`, `local`, `nodemailerAdapter`, `openAIAdapter`, `claudeAdapter`).
+
+### Fixed
+- `MISSING_REQUIRED_PARAM` zamiast `throw new Error('... is required')` w `resolveEntry` / `resolveEntries` / `countEntries`. Context zawiera `op` + `missing`.
+- `INVALID_DATA` zamiast `throw Error('Invalid data: ' + JSON.stringify(parsedData.error.flatten()))` w `createEntryVersion` / `updateEntryVersion` / `createFormSubmission`. Context zawiera `collection`/`entryId`/`lang` (entries) lub `formSlug` (forms). Body errora to czytelna lista `field.path: message`.
+- `ENTRY_NOT_FOUND` z `{ collection, id }` w `_getDbEntryOrThrow` / `_getRawEntryOrThrow`; `ENTRY_VERSION_NOT_FOUND` z `{ versionId, entryId, lang }` w `_getDbEntryVersionOrThrow`.
+
+### Breaking
+- **Strict config validation w `defineConfig`** — invalid configs które wcześniej "działały" w runtime (np. duplicate slug, brak default locale, relation do nieistniejącej kolekcji, brak metody w adapterze) **teraz throwują `ConfigValidationError` na starcie**. Najczęstsze przypadki + fix:
+  - **Duplicate slug**: dwie kolekcje/singles/forms z tym samym `slug` → unique slug per kategoria.
+  - **Invalid language code**: `code: 'ENGLISH'` → `code: 'en'` (ISO-639-1, opcjonalnie z regionem `'pl-PL'`).
+  - **Multiple default locales**: dwa `{ default: true }` → tylko jeden.
+  - **Missing adapter method**: stub adaptera bez `getEntries` etc. → zaimportuj pełen `pg()` / `local()` lub doimplementuj brakujące metody.
+  - **Invalid relation target**: `{ type: 'relation', collection: 'authors' }` przy braku kolekcji `authors` → dodaj kolekcję lub popraw target.
+- **Resolver / operation error format** — błędy z `resolveEntry` / `resolveEntries` / `countEntries` / `createEntryVersion` / `updateEntryVersion` / `createFormSubmission` rzucają teraz `CmsError` (extends `Error`). `error.message` zachowuje stary opis (przy `toString()` poprzedzony `[CODE]`) — string-matching `error.message === 'Entry not found'` może się rozjechać. **Migracja:**
+  ```ts
+  import { CmsError } from 'includio-cms';
+
+  try { await resolveEntry({ id }); }
+  catch (e) {
+    if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { ... }
+  }
+  ```
+- **`.env.example` reformatted** — `DEMO_USER_EMAIL`, `DEMO_USER_PASSWORD`, `DEMO_RESET_KEY` usunięte (były tylko dla wewnętrznego demo skasowanego w Fazie 1). Jeśli polegałeś na nich → trzymaj w lokalnym `.env`, nie w `.env.example`.
+
+### Notes
+
+## Czytelność błędów config
+
+Po update — invalid config wyrzuci na starcie:
+
+```
+ConfigValidationError: CMSConfig validation failed (2 issues):
+  - languages[0]: must be a 2-letter ISO code (e.g. 'en' or 'pl-PL')
+  - collections[1].slug: duplicate collection slug 'posts' — Hint: each collection/single/form must have a unique `slug`
+```
+
+Każdy issue ma `path` (JS-notation: `collections[1].slug`, `apiKeys[0].permissions[2]`) i `message`. Tam gdzie da się rozsądnie zgadnąć, dochodzi `Hint:` z fix-suggestion.
+
+## Pattern: branchowanie po error code
+
+Stary kod string-matchujący po `error.message` musi się przepisać:
+
+```ts
+// PRZED
+catch (e) {
+  if ((e as Error).message === 'Entry not found') { /* 404 */ }
+}
+
+// PO
+import { CmsError } from 'includio-cms';
+catch (e) {
+  if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { /* 404 */ }
+}
+```
+
+Dostępne kody w v0.22.0: `ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`, `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`.
+
+## Nowe envy (opt-in)
+
+Skopiuj `node_modules/includio-cms/.env.example` do swojego `.env` — domyślne wartości działają OOTB:
+
+- `INCLUDIO_SHARP_TIMEOUT_MS` (default 30000)
+- `INCLUDIO_RATE_LIMIT_MAX` / `INCLUDIO_RATE_LIMIT_WINDOW_MS` (default 200/60000)
+- `INCLUDIO_FORM_RATE_LIMIT_MAX` / `INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS` (default 5/3600000)
+- `INCLUDIO_CSRF_ALLOWED_ORIGINS` (default: same-origin only)
+
+## CLI helpy
+
+```bash
+includio --help
+includio scaffold admin --help
+includio install-peers --help
+includio create-user --help
+includio --version
+```
+
+Brak SQL migration.
+
 ## 0.21.0 — 2026-04-30
 
 Faza 5 część 2 — security finish: form rate-limit DRY refactor, API keys `expiresAt` / `rotatedAt`, sharp timeout 30s, `{@html}` audit close. `KNOWN-RISKS.md` w root jako single source of truth dla zaakceptowanych ryzyk v1.0. Plus: faza 6 setup — vitest coverage (info-only), docker test profile, integration test scaffolding (`tests/`).