includio-cms 0.18.0 → 0.20.0

package/dist/types/adapters/db.d.ts

@@ -4,6 +4,15 @@ import type { ImageFieldStyle } from '../fields.js';
 import type { FormSubmission } from '../forms.js';
 import type { ImageStyle, MediaFile, MediaTag, UploadedMediaFile, VideoStyle, VideoStyleStatus } from '../media.js';
 export type { FilesAdapter } from './files.js';
+/**
+ * Contract for database adapters. Drives entries, versions, media, tags, form submissions,
+ * consent logs, and image/video styles. Default implementation: `includio-cms/db-postgres`.
+ *
+ * To build a custom adapter, implement every required method (optionals are marked `?`).
+ * See README — "Writing your own adapter".
+ *
+ * @public
+ */
 export interface DatabaseAdapter {
     createEntry: CreateEntry;
     getEntries: GetEntries;

package/dist/types/adapters/email.d.ts

@@ -1,4 +1,10 @@
+/** @public */
 export type EmailAdapterFactory = () => EmailAdapter;
+/**
+ * Contract for email adapters. Used by `better-auth` reset-password flow and form submission
+ * notifications. Default implementation: `includio-cms/email-nodemailer`.
+ * @public
+ */
 export interface EmailAdapter {
     sendMail: SendMail;
     defaultFromAddress: string;

package/dist/types/adapters/files.d.ts

@@ -1,4 +1,9 @@
 import type { UploadedMediaFile } from '../media.js';
+/**
+ * Contract for file storage adapters. Used by media upload pipeline + private file flow
+ * (e.g. shop receipts). Default implementation: `includio-cms/files-local`.
+ * @public
+ */
 export interface FilesAdapter {
     downloadFile: DownloadFile;
     uploadFile: UploadFile;

package/dist/types/index.d.ts

@@ -14,3 +14,4 @@ export { type PluginConfig, type CustomFieldDefinition } from './plugins.js';
 export { type Language, type Localized } from './languages.js';
 export { type Layout, type LayoutNode, type LayoutPreset, type LayoutNodeType, type ColumnRatio, type SectionNode, type ColumnsNode, type CardNode, type AccordionNode, type StackNode } from './layout.js';
 export { type CmsContext } from './cms-context.js';
+export { type UserData, type Breadcrumb } from '../admin/types.js';

package/dist/types/index.js

@@ -14,3 +14,4 @@ export {} from './plugins.js';
 export {} from './languages.js';
 export {} from './layout.js';
 export {} from './cms-context.js';
+export {} from '../admin/types.js';

package/dist/types/plugins.d.ts

@@ -3,6 +3,10 @@ import type { z } from 'zod';
 import type { RawEntry } from './entries.js';
 import type { CustomField } from './fields.js';
 import type { PopulateCtx } from '../core/server/entries/operations/resolveEntry.js';
+/**
+ * Defines a custom field type contributed by a plugin.
+ * @experimental Plugin system finalizes in 1.x — shape may change.
+ */
 export interface CustomFieldDefinition {
     /** Unique field type slug, e.g. 'photo-grid' */
     fieldType: string;
@@ -20,6 +24,10 @@ export interface CustomFieldDefinition {
      */
     populateResolver?: (value: unknown, field: CustomField, ctx: PopulateCtx) => Promise<unknown>;
 }
+/**
+ * CMS plugin configuration — register custom field types and CRUD lifecycle hooks.
+ * @experimental Plugin hooks API not finalized — may change in 1.x without breaking semver.
+ */
 export interface PluginConfig {
     slug: string;
     fields?: CustomFieldDefinition[];

package/dist/updates/{0.17.0 → 0.18.0}/index.js

@@ -1,5 +1,5 @@
 export const update = {
-    version: '0.17.0',
+    version: '0.18.0',
     date: '2026-04-29',
     description: 'Konsolidacja entry resolverów — kanoniczny `resolveEntry()` / `resolveEntries()` / `countEntries()` w jednym public API. Locale strict, cycle detection, populate config per-field opt-out + maxDepth. Hard remove starych funkcji (getEntry, getEntries, getRawEntry/ies, getDbEntry/ies, populateEntryData) z public surface — przeniesione do internal lub całkowicie usunięte.',
     features: [

package/dist/updates/0.19.0/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.19.0/index.js

@@ -0,0 +1,40 @@
+export const update = {
+    version: '0.19.0',
+    date: '2026-04-29',
+    description: 'Adapter contracts final + 3rd-party SDKs (`@anthropic-ai/sdk`, `openai`, `nodemailer`) przeniesione do `peerDependenciesMeta` jako optional. Adapter typy + factory oznaczone `@public` JSDoc. README sekcja "Writing your own adapter".',
+    features: [
+        'Adapter typy (`DatabaseAdapter`, `FilesAdapter`, `EmailAdapter`, `AIAdapter`) finalne, oznaczone `@public` JSDoc — stabilna powierzchnia kontraktu, TypeScript egzekwuje surface.',
+        'Factory funkcje adapterów (`pg`, `local`, `nodemailerAdapter`, `openAIAdapter`, `claudeAdapter`) oznaczone `@public`.',
+        'README sekcja "Writing your own adapter" + przykład bazujący na `db-postgres` + tabela optional peer dependencies.',
+        'Lazy import 3 SDK (`@anthropic-ai/sdk`, `openai`, `nodemailer`) w factory adapterach — SDK nie ładuje się dopóki adapter nie jest faktycznie użyty.'
+    ],
+    fixes: [
+        'Bundle slim — instalacja `includio-cms` w czystym projekcie nie ciąga już ~7-9MB SDK (anthropic + openai + nodemailer). Zostają w peer optional, doinstalowane tylko gdy faktycznie potrzebne.'
+    ],
+    breakingChanges: [
+        '**`@anthropic-ai/sdk`, `openai`, `nodemailer` przeniesione z `dependencies` do `peerDependenciesMeta` jako optional**. Userland używający `email-nodemailer`/`ai-openai`/`ai-claude` musi sam doinstalować odpowiedni SDK: `pnpm add nodemailer`, `pnpm add openai`, `pnpm add @anthropic-ai/sdk`. Brak peer = throw przy pierwszym użyciu adaptera (`generateAltText`/`sendMail`) z czytelnym komunikatem co doinstalować.',
+        '**`runed` przeniesione z `peerDependenciesMeta.optional` do required peer**. `runed` jest hard-importowane w admin UI (PersistedState), więc opcjonalność była fikcyjna — userland uruchamiający admin BEZ `runed` dostawał crash przy bootcie. Teraz peer wymaga jawnej instalacji (lub pozostaje pulled przez SvelteKit projektu).'
+    ],
+    notes: `Migracja:
+
+1. Dodaj wymagane peer SDK do swojego \`package.json\`:
+
+\`\`\`bash
+# Jeśli używasz nodemailerAdapter:
+pnpm add nodemailer
+
+# Jeśli używasz openAIAdapter:
+pnpm add openai
+
+# Jeśli używasz claudeAdapter:
+pnpm add @anthropic-ai/sdk
+\`\`\`
+
+2. \`runed\` był już peer wcześniej, ale teraz nie jest optional — upewnij się że jest zainstalowane (zwykle pulled przez SvelteKit). Jeśli \`pnpm install\` zgłasza missing peer, dodaj jawnie: \`pnpm add runed\`.
+
+Brak SQL migration. Zmiana czysto package-level.
+
+Pisanie własnych adapterów:
+
+Wszystkie 4 typy adapterów (\`DatabaseAdapter\`, \`FilesAdapter\`, \`EmailAdapter\`, \`AIAdapter\`) mają teraz \`@public\` kontrakty. Patrz README sekcja "Writing your own adapter" + przykład bazujący na \`db-postgres\`.`
+};

package/dist/updates/0.20.0/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.20.0/index.js

@@ -0,0 +1,54 @@
+export const update = {
+    version: '0.20.0',
+    date: '2026-04-29',
+    description: 'API Surface Lock — exports trim 26→15, JSDoc tagi (`@public`/`@experimental`/`@internal`), autogenerowany `API.md`. Powierzchnia publiczna zamrożona w v1.0 — w 1.x tylko `@experimental` może się zmienić bez breaking semver.',
+    features: [
+        '`API.md` w root — autogenerowany przez `scripts/generate-api-md.ts` (ts-morph). 15 entry pointów, ~345 stable, 2 experimental. Skrypt wpięty w `prepublishOnly`.',
+        'Wszystkie publiczne `define*` helpery (`defineConfig`, `defineCollection`, `defineSingle`, `defineForm`, `defineObject`) oznaczone `@public`.',
+        '`getCMS`, `getAuth`, `createEntityAPI`, `resolveMediaWithStyles`, `includioCMS`, `cmsLayoutLoad`, `getPreviewEntry`, `createFormSubmission`, `parseFormDataForSubmission`, `createConsentLog`, `createRestApiHandler` — `@public`.',
+        '`PluginConfig` + `CustomFieldDefinition` oznaczone `@experimental` — plugin hooks API finalizujemy w 1.x.'
+    ],
+    fixes: [],
+    breakingChanges: [
+        '**`package.json` exports trim 26→15.** Usunięte / scalone entry pointy poniżej. Każdy import wymaga jednorazowej migracji (znajdź-i-zamień).',
+        '`includio-cms/admin` → `includio-cms/types` (typy `UserData`, `Breadcrumb` przeniesione do publicznych typów).',
+        '`includio-cms/admin/helpers` → `includio-cms/admin/client` (re-eksport — zmień tylko ścieżkę importu).',
+        '`includio-cms/admin/ui` → `includio-cms/admin/client` (re-eksport — zmień tylko ścieżkę importu).',
+        '`includio-cms/admin/client/account` → `includio-cms/admin/client` (re-eksport — `AccountPage` dostępny pod nową ścieżką).',
+        '`includio-cms/admin/api/*` (wildcard) → **usunięte**. Były to internalsy (media-gc, upload, transcode, replace) — nie powinny być publiczne. Brak migracji.',
+        '`includio-cms/admin/api/rest/handler` → `includio-cms/sveltekit/server` (`createRestApiHandler` — zmień ścieżkę importu).',
+        '`includio-cms/admin/client/*.svelte` (wildcard) → użyj nazwanych eksportów z `includio-cms/admin/client`.',
+        '`includio-cms/sveltekit/components/*.svelte` (wildcard) → użyj nazwanych eksportów z `includio-cms/sveltekit`.',
+        '`includio-cms/db-postgres/schema-core` + `includio-cms/db-postgres/schema-shop` + `includio-cms/auth-schema` → `includio-cms/db-postgres` (jeden barrel — wszystkie tabele, w tym auth, dostępne pod jedną ścieżką).',
+        '`includio-cms/auth` → `includio-cms/core` (`getAuth` — zmień ścieżkę importu).',
+        '`includio-cms/entity` → `includio-cms/core` (`createEntityAPI` — zmień ścieżkę importu).',
+        '`includio-cms/shop/svelte` → `includio-cms/shop/client` (`OrderStatus`, `InpostPicker`, `DEFAULT_LABELS_PL`, `OrderStatusLabels` — zmień ścieżkę importu).',
+        '`includio-cms/updates` → **usunięte** (internal CLI tooling, nigdy nie powinno być w runtime API).'
+    ],
+    notes: `Migracja (znajdź-i-zamień):
+
+\`\`\`bash
+# Przykładowe sed'y (dostosuj do swojego edytora):
+sed -i '' "s|'includio-cms/admin/helpers'|'includio-cms/admin/client'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/admin/ui'|'includio-cms/admin/client'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/auth'|'includio-cms/core'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/entity'|'includio-cms/core'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/shop/svelte'|'includio-cms/shop/client'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/auth-schema'|'includio-cms/db-postgres'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/db-postgres/schema-core'|'includio-cms/db-postgres'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/db-postgres/schema-shop'|'includio-cms/db-postgres'|g" src/**/*.ts
+sed -i '' "s|'includio-cms/admin/api/rest/handler'|'includio-cms/sveltekit/server'|g" src/**/*.ts
+\`\`\`
+
+Po migracji uruchom \`pnpm check\` — TypeScript zweryfikuje czy wszystkie symbole są dostępne pod nową ścieżką.
+
+API Surface freeze v1.0:
+
+- **\`@public\`** — stabilne, semver-protected w v1.0. Breaking change wymaga major bump.
+- **\`@experimental\`** — może się zmienić w 1.x bez breaking semver (np. \`PluginConfig\` — plugin hooks API).
+- **\`@internal\`** — implementation detail, NIE importować. Nie listowane w \`API.md\`.
+
+Pełna lista publicznych symboli per entry point: \`API.md\` w root paczki (regenerowany przy każdym \`npm publish\`).
+
+Brak SQL migration. Zmiana czysto package-level.`
+};

package/dist/updates/index.js

@@ -51,8 +51,10 @@ import { update as update0153 } from './0.15.3/index.js';
 import { update as update0154 } from './0.15.4/index.js';
 import { update as update0155 } from './0.15.5/index.js';
 import { update as update0160 } from './0.16.0/index.js';
-import { update as update0170 } from './0.17.0/index.js';
-export const updates = [update0065, update0066, update0067, update0068, update0069, update010, update011, update012, update013, update014, update015, update020, update022, update050, update051, update052, update053, update054, update055, update056, update057, update058, update060, update061, update062, update070, update071, update072, update073, update080, update090, update0100, update0110, update0120, update0130, update0131, update0132, update0133, update0134, update0140, update0141, update0142, update0143, update0144, update0145, update0146, update0150, update0151, update0152, update0153, update0154, update0155, update0160, update0170];
+import { update as update0180 } from './0.18.0/index.js';
+import { update as update0190 } from './0.19.0/index.js';
+import { update as update0200 } from './0.20.0/index.js';
+export const updates = [update0065, update0066, update0067, update0068, update0069, update010, update011, update012, update013, update014, update015, update020, update022, update050, update051, update052, update053, update054, update055, update056, update057, update058, update060, update061, update062, update070, update071, update072, update073, update080, update090, update0100, update0110, update0120, update0130, update0131, update0132, update0133, update0134, update0140, update0141, update0142, update0143, update0144, update0145, update0146, update0150, update0151, update0152, update0153, update0154, update0155, update0160, update0180, update0190, update0200];
 export const getUpdatesFrom = (fromVersion) => {
     const fromParts = fromVersion.split('.').map(Number);
     return updates.filter((update) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "includio-cms",
-	"version": "0.18.0",
+	"version": "0.20.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -25,7 +25,8 @@
 		"build:cli": "tsc cli/init/index.ts --outDir dist/cli/init --module commonjs --esModuleInterop",
 		"changelog": "tsx scripts/generate-changelog.ts",
 		"docs:compile": "tsx scripts/compile-docs.ts",
-		"prepublishOnly": "tsx scripts/generate-changelog.ts && tsx scripts/compile-docs.ts"
+		"api:generate": "tsx scripts/generate-api-md.ts",
+		"prepublishOnly": "tsx scripts/generate-changelog.ts && tsx scripts/compile-docs.ts && tsx scripts/generate-api-md.ts && git commit -am \"Prepublish v${version} (CHANGELOG.md, DOCS.md and API.md updated)\""
 	},
 	"bin": {
 		"includio": "./dist/cli/index.js"
@@ -38,6 +39,7 @@
 		"CHANGELOG.md",
 		"ROADMAP.md",
 		"DOCS.md",
+		"API.md",
 		"LICENSE"
 	],
 	"sideEffects": [
@@ -56,87 +58,33 @@
 			"svelte": "./dist/core/index.js",
 			"node": "./dist/core/index.js"
 		},
-		"./entity": {
-			"types": "./dist/entity/index.d.ts",
-			"node": "./dist/entity/index.js"
-		},
 		"./types": {
 			"types": "./dist/types/index.d.ts",
 			"svelte": "./dist/types/index.js",
 			"node": "./dist/types/index.js"
 		},
-		"./admin/helpers": {
-			"types": "./dist/admin/helpers/index.d.ts",
-			"svelte": "./dist/admin/helpers/index.js"
-		},
-		"./admin/ui": {
-			"types": "./dist/admin/ui/index.d.ts",
-			"svelte": "./dist/admin/ui/index.js"
-		},
-		"./admin": {
-			"types": "./dist/admin/index.d.ts",
-			"svelte": "./dist/admin/index.js"
-		},
-		"./admin/api/*": {
-			"types": "./dist/admin/api/*.d.ts",
-			"svelte": "./dist/admin/api/*.js",
-			"node": "./dist/admin/api/*.js"
-		},
-		"./admin/api/rest/handler": {
-			"types": "./dist/admin/api/rest/handler.d.ts",
-			"svelte": "./dist/admin/api/rest/handler.js",
-			"node": "./dist/admin/api/rest/handler.js"
-		},
-		"./admin/client/account": {
-			"types": "./dist/admin/client/account/index.d.ts",
-			"svelte": "./dist/admin/client/account/index.js"
-		},
-		"./admin/remote": {
-			"types": "./dist/admin/remote/index.d.ts",
-			"svelte": "./dist/admin/remote/index.js"
-		},
 		"./admin/client": {
 			"types": "./dist/admin/client/index.d.ts",
 			"svelte": "./dist/admin/client/index.js"
 		},
-		"./admin/client/*.svelte": {
-			"types": "./dist/admin/client/*.svelte.d.ts",
-			"svelte": "./dist/admin/client/*.svelte"
+		"./admin/remote": {
+			"types": "./dist/admin/remote/index.d.ts",
+			"svelte": "./dist/admin/remote/index.js"
 		},
 		"./sveltekit": {
 			"types": "./dist/sveltekit/index.d.ts",
 			"svelte": "./dist/sveltekit/index.js",
 			"node": "./dist/sveltekit/index.js"
 		},
-		"./sveltekit/components/*.svelte": {
-			"types": "./dist/sveltekit/components/*.svelte.d.ts",
-			"svelte": "./dist/sveltekit/components/*.svelte"
-		},
 		"./sveltekit/server": {
 			"types": "./dist/sveltekit/server/index.d.ts",
 			"svelte": "./dist/sveltekit/server/index.js",
 			"node": "./dist/sveltekit/server/index.js"
 		},
-		"./updates": {
-			"types": "./dist/updates/index.d.ts",
-			"node": "./dist/updates/index.js"
-		},
 		"./db-postgres": {
 			"types": "./dist/db-postgres/index.d.ts",
 			"node": "./dist/db-postgres/index.js"
 		},
-		"./db-postgres/schema-core": {
-			"types": "./dist/db-postgres/schema-core.d.ts",
-			"node": "./dist/db-postgres/schema-core.js"
-		},
-		"./db-postgres/schema-shop": {
-			"types": "./dist/db-postgres/schema-shop.d.ts",
-			"node": "./dist/db-postgres/schema-shop.js"
-		},
-		"./auth-schema": {
-			"types": "./dist/server/db/schema/auth-schema.d.ts",
-			"node": "./dist/server/db/schema/auth-schema.js"
-		},
 		"./shop": {
 			"types": "./dist/shop/index.d.ts",
 			"svelte": "./dist/shop/index.js",
@@ -151,10 +99,6 @@
 			"types": "./dist/shop/http/index.d.ts",
 			"node": "./dist/shop/http/index.js"
 		},
-		"./shop/svelte": {
-			"types": "./dist/shop/svelte/index.d.ts",
-			"svelte": "./dist/shop/svelte/index.js"
-		},
 		"./files-local": {
 			"types": "./dist/files-local/index.d.ts",
 			"node": "./dist/files-local/index.js"
@@ -167,16 +111,13 @@
 			"types": "./dist/ai-openai/index.d.ts",
 			"node": "./dist/ai-openai/index.js"
 		},
-		"./auth": {
-			"types": "./dist/server/auth.d.ts",
-			"node": "./dist/server/auth.js"
-		},
 		"./ai-claude": {
 			"types": "./dist/ai-claude/index.d.ts",
 			"node": "./dist/ai-claude/index.js"
 		}
 	},
 	"peerDependencies": {
+		"@anthropic-ai/sdk": ">=0.39.0",
 		"@sveltejs/kit": "^2.48.0",
 		"@sveltejs/vite-plugin-svelte": "^6.2.1",
 		"better-auth": "^1.3.34",
@@ -184,6 +125,8 @@
 		"drizzle-orm": "^0.40.0",
 		"embla-carousel-svelte": "^8.6.0",
 		"formsnap": "^2.0.1",
+		"nodemailer": ">=7.0.0",
+		"openai": ">=6.0.0",
 		"paneforge": "^1.0.2",
 		"postgres": "^3.4.5",
 		"runed": "^0.35.1",
@@ -198,7 +141,13 @@
 		"zod": "^4.0.0"
 	},
 	"peerDependenciesMeta": {
-		"runed": {
+		"@anthropic-ai/sdk": {
+			"optional": true
+		},
+		"nodemailer": {
+			"optional": true
+		},
+		"openai": {
 			"optional": true
 		},
 		"svelte-tiptap": {
@@ -215,6 +164,7 @@
 		}
 	},
 	"devDependencies": {
+		"@anthropic-ai/sdk": "^0.39.0",
 		"@chromatic-com/storybook": "^5.0.1",
 		"@eslint/compat": "^1.2.5",
 		"@eslint/js": "^9.18.0",
@@ -237,6 +187,8 @@
 		"@types/fluent-ffmpeg": "^2.1.27",
 		"@types/node": "^22",
 		"@types/nodemailer": "^7.0.4",
+		"nodemailer": "^7.0.11",
+		"openai": "^6.9.0",
 		"better-auth": "^1.3.34",
 		"bits-ui": "^2.11.5",
 		"clsx": "^2.1.1",
@@ -283,7 +235,6 @@
 		"svelte"
 	],
 	"dependencies": {
-		"@anthropic-ai/sdk": "^0.39.0",
 		"@inlang/paraglide-js": "^2.0.0",
 		"@internationalized/date": "^3.8.2",
 		"@lucide/svelte": "^0.544.0",
@@ -316,8 +267,6 @@
 		"isomorphic-dompurify": "3.0.0-rc.2",
 		"lowlight": "^3.3.0",
 		"mrmime": "^2.0.1",
-		"nodemailer": "^7.0.11",
-		"openai": "^6.9.0",
 		"path-to-regexp": "^8.2.0",
 		"readline": "^1.3.0",
 		"slugify": "^1.6.6",