lynkow 1.32.0 → 1.32.20

package/dist/index.d.mts

@@ -290,24 +290,33 @@ declare class CategoriesService extends BaseService {
  * @example
  * ```typescript
  * const lynkow = createClient({ siteId: '...' })
- * const { data } = await lynkow.tags.list()
+ * const { data, meta } = await lynkow.tags.list({ limit: 50 })
  * ```
  */
 declare class TagsService extends BaseService {
     /**
-     * Retrieves the complete list of tags available on the site.
-     * Returns all tags (no pagination). Cached for 5 minutes per locale.
+     * Retrieves a paginated list of tags available on the site.
      *
+     * Cached for 5 minutes per (locale + pagination) combination. The cache
+     * key splits on `page` and `limit` so adjacent pages do not collide.
+     *
+     * @param filters - Pagination filters: `page` (1-based), `limit` (1-100), `perPage` (deprecated alias)
      * @param options - Request options; use `locale` to fetch localized tag names
-     * @returns An object containing `data` (array of `Tag` with id, name, slug, and locale)
+     * @returns `{ data: Tag[], meta: PaginationMeta }`. Server defaults to 20 items per page (ADR-0022 D3); pass `{ limit: 100 }` to recover pre-1.32.2 behavior.
      *
      * @example
      * ```typescript
-     * const { data } = await lynkow.tags.list()
-     * data.forEach(tag => console.log(tag.name)) // "Featured", "Tutorial", etc.
+     * // Default: first 20 tags.
+     * const { data, meta } = await lynkow.tags.list()
+     *
+     * // Page through everything.
+     * for (let page = 1; page <= meta.lastPage; page++) {
+     *   const { data } = await lynkow.tags.list({ page, limit: 50 })
+     *   data.forEach(t => console.log(t.name))
+     * }
      * ```
      */
-    list(options?: BaseRequestOptions): Promise<TagsListResponse>;
+    list(filters?: TagsListFilters, options?: BaseRequestOptions): Promise<TagsListResponse>;
     /**
      * Invalidate every cached tag response (lists, tag-filtered contents).
      * Call after an admin mutation or on receipt of a `tag.*` webhook so
@@ -566,15 +575,15 @@ declare class BlocksService extends BaseService {
  * ```typescript
  * const lynkow = createClient({ siteId: '...' })
  *
- * // Fetch form schema to render the form
+ * // Fetch the form schema to render the form
  * const form = await lynkow.forms.getBySlug('contact')
  *
- * // Submit form data
- * await lynkow.forms.submit('contact', {
- *   name: 'Jane',
- *   email: 'jane@example.com',
- *   message: 'Hello!'
- * })
+ * // Build the submission payload using each field's auto-generated id
+ * const data = Object.fromEntries(
+ *   form.schema.fields.map(field => [field.id, readUserValue(field)])
+ * )
+ *
+ * await lynkow.forms.submit('contact', data)
  * ```
  */
 declare class FormsService extends BaseService {
@@ -586,22 +595,31 @@ declare class FormsService extends BaseService {
     constructor(config: InternalConfig);
     /**
      * Retrieves a form definition by its slug, including the field schema,
-     * validation rules, settings (submit label, success message), and spam
-     * protection configuration (honeypot/reCAPTCHA). Cached for 10 minutes.
+     * behavior settings (submit label, success message), and spam protection
+     * configuration (honeypot/reCAPTCHA). Cached for 10 minutes.
      *
      * @param slug - The unique slug of the form (e.g. `'contact'`, `'newsletter'`, `'feedback'`)
-     * @returns The `Form` object with `schema` (array of `FormField` with type, label,
-     *   required, validation, options), `settings` (submitLabel, successMessage, redirectUrl),
-     *   and spam protection flags (honeypotEnabled, recaptchaEnabled, recaptchaSiteKey)
+     * @returns The `Form` object. The `schema` property is a `FormSchema`
+     *   object with `fields` (the ordered list of `FormField`), `settings`
+     *   (submitLabel, successMessage, redirectUrl, etc.), `conditions`
+     *   (cross-field rules), and an optional `pages` array for multi-page forms.
+     *   Spam protection flags live at the top level (`honeypotEnabled`,
+     *   `recaptchaEnabled`, `recaptchaSiteKey`).
      * @throws {LynkowError} With code `'NOT_FOUND'` if no active form matches the slug
      *
      * @example
      * ```typescript
      * const form = await lynkow.forms.getBySlug('contact')
-     * // Iterate fields to render the form dynamically
-     * form.schema.forEach(field => {
-     *   console.log(field.name, field.type, field.required)
+     *
+     * // Render fields in order. Each field's `id` is the key you use later
+     * // when submitting, not its label or any semantic name.
+     * form.schema.fields.forEach(field => {
+     *   console.log(field.id, field.type, field.label, field.required)
      * })
+     *
+     * // Use schema.settings to wire the submit button and success message
+     * console.log(form.schema.settings.submitLabel)
+     *
      * // Check spam protection config
      * if (form.recaptchaEnabled) {
      *   // Render reCAPTCHA widget using form.recaptchaSiteKey
@@ -611,15 +629,18 @@ declare class FormsService extends BaseService {
     getBySlug(slug: string): Promise<Form>;
     /**
      * Submits form data to the API. Anti-spam honeypot fields (`_hp`, `_ts`) are
-     * injected automatically by the SDK -- you do not need to add them yourself.
+     * injected automatically by the SDK; you do not need to add them yourself.
      * If the form has reCAPTCHA enabled, pass the token via `options.recaptchaToken`.
      *
      * @param slug - The slug of the form to submit to (e.g. `'contact'`)
-     * @param data - Key-value pairs matching the form's field names.
-     *   Values can be `string`, `number`, `boolean`, or `File`.
+     * @param data - Key-value pairs keyed by `FormField.id` (auto-generated by
+     *   the admin, e.g. `'field_1764776796820'`) from the schema returned by
+     *   `getBySlug()`. Do not use semantic names like `'name'` or `'email'`
+     *   unless those happen to be the actual field ids; field ids are not
+     *   human-readable. Values can be `string`, `number`, `boolean`, or `File`.
      * @param options - Optional submission options:
-     *   - `recaptchaToken` — the reCAPTCHA v3 token (required if reCAPTCHA is enabled on the form)
-     *   - `fetchOptions` — custom fetch options (e.g. AbortSignal)
+     *   - `recaptchaToken`: the reCAPTCHA v3 token (required if reCAPTCHA is enabled on the form)
+     *   - `fetchOptions`: custom fetch options (e.g. AbortSignal)
      * @returns A `FormSubmitResponse` with `message` (confirmation text), `status`
      *   (`'success'` for immediate acceptance, `'pending'` if double opt-in is enabled),
      *   and optionally `submissionId`
@@ -629,11 +650,16 @@ declare class FormsService extends BaseService {
      *
      * @example
      * ```typescript
-     * const result = await lynkow.forms.submit('contact', {
-     *   name: 'John Doe',
-     *   email: 'john@example.com',
-     *   message: 'Hello!'
-     * })
+     * const form = await lynkow.forms.getBySlug('contact')
+     *
+     * // Build the payload with field.id as key. The SDK does not transform
+     * // semantic names into ids; you must do that yourself based on the schema.
+     * const data: Record<string, string> = {}
+     * for (const field of form.schema.fields) {
+     *   data[field.id] = readValueForField(field) // your UI binding
+     * }
+     *
+     * const result = await lynkow.forms.submit('contact', data)
      *
      * if (result.status === 'pending') {
      *   // Show "check your email" confirmation
@@ -3324,13 +3350,14 @@ interface GlobalBlock {
  *
  * Maps to standard HTML input types, with a few additions:
  * - `'textarea'`: multi-line text input (`<textarea>`)
- * - `'select'`: dropdown menu (`<select>`) — requires `options`
- * - `'radio'`: radio button group — requires `options`
- * - `'checkbox'`: checkbox or checkbox group — uses `options` if present, otherwise single boolean
- * - `'file'`: file upload input — accepts files via multipart form submission
- * - `'hidden'`: hidden input — not displayed to users, useful for tracking parameters
+ * - `'select'`: dropdown menu (`<select>`); requires `options`
+ * - `'radio'`: radio button group; requires `options`
+ * - `'checkbox'`: checkbox or checkbox group; uses `options` if present, otherwise single boolean
+ * - `'file'`: file upload input; accepts files via multipart form submission
+ * - `'rating'`: star/score rating input
+ * - `'hidden'`: hidden input; not displayed to users, useful for tracking parameters
  */
-type FormFieldType = 'text' | 'email' | 'tel' | 'url' | 'textarea' | 'number' | 'date' | 'datetime' | 'time' | 'select' | 'radio' | 'checkbox' | 'file' | 'hidden';
+type FormFieldType = 'text' | 'email' | 'tel' | 'url' | 'textarea' | 'number' | 'date' | 'datetime' | 'time' | 'select' | 'radio' | 'checkbox' | 'file' | 'rating' | 'hidden';
 /**
  * A selectable option for `select`, `radio`, and `checkbox` field types.
  */
@@ -3354,7 +3381,8 @@ interface FormFieldOption {
  * Which rules are relevant depends on the field type:
  * - `minLength`/`maxLength`: text-based fields (`text`, `email`, `textarea`, `url`, `tel`)
  * - `min`/`max`: `number` fields only
- * - `pattern`: any text-based field — validated as a JavaScript RegExp
+ * - `pattern`: any text-based field; validated as a JavaScript RegExp
+ * - `accept`/`maxSize`: `file` field only
  */
 interface FormFieldValidation {
     /**
@@ -3372,13 +3400,13 @@ interface FormFieldValidation {
     /**
      * Minimum numeric value (inclusive).
      * Only applicable to `number` field type.
-     * Ignored for text fields — use `minLength` instead.
+     * Ignored for text fields. Use `minLength` instead.
      */
     min?: number;
     /**
      * Maximum numeric value (inclusive).
      * Only applicable to `number` field type.
-     * Ignored for text fields — use `maxLength` instead.
+     * Ignored for text fields. Use `maxLength` instead.
      */
     max?: number;
     /**
@@ -3387,6 +3415,16 @@ interface FormFieldValidation {
      * Applicable to any text-based field type.
      */
     pattern?: string;
+    /**
+     * Accepted MIME types or extensions for `file` fields (e.g. `'image/*,.pdf'`).
+     * Mirrors the HTML `accept` attribute. Ignored for non-`file` fields.
+     */
+    accept?: string;
+    /**
+     * Maximum file size in bytes for `file` fields.
+     * Ignored for non-`file` fields.
+     */
+    maxSize?: number;
     /**
      * Custom error message displayed when validation fails.
      * `undefined` means the browser/framework default message is used.
@@ -3394,6 +3432,56 @@ interface FormFieldValidation {
      */
     message?: string;
 }
+/**
+ * Conditional logic rule applied to a form field.
+ *
+ * When the referenced `field` matches the operator/value combination, the
+ * `action` is applied (show, hide, require, or skip to a target page).
+ * Used for dynamic forms where some fields appear conditionally based on
+ * earlier answers.
+ */
+interface FormCondition {
+    /**
+     * The `FormField.id` of the field whose value triggers this condition.
+     */
+    field: string;
+    /**
+     * Comparison operator applied to the referenced field's current value.
+     */
+    operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'is_empty' | 'is_not_empty';
+    /**
+     * Value compared against the referenced field. Type depends on the field
+     * type: string for text fields, number for number fields, boolean for
+     * checkboxes. `undefined` for `is_empty` / `is_not_empty`.
+     */
+    value?: unknown;
+    /**
+     * Effect applied when the condition matches:
+     * - `'show'` / `'hide'`: toggle visibility of the target field
+     * - `'require'`: mark the target field required
+     * - `'skip_to_page'`: jump to the page identified by `targetPage`
+     */
+    action: 'show' | 'hide' | 'require' | 'skip_to_page';
+    /**
+     * Target page index for `skip_to_page` actions.
+     * Ignored for other actions.
+     */
+    targetPage?: number;
+}
+/**
+ * Phone field configuration.
+ * Only relevant for fields of type `'tel'`.
+ */
+interface FormFieldPhoneOptions {
+    /**
+     * Whether the country-code selector is rendered next to the phone input.
+     */
+    showCountryCode: boolean;
+    /**
+     * Default country code (e.g. `'+33'`, `'+1'`).
+     */
+    defaultCountryCode: string;
+}
 /**
  * A single field definition in a form schema.
  * Describes the input type, label, validation, and layout for one form field.
@@ -3403,11 +3491,11 @@ interface FormFieldValidation {
 interface FormField {
     /**
      * Field identifier, used as the key in submission data.
-     * Unique within the form. Lowercase, alphanumeric with underscores or hyphens
-     * (e.g. `'first_name'`, `'email'`). Max 100 characters.
-     * This is the key you use in `FormSubmitData` when submitting.
+     * Auto-generated by the admin (e.g. `'field_1764776796820'`), unique within
+     * the form. This is the key you must use in `FormSubmitData` when calling
+     * `forms.submit()`.
      */
-    name: string;
+    id: string;
     /**
      * HTML input type for this field.
      * Determines the rendered input element and applicable validation rules.
@@ -3417,7 +3505,7 @@ interface FormField {
     type: FormFieldType;
     /**
      * Human-readable label displayed above or beside the input.
-     * Max 255 characters. Always present — use this as the `<label>` text.
+     * Max 255 characters. Always present. Use this as the `<label>` text.
      */
     label: string;
     /**
@@ -3426,12 +3514,19 @@ interface FormField {
      * Use as the HTML `placeholder` attribute.
      */
     placeholder?: string;
+    /**
+     * Help text displayed below the input to guide the user.
+     * Max 500 characters. `undefined` if not configured.
+     * Render as a small description below the field (e.g. `<small>` or `aria-describedby`).
+     */
+    description?: string;
     /**
      * Whether this field must be filled before submission.
      * When `true`, the server will reject submissions with this field empty.
      * Render a required indicator (e.g. `*`) and set the HTML `required` attribute.
+     * `undefined` is treated as `false`.
      */
-    required: boolean;
+    required?: boolean;
     /**
      * Selectable options for `select`, `radio`, and `checkbox` field types.
      * `undefined` for field types that don't use options (text, email, number, etc.).
@@ -3444,7 +3539,7 @@ interface FormField {
     /**
      * Validation rules applied to this field's value.
      * `undefined` if no extra validation beyond `required` is configured.
-     * Rules are enforced server-side — client-side validation is optional but recommended for UX.
+     * Rules are enforced server-side; client-side validation is optional but recommended for UX.
      *
      * @see {@link FormFieldValidation}
      */
@@ -3453,72 +3548,157 @@ interface FormField {
      * Pre-filled default value for the field.
      * Type depends on the field type: `string` for text fields, `number` for number fields,
      * `boolean` for checkbox (single toggle mode).
-     * `undefined` if no default is set — the field starts empty.
+     * `undefined` if no default is set. The field starts empty.
      */
     defaultValue?: string | number | boolean;
-    /**
-     * Help text displayed below the input to guide the user.
-     * Max 500 characters. `undefined` if not configured.
-     * Render as a small description below the field (e.g. `<small>` or `aria-describedby`).
-     */
-    helpText?: string;
     /**
      * Layout width hint for responsive form layouts:
      * - `'full'`: spans the entire form width (100%)
-     * - `'half'`: spans half the form width (50%) — place two `half` fields side by side
-     * - `'third'`: spans one third of the form width (33%) — place three `third` fields in a row
+     * - `'half'`: spans half the form width (50%); place two `half` fields side by side
+     * - `'third'`: spans one third of the form width (33%); place three `third` fields in a row
      *
      * `undefined` defaults to `'full'`.
      */
     width?: 'full' | 'half' | 'third';
+    /**
+     * Per-field conditional logic. When present, the field is only rendered or
+     * required based on the values of earlier fields. Conditions defined here
+     * are scoped to this field; cross-field rules live in `FormSchema.conditions`.
+     *
+     * @see {@link FormCondition}
+     */
+    conditions?: FormCondition[];
+    /**
+     * Configuration for `tel` (phone) fields.
+     * `undefined` for non-phone field types.
+     */
+    phoneOptions?: FormFieldPhoneOptions;
 }
 /**
- * Form behavior settings controlling what happens after submission.
+ * Form behavior settings nested under `FormSchema.settings`.
+ * Controls submit button text, success message, redirect, and progress UI.
  */
-interface FormSettings {
+interface FormSchemaSettings {
     /**
-     * Text displayed on the submit button (e.g. `'Send'`, `'Subscribe'`, `'Submit'`).
-     * Max 100 characters. Always present.
+     * Text displayed on the submit button (e.g. `'Send'`, `'Subscribe'`).
+     * `undefined` falls back to a default label rendered by the host application.
      */
-    submitLabel: string;
+    submitLabel?: string;
     /**
      * Success message displayed after a successful submission.
-     * Max 1000 characters. Shown inline on the page.
-     *
-     * Ignored if `redirectUrl` is set — the user is redirected instead of seeing this message.
+     * Shown inline on the page. Ignored if `redirectUrl` is set.
+     * `undefined` falls back to a default message.
      */
-    successMessage: string;
+    successMessage?: string;
     /**
      * URL to redirect the user to after successful submission.
-     * Max 500 characters. Must be a valid URL (e.g. `'https://example.com/thank-you'`).
-     * When set, takes precedence over `successMessage` — the user is navigated away immediately.
+     * Must be a valid URL. When set, takes precedence over `successMessage`.
      * `undefined` means show `successMessage` inline instead.
      */
     redirectUrl?: string;
     /**
-     * Whether double opt-in email confirmation is enabled.
-     * When `true`, the form sends a confirmation email to the user before
-     * recording the submission as confirmed. Useful for newsletter signups.
-     * `undefined` or `false` means submissions are recorded immediately.
+     * Whether the form requires the visitor to be authenticated.
+     * Enforced server-side. `undefined` is treated as `false`.
      */
-    doubleOptIn?: boolean;
+    requireAuth?: boolean;
+    /**
+     * Message displayed when the form is closed (no longer accepting submissions).
+     * `undefined` falls back to a default message.
+     */
+    closedMessage?: string;
+    /**
+     * Whether to render a progress bar for multi-page forms.
+     * `undefined` is treated as `false`.
+     */
+    showProgressBar?: boolean;
+}
+/**
+ * Backwards-compatible alias for {@link FormSchemaSettings}.
+ *
+ * @deprecated Use `FormSchemaSettings` directly. The old root-level
+ *   `Form.settings` property has been removed in 1.32.1; settings now live
+ *   under `Form.schema.settings`. This alias will be removed in a future
+ *   major version.
+ */
+type FormSettings = FormSchemaSettings;
+/**
+ * Page definition for multi-page forms.
+ *
+ * Multi-page forms split fields across pages, identified by `fields` (a list
+ * of `FormField.id` values that belong to the page). Single-page forms have
+ * no `pages` entry on the schema.
+ */
+interface FormPage {
+    /**
+     * Page title displayed at the top of the page.
+     * `undefined` if not configured.
+     */
+    title?: string;
+    /**
+     * Page description displayed below the title.
+     * `undefined` if not configured.
+     */
+    description?: string;
+    /**
+     * Ordered list of `FormField.id` values that belong to this page.
+     * Each id must reference a field in `FormSchema.fields`.
+     */
+    fields: string[];
+}
+/**
+ * Full schema describing a form's fields, layout, behavior, and conditional logic.
+ *
+ * Returned as the `schema` property of {@link Form} by `forms.getBySlug()`.
+ * Render `fields` in order to build the form UI dynamically. Use `settings`
+ * to wire the submit button and post-submission behavior. Use `conditions`
+ * for cross-field rules (e.g. show field B when field A equals X).
+ */
+interface FormSchema {
+    /**
+     * Ordered array of field definitions that make up the form.
+     * Render in order to build the form UI.
+     *
+     * @see {@link FormField}
+     */
+    fields: FormField[];
+    /**
+     * Page definitions for multi-page forms.
+     * `undefined` for single-page forms.
+     *
+     * @see {@link FormPage}
+     */
+    pages?: FormPage[];
+    /**
+     * Behavior settings (submit label, success message, redirect, progress bar).
+     *
+     * @see {@link FormSchemaSettings}
+     */
+    settings: FormSchemaSettings;
+    /**
+     * Cross-field conditional logic rules. Each rule references a field by id,
+     * compares its value, and applies an action (show/hide/require/skip).
+     *
+     * @see {@link FormCondition}
+     */
+    conditions: FormCondition[];
 }
 /**
  * A public form available for submission.
- * Returned by `GET /public/forms/:slug`.
+ * Returned by `GET /public/{siteId}/forms/{slug}` and unwrapped from the
+ * `{ data }` envelope by `forms.getBySlug()`.
  *
- * Use `schema` to dynamically render the form fields, `settings` to configure
- * the submit button and post-submission behavior, and the spam protection fields
- * to set up honeypot or reCAPTCHA if enabled.
+ * Use `schema.fields` to dynamically render the form fields, `schema.settings`
+ * to configure the submit button and post-submission behavior, and the spam
+ * protection flags to set up honeypot or reCAPTCHA if enabled.
  *
  * Only forms with `status: 'active'` are returned by the public API.
  * Draft, closed, and archived forms are never returned.
  */
 interface Form {
     /**
-     * Unique numeric form ID. Auto-incremented.
+     * Unique form identifier (UUID v4).
      */
-    id: number;
+    id: string;
     /**
      * Form display name (e.g. `'Contact Us'`, `'Newsletter Signup'`). Max 255 characters.
      */
@@ -3526,8 +3706,8 @@ interface Form {
     /**
      * URL-friendly slug, unique within the site.
      * Lowercase, hyphenated (e.g. `'contact-us'`). Max 255 characters.
-     * Used to fetch the form: `GET /public/forms/:slug`.
-     * Also used as the submission endpoint: `POST /public/forms/:slug/submit`.
+     * Used to fetch the form: `GET /public/{siteId}/forms/{slug}`.
+     * Also used as the submission endpoint: `POST /public/{siteId}/forms/{slug}/submit`.
      */
     slug: string;
     /**
@@ -3537,18 +3717,12 @@ interface Form {
      */
     description: string | null;
     /**
-     * Ordered array of field definitions that make up the form.
-     * Render these in order to build the form UI dynamically.
-     *
-     * @see {@link FormField}
-     */
-    schema: FormField[];
-    /**
-     * Form behavior settings (submit button text, success message, redirect).
+     * Schema describing the form's fields, layout, behavior settings, and
+     * conditional logic. Iterate `schema.fields` to render the form.
      *
-     * @see {@link FormSettings}
+     * @see {@link FormSchema}
      */
-    settings: FormSettings;
+    schema: FormSchema;
     /**
      * Form status. Always `'active'` via the public API.
      * Draft, closed, and archived forms are never returned by public endpoints.
@@ -3579,7 +3753,7 @@ interface Form {
      * 3. Include the reCAPTCHA token in the submission payload
      *
      * The SDK handles this automatically if you use `lynkow.forms.submit()`.
-     * Cannot be combined with honeypot — only one spam protection method is active.
+     * Cannot be combined with honeypot; only one spam protection method is active.
      *
      * `undefined` or `false` means reCAPTCHA is not active.
      */
@@ -3590,17 +3764,21 @@ interface Form {
      * `null` or `undefined` when reCAPTCHA is not configured.
      *
      * Pass this to `grecaptcha.render()` or the `sitekey` parameter in the reCAPTCHA script URL.
-     * The secret key is never exposed — it stays server-side.
+     * The secret key is never exposed; it stays server-side.
      */
     recaptchaSiteKey?: string | null;
 }
 /**
  * Data payload for submitting a form.
  *
- * Keys correspond to `FormField.name` values from the form's `schema`.
+ * Keys correspond to `FormField.id` values from the form's `schema.fields`.
+ * IDs are auto-generated by the admin (e.g. `'field_1764776796820'`),
+ * not human-readable names. Always derive the keys from the schema returned
+ * by `forms.getBySlug()`; do not hard-code semantic names.
+ *
  * Value types depend on the field type:
  * - Text fields (`text`, `email`, `textarea`, `url`, `tel`): `string`
- * - Number fields: `number`
+ * - Number fields (`number`, `rating`): `number`
  * - Checkbox (single): `boolean`
  * - File fields: `File` (browser File object)
  * - Select/radio/checkbox (with options): `string` (the selected option's `value`)
@@ -3610,13 +3788,15 @@ interface Form {
  *
  * @example
  * ```typescript
- * const data: FormSubmitData = {
- *   name: 'Jane Doe',
- *   email: 'jane@example.com',
- *   message: 'Hello!',
- *   newsletter: true,
+ * const form = await lynkow.forms.getBySlug('contact')
+ *
+ * // Build the payload keyed by field.id (the auto-generated identifier)
+ * const data: FormSubmitData = {}
+ * for (const field of form.schema.fields) {
+ *   data[field.id] = readValueForField(field) // your UI binding
  * }
- * await lynkow.forms.submit('contact-us', data)
+ *
+ * await lynkow.forms.submit('contact', data)
  * ```
  */
 type FormSubmitData = Record<string, string | number | boolean | File>;
@@ -4594,14 +4774,21 @@ interface CategoryDetailResponse {
 }
 /**
  * Response from `tags.list()`.
- * Returns all tags in a single non-paginated response.
+ * Paginated since SDK 1.32.2 (the wire was already returning `meta`; the SDK
+ * type now exposes it). Server-side default is 20 items per page on
+ * `/v1/tags` and `/public/.../tags`, with `maxLimit=100` (ADR-0022 D3).
  */
 interface TagsListResponse {
     /**
-     * Flat array of all tags for the current locale.
-     * Not paginated -- all tags are returned at once.
+     * Tags for the current page in the current locale.
+     * Empty array when no tags match (or when paging past the last page).
      */
     data: Tag[];
+    /**
+     * Pagination metadata describing total count, page position, and navigation
+     * flags. See {@link PaginationMeta}.
+     */
+    meta: PaginationMeta;
 }
 /**
  * Response from `pages.list()`.
@@ -4878,7 +5065,11 @@ interface BaseRequestOptions {
 }
 /**
  * Pagination options for list endpoints.
- * All values are 1-based integers. The API defaults to page 1 with 15 items per page.
+ *
+ * All values are 1-based integers. The server default is 20 items per page
+ * on public-tier endpoints (`/public`, `/v1`) and 50 on admin-tier
+ * endpoints (`/api`, `/admin`), per ADR-0022 D3. Documented exceptions:
+ * SSG endpoints like `/public/.../categories/:slug` default to 500.
  */
 interface PaginationOptions {
     /**
@@ -4889,8 +5080,10 @@ interface PaginationOptions {
     page?: number;
     /**
      * Maximum number of items per page.
-     * Defaults to 15. Maximum allowed value is 100.
-     * Values above 100 are silently capped by the API.
+     * Server default is 20 on public-tier endpoints (`/public`, `/v1`).
+     * Maximum allowed value is 100 (except documented SSG exceptions like
+     * `/public/.../categories/:slug` which permit up to 500).
+     * Values above the per-endpoint maximum are silently capped by the API.
      */
     limit?: number;
     /**
@@ -4977,6 +5170,25 @@ interface CategoryOptions extends PaginationOptions {
      */
     locale?: string;
 }
+/**
+ * Filters for the `tags.list()` endpoint.
+ *
+ * Pagination + locale. The public `/v1/tags` endpoint does not expose
+ * search or sort on its public surface. `limit` defaults to 20 server-side
+ * on the public-tier mounts (`/public/.../tags`, `/v1/tags`) per
+ * ADR-0022 D3, with `maxLimit=100`.
+ */
+interface TagsListFilters extends PaginationOptions {
+    /**
+     * Locale override for this request.
+     * When omitted, uses the client's default locale or the site's default locale.
+     * If both `filters.locale` and `options.locale` are passed, `options.locale`
+     * wins (mirrors `contents.list()` precedence).
+     *
+     * @example 'fr'
+     */
+    locale?: string;
+}
 /**
  * Filters for the `reviews.list()` endpoint.
  * Only approved reviews are returned; these filters further narrow the result set.
@@ -6670,4 +6882,4 @@ declare function renderJsonLdGraph(nodes: object[] | null | undefined): string;
  */
 declare function mergeIntoGraph(server: object[] | null | undefined, custom: object[] | null | undefined): object[];
 
-export { type Alternate, AnalyticsService, type ApiErrorDetail, type Author, type BaseRequestOptions, BlocksService, BrandingService, type CategoriesListResponse, CategoriesService, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, ConsentService, type Content, type ContentBody, type ContentResolveResponse, type ContentSchema, type ContentSummary, type ContentsFilters, type ContentsListResponse, ContentsService, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, CookiesService, type EnhancementsInitOptions, EnhancementsService, type ErrorCode, type EventData, type EventName, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormSettings, type FormSubmitData, type FormSubmitResponse, FormsService, type GlobalBlock, type GlobalBlockResponse, type ImageVariants, type JsonLdGraphConfig, type JsonLdNode, type JsonLdNodeSource, type LegalDocument, LegalService, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, MediaHelperService, type Page, type PageSeo, type PageSummary, type PagesListResponse, PagesService, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, PathsService, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, ReviewsService, type SchemaField, type SchemaFieldOption, type SchemaFieldType, type SchemaFieldValidation, type SearchConfig, type SearchHit, type SearchOptions, type SearchProfilePublic, type SearchResponse, SearchService, SeoService, type SiteConfig, type SiteConfigResponse, SiteService, type SortOptions, type SrcsetOptions, type SubmitOptions, type Tag, type TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, mergeIntoGraph, onSiteThemeChange, renderJsonLdGraph };
+export { type Alternate, AnalyticsService, type ApiErrorDetail, type Author, type BaseRequestOptions, BlocksService, BrandingService, type CategoriesListResponse, CategoriesService, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, ConsentService, type Content, type ContentBody, type ContentResolveResponse, type ContentSchema, type ContentSummary, type ContentsFilters, type ContentsListResponse, ContentsService, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, CookiesService, type EnhancementsInitOptions, EnhancementsService, type ErrorCode, type EventData, type EventName, type Form, type FormCondition, type FormField, type FormFieldOption, type FormFieldPhoneOptions, type FormFieldType, type FormFieldValidation, type FormPage, type FormSchema, type FormSchemaSettings, type FormSettings, type FormSubmitData, type FormSubmitResponse, FormsService, type GlobalBlock, type GlobalBlockResponse, type ImageVariants, type JsonLdGraphConfig, type JsonLdNode, type JsonLdNodeSource, type LegalDocument, LegalService, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, MediaHelperService, type Page, type PageSeo, type PageSummary, type PagesListResponse, PagesService, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, PathsService, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, ReviewsService, type SchemaField, type SchemaFieldOption, type SchemaFieldType, type SchemaFieldValidation, type SearchConfig, type SearchHit, type SearchOptions, type SearchProfilePublic, type SearchResponse, SearchService, SeoService, type SiteConfig, type SiteConfigResponse, SiteService, type SortOptions, type SrcsetOptions, type SubmitOptions, type Tag, type TagsListFilters, type TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, mergeIntoGraph, onSiteThemeChange, renderJsonLdGraph };