includio-cms 0.19.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,6 +3,61 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 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".

package/DOCS.md

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

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/components/ui/input-group/input-group-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const InputGroupInput: import("svelte").Component<(Omit<import("svelte/e
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "image" | "url" | "text" | "date" | "radio" | "color" | "button" | "checkbox" | "search" | (string & {}) | "email" | "time" | "password" | "hidden" | "reset" | "submit" | "tel" | "datetime-local" | "month" | "range" | "week";
+    type?: "number" | "image" | "url" | "text" | "date" | "radio" | "color" | "button" | "checkbox" | "search" | (string & {}) | "email" | "password" | "time" | "hidden" | "reset" | "submit" | "tel" | "datetime-local" | "month" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/components/ui/sidebar/sidebar-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const SidebarInput: import("svelte").Component<(Omit<import("svelte/elem
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "image" | "url" | "text" | "date" | "radio" | "color" | "button" | "checkbox" | "search" | (string & {}) | "email" | "time" | "password" | "hidden" | "reset" | "submit" | "tel" | "datetime-local" | "month" | "range" | "week";
+    type?: "number" | "image" | "url" | "text" | "date" | "radio" | "color" | "button" | "checkbox" | "search" | (string & {}) | "email" | "password" | "time" | "hidden" | "reset" | "submit" | "tel" | "datetime-local" | "month" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/core/cms.d.ts

@@ -38,4 +38,8 @@ export declare class CMS implements ICMS {
     getFormBySlug(slug: string): FormConfig;
 }
 export declare function initCMS(config: CMSConfig): CMS;
+/**
+ * Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
+ * @public
+ */
 export declare function getCMS(): CMS;

package/dist/core/cms.js

@@ -159,6 +159,10 @@ export function initCMS(config) {
         .catch((e) => console.warn('[cms] Failed to start background maintenance:', e));
     return cms;
 }
+/**
+ * Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
+ * @public
+ */
 export function getCMS() {
     if (!cms) {
         throw new Error('CMS not initialized. Call initCMS() first with your CMS config.');

package/dist/core/index.d.ts

@@ -1,2 +1,4 @@
 export { getCMS } from './cms.js';
 export { resolveMediaWithStyles, type ResolvedMedia } from './server/fields/utils/resolveMedia.js';
+export { createEntityAPI } from '../entity/index.js';
+export { getAuth } from '../server/auth.js';

package/dist/core/index.js

@@ -1,2 +1,4 @@
 export { getCMS } from './cms.js';
 export { resolveMediaWithStyles } from './server/fields/utils/resolveMedia.js';
+export { createEntityAPI } from '../entity/index.js';
+export { getAuth } from '../server/auth.js';

package/dist/core/server/consentLogs/operations/create.d.ts

@@ -1,2 +1,6 @@
 import type { ConsentLogData } from '../../../../types/consent.js';
+/**
+ * Persists a CMP consent log entry via the database adapter.
+ * @public
+ */
 export declare const createConsentLog: (data: ConsentLogData) => Promise<void>;

package/dist/core/server/consentLogs/operations/create.js

@@ -1,4 +1,8 @@
 import { getCMS } from '../../../cms.js';
+/**
+ * Persists a CMP consent log entry via the database adapter.
+ * @public
+ */
 export const createConsentLog = async (data) => {
     await getCMS().databaseAdapter.createConsentLog(data);
 };

package/dist/core/server/fields/utils/resolveMedia.d.ts

@@ -1,12 +1,15 @@
 import type { ImageFieldStyle } from '../../../../types/fields.js';
 import type { ImageStyle, MediaFile } from '../../../../types/media.js';
+/**
+ * @public
+ */
 export interface ResolvedMedia {
     data: MediaFile;
     styles: Record<string, ImageStyle>;
     blurDataUrl: string | null;
 }
 /**
- * Resolve media files by IDs and generate image styles.
- * Useful for plugins that need to resolve media references (e.g. photo-grid).
+ * Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+ * @public
  */
 export declare function resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>;

package/dist/core/server/fields/utils/resolveMedia.js

@@ -1,8 +1,8 @@
 import { getCMS } from '../../../cms.js';
 import { getImageStyles } from './imageStyles.js';
 /**
- * Resolve media files by IDs and generate image styles.
- * Useful for plugins that need to resolve media references (e.g. photo-grid).
+ * Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+ * @public
  */
 export async function resolveMediaWithStyles(mediaIds, styles) {
     if (!mediaIds.length)

package/dist/core/server/forms/submissions/operations/create.d.ts

@@ -1,7 +1,14 @@
+/**
+ * @public
+ */
 export interface CreateFormSubmissionOptions {
     slug: string;
     data: Record<string, unknown>;
     ip?: string;
     userAgent?: string;
 }
+/**
+ * Persists a form submission and triggers best-effort notification email. Returns `true` if the row was written (email failures are logged, do not affect return).
+ * @public
+ */
 export declare const createFormSubmission: (options: CreateFormSubmissionOptions) => Promise<boolean>;