# Client reference

Every public function, class and type, as published at version `0.1.0-alpha.7`. The [JavaScript SDK](/guides/javascript-sdk/) page has the overview and examples.

`@formerie/client/browser` has the same exports.

## Clients and addresses

### buildBrandedSchemaUrl

The schema address under `/v1/`, with no workspace handle.

```ts
function buildBrandedSchemaUrl(endpoint: string, form: string): string;
```

### buildBrandedSubmitUrl

The submit address under `/v1/`, with no workspace handle.

```ts
function buildBrandedSubmitUrl(endpoint: string, form: string): string;
```

### buildBrandedValidateUrl

The validate address under `/v1/`, with no workspace handle.

```ts
function buildBrandedValidateUrl(endpoint: string, form: string): string;
```

### buildCanonicalSchemaUrl

The schema address under `/v1/`, as `FormerieClient` calls it.

```ts
function buildCanonicalSchemaUrl(endpoint: string, workspace: string, form: string): string;
```

### buildCanonicalSubmitUrl

The submit address under `/v1/`, as `FormerieClient` calls it.

```ts
function buildCanonicalSubmitUrl(endpoint: string, workspace: string, form: string): string;
```

### buildCanonicalValidateUrl

The validate address under `/v1/`, as `FormerieClient` calls it.

```ts
function buildCanonicalValidateUrl(endpoint: string, workspace: string, form: string): string;
```

### buildFormRuntimeHostedFormUrl

The hosted page's address on a hostname connected to one form.

```ts
function buildFormRuntimeHostedFormUrl(endpoint: string): string;
```

### buildFormRuntimeSchemaUrl

The schema route's address on a hostname connected to one form.

```ts
function buildFormRuntimeSchemaUrl(endpoint: string): string;
```

### buildFormRuntimeSubmitUrl

The submit route's address on a hostname connected to one form.

```ts
function buildFormRuntimeSubmitUrl(endpoint: string): string;
```

### buildFormRuntimeValidateUrl

The validate route's address on a hostname connected to one form.

```ts
function buildFormRuntimeValidateUrl(endpoint: string): string;
```

### buildRuntimeEmbedScriptUrl

The address of `embed.js` on a host.

```ts
function buildRuntimeEmbedScriptUrl(endpoint: string): string;
```

### buildRuntimeHostedFormUrl

The hosted page's address, for a workspace and a form.

```ts
function buildRuntimeHostedFormUrl(endpoint: string, workspace: string, form: string): string;
```

### buildRuntimeSchemaUrl

The schema route's address, for a workspace and a form.

```ts
function buildRuntimeSchemaUrl(endpoint: string, workspace: string, form: string): string;
```

### buildRuntimeSubmitUrl

The submit route's address, for a workspace and a form.

```ts
function buildRuntimeSubmitUrl(endpoint: string, workspace: string, form: string): string;
```

### buildRuntimeValidateUrl

The validate route's address, for a workspace and a form.

```ts
function buildRuntimeValidateUrl(endpoint: string, workspace: string, form: string): string;
```

### buildWorkspaceRuntimeHostedFormUrl

The hosted page's address on a hostname connected to a workspace.

```ts
function buildWorkspaceRuntimeHostedFormUrl(endpoint: string, form: string): string;
```

### buildWorkspaceRuntimeSchemaUrl

The schema route's address on a hostname connected to a workspace.

```ts
function buildWorkspaceRuntimeSchemaUrl(endpoint: string, form: string): string;
```

### buildWorkspaceRuntimeSubmitUrl

The submit route's address on a hostname connected to a workspace.

```ts
function buildWorkspaceRuntimeSubmitUrl(endpoint: string, form: string): string;
```

### buildWorkspaceRuntimeValidateUrl

The validate route's address on a hostname connected to a workspace.

```ts
function buildWorkspaceRuntimeValidateUrl(endpoint: string, form: string): string;
```

### FORMERIE_API_ENDPOINT

The address `FormerieClient` calls by default.

```ts
const FORMERIE_API_ENDPOINT = "https://api.formerie.com";
```

### FORMERIE_RUNTIME_ENDPOINT

The address `FormerieRuntimeClient` calls by default.

```ts
const FORMERIE_RUNTIME_ENDPOINT = "https://forms.formerie.com";
```

### FormerieClient

The same requests on `api.formerie.com`. Use `FormerieRuntimeClient` for anything new.

```ts
class FormerieClient {
    constructor(config?: FormerieClientConfig);
    submit(workspace: string, form: string, payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
    submitBranded(form: string, payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
    validate(workspace: string, form: string, payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
    validateBranded(form: string, payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
    schema(workspace: string, form: string, options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
    schemaBranded(form: string, options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
    canonicalUrl(workspace: string, form: string): string;
    brandedUrl(form: string): string;
    canonicalSchemaUrl(workspace: string, form: string): string;
    brandedSchemaUrl(form: string): string;
    canonicalValidateUrl(workspace: string, form: string): string;
    brandedValidateUrl(form: string): string;
}
```

### FormerieRuntimeClient

The client to use. Reads the schema, checks answers and submits, on `forms.formerie.com` or a hostname you've connected. `submitWorkspace` and its siblings suit a hostname connected to a workspace, and `submitForm` and its siblings a hostname connected to one form.

```ts
class FormerieRuntimeClient extends FormerieClient {
    constructor(config?: FormerieRuntimeClientConfig);
    submit(workspace: string, form: string, payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
    submitWorkspace(form: string, payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
    submitBranded(form: string, payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
    submitForm(payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
    validate(workspace: string, form: string, payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
    validateWorkspace(form: string, payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
    validateBranded(form: string, payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
    validateForm(payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
    schema(workspace: string, form: string, options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
    schemaWorkspace(form: string, options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
    schemaBranded(form: string, options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
    schemaForm(options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
    canonicalUrl(workspace: string, form: string): string;
    brandedUrl(form: string): string;
    canonicalSchemaUrl(workspace: string, form: string): string;
    brandedSchemaUrl(form: string): string;
    canonicalValidateUrl(workspace: string, form: string): string;
    brandedValidateUrl(form: string): string;
    hostedUrl(workspace: string, form: string): string;
    hostedWorkspaceUrl(form: string): string;
    hostedFormUrl(): string;
    embedScriptUrl(): string;
}
```

### FormServiceClient

An older name for `FormerieClient`.

```ts
class FormServiceClient extends FormerieClient {}
```

## Embeds

### buildFormerieEmbedIframeUrl

The address an embed's iframe loads, on a host and for an optional form.

```ts
function buildFormerieEmbedIframeUrl(endpoint: string, form?: string): string;
```

### mountFormerieEmbed

Loads the hosted page in an iframe. Answers `null` when there's no document or no target to put it in.

```ts
function mountFormerieEmbed(options?: MountFormerieEmbedOptions): MountedFormerieEmbed | null;
```

### MountedFormerieEmbed

```ts
interface MountedFormerieEmbed {
    destroy(): void;
    element: Element;
    iframe: HTMLIFrameElement;
}
```

### MountFormerieEmbedOptions

```ts
interface MountFormerieEmbedOptions {
    document?: Document;
    endpoint?: string;
    form?: string;
    height?: string;
    script?: HTMLScriptElement | null;
    target?: Element | string | null;
    title?: string;
}
```

## Reading responses

### getFieldErrors

Every problem with one field path, from an error response.

```ts
function getFieldErrors(response: ErrorCapableResponse, path: string): ValidationIssue[];
```

### getFirstFieldError

The first problem with one field path, or `null`.

```ts
function getFirstFieldError(response: ErrorCapableResponse, path: string): ValidationIssue | null;
```

### getFormErrors

The problems that belong to the whole form rather than one field.

```ts
function getFormErrors(response: ErrorCapableResponse): ValidationIssue[];
```

### isSubmitError

Whether a response is an error.

```ts
function isSubmitError(response: ErrorCapableResponse): response is SubmitErrorResponse;
```

### isSubmitSuccess

Whether a submit response was accepted.

```ts
function isSubmitSuccess(response: SubmitResponse): response is SubmitSuccessResponse;
```

### isValidateSuccess

Whether a validate response passed.

```ts
function isValidateSuccess(response: ValidateResponse): response is ValidateSuccessResponse;
```

### isValidationError

Whether a response is a `VALIDATION_FAILED` error.

```ts
function isValidationError(response: ErrorCapableResponse): response is SubmitErrorResponse & {
    error: ValidationFailedError;
};
```

## Fallback messages

### DEFAULT_ERROR_MESSAGES

The SDK's fallback message for each error code.

```ts
const DEFAULT_ERROR_MESSAGES: Record<FormerieErrorCode, string>;
```

### DEFAULT_FIELD_ERROR_MESSAGES

The SDK's fallback message for each built-in field error code.

```ts
const DEFAULT_FIELD_ERROR_MESSAGES: Record<BuiltInFieldErrorCode, string>;
```

### messageForErrorCode

The fallback message for an error code. Prefer the message the server sends.

```ts
function messageForErrorCode(code: FormerieErrorCode): string;
```

### messageForFieldErrorCode

The fallback message for a field error code. Prefer the message the server sends.

```ts
function messageForFieldErrorCode(code: FieldErrorCode): string;
```

## Drawing forms

### applyFormerieVerificationError

Shows a verification error on a form.

```ts
function applyFormerieVerificationError(form: HTMLFormElement, message: string): void;
```

### bindFormerieForm

Adds Formerie's behaviour to a `<form>` your page already rendered.

```ts
function bindFormerieForm(form: HTMLFormElement, options: BindFormerieFormOptions): MountedFormerieForm;
```

### bindFormerieHostedForm

The same, for a server-rendered page that has both a form shell and a public schema script.

```ts
function bindFormerieHostedForm(options?: BindFormerieHostedFormOptions): MountedFormerieForm;
```

### clearFormerieVerificationError

Clears a form's verification error.

```ts
function clearFormerieVerificationError(form: HTMLFormElement): void;
```

### collectFormerieVerificationToken

Gets the verification token from a form's widget, when the form requires one.

```ts
function collectFormerieVerificationToken(options: FormerieVerificationTokenOptions): Promise<string | undefined>;
```

### describeFormerieRenderFields

A flat description of each field to draw, for your own renderer.

```ts
function describeFormerieRenderFields(schema: PublicSchemaInput, values?: Record<string, unknown>, options?: DescribeFormerieRenderFieldsOptions): FormerieRenderField[];
```

### describeFormerieRenderModel

The fields and steps to draw, for your own renderer.

```ts
function describeFormerieRenderModel(schema: PublicSchemaInput, values?: Record<string, unknown>, options?: DescribeFormerieRenderModelOptions): FormerieRenderModel;
```

### loadFormerieRuntimeSchema

Loads the public schema for a mount target.

```ts
function loadFormerieRuntimeSchema(options: LoadFormerieRuntimeSchemaOptions): Promise<PublicFormSchemaResult>;
```

### mountFormerieForm

The same, when your app already has the public schema.

```ts
function mountFormerieForm(target: Element | string, options: MountFormerieFormOptions): MountedFormerieForm;
```

### mountFormerieRuntimeForm

Loads a form's public schema and does the rest: draws it, collects answers and any verification token, submits, and shows errors from the server.

```ts
function mountFormerieRuntimeForm(target: Element | string, options: MountFormerieRuntimeFormOptions): Promise<MountedFormerieForm>;
```

### readFormerieHostedSchema

Reads the public schema from the JSON script in a hosted page. Throws if it's missing or empty.

```ts
function readFormerieHostedSchema(options?: ReadFormerieHostedSchemaOptions): PublicFormSchemaResponse;
```

### renderFormerieFormHtml

The form's HTML as a string, from a public schema.

```ts
function renderFormerieFormHtml(schema: PublicSchemaInput, options?: RenderFormerieFormHtmlOptions): string;
```

### renderFormerieVerificationHtml

The HTML and script details for a schema's human verification.

```ts
function renderFormerieVerificationHtml(verification: PublicFormSchemaResponse["verification"], options?: RenderFormerieVerificationHtmlOptions): FormerieVerificationHtml;
```

### resetFormerieVerificationWidget

Resets a form's verification widget, so it can give a new token.

```ts
function resetFormerieVerificationWidget(form: HTMLFormElement): void;
```

### syncFormerieFormVisibility

Shows and hides a mounted form's fields to match its answers, and returns each field's state.

```ts
function syncFormerieFormVisibility(form: HTMLFormElement, schema: PublicSchemaInput, values?: Record<string, unknown>): Record<string, PublicFieldVisibilityState>;
```

### BindFormerieFormOptions

```ts
type BindFormerieFormOptions = Omit<MountFormerieFormOptions, "formAttributes" | "includeHiddenFields" | "submitLabel">;
```

### BindFormerieHostedFormOptions

```ts
interface BindFormerieHostedFormOptions extends Omit<BindFormerieFormOptions, "schema"> {
    form?: HTMLFormElement | string;
    root?: ParentNode;
    schema?: PublicFormSchemaResponse;
    schemaElement?: HTMLScriptElement | string;
}
```

### DescribeFormerieRenderFieldsOptions

```ts
interface DescribeFormerieRenderFieldsOptions {
    includeHidden?: boolean;
}
```

### DescribeFormerieRenderModelOptions

```ts
interface DescribeFormerieRenderModelOptions extends DescribeFormerieRenderFieldsOptions {
    includeEmptySteps?: boolean;
}
```

### FormerieHeadingLevel

```ts
type FormerieHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
```

### FormerieRenderClassNames

```ts
interface FormerieRenderClassNames {
    checkboxField?: string;
    field?: string;
    fieldDescription?: string;
    fieldError?: string;
    honeypot?: string;
    status?: string;
    verification?: string;
    verificationError?: string;
}
```

### FormerieRenderControl

```ts
type FormerieRenderControl = "array" | "checkbox" | "checkbox-group" | "input" | "select" | "textarea";
```

### FormerieRenderField

```ts
interface FormerieRenderField {
    control: FormerieRenderControl;
    description?: string;
    id: string;
    inputMode?: string;
    inputType?: string;
    label: string;
    max?: number | string;
    maxLength?: number;
    min?: number | string;
    minLength?: number;
    multiple?: boolean;
    name: string;
    node: PublicArrayField | PublicScalarField;
    options?: string[];
    placeholder?: string;
    path: string;
    required: boolean;
    step?: string;
    value?: unknown;
    visibility: PublicFieldVisibilityState;
}
```

### FormerieRenderModel

```ts
interface FormerieRenderModel {
    fields: FormerieRenderField[];
    fieldsByPath: Record<string, FormerieRenderField>;
    steps: FormerieRenderStep[];
    unsteppedFields: FormerieRenderField[];
}
```

### FormerieRenderStep

```ts
interface FormerieRenderStep {
    fields: FormerieRenderField[];
    id: string;
    label: string;
    validateOn?: PublicFormStep["validateOn"];
}
```

### FormerieRuntimeMountTarget

```ts
type FormerieRuntimeMountTarget = FormerieTarget | {
    formBound: true;
};
```

### FormerieVerificationHtml

```ts
interface FormerieVerificationHtml {
    attributes: string;
    markup: string;
    scripts: string;
}
```

### FormerieVerificationTokenOptions

```ts
interface FormerieVerificationTokenOptions {
    form: HTMLFormElement;
}
```

### LoadFormerieRuntimeSchemaOptions

```ts
interface LoadFormerieRuntimeSchemaOptions {
    client?: FormerieRuntimeClient;
    endpoint?: string;
    schemaOptions?: SubmitRequestOptions;
    target: FormerieRuntimeMountTarget;
}
```

### MountedFormerieForm

```ts
interface MountedFormerieForm {
    destroy(): void;
    element: Element;
    form: HTMLFormElement;
    submit(): Promise<SubmitResponse>;
    values(): Record<string, unknown>;
}
```

### MountFormerieFormOptions

```ts
interface MountFormerieFormOptions extends RenderFormerieFormHtmlOptions {
    client?: FormerieRuntimeClient;
    endpoint?: string;
    fetcher?: typeof fetch;
    focusInvalid?: boolean;
    loadVerificationScript?: boolean;
    metadata?: CreateFormerieSubmitPayloadOptions["metadata"] | (() => CreateFormerieSubmitPayloadOptions["metadata"] | Promise<CreateFormerieSubmitPayloadOptions["metadata"]>);
    onError?: (response: SubmitResponse) => void;
    onSubmit?: (payload: SubmitPayload) => SubmitResponse | Promise<SubmitResponse>;
    onSuccess?: (response: SubmitResponse & {
        ok: true;
    }) => void;
    pendingMessage?: string;
    resetOnSuccess?: boolean;
    schema: PublicFormSchemaResponse;
    submitOptions?: SubmitRequestOptions;
    submitUrl?: string;
    target?: FormerieRuntimeMountTarget;
    turnstileToken?: string | (() => string | Promise<string | undefined> | undefined);
    verificationToken?: string | (() => string | Promise<string | undefined> | undefined);
}
```

### MountFormerieRuntimeFormOptions

```ts
interface MountFormerieRuntimeFormOptions extends Omit<MountFormerieFormOptions, "client" | "endpoint" | "schema" | "target">, LoadFormerieRuntimeSchemaOptions {
}
```

### ReadFormerieHostedSchemaOptions

```ts
interface ReadFormerieHostedSchemaOptions {
    root?: ParentNode;
    schemaElement?: HTMLScriptElement | string;
}
```

### RenderFormerieFormHtmlOptions

```ts
interface RenderFormerieFormHtmlOptions {
    classes?: FormerieRenderClassNames;
    formAttributes?: Record<string, boolean | number | string | null | undefined>;
    headingLevel?: FormerieHeadingLevel;
    honeypotField?: string;
    honeypotLabel?: string;
    includeHeading?: boolean;
    includeHiddenFields?: boolean;
    includeVerification?: boolean;
    submitLabel?: string;
    values?: Record<string, unknown>;
}
```

### RenderFormerieVerificationHtmlOptions

```ts
interface RenderFormerieVerificationHtmlOptions {
    containerClass?: string;
    errorClass?: string;
}
```

## The schema and answers

### applyFormerieValidationErrors

Shows a response's errors next to the matching inputs, and returns the paths it placed.

```ts
function applyFormerieValidationErrors(root: ParentNode, source: SubmitResponse | ValidateResponse | ValidationFailedError | unknown, options?: ApplyFormerieValidationErrorsOptions): string[];
```

### clearFormerieValidationErrors

Clears errors shown by `applyFormerieValidationErrors`.

```ts
function clearFormerieValidationErrors(root: ParentNode, options?: ApplyFormerieValidationErrorsOptions): void;
```

### collectFormerieFormFields

Reads a form element's answers as nested fields.

```ts
function collectFormerieFormFields(form: HTMLFormElement, options?: FormerieFieldCollectionOptions): Record<string, unknown>;
```

### createFormerieSubmitPayload

Builds the submit body from `FormData`, a form element or an object.

```ts
function createFormerieSubmitPayload(source: FormData | HTMLFormElement | Record<string, unknown>, options?: CreateFormerieSubmitPayloadOptions): SubmitPayload;
```

### evaluatePublicCondition

Whether a condition from a public schema holds for these answers.

```ts
function evaluatePublicCondition(condition: unknown, values: Record<string, unknown>): boolean;
```

### evaluatePublicFieldVisibility

Each visibility rule's path, with its state for these answers.

```ts
function evaluatePublicFieldVisibility(schema: PublicSchemaInput, values: Record<string, unknown>): Record<string, PublicFieldVisibilityState>;
```

### firstValidationMessageForField

A response's first message for one field path, or `null`.

```ts
function firstValidationMessageForField(source: SubmitResponse | ValidateResponse | ValidationFailedError | unknown, path: string): string | null;
```

### formDataToFormerieFields

Turns `FormData` into nested fields.

```ts
function formDataToFormerieFields(formData: FormData, options?: FormerieFieldCollectionOptions): Record<string, unknown>;
```

### getPublicFieldVisibility

One field path's state for these answers.

```ts
function getPublicFieldVisibility(schema: PublicSchemaInput, values: Record<string, unknown>, path: string): PublicFieldVisibilityState;
```

### getPublicSchemaField

Finds one field in a public schema by its path.

```ts
function getPublicSchemaField(schema: PublicSchemaInput, path: string): PublicSchemaNode | undefined;
```

### isPublicSchemaPathHidden

Whether a field path is hidden for these answers.

```ts
function isPublicSchemaPathHidden(schema: PublicSchemaInput, values: Record<string, unknown>, path: string): boolean;
```

### listPublicSchemaFields

Lists every field in a public schema, with its path.

```ts
function listPublicSchemaFields(schema: PublicSchemaInput): PublicSchemaFieldEntry[];
```

### resolveFormerieFieldValue

Reads a value by field path, such as `contact.email`.

```ts
function resolveFormerieFieldValue(values: Record<string, unknown>, path: string): unknown;
```

### resolveHiddenPublicSchemaPaths

Every field path hidden for these answers.

```ts
function resolveHiddenPublicSchemaPaths(schema: PublicSchemaInput, values: Record<string, unknown>): Set<string>;
```

### setFormerieFieldValue

Sets a value by field path.

```ts
function setFormerieFieldValue(fields: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
```

### validateFormeriePublicFields

Checks answers in the browser against a public schema, for quick feedback. The server still has the final say.

```ts
function validateFormeriePublicFields(schema: PublicSchemaInput, submittedFields: unknown, options?: ValidateFormeriePublicFieldsOptions): FormeriePublicFieldsValidationResult;
```

### validationIssuesByField

A response's problems, by field path.

```ts
function validationIssuesByField(source: SubmitResponse | ValidateResponse | ValidationFailedError | unknown): Record<string, ValidationIssue[]>;
```

### validationMessagesByField

A response's messages, by field path.

```ts
function validationMessagesByField(source: SubmitResponse | ValidateResponse | ValidationFailedError | unknown): Record<string, string[]>;
```

### validationMessagesForField

A response's messages for one field path.

```ts
function validationMessagesForField(source: SubmitResponse | ValidateResponse | ValidationFailedError | unknown, path: string): string[];
```

### visiblePublicSchemaFields

Lists the fields visible for these answers.

```ts
function visiblePublicSchemaFields(schema: PublicSchemaInput, values: Record<string, unknown>): PublicSchemaFieldEntry[];
```

### ApplyFormerieValidationErrorsOptions

```ts
interface ApplyFormerieValidationErrorsOptions {
    clearExisting?: boolean;
    errorAttribute?: string;
    errorForAttribute?: string;
    fieldAttribute?: string;
    invalidAttribute?: string;
}
```

### CreateFormerieSubmitPayloadOptions

```ts
interface CreateFormerieSubmitPayloadOptions extends FormerieFieldCollectionOptions {
    metadata?: Record<string, unknown>;
    turnstileToken?: string;
    verificationToken?: string;
}
```

### FormerieFieldCollectionOptions

```ts
interface FormerieFieldCollectionOptions {
    schema?: PublicSchemaInput;
    includeMissingCheckboxes?: boolean;
}
```

### FormeriePublicFieldsValidationResult

```ts
interface FormeriePublicFieldsValidationResult {
    ok: boolean;
    values: Record<string, unknown>;
    errors: Record<string, ValidationIssue[]>;
    issues: ValidationIssue[];
}
```

### PublicSchemaFieldEntry

```ts
interface PublicSchemaFieldEntry {
    path: string;
    key: string;
    parentPath?: string;
    depth: number;
    repeated: boolean;
    node: PublicSchemaNode;
}
```

### PublicSchemaInput

```ts
type PublicSchemaInput = PublicFormSchemaResponse | Record<string, PublicSchemaNode>;
```

### ValidateFormeriePublicFieldsOptions

```ts
interface ValidateFormeriePublicFieldsOptions {
    mode?: "final" | "partial" | "step";
    paths?: string[];
    step?: string;
}
```

## Target helpers

### isBrandedFormerieTarget

Whether a target is a form on a hostname connected to a workspace.

```ts
function isBrandedFormerieTarget(target: FormerieTarget): target is BrandedFormerieTarget;
```

### schemaFormerieTarget

Reads the schema of a target.

```ts
function schemaFormerieTarget(client: FormerieClient, target: FormerieTarget, options?: SubmitRequestOptions): Promise<PublicFormSchemaResult>;
```

### submitFormerieTarget

Submits to a target.

```ts
function submitFormerieTarget(client: FormerieClient, target: FormerieTarget, payload: SubmitPayload, options?: SubmitRequestOptions): Promise<SubmitResponse>;
```

### validateFormerieTarget

Checks answers for a target.

```ts
function validateFormerieTarget(client: FormerieClient, target: FormerieTarget, payload: ValidatePayload, options?: SubmitRequestOptions): Promise<ValidateResponse>;
```

### BrandedFormerieTarget

```ts
interface BrandedFormerieTarget {
    form: string;
    branded: true;
}
```

### CanonicalFormerieTarget

```ts
type CanonicalFormerieTarget = WorkspaceFormerieTarget;
```

### FormerieTarget

```ts
type FormerieTarget = CanonicalFormerieTarget | BrandedFormerieTarget;
```

### WorkspaceFormerieTarget

```ts
interface WorkspaceFormerieTarget {
    workspace: string;
    form: string;
    branded?: false;
}
```

## Types

### BuiltInFieldErrorCode

```ts
type BuiltInFieldErrorCode = "FIELD_REQUIRED" | "FIELD_TYPE_INVALID" | "FIELD_STRING_TOO_SHORT" | "FIELD_STRING_TOO_LONG" | "FIELD_STRING_LENGTH_INVALID" | "FIELD_STRING_PREFIX_INVALID" | "FIELD_STRING_SUFFIX_INVALID" | "FIELD_STRING_CONTAINS_REQUIRED" | "FIELD_STRING_CONTAINS_FORBIDDEN" | "FIELD_EMAIL_INVALID" | "FIELD_PHONE_INVALID" | "FIELD_UUID_INVALID" | "FIELD_COUNTRY_CODE_INVALID" | "FIELD_POSTAL_CODE_INVALID" | "FIELD_REGION_CODE_INVALID" | "FIELD_URL_INVALID" | "FIELD_URL_PROTOCOL_NOT_ALLOWED" | "FIELD_DATE_INVALID" | "FIELD_DATE_TOO_EARLY" | "FIELD_DATE_TOO_LATE" | "FIELD_TIME_INVALID" | "FIELD_DATETIME_INVALID" | "FIELD_NUMBER_TOO_SMALL" | "FIELD_NUMBER_TOO_LARGE" | "FIELD_INTEGER_REQUIRED" | "FIELD_DECIMAL_PLACES_INVALID" | "FIELD_VALUE_NOT_ALLOWED" | "FIELD_PATTERN_INVALID" | "FIELD_ACCEPTED_REQUIRED" | "FIELD_SELECTION_TOO_FEW" | "FIELD_SELECTION_TOO_MANY" | "FIELD_ARRAY_TOO_SHORT" | "FIELD_ARRAY_TOO_LONG" | "FIELD_ARRAY_DUPLICATES" | "FIELD_OBJECT_INVALID" | "FORM_RULE_FAILED";
```

### FieldErrorCode

```ts
type FieldErrorCode = BuiltInFieldErrorCode | (string & {});
```

### FormerieClientConfig

```ts
interface FormerieClientConfig {
    endpoint?: string;
    fetcher?: typeof fetch;
    defaultHeaders?: HeadersInit;
}
```

### FormerieError

```ts
interface FormerieError {
    code: FormerieErrorCode;
    message: string;
}
```

### FormerieErrorCode

```ts
type FormerieErrorCode = "BAD_REQUEST" | "INVALID_JSON" | "FORM_NOT_FOUND" | "FORM_DISABLED" | "FORBIDDEN_ORIGIN" | "VALIDATION_FAILED" | "SPAM_REJECTED" | "TURNSTILE_FAILED" | "QUEUE_FAILED" | "UNAUTHORIZED" | "DEAD_LETTER_NOT_FOUND" | "DEAD_LETTER_NOT_REPLAYABLE" | "RATE_LIMITED" | "FORM_QUOTA_REACHED" | "FORM_NOT_OPEN" | "FORM_CLOSED" | "DUPLICATE_SUBMISSION" | "INTERNAL_ERROR" | "NETWORK_ERROR" | "INVALID_RESPONSE";
```

### FormerieRuntimeClientConfig

```ts
interface FormerieRuntimeClientConfig extends FormerieClientConfig {
}
```

### FormServiceClientConfig

```ts
interface FormServiceClientConfig extends FormerieClientConfig {
}
```

### FormServiceError

```ts
interface FormServiceError extends FormerieError {
}
```

### FormServiceErrorCode

```ts
type FormServiceErrorCode = FormerieErrorCode;
```

### PublicArrayField

```ts
interface PublicArrayField {
    type: "array";
    description?: string;
    label?: string;
    required?: boolean;
    minItems?: number;
    maxItems?: number;
    uniqueItems?: boolean;
    item: PublicSchemaNode;
    messages?: Record<string, string>;
}
```

### PublicCompositeValidator

```ts
interface PublicCompositeValidator {
    type: "allOf" | "anyOf";
    validators: PublicContextualValidator[];
    code: string;
    message: string;
    rule?: string;
}
```

### PublicContextualValidator

```ts
type PublicContextualValidator = PublicFieldValidator | PublicRequiredValidator | PublicCompositeValidator;
```

### PublicFieldValidator

```ts
interface PublicFieldValidator {
    type: "regex" | PublicNativeFieldValidatorType;
    code: string;
    message: string;
    rule?: string;
    allowedProtocols?: string[];
    country?: "CA" | "US";
    flags?: string;
    pattern?: string;
    value?: string;
    version?: "any" | "v4" | "v7";
}
```

### PublicFieldVisibilityState

```ts
type PublicFieldVisibilityState = "visible" | "hidden";
```

### PublicFormBehaviorSettings

```ts
interface PublicFormBehaviorSettings {
    submitButtonLabel?: string;
    successMessage?: string;
    successRedirectUrl?: string;
}
```

### PublicFormBrandingSettings

```ts
interface PublicFormBrandingSettings {
    accentColor?: string;
    accentTextColor?: string;
    backgroundColor?: string;
    borderColor?: string;
    brandName?: string;
    customCss?: string;
    density?: "compact" | "comfortable" | "spacious";
    errorColor?: string;
    errorTextColor?: string;
    fieldBackgroundColor?: string;
    fontPreset?: "arial" | "georgia" | "helvetica" | "inter" | "mono" | "system" | "times" | "verdana";
    logoUrl?: string;
    mutedTextColor?: string;
    previewTheme?: "dark" | "light";
    radius?: "none" | "soft" | "round";
    surfaceColor?: string;
    textColor?: string;
    themes?: {
        dark?: PublicFormBrandingTheme;
        light?: PublicFormBrandingTheme;
    };
}
```

### PublicFormBrandingTheme

```ts
interface PublicFormBrandingTheme {
    accentColor?: string;
    accentTextColor?: string;
    backgroundColor?: string;
    borderColor?: string;
    errorColor?: string;
    errorTextColor?: string;
    fieldBackgroundColor?: string;
    mutedTextColor?: string;
    surfaceColor?: string;
    textColor?: string;
}
```

### PublicFormLayoutSettings

```ts
interface PublicFormLayoutSettings {
    containerMaxWidth?: string;
    containerMinWidth?: string;
    containerWidthMode?: "contained" | "custom" | "full";
}
```

### PublicFormSchemaResponse

```ts
interface PublicFormSchemaResponse {
    ok: true;
    enabled: boolean;
    formHandle: string;
    metadata?: {
        schemaVersion?: string;
        label?: string;
        description?: string;
    };
    schemaId: string;
    settings?: PublicFormSettings;
    turnstile: {
        required: boolean;
    };
    verification?: {
        provider: "turnstile" | "recaptcha-v2" | "recaptcha-v3";
        required: boolean;
        siteKey?: string;
        expectedAction?: string;
    };
    limits?: {
        maxSubmissionJsonBytes?: number;
        schedule?: {
            opensAt?: string;
            closesAt?: string;
            notOpenMessage?: string;
            closedMessage?: string;
        };
    };
    fields: Record<string, PublicSchemaNode>;
    steps?: PublicFormStep[];
    visibilityRules?: PublicVisibilityRule[];
    validationRules?: PublicValidationRule[];
    workspaceHandle: string;
}
```

### PublicFormSchemaResult

```ts
type PublicFormSchemaResult = PublicFormSchemaResponse | SubmitErrorResponse;
```

### PublicFormSettings

```ts
interface PublicFormSettings {
    behavior?: PublicFormBehaviorSettings;
    branding?: PublicFormBrandingSettings;
    layout?: PublicFormLayoutSettings;
}
```

### PublicFormStep

```ts
interface PublicFormStep {
    id: string;
    label?: string;
    fields: string[];
    validateOn?: "change" | "blur" | "stepSubmit";
}
```

### PublicNativeFieldValidatorType

```ts
type PublicNativeFieldValidatorType = "contains" | "countryCode" | "domain" | "email" | "endsWith" | "ip" | "ipv4" | "ipv6" | "notContains" | "phoneE164" | "postalCode" | "regionCode" | "startsWith" | "url" | "uuid";
```

### PublicObjectField

```ts
interface PublicObjectField {
    type: "object";
    description?: string;
    label?: string;
    required?: boolean;
    fields: Record<string, PublicSchemaNode>;
    messages?: Record<string, string>;
}
```

### PublicRequiredValidator

```ts
interface PublicRequiredValidator {
    type: "required";
    code: string;
    message: string;
    rule?: string;
}
```

### PublicScalarField

```ts
interface PublicScalarField {
    type: "string" | "email" | "url" | "phone" | "number" | "boolean" | "date" | "textarea" | "select" | "checkbox";
    defaultValue?: string | number | boolean | string[];
    description?: string;
    label?: string;
    placeholder?: string;
    required?: boolean;
    min?: number;
    max?: number;
    exactLength?: number;
    pattern?: string;
    allowedValues?: string[];
    allowedProtocols?: string[];
    phoneFormat?: "e164";
    uuidVersion?: "any" | "v4" | "v7";
    countryCode?: "iso2";
    postalCodeCountry?: "CA" | "US";
    regionCodeCountry?: "CA" | "US";
    dateMin?: string;
    dateMax?: string;
    timeFormat?: "HH:mm" | "HH:mm:ss";
    dateTimeFormat?: "iso8601";
    startsWith?: string;
    endsWith?: string;
    contains?: string;
    notContains?: string;
    caseTransform?: "upper" | "lower";
    collapseWhitespace?: boolean;
    integer?: boolean;
    maxDecimalPlaces?: number;
    accepted?: boolean;
    minSelections?: number;
    maxSelections?: number;
    trim?: boolean;
    normalizeEmail?: boolean;
    pipeline?: PublicFieldPipelineStep[];
    sanitizers?: PublicFieldSanitizer[];
    transformers?: PublicFieldTransformer[];
    validators?: PublicFieldValidator[];
    messages?: Record<string, string>;
}
```

### PublicSchemaNode

```ts
type PublicSchemaNode = PublicScalarField | PublicObjectField | PublicArrayField;
```

### PublicValidationAction

```ts
interface PublicValidationAction {
    path: string;
    validator?: PublicContextualValidator;
}
```

### PublicValidationRule

```ts
interface PublicValidationRule {
    id: string;
    label?: string;
    when: unknown;
    then: PublicValidationAction[];
}
```

### PublicVisibilityRule

```ts
interface PublicVisibilityRule {
    id: string;
    label?: string;
    path: string;
    default?: PublicFieldVisibilityState;
    when: unknown;
    state: PublicFieldVisibilityState;
}
```

### SubmitErrorResponse

```ts
interface SubmitErrorResponse {
    ok: false;
    error: FormerieError | ValidationFailedError;
}
```

### SubmitPayload

```ts
interface SubmitPayload {
    fields: Record<string, unknown>;
    turnstileToken?: string;
    verificationToken?: string;
    metadata?: Record<string, unknown>;
}
```

### SubmitRequestOptions

```ts
interface SubmitRequestOptions {
    signal?: AbortSignal;
    headers?: HeadersInit;
}
```

### SubmitResponse

```ts
type SubmitResponse = SubmitSuccessResponse | SubmitErrorResponse;
```

### SubmitSuccessResponse

```ts
interface SubmitSuccessResponse {
    ok: true;
    submissionId: string;
    status: "accepted";
}
```

### ValidatePayload

```ts
interface ValidatePayload {
    fields: Record<string, unknown>;
    mode?: "partial" | "step";
    step?: string;
    metadata?: Record<string, unknown>;
}
```

### ValidateResponse

```ts
type ValidateResponse = ValidateSuccessResponse | SubmitErrorResponse;
```

### ValidateSuccessResponse

```ts
interface ValidateSuccessResponse {
    ok: true;
    status: "valid";
    mode: "partial" | "step";
    step?: string;
    values: Record<string, unknown>;
}
```

### ValidationFailedError

```ts
interface ValidationFailedError extends FormerieError {
    code: "VALIDATION_FAILED";
    fields: Record<string, ValidationIssue[]>;
    issues: ValidationIssue[];
}
```

### ValidationIssue

```ts
interface ValidationIssue {
    path: string;
    code: FieldErrorCode;
    message: string;
    rule: string;
    params?: Record<string, unknown>;
}
```