lynkow 1.32.0 → 1.32.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -566,15 +566,15 @@ declare class BlocksService extends BaseService {
566
566
  * ```typescript
567
567
  * const lynkow = createClient({ siteId: '...' })
568
568
  *
569
- * // Fetch form schema to render the form
569
+ * // Fetch the form schema to render the form
570
570
  * const form = await lynkow.forms.getBySlug('contact')
571
571
  *
572
- * // Submit form data
573
- * await lynkow.forms.submit('contact', {
574
- * name: 'Jane',
575
- * email: 'jane@example.com',
576
- * message: 'Hello!'
577
- * })
572
+ * // Build the submission payload using each field's auto-generated id
573
+ * const data = Object.fromEntries(
574
+ * form.schema.fields.map(field => [field.id, readUserValue(field)])
575
+ * )
576
+ *
577
+ * await lynkow.forms.submit('contact', data)
578
578
  * ```
579
579
  */
580
580
  declare class FormsService extends BaseService {
@@ -586,22 +586,31 @@ declare class FormsService extends BaseService {
586
586
  constructor(config: InternalConfig);
587
587
  /**
588
588
  * Retrieves a form definition by its slug, including the field schema,
589
- * validation rules, settings (submit label, success message), and spam
590
- * protection configuration (honeypot/reCAPTCHA). Cached for 10 minutes.
589
+ * behavior settings (submit label, success message), and spam protection
590
+ * configuration (honeypot/reCAPTCHA). Cached for 10 minutes.
591
591
  *
592
592
  * @param slug - The unique slug of the form (e.g. `'contact'`, `'newsletter'`, `'feedback'`)
593
- * @returns The `Form` object with `schema` (array of `FormField` with type, label,
594
- * required, validation, options), `settings` (submitLabel, successMessage, redirectUrl),
595
- * and spam protection flags (honeypotEnabled, recaptchaEnabled, recaptchaSiteKey)
593
+ * @returns The `Form` object. The `schema` property is a `FormSchema`
594
+ * object with `fields` (the ordered list of `FormField`), `settings`
595
+ * (submitLabel, successMessage, redirectUrl, etc.), `conditions`
596
+ * (cross-field rules), and an optional `pages` array for multi-page forms.
597
+ * Spam protection flags live at the top level (`honeypotEnabled`,
598
+ * `recaptchaEnabled`, `recaptchaSiteKey`).
596
599
  * @throws {LynkowError} With code `'NOT_FOUND'` if no active form matches the slug
597
600
  *
598
601
  * @example
599
602
  * ```typescript
600
603
  * const form = await lynkow.forms.getBySlug('contact')
601
- * // Iterate fields to render the form dynamically
602
- * form.schema.forEach(field => {
603
- * console.log(field.name, field.type, field.required)
604
+ *
605
+ * // Render fields in order. Each field's `id` is the key you use later
606
+ * // when submitting, not its label or any semantic name.
607
+ * form.schema.fields.forEach(field => {
608
+ * console.log(field.id, field.type, field.label, field.required)
604
609
  * })
610
+ *
611
+ * // Use schema.settings to wire the submit button and success message
612
+ * console.log(form.schema.settings.submitLabel)
613
+ *
605
614
  * // Check spam protection config
606
615
  * if (form.recaptchaEnabled) {
607
616
  * // Render reCAPTCHA widget using form.recaptchaSiteKey
@@ -611,15 +620,18 @@ declare class FormsService extends BaseService {
611
620
  getBySlug(slug: string): Promise<Form>;
612
621
  /**
613
622
  * Submits form data to the API. Anti-spam honeypot fields (`_hp`, `_ts`) are
614
- * injected automatically by the SDK -- you do not need to add them yourself.
623
+ * injected automatically by the SDK; you do not need to add them yourself.
615
624
  * If the form has reCAPTCHA enabled, pass the token via `options.recaptchaToken`.
616
625
  *
617
626
  * @param slug - The slug of the form to submit to (e.g. `'contact'`)
618
- * @param data - Key-value pairs matching the form's field names.
619
- * Values can be `string`, `number`, `boolean`, or `File`.
627
+ * @param data - Key-value pairs keyed by `FormField.id` (auto-generated by
628
+ * the admin, e.g. `'field_1764776796820'`) from the schema returned by
629
+ * `getBySlug()`. Do not use semantic names like `'name'` or `'email'`
630
+ * unless those happen to be the actual field ids; field ids are not
631
+ * human-readable. Values can be `string`, `number`, `boolean`, or `File`.
620
632
  * @param options - Optional submission options:
621
- * - `recaptchaToken` the reCAPTCHA v3 token (required if reCAPTCHA is enabled on the form)
622
- * - `fetchOptions` custom fetch options (e.g. AbortSignal)
633
+ * - `recaptchaToken`: the reCAPTCHA v3 token (required if reCAPTCHA is enabled on the form)
634
+ * - `fetchOptions`: custom fetch options (e.g. AbortSignal)
623
635
  * @returns A `FormSubmitResponse` with `message` (confirmation text), `status`
624
636
  * (`'success'` for immediate acceptance, `'pending'` if double opt-in is enabled),
625
637
  * and optionally `submissionId`
@@ -629,11 +641,16 @@ declare class FormsService extends BaseService {
629
641
  *
630
642
  * @example
631
643
  * ```typescript
632
- * const result = await lynkow.forms.submit('contact', {
633
- * name: 'John Doe',
634
- * email: 'john@example.com',
635
- * message: 'Hello!'
636
- * })
644
+ * const form = await lynkow.forms.getBySlug('contact')
645
+ *
646
+ * // Build the payload with field.id as key. The SDK does not transform
647
+ * // semantic names into ids; you must do that yourself based on the schema.
648
+ * const data: Record<string, string> = {}
649
+ * for (const field of form.schema.fields) {
650
+ * data[field.id] = readValueForField(field) // your UI binding
651
+ * }
652
+ *
653
+ * const result = await lynkow.forms.submit('contact', data)
637
654
  *
638
655
  * if (result.status === 'pending') {
639
656
  * // Show "check your email" confirmation
@@ -3324,13 +3341,14 @@ interface GlobalBlock {
3324
3341
  *
3325
3342
  * Maps to standard HTML input types, with a few additions:
3326
3343
  * - `'textarea'`: multi-line text input (`<textarea>`)
3327
- * - `'select'`: dropdown menu (`<select>`) requires `options`
3328
- * - `'radio'`: radio button group requires `options`
3329
- * - `'checkbox'`: checkbox or checkbox group uses `options` if present, otherwise single boolean
3330
- * - `'file'`: file upload input accepts files via multipart form submission
3331
- * - `'hidden'`: hidden input — not displayed to users, useful for tracking parameters
3344
+ * - `'select'`: dropdown menu (`<select>`); requires `options`
3345
+ * - `'radio'`: radio button group; requires `options`
3346
+ * - `'checkbox'`: checkbox or checkbox group; uses `options` if present, otherwise single boolean
3347
+ * - `'file'`: file upload input; accepts files via multipart form submission
3348
+ * - `'rating'`: star/score rating input
3349
+ * - `'hidden'`: hidden input; not displayed to users, useful for tracking parameters
3332
3350
  */
3333
- type FormFieldType = 'text' | 'email' | 'tel' | 'url' | 'textarea' | 'number' | 'date' | 'datetime' | 'time' | 'select' | 'radio' | 'checkbox' | 'file' | 'hidden';
3351
+ type FormFieldType = 'text' | 'email' | 'tel' | 'url' | 'textarea' | 'number' | 'date' | 'datetime' | 'time' | 'select' | 'radio' | 'checkbox' | 'file' | 'rating' | 'hidden';
3334
3352
  /**
3335
3353
  * A selectable option for `select`, `radio`, and `checkbox` field types.
3336
3354
  */
@@ -3354,7 +3372,8 @@ interface FormFieldOption {
3354
3372
  * Which rules are relevant depends on the field type:
3355
3373
  * - `minLength`/`maxLength`: text-based fields (`text`, `email`, `textarea`, `url`, `tel`)
3356
3374
  * - `min`/`max`: `number` fields only
3357
- * - `pattern`: any text-based field validated as a JavaScript RegExp
3375
+ * - `pattern`: any text-based field; validated as a JavaScript RegExp
3376
+ * - `accept`/`maxSize`: `file` field only
3358
3377
  */
3359
3378
  interface FormFieldValidation {
3360
3379
  /**
@@ -3372,13 +3391,13 @@ interface FormFieldValidation {
3372
3391
  /**
3373
3392
  * Minimum numeric value (inclusive).
3374
3393
  * Only applicable to `number` field type.
3375
- * Ignored for text fields use `minLength` instead.
3394
+ * Ignored for text fields. Use `minLength` instead.
3376
3395
  */
3377
3396
  min?: number;
3378
3397
  /**
3379
3398
  * Maximum numeric value (inclusive).
3380
3399
  * Only applicable to `number` field type.
3381
- * Ignored for text fields use `maxLength` instead.
3400
+ * Ignored for text fields. Use `maxLength` instead.
3382
3401
  */
3383
3402
  max?: number;
3384
3403
  /**
@@ -3387,6 +3406,16 @@ interface FormFieldValidation {
3387
3406
  * Applicable to any text-based field type.
3388
3407
  */
3389
3408
  pattern?: string;
3409
+ /**
3410
+ * Accepted MIME types or extensions for `file` fields (e.g. `'image/*,.pdf'`).
3411
+ * Mirrors the HTML `accept` attribute. Ignored for non-`file` fields.
3412
+ */
3413
+ accept?: string;
3414
+ /**
3415
+ * Maximum file size in bytes for `file` fields.
3416
+ * Ignored for non-`file` fields.
3417
+ */
3418
+ maxSize?: number;
3390
3419
  /**
3391
3420
  * Custom error message displayed when validation fails.
3392
3421
  * `undefined` means the browser/framework default message is used.
@@ -3394,6 +3423,56 @@ interface FormFieldValidation {
3394
3423
  */
3395
3424
  message?: string;
3396
3425
  }
3426
+ /**
3427
+ * Conditional logic rule applied to a form field.
3428
+ *
3429
+ * When the referenced `field` matches the operator/value combination, the
3430
+ * `action` is applied (show, hide, require, or skip to a target page).
3431
+ * Used for dynamic forms where some fields appear conditionally based on
3432
+ * earlier answers.
3433
+ */
3434
+ interface FormCondition {
3435
+ /**
3436
+ * The `FormField.id` of the field whose value triggers this condition.
3437
+ */
3438
+ field: string;
3439
+ /**
3440
+ * Comparison operator applied to the referenced field's current value.
3441
+ */
3442
+ operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'is_empty' | 'is_not_empty';
3443
+ /**
3444
+ * Value compared against the referenced field. Type depends on the field
3445
+ * type: string for text fields, number for number fields, boolean for
3446
+ * checkboxes. `undefined` for `is_empty` / `is_not_empty`.
3447
+ */
3448
+ value?: unknown;
3449
+ /**
3450
+ * Effect applied when the condition matches:
3451
+ * - `'show'` / `'hide'`: toggle visibility of the target field
3452
+ * - `'require'`: mark the target field required
3453
+ * - `'skip_to_page'`: jump to the page identified by `targetPage`
3454
+ */
3455
+ action: 'show' | 'hide' | 'require' | 'skip_to_page';
3456
+ /**
3457
+ * Target page index for `skip_to_page` actions.
3458
+ * Ignored for other actions.
3459
+ */
3460
+ targetPage?: number;
3461
+ }
3462
+ /**
3463
+ * Phone field configuration.
3464
+ * Only relevant for fields of type `'tel'`.
3465
+ */
3466
+ interface FormFieldPhoneOptions {
3467
+ /**
3468
+ * Whether the country-code selector is rendered next to the phone input.
3469
+ */
3470
+ showCountryCode: boolean;
3471
+ /**
3472
+ * Default country code (e.g. `'+33'`, `'+1'`).
3473
+ */
3474
+ defaultCountryCode: string;
3475
+ }
3397
3476
  /**
3398
3477
  * A single field definition in a form schema.
3399
3478
  * Describes the input type, label, validation, and layout for one form field.
@@ -3403,11 +3482,11 @@ interface FormFieldValidation {
3403
3482
  interface FormField {
3404
3483
  /**
3405
3484
  * Field identifier, used as the key in submission data.
3406
- * Unique within the form. Lowercase, alphanumeric with underscores or hyphens
3407
- * (e.g. `'first_name'`, `'email'`). Max 100 characters.
3408
- * This is the key you use in `FormSubmitData` when submitting.
3485
+ * Auto-generated by the admin (e.g. `'field_1764776796820'`), unique within
3486
+ * the form. This is the key you must use in `FormSubmitData` when calling
3487
+ * `forms.submit()`.
3409
3488
  */
3410
- name: string;
3489
+ id: string;
3411
3490
  /**
3412
3491
  * HTML input type for this field.
3413
3492
  * Determines the rendered input element and applicable validation rules.
@@ -3417,7 +3496,7 @@ interface FormField {
3417
3496
  type: FormFieldType;
3418
3497
  /**
3419
3498
  * Human-readable label displayed above or beside the input.
3420
- * Max 255 characters. Always present use this as the `<label>` text.
3499
+ * Max 255 characters. Always present. Use this as the `<label>` text.
3421
3500
  */
3422
3501
  label: string;
3423
3502
  /**
@@ -3426,12 +3505,19 @@ interface FormField {
3426
3505
  * Use as the HTML `placeholder` attribute.
3427
3506
  */
3428
3507
  placeholder?: string;
3508
+ /**
3509
+ * Help text displayed below the input to guide the user.
3510
+ * Max 500 characters. `undefined` if not configured.
3511
+ * Render as a small description below the field (e.g. `<small>` or `aria-describedby`).
3512
+ */
3513
+ description?: string;
3429
3514
  /**
3430
3515
  * Whether this field must be filled before submission.
3431
3516
  * When `true`, the server will reject submissions with this field empty.
3432
3517
  * Render a required indicator (e.g. `*`) and set the HTML `required` attribute.
3518
+ * `undefined` is treated as `false`.
3433
3519
  */
3434
- required: boolean;
3520
+ required?: boolean;
3435
3521
  /**
3436
3522
  * Selectable options for `select`, `radio`, and `checkbox` field types.
3437
3523
  * `undefined` for field types that don't use options (text, email, number, etc.).
@@ -3444,7 +3530,7 @@ interface FormField {
3444
3530
  /**
3445
3531
  * Validation rules applied to this field's value.
3446
3532
  * `undefined` if no extra validation beyond `required` is configured.
3447
- * Rules are enforced server-side client-side validation is optional but recommended for UX.
3533
+ * Rules are enforced server-side; client-side validation is optional but recommended for UX.
3448
3534
  *
3449
3535
  * @see {@link FormFieldValidation}
3450
3536
  */
@@ -3453,72 +3539,157 @@ interface FormField {
3453
3539
  * Pre-filled default value for the field.
3454
3540
  * Type depends on the field type: `string` for text fields, `number` for number fields,
3455
3541
  * `boolean` for checkbox (single toggle mode).
3456
- * `undefined` if no default is set the field starts empty.
3542
+ * `undefined` if no default is set. The field starts empty.
3457
3543
  */
3458
3544
  defaultValue?: string | number | boolean;
3459
- /**
3460
- * Help text displayed below the input to guide the user.
3461
- * Max 500 characters. `undefined` if not configured.
3462
- * Render as a small description below the field (e.g. `<small>` or `aria-describedby`).
3463
- */
3464
- helpText?: string;
3465
3545
  /**
3466
3546
  * Layout width hint for responsive form layouts:
3467
3547
  * - `'full'`: spans the entire form width (100%)
3468
- * - `'half'`: spans half the form width (50%) place two `half` fields side by side
3469
- * - `'third'`: spans one third of the form width (33%) place three `third` fields in a row
3548
+ * - `'half'`: spans half the form width (50%); place two `half` fields side by side
3549
+ * - `'third'`: spans one third of the form width (33%); place three `third` fields in a row
3470
3550
  *
3471
3551
  * `undefined` defaults to `'full'`.
3472
3552
  */
3473
3553
  width?: 'full' | 'half' | 'third';
3554
+ /**
3555
+ * Per-field conditional logic. When present, the field is only rendered or
3556
+ * required based on the values of earlier fields. Conditions defined here
3557
+ * are scoped to this field; cross-field rules live in `FormSchema.conditions`.
3558
+ *
3559
+ * @see {@link FormCondition}
3560
+ */
3561
+ conditions?: FormCondition[];
3562
+ /**
3563
+ * Configuration for `tel` (phone) fields.
3564
+ * `undefined` for non-phone field types.
3565
+ */
3566
+ phoneOptions?: FormFieldPhoneOptions;
3474
3567
  }
3475
3568
  /**
3476
- * Form behavior settings controlling what happens after submission.
3569
+ * Form behavior settings nested under `FormSchema.settings`.
3570
+ * Controls submit button text, success message, redirect, and progress UI.
3477
3571
  */
3478
- interface FormSettings {
3572
+ interface FormSchemaSettings {
3479
3573
  /**
3480
- * Text displayed on the submit button (e.g. `'Send'`, `'Subscribe'`, `'Submit'`).
3481
- * Max 100 characters. Always present.
3574
+ * Text displayed on the submit button (e.g. `'Send'`, `'Subscribe'`).
3575
+ * `undefined` falls back to a default label rendered by the host application.
3482
3576
  */
3483
- submitLabel: string;
3577
+ submitLabel?: string;
3484
3578
  /**
3485
3579
  * Success message displayed after a successful submission.
3486
- * Max 1000 characters. Shown inline on the page.
3487
- *
3488
- * Ignored if `redirectUrl` is set — the user is redirected instead of seeing this message.
3580
+ * Shown inline on the page. Ignored if `redirectUrl` is set.
3581
+ * `undefined` falls back to a default message.
3489
3582
  */
3490
- successMessage: string;
3583
+ successMessage?: string;
3491
3584
  /**
3492
3585
  * URL to redirect the user to after successful submission.
3493
- * Max 500 characters. Must be a valid URL (e.g. `'https://example.com/thank-you'`).
3494
- * When set, takes precedence over `successMessage` — the user is navigated away immediately.
3586
+ * Must be a valid URL. When set, takes precedence over `successMessage`.
3495
3587
  * `undefined` means show `successMessage` inline instead.
3496
3588
  */
3497
3589
  redirectUrl?: string;
3498
3590
  /**
3499
- * Whether double opt-in email confirmation is enabled.
3500
- * When `true`, the form sends a confirmation email to the user before
3501
- * recording the submission as confirmed. Useful for newsletter signups.
3502
- * `undefined` or `false` means submissions are recorded immediately.
3591
+ * Whether the form requires the visitor to be authenticated.
3592
+ * Enforced server-side. `undefined` is treated as `false`.
3593
+ */
3594
+ requireAuth?: boolean;
3595
+ /**
3596
+ * Message displayed when the form is closed (no longer accepting submissions).
3597
+ * `undefined` falls back to a default message.
3503
3598
  */
3504
- doubleOptIn?: boolean;
3599
+ closedMessage?: string;
3600
+ /**
3601
+ * Whether to render a progress bar for multi-page forms.
3602
+ * `undefined` is treated as `false`.
3603
+ */
3604
+ showProgressBar?: boolean;
3605
+ }
3606
+ /**
3607
+ * Backwards-compatible alias for {@link FormSchemaSettings}.
3608
+ *
3609
+ * @deprecated Use `FormSchemaSettings` directly. The old root-level
3610
+ * `Form.settings` property has been removed in 1.32.1; settings now live
3611
+ * under `Form.schema.settings`. This alias will be removed in a future
3612
+ * major version.
3613
+ */
3614
+ type FormSettings = FormSchemaSettings;
3615
+ /**
3616
+ * Page definition for multi-page forms.
3617
+ *
3618
+ * Multi-page forms split fields across pages, identified by `fields` (a list
3619
+ * of `FormField.id` values that belong to the page). Single-page forms have
3620
+ * no `pages` entry on the schema.
3621
+ */
3622
+ interface FormPage {
3623
+ /**
3624
+ * Page title displayed at the top of the page.
3625
+ * `undefined` if not configured.
3626
+ */
3627
+ title?: string;
3628
+ /**
3629
+ * Page description displayed below the title.
3630
+ * `undefined` if not configured.
3631
+ */
3632
+ description?: string;
3633
+ /**
3634
+ * Ordered list of `FormField.id` values that belong to this page.
3635
+ * Each id must reference a field in `FormSchema.fields`.
3636
+ */
3637
+ fields: string[];
3638
+ }
3639
+ /**
3640
+ * Full schema describing a form's fields, layout, behavior, and conditional logic.
3641
+ *
3642
+ * Returned as the `schema` property of {@link Form} by `forms.getBySlug()`.
3643
+ * Render `fields` in order to build the form UI dynamically. Use `settings`
3644
+ * to wire the submit button and post-submission behavior. Use `conditions`
3645
+ * for cross-field rules (e.g. show field B when field A equals X).
3646
+ */
3647
+ interface FormSchema {
3648
+ /**
3649
+ * Ordered array of field definitions that make up the form.
3650
+ * Render in order to build the form UI.
3651
+ *
3652
+ * @see {@link FormField}
3653
+ */
3654
+ fields: FormField[];
3655
+ /**
3656
+ * Page definitions for multi-page forms.
3657
+ * `undefined` for single-page forms.
3658
+ *
3659
+ * @see {@link FormPage}
3660
+ */
3661
+ pages?: FormPage[];
3662
+ /**
3663
+ * Behavior settings (submit label, success message, redirect, progress bar).
3664
+ *
3665
+ * @see {@link FormSchemaSettings}
3666
+ */
3667
+ settings: FormSchemaSettings;
3668
+ /**
3669
+ * Cross-field conditional logic rules. Each rule references a field by id,
3670
+ * compares its value, and applies an action (show/hide/require/skip).
3671
+ *
3672
+ * @see {@link FormCondition}
3673
+ */
3674
+ conditions: FormCondition[];
3505
3675
  }
3506
3676
  /**
3507
3677
  * A public form available for submission.
3508
- * Returned by `GET /public/forms/:slug`.
3678
+ * Returned by `GET /public/{siteId}/forms/{slug}` and unwrapped from the
3679
+ * `{ data }` envelope by `forms.getBySlug()`.
3509
3680
  *
3510
- * Use `schema` to dynamically render the form fields, `settings` to configure
3511
- * the submit button and post-submission behavior, and the spam protection fields
3512
- * to set up honeypot or reCAPTCHA if enabled.
3681
+ * Use `schema.fields` to dynamically render the form fields, `schema.settings`
3682
+ * to configure the submit button and post-submission behavior, and the spam
3683
+ * protection flags to set up honeypot or reCAPTCHA if enabled.
3513
3684
  *
3514
3685
  * Only forms with `status: 'active'` are returned by the public API.
3515
3686
  * Draft, closed, and archived forms are never returned.
3516
3687
  */
3517
3688
  interface Form {
3518
3689
  /**
3519
- * Unique numeric form ID. Auto-incremented.
3690
+ * Unique form identifier (UUID v4).
3520
3691
  */
3521
- id: number;
3692
+ id: string;
3522
3693
  /**
3523
3694
  * Form display name (e.g. `'Contact Us'`, `'Newsletter Signup'`). Max 255 characters.
3524
3695
  */
@@ -3526,8 +3697,8 @@ interface Form {
3526
3697
  /**
3527
3698
  * URL-friendly slug, unique within the site.
3528
3699
  * Lowercase, hyphenated (e.g. `'contact-us'`). Max 255 characters.
3529
- * Used to fetch the form: `GET /public/forms/:slug`.
3530
- * Also used as the submission endpoint: `POST /public/forms/:slug/submit`.
3700
+ * Used to fetch the form: `GET /public/{siteId}/forms/{slug}`.
3701
+ * Also used as the submission endpoint: `POST /public/{siteId}/forms/{slug}/submit`.
3531
3702
  */
3532
3703
  slug: string;
3533
3704
  /**
@@ -3537,18 +3708,12 @@ interface Form {
3537
3708
  */
3538
3709
  description: string | null;
3539
3710
  /**
3540
- * Ordered array of field definitions that make up the form.
3541
- * Render these in order to build the form UI dynamically.
3711
+ * Schema describing the form's fields, layout, behavior settings, and
3712
+ * conditional logic. Iterate `schema.fields` to render the form.
3542
3713
  *
3543
- * @see {@link FormField}
3714
+ * @see {@link FormSchema}
3544
3715
  */
3545
- schema: FormField[];
3546
- /**
3547
- * Form behavior settings (submit button text, success message, redirect).
3548
- *
3549
- * @see {@link FormSettings}
3550
- */
3551
- settings: FormSettings;
3716
+ schema: FormSchema;
3552
3717
  /**
3553
3718
  * Form status. Always `'active'` via the public API.
3554
3719
  * Draft, closed, and archived forms are never returned by public endpoints.
@@ -3579,7 +3744,7 @@ interface Form {
3579
3744
  * 3. Include the reCAPTCHA token in the submission payload
3580
3745
  *
3581
3746
  * The SDK handles this automatically if you use `lynkow.forms.submit()`.
3582
- * Cannot be combined with honeypot only one spam protection method is active.
3747
+ * Cannot be combined with honeypot; only one spam protection method is active.
3583
3748
  *
3584
3749
  * `undefined` or `false` means reCAPTCHA is not active.
3585
3750
  */
@@ -3590,17 +3755,21 @@ interface Form {
3590
3755
  * `null` or `undefined` when reCAPTCHA is not configured.
3591
3756
  *
3592
3757
  * Pass this to `grecaptcha.render()` or the `sitekey` parameter in the reCAPTCHA script URL.
3593
- * The secret key is never exposed it stays server-side.
3758
+ * The secret key is never exposed; it stays server-side.
3594
3759
  */
3595
3760
  recaptchaSiteKey?: string | null;
3596
3761
  }
3597
3762
  /**
3598
3763
  * Data payload for submitting a form.
3599
3764
  *
3600
- * Keys correspond to `FormField.name` values from the form's `schema`.
3765
+ * Keys correspond to `FormField.id` values from the form's `schema.fields`.
3766
+ * IDs are auto-generated by the admin (e.g. `'field_1764776796820'`),
3767
+ * not human-readable names. Always derive the keys from the schema returned
3768
+ * by `forms.getBySlug()`; do not hard-code semantic names.
3769
+ *
3601
3770
  * Value types depend on the field type:
3602
3771
  * - Text fields (`text`, `email`, `textarea`, `url`, `tel`): `string`
3603
- * - Number fields: `number`
3772
+ * - Number fields (`number`, `rating`): `number`
3604
3773
  * - Checkbox (single): `boolean`
3605
3774
  * - File fields: `File` (browser File object)
3606
3775
  * - Select/radio/checkbox (with options): `string` (the selected option's `value`)
@@ -3610,13 +3779,15 @@ interface Form {
3610
3779
  *
3611
3780
  * @example
3612
3781
  * ```typescript
3613
- * const data: FormSubmitData = {
3614
- * name: 'Jane Doe',
3615
- * email: 'jane@example.com',
3616
- * message: 'Hello!',
3617
- * newsletter: true,
3782
+ * const form = await lynkow.forms.getBySlug('contact')
3783
+ *
3784
+ * // Build the payload keyed by field.id (the auto-generated identifier)
3785
+ * const data: FormSubmitData = {}
3786
+ * for (const field of form.schema.fields) {
3787
+ * data[field.id] = readValueForField(field) // your UI binding
3618
3788
  * }
3619
- * await lynkow.forms.submit('contact-us', data)
3789
+ *
3790
+ * await lynkow.forms.submit('contact', data)
3620
3791
  * ```
3621
3792
  */
3622
3793
  type FormSubmitData = Record<string, string | number | boolean | File>;
@@ -6670,4 +6841,4 @@ declare function renderJsonLdGraph(nodes: object[] | null | undefined): string;
6670
6841
  */
6671
6842
  declare function mergeIntoGraph(server: object[] | null | undefined, custom: object[] | null | undefined): object[];
6672
6843
 
6673
- 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 };
6844
+ 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 TagsListResponse, TagsService, type TipTapMark, type TipTapNode, type TransformOptions, browserOnly, browserOnlyAsync, createClient, createLynkowClient, detectSiteTheme, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer, mergeIntoGraph, onSiteThemeChange, renderJsonLdGraph };