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 +266 -95
- package/dist/index.d.ts +266 -95
- package/dist/index.js.map +1 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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
|
-
* //
|
|
573
|
-
*
|
|
574
|
-
*
|
|
575
|
-
*
|
|
576
|
-
*
|
|
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
|
-
*
|
|
590
|
-
*
|
|
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
|
|
594
|
-
*
|
|
595
|
-
*
|
|
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
|
-
*
|
|
602
|
-
*
|
|
603
|
-
*
|
|
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
|
|
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
|
|
619
|
-
*
|
|
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
|
|
622
|
-
* - `fetchOptions
|
|
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
|
|
633
|
-
*
|
|
634
|
-
*
|
|
635
|
-
*
|
|
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>`)
|
|
3328
|
-
* - `'radio'`: radio button group
|
|
3329
|
-
* - `'checkbox'`: checkbox or checkbox group
|
|
3330
|
-
* - `'file'`: file upload input
|
|
3331
|
-
* - `'
|
|
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
|
|
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
|
|
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
|
|
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
|
-
*
|
|
3407
|
-
*
|
|
3408
|
-
*
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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%)
|
|
3469
|
-
* - `'third'`: spans one third of the form width (33%)
|
|
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
|
|
3569
|
+
* Form behavior settings nested under `FormSchema.settings`.
|
|
3570
|
+
* Controls submit button text, success message, redirect, and progress UI.
|
|
3477
3571
|
*/
|
|
3478
|
-
interface
|
|
3572
|
+
interface FormSchemaSettings {
|
|
3479
3573
|
/**
|
|
3480
|
-
* Text displayed on the submit button (e.g. `'Send'`, `'Subscribe'
|
|
3481
|
-
*
|
|
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
|
|
3577
|
+
submitLabel?: string;
|
|
3484
3578
|
/**
|
|
3485
3579
|
* Success message displayed after a successful submission.
|
|
3486
|
-
*
|
|
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
|
|
3583
|
+
successMessage?: string;
|
|
3491
3584
|
/**
|
|
3492
3585
|
* URL to redirect the user to after successful submission.
|
|
3493
|
-
*
|
|
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
|
|
3500
|
-
*
|
|
3501
|
-
|
|
3502
|
-
|
|
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
|
-
|
|
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
|
|
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`
|
|
3511
|
-
* the submit button and post-submission behavior, and the spam
|
|
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
|
|
3690
|
+
* Unique form identifier (UUID v4).
|
|
3520
3691
|
*/
|
|
3521
|
-
id:
|
|
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
|
|
3530
|
-
* Also used as the submission endpoint: `POST /public/forms
|
|
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
|
-
*
|
|
3541
|
-
*
|
|
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
|
|
3714
|
+
* @see {@link FormSchema}
|
|
3544
3715
|
*/
|
|
3545
|
-
schema:
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
3614
|
-
*
|
|
3615
|
-
*
|
|
3616
|
-
*
|
|
3617
|
-
*
|
|
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
|
-
*
|
|
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 };
|