includio-cms 0.18.0 → 0.20.0

package/API.md

@@ -0,0 +1,409 @@
+# includio-cms — Public API v0.20.0
+
+> Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
+
+Entry points: **15** · Stable: **345** · Experimental: **2**
+
+Tags:
+- `@public` — frozen for v1.0; semver-protected.
+- `@experimental` — may change in 1.x without breaking semver.
+- `@internal` — implementation detail; not listed here, do not import.
+
+## Stable
+
+### `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.
+- `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).
+
+### `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.
+- `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).
+
+### `includio-cms/types`
+
+- `interface AccordionNode`
+- `interface ApiKeyConfig`
+- `interface ArrayField`
+- `interface AuthConfig`
+- `interface BaseField`
+- `interface BlocksField`
+- `interface BooleanField`
+- `interface Breadcrumb`
+- `interface CardNode`
+- `interface CheckboxesField`
+- `interface CMSConfig`
+- `interface CmsContext`
+- `interface CollectionConfig`
+- `type ColumnRatio = | '1fr 1fr' | '2fr 1fr' | '1fr 2fr' | '3fr 1fr' | '1fr 3fr' | '1fr 1fr 1fr'`
+- `interface ColumnsNode`
+- `interface ConfigBase`
+- `interface ConsentLogData`
+- `interface ContentField`
+- `interface CustomField`
+- `interface DateField`
+- `interface DateTimeField`
+- `type Entry = { _id: string; _slug: string; _type: EntryType; _publishedAt?: Date | null; _url?: string; _sortO...`
+- `type EntryStatus = (typeof entryStatuses)[number]`
+- `type EntryType = (typeof entryTypes)[number]`
+- `type EntryVersionStatus = (typeof entryVersionStatuses)[number]`
+- `type Field = | TextField | ContentField | NumberField | BooleanField | DateField | DateTimeField | FileField |...`
+- `interface FieldCondition`
+- `type FieldType = | 'text' | 'content' | 'number' | 'boolean' | 'date' | 'datetime' | 'file' | 'media' | 'select' |...`
+- `interface FileField`
+- `type FlatImageFieldData = MediaFile & { _styles: Record<string, ImageStyle>; _blurDataUrl?: string | null; }`
+- `type FlatMediaFieldData = FlatImageFieldData | FlatVideoFieldData`
+- `type FlatVideoFieldData = MediaFile & { _styles: Record<string, VideoStyle>; _transcript: MediaFile | null; _audioDescripti...`
+- `interface FormBaseField`
+- `interface FormCheckboxField`
+- `interface FormConfig`
+- `interface FormEmailField`
+- `type FormField = | FormTextField | FormEmailField | FormTextareaField | FormCheckboxField | FormSelectField | Form...`
+- `type FormFieldType = 'text' | 'email' | 'textarea' | 'checkbox' | 'select' | 'file'`
+- `interface FormSelectField`
+- `interface FormSubmission`
+- `interface FormTextareaField`
+- `interface FormTextField`
+- `type IconName = keyof typeof iconMap`
+- `interface ImageFieldData`
+- `interface ImageFieldStyle`
+- `interface ImageStyle`
+- `type Language = 'en' | 'pl'`
+- `type Layout = LayoutPreset | LayoutNode[]`
+- `type LayoutNode = SectionNode | ColumnsNode | CardNode | AccordionNode | StackNode`
+- `type LayoutNodeType = 'section' | 'columns' | 'card' | 'accordion' | 'stack'`
+- `type LayoutPreset = | 'sidebar-right' | 'two-column' | { preset: 'sidebar-right'; sidebar: string[] } | { preset: 'tw...`
+- `type Localized = Partial<Record<InterfaceLanguage, string>> | string`
+- `interface MediaField`
+- `type MediaFieldData = ImageFieldData | VideoFieldData`
+- `interface MediaFile`
+- `type MediaFileType = 'image' | 'video' | 'audio' | 'pdf' | 'other'`
+- `interface MediaTag`
+- `interface NumberField`
+- `interface ObjectField`
+- `type ObjectFieldData = { _id?: string; _slug?: string; } & Record<string, unknown>`
+- `interface RadioField`
+- `interface RelationField`
+- `type RelationFieldData = string | string[]`
+- `interface SCFigureAttrs`
+- `interface SCInlineBlockAttrs`
+- `interface SCMark`
+- `interface SCNode`
+- `interface SCTypedInlineBlock`
+- `interface SCVideoAttrs`
+- `interface SectionNode`
+- `interface SelectField`
+- `interface SeoField`
+- `interface SeoFieldData`
+- `interface ShopField`
+- `interface ShopFieldData`
+- `type SimpleArrayItemType = 'text' | 'number' | 'url'`
+- `interface SingleConfig`
+- `interface SlugField`
+- `interface StackNode`
+- `interface StructuredContentDoc`
+- `interface TextField`
+- `interface TypographyConfig`
+- `interface UrlField`
+- `type UrlFieldData = { id?: string; url: Record<string, string>; text?: Record<string, string>; newTab?: boolean; rel?...`
+- `interface UserData`
+- `interface VideoFieldData`
+- `interface VideoFieldStyle`
+- `interface VideoStyle`
+- `type VideoStyleStatus = 'pending' | 'processing' | 'done' | 'failed'`
+
+### `includio-cms/admin/client`
+
+- `const AcceptInvitePage: LegacyComponentType`
+- `const AdminAfterLoginLayout: LegacyComponentType`
+- `const AdminLayout: LegacyComponentType`
+- `const Badge: LegacyComponentType`
+- `buildCustomFieldsMap(...plugins: PluginConfig[]): Map<string, CustomFieldDefinition>` — Build a Map<fieldType, CustomFieldDefinition> from plugin configs.
+- `const Button: LegacyComponentType`
+- `Card`
+- `const CollectionPage: LegacyComponentType`
+- `const DashboardPage: LegacyComponentType`
+- `Dialog`
+- `const EntryPage: LegacyComponentType`
+- `const FileMiniature: LegacyComponentType`
+- `const FormPage: LegacyComponentType`
+- `const FormSubmissionPage: LegacyComponentType`
+- `getContentLanguage`
+- `getCustomFields(): Map<string, CustomFieldDefinition>`
+- `getLocalizedLabel(label: Localized | undefined, lang: InterfaceLanguage): string`
+- `getRemotes(): typeof remotes`
+- `const Input: LegacyComponentType`
+- `const Label: LegacyComponentType`
+- `const LoginPage: LegacyComponentType`
+- `const MaintenancePage: LegacyComponentType`
+- `const MediaPage: LegacyComponentType`
+- `const MediaSelector: LegacyComponentType`
+- `const ResetPasswordPage: LegacyComponentType`
+- `const Separator: LegacyComponentType`
+- `const ShippingMethodEditPage: LegacyComponentType`
+- `const ShippingMethodNewPage: LegacyComponentType`
+- `const ShippingMethodsListPage: LegacyComponentType`
+- `const ShopOrderDetailPage: LegacyComponentType`
+- `const ShopOrdersListPage: LegacyComponentType`
+- `const ShopProductsListPage: LegacyComponentType`
+- `const Skeleton: LegacyComponentType`
+- `Tabs`
+- `Tooltip`
+- `useField(form: SuperForm<Record<string, unknown>>, path: FormPathLeaves<Record<string, unknown>>): <inferred>` — Simplified wrapper around sveltekit-superforms' formFieldProxy.
+- `useInterfaceLanguage(): <inferred>`
+- `const UsersPage: LegacyComponentType`
+
+### `includio-cms/admin/remote`
+
+- `const archiveEntryCommand: <inferred>`
+- `const bulkDeleteMediaFiles: <inferred>`
+- `const bulkSetMediaFileTags: <inferred>`
+- `const cancelShipmentForOrderCmd: <inferred>`
+- `const countMediaFiles: <inferred>`
+- `const createEntry: <inferred>`
+- `const createMediaTag: <inferred>`
+- `const createShipmentForOrderCmd: <inferred>`
+- `const createShippingMethodCmd: <inferred>`
+- `const deleteEntryCommand: <inferred>`
+- `const deleteFormSubmission: <inferred>`
+- `const deleteFormSubmissions: <inferred>`
+- `const deleteMediaFile: <inferred>`
+- `const deleteMediaTag: <inferred>`
+- `const deleteShippingMethodCmd: <inferred>`
+- `const deleteShopDataForEntry: <inferred>`
+- `const exportFormSubmissions: <inferred>`
+- `const findMediaReferences: <inferred>`
+- `const generateAltText: <inferred>`
+- `const getAltOverview: <inferred>`
+- `const getCollection: <inferred>`
+- `const getCollections: <inferred>`
+- `const getEmailConfigured: <inferred>`
+- `const getEntries: <inferred>`
+- `const getEntry: <inferred>`
+- `const getEntryForEntryPage: <inferred>`
+- `const getEntryLabels: <inferred>`
+- `const getEntryVersion: <inferred>`
+- `const getFileById: <inferred>`
+- `const getForm: <inferred>`
+- `const getForms: <inferred>`
+- `const getFormSubmission: <inferred>`
+- `const getFormSubmissions: <inferred>`
+- `const getLanguages: <inferred>`
+- `const getMedia: <inferred>`
+- `const getMediaFiles: <inferred>`
+- `const getMediaTags: <inferred>`
+- `const getMediaTagsWithCounts: <inferred>`
+- `const getOrderForAdmin: <inferred>`
+- `const getRawEntries: <inferred>`
+- `const getRawEntry: <inferred>`
+- `const getRecentActivity: <inferred>`
+- `const getRecentEntries: <inferred>`
+- `const getRecordBySlug: <inferred>`
+- `const getShippingMethodForAdmin: <inferred>`
+- `const getShopConfig: <inferred>`
+- `const getShopDataForEntry: <inferred>`
+- `const getShopEnabled: <inferred>`
+- `const getSingles: <inferred>`
+- `const getSubmissionsOverview: <inferred>`
+- `const isAIAvailable: <inferred>`
+- `const listOrdersAdmin: <inferred>`
+- `const listShippingMethodsAdmin: <inferred>`
+- `const listShopableCollections: <inferred>`
+- `const listShopProductEntries: <inferred>`
+- `const populatePreviewData: <inferred>`
+- `const regenerateVideoPoster: <inferred>`
+- `const renameMediaFile: <inferred>`
+- `const reorderEntriesCommand: <inferred>`
+- `const reorderShippingMethodsCmd: <inferred>`
+- `const resendOrderEmailCmd: <inferred>`
+- `const setFocalPoint: <inferred>`
+- `const setMediaFileAlt: <inferred>`
+- `const setMediaFileTags: <inferred>`
+- `const unarchiveEntryCommand: <inferred>`
+- `const updateEntryCommand: <inferred>`
+- `const updateEntryVersionCommand: <inferred>`
+- `const updateFormSubmission: <inferred>`
+- `const updateMediaAccessibility: <inferred>`
+- `const updateMediaTag: <inferred>`
+- `const updateOrderStatusCmd: <inferred>`
+- `const updateShippingMethodCmd: <inferred>`
+- `const upsertShopDataForEntry: <inferred>`
+
+### `includio-cms/sveltekit`
+
+- `const CmsProvider: LegacyComponentType`
+- `defineCollection(config: CollectionInput): CollectionConfig` — Defines a collection (multi-entry content type).
+- `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).
+- `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.
+- `extractMediaRefs(doc: StructuredContentDoc): MediaRef[]` — Extract media references from figure/video/image nodes.
+- `extractText(doc: StructuredContentDoc): string` — Extract all plain text from doc (useful for excerpts, search indexing).
+- `getCustomFields(): Map<string, CustomFieldDefinition>`
+- `getLink(link: string | { url: string | Record<string, string> } |..., language?: string): string` — Resolves a link value to a URL string.
+- `getRemotes(): typeof remotes`
+- `const HybridTarget: LegacyComponentType`
+- `const Image: LegacyComponentType`
+- `isImageFieldData(media: MediaFieldData): media is ImageFieldData`
+- `isVideoFieldData(media: MediaFieldData): media is VideoFieldData`
+- `const Media: LegacyComponentType`
+- `const Preview: LegacyComponentType`
+- `setCustomFields(defs: Map<string, CustomFieldDefinition>): <inferred>`
+- `setPreferMp4(value: boolean): <inferred>`
+- `setRemotes(data: typeof remotes): <inferred>`
+- `const StructuredContent: LegacyComponentType`
+- `structuredToHtml(doc: StructuredContentDoc, options: StructuredToHtmlOptions = {}): string` — Convert a StructuredContentDoc to an HTML string.
+- `const Video: LegacyComponentType`
+
+### `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.
+- `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`.
+- `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.
+- `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`
+- `resolveEntry(opts: ResolveEntryOptions): Promise<Entry | null>` — Fetch a single populated Entry.
+- `interface ResolveEntryOptions`
+- `type ResolveStatus = 'published' | 'draft' | 'scheduled'` — Status filter for `resolveEntry`/`resolveEntries`/`countEntries`.
+
+### `includio-cms/db-postgres`
+
+- `const account: <inferred>`
+- `const accountRelations: <inferred>`
+- `const consentLogsTable: <inferred>`
+- `type DatabaseAdapterWithDrizzle = DatabaseAdapter & { _drizzle: ReturnType<typeof drizzle<typeof schema>>; }`
+- `const entriesTable: <inferred>`
+- `const entryVersionsTable: <inferred>`
+- `const formSubmissionsTable: <inferred>`
+- `const imageStylesTable: <inferred>`
+- `type InpostParcelSize = 'A' | 'B' | 'C'`
+- `type InpostServiceType = | 'inpost_locker_standard' | 'inpost_locker_express' | 'inpost_courier_standard' | 'inpost_courie...`
+- `const invitation: <inferred>`
+- `const mediaFilesTable: <inferred>`
+- `const mediaFileTagsTable: <inferred>`
+- `const mediaTagsTable: <inferred>`
+- `pg(config: Config): DatabaseAdapterWithDrizzle` — Postgres database adapter (drizzle + `postgres`).
+- `const session: <inferred>`
+- `const sessionRelations: <inferred>`
+- `interface ShippingCarrierConfig`
+- `type ShopCarrierType = 'none' | 'inpost' | string`
+- `const shopOrderItemsTable: <inferred>`
+- `const shopOrdersTable: <inferred>`
+- `const shopOrderStatusHistoryTable: <inferred>`
+- `const shopPaymentsTable: <inferred>`
+- `type ShopPaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded' | 'cancelled'`
+- `const shopProductsTable: <inferred>`
+- `const shopProductVariantsTable: <inferred>`
+- `const shopShippingMethodsTable: <inferred>`
+- `const shopStockReservationsTable: <inferred>`
+- `const user: <inferred>`
+- `const userRelations: <inferred>`
+- `const verification: <inferred>`
+- `const videoStylesTable: <inferred>`
+
+### `includio-cms/shop`
+
+- `interface CarrierAdapter`
+- `interface CarrierEvent`
+- `interface ConsentConfig`
+- `type Currency = 'PLN'`
+- `defineShop(config: ShopConfig): ResolvedShopConfig`
+- `type GeowidgetConfigPreset = | 'parcelcollect' | 'parcelsend' | 'parcelcollect247' | string`
+- `type I18nText = { [lang: string]: string; }`
+- `inpostAdapter(opts: InpostAdapterOptions): CarrierAdapter`
+- `interface InpostAdapterOptions`
+- `type InpostEnvironment = 'production' | 'sandbox'` — InPost Points API — public, no auth required. Used to validate that a parcel
+- `interface InpostSenderAddress`
+- `manualAdapter(opts: ManualPaymentAdapterOptions = {}): PaymentAdapter` — Manual payment adapter — order goes to awaitingPayment, admin marks as paid later
+- `interface OrderRef`
+- `type OrderStatus = | 'new' | 'awaitingPayment' | 'paid' | 'preparing' | 'sent' | 'done' | 'cancelled' | 'paymentReje...`
+- `interface PaymentAdapter`
+- `interface PaymentCreateContext`
+- `interface PaymentCreateResult`
+- `interface PaymentEvent`
+- `payuAdapter(opts: PayuAdapterOptions): PaymentAdapter`
+- `interface PayuAdapterOptions`
+- `interface ResolvedShopConfig`
+- `interface ShipmentCreateInput`
+- `interface ShipmentCreateResult`
+- `interface ShipmentLabel`
+- `interface ShopConfig`
+- `interface ShopFeatures`
+
+### `includio-cms/shop/client`
+
+- `interface CartItemRef`
+- `interface CartLine`
+- `interface CartSnapshot`
+- `interface CheckoutInput`
+- `interface CheckoutResult`
+- `createOrderState(opts: CreateOrderStateOptions): OrderState`
+- `interface CreateOrderStateOptions`
+- `createShopClient(options: ShopClientOptions = {}): ShopClient`
+- `const DEFAULT_LABELS_PL: OrderStatusLabels`
+- `const InpostPicker: LegacyComponentType`
+- `interface OrderDetailResponse`
+- `type OrderPaymentPhase = 'idle' | 'polling' | 'retrying' | 'refreshing'`
+- `type OrderState = OrderStateImpl`
+- `const OrderStatus: LegacyComponentType`
+- `interface OrderStatusLabels`
+- `interface RefreshPaymentResult`
+- `interface RetryPaymentResult`
+- `interface ShippingMethodPublic`
+- `interface ShopClient`
+- `interface ShopClientOptions`
+
+### `includio-cms/shop/http`
+
+- `createCarrierConfigHandler(): { GET: RequestHandler }` — Public endpoint that returns front-end facing carrier widget descriptor for
+- `createCarrierWebhookHandler(): { POST: RequestHandler }` — Public webhook receiver for carrier events (e.g. ShipX `shipment_status_changed`).
+- `createCartHandler(): { GET: RequestHandler; POST: RequestHandler; PATCH: RequestHandler; DELETE: R...`
+- `createCheckoutHandler(): { POST: RequestHandler }`
+- `createOrderHandler(): { GET: RequestHandler }`
+- `createPaymentWebhookHandler(): { POST: RequestHandler }`
+- `createRefreshPaymentHandler(): { POST: RequestHandler }`
+- `createRetryPaymentHandler(): { POST: RequestHandler }`
+- `createShipmentLabelHandler(): { GET: RequestHandler }` — Admin-only PDF proxy that streams the carrier label without exposing the
+- `createShippingMethodsHandler(): { GET: RequestHandler }`
+
+### `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).
+- `interface LocalFilesConfig`
+
+### `includio-cms/email-nodemailer`
+
+- `nodemailerAdapter(options: Options): EmailAdapter` — SMTP email adapter built on `nodemailer`.
+
+### `includio-cms/ai-openai`
+
+- `openAIAdapter(config: AIConfig): AIAdapter` — OpenAI AI adapter for `generateAltText`.
+
+### `includio-cms/ai-claude`
+
+- `claudeAdapter(config: AIConfig): AIAdapter` — Anthropic Claude AI adapter for `generateAltText`.
+
+## Experimental
+
+### `includio-cms/types`
+
+- `interface CustomFieldDefinition` — Defines a custom field type contributed by a plugin.
+- `interface PluginConfig` — CMS plugin configuration — register custom field types and CRUD lifecycle hooks.

package/CHANGELOG.md

@@ -3,7 +3,104 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
-## 0.17.0 — 2026-04-29
+## 0.20.0 — 2026-04-29
+
+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.
+
+### Added
+- `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.
+
+### Breaking
+- **`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.
+
+## 0.19.0 — 2026-04-29
+
+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".
+
+### Added
+- 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.
+
+### Fixed
+- 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.
+
+### Breaking
+- **`@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`.
+
+## 0.18.0 — 2026-04-29
 
 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.
 

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.18.0)
+# Includio CMS Documentation (v0.20.0)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 

package/README.md

@@ -38,6 +38,68 @@ export default defineConfig({
 
 See the [full documentation](/docs) for installation, configuration, and usage.
 
+## Writing your own adapter
+
+`includio-cms` ships with default adapters (`db-postgres`, `files-local`, `email-nodemailer`, `ai-openai`, `ai-claude`). Each is a factory returning an object that implements a `@public` contract from `includio-cms/types`. Build your own by implementing the same interface — TypeScript will enforce the surface.
+
+Four adapter contracts:
+
+- `DatabaseAdapter` — entries, versions, media, tags, form submissions, consent logs.
+- `FilesAdapter` — file upload/download/list, optional private files (e.g. shop receipts).
+- `EmailAdapter` — `sendMail`, default from address/name.
+- `AIAdapter` — currently `generateAltText(fileId)`.
+
+Source of truth: [`src/lib/types/adapters/`](src/lib/types/adapters/).
+
+### Minimal custom DB adapter (sketch)
+
+```ts
+import type { DatabaseAdapter } from 'includio-cms/types';
+
+export function myDbAdapter(config: { connection: string }): DatabaseAdapter {
+  // ...connect, prepare your client...
+  return {
+    createEntry: async (data) => { /* ... */ },
+    getEntries: async (opts) => { /* ... */ },
+    countEntries: async (opts) => { /* ... */ },
+    updateEntry: async (data) => { /* ... */ },
+    archiveEntry: async (data) => { /* ... */ },
+    deleteEntry: async (data) => { /* ... */ },
+    createEntryVersion: async (data) => { /* ... */ },
+    updateEntryVersion: async (data) => { /* ... */ },
+    getEntryVersions: async (data) => { /* ... */ },
+    deleteEntryVersion: async (data) => { /* ... */ },
+    // ...form submissions, media files, image/video styles, tags, consent logs...
+  };
+}
+```
+
+Wire it in `cms.config.ts`:
+
+```ts
+import { defineConfig } from 'includio-cms/sveltekit';
+import { myDbAdapter } from './my-adapter.js';
+
+export default defineConfig({
+  db: myDbAdapter({ connection: process.env.MY_DB_URL! }),
+  // ...
+});
+```
+
+Reference implementation: [`src/lib/db-postgres/index.ts`](src/lib/db-postgres/index.ts) (drizzle + `postgres`).
+
+### Optional peer dependencies
+
+The default email + AI adapters depend on third-party SDKs that **are not installed by default**. If you use them, install the peer:
+
+| Adapter                   | Required peer            | Install                                |
+| ------------------------- | ------------------------ | -------------------------------------- |
+| `email-nodemailer`        | `nodemailer`             | `pnpm add nodemailer`                  |
+| `ai-openai`               | `openai`                 | `pnpm add openai`                      |
+| `ai-claude`               | `@anthropic-ai/sdk`      | `pnpm add @anthropic-ai/sdk`           |
+
+Each SDK is loaded lazily on first call. Missing peer throws a clear error at runtime — install it and the adapter wakes up.
+
 ## Links
 
 - [Full Documentation](DOCS.md)

package/ROADMAP.md

@@ -338,6 +338,7 @@
 
 > 13 faz w ~16 sesjach, droga 0.16 → 1.0.0. Lean scope: stabilizacja, security, testy, docs, audit + polish shopa. Bez nowych feature'ów.
 
+- [x] `[breaking]` `[P0]` API surface lock — exports trim 26→15, JSDoc tagi (@public/@internal/@experimental), `API.md` autogenerated (0.20.0) <!-- files: package.json, scripts/generate-api-md.ts -->
 - [ ] `[fix]` `[P1]` Select field — `defaultValue` propagacja do zod schema (full repro: `ideas/post-v1/select-field-defaultvalue-bug.md`); fix planowany w Fazie 12 (RC)
 
 ## v1.x — Post-v1.0 deferred

package/dist/admin/api/rest/handler.d.ts

@@ -1,4 +1,8 @@
 import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * 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`.
+ * @public
+ */
 export declare function createRestApiHandler(): {
     GET: RequestHandler;
     POST: RequestHandler;

package/dist/admin/api/rest/handler.js

@@ -49,6 +49,10 @@ function matchRoute(method, path) {
     }
     return null;
 }
+/**
+ * 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`.
+ * @public
+ */
 export function createRestApiHandler() {
     function handle(method) {
         return async (event) => {

package/dist/admin/client/index.d.ts

@@ -18,3 +18,5 @@ export { default as ShippingMethodNewPage } from './shop/shipping-method-new-pag
 export { default as ShippingMethodEditPage } from './shop/shipping-method-edit-page.svelte';
 export { default as ShopOrdersListPage } from './shop/shop-orders-list-page.svelte';
 export { default as ShopOrderDetailPage } from './shop/shop-order-detail-page.svelte';
+export * from '../helpers/index.js';
+export * from '../ui/index.js';

package/dist/admin/client/index.js

@@ -18,3 +18,7 @@ export { default as ShippingMethodNewPage } from './shop/shipping-method-new-pag
 export { default as ShippingMethodEditPage } from './shop/shipping-method-edit-page.svelte';
 export { default as ShopOrdersListPage } from './shop/shop-orders-list-page.svelte';
 export { default as ShopOrderDetailPage } from './shop/shop-order-detail-page.svelte';
+// Folded from `./admin/helpers` (dropped as separate export in 0.20.0)
+export * from '../helpers/index.js';
+// Folded from `./admin/ui` (dropped as separate export in 0.20.0)
+export * from '../ui/index.js';

package/dist/ai-claude/index.d.ts

@@ -1,2 +1,11 @@
 import type { AIAdapter, AIConfig } from '../types/adapters/ai.js';
+/**
+ * Anthropic Claude AI adapter for `generateAltText`.
+ *
+ * `@anthropic-ai/sdk` is an **optional peer dependency** — install it in your
+ * project (`pnpm add @anthropic-ai/sdk`) when using this adapter. SDK loads
+ * lazily on first call; missing peer throws a clear error.
+ *
+ * @public
+ */
 export declare function claudeAdapter(config: AIConfig): AIAdapter;