@nextlyhq/plugin-form-builder 0.0.2-alpha.65 → 0.0.2-alpha.67

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as nextly from 'nextly';
 import { CollectionConfig, PluginContext } from 'nextly';
 import { PluginDefinition } from '@nextlyhq/plugin-sdk';
-import { R as ResolvedFormBuilderConfig, F as FormBuilderPluginOptions, a as FormConfig, b as FormSettings, c as FormNotifications, C as CheckboxFormField, D as DateFormField, E as EmailFormField, d as FileFormField, H as HiddenFormField, N as NumberFormField, P as PhoneFormField, e as RadioFormField, S as SelectFormField, T as TextFormField, f as TextareaFormField, g as TimeFormField, U as UrlFormField, h as ConditionalLogic, A as AnyFormField, i as SubmissionDocument, j as FormDocument, W as WebhookEvent } from './types-hLfLe81K.js';
-export { B as BUILT_IN_FORM_FIELD_TYPES, k as BaseFormField, l as ConditionalLogicCondition, m as CustomFormField, n as EmailConfig, o as FieldBlockConfig, p as FormAccess, q as FormField, r as FormFieldType, s as FormFieldTypeId, t as FormHookContext, u as FormHooks, v as FormNotification, w as FormNotificationItem, x as FormSubmission, V as ValidationRules, y as WebhookConfig, z as isCheckboxFormField, G as isEmailFormField, I as isFileFormField, J as isFormField, K as isFormFieldType, L as isKnownFormField, M as isSelectFormField, O as isTextFormField } from './types-hLfLe81K.js';
+import { R as ResolvedFormBuilderConfig, F as FormBuilderPluginOptions, a as FormConfig, b as FormSettings, c as FormNotifications, C as CheckboxFormField, D as DateFormField, E as EmailFormField, d as FileFormField, H as HiddenFormField, N as NumberFormField, P as PhoneFormField, e as RadioFormField, S as SelectFormField, T as TextFormField, f as TextareaFormField, g as TimeFormField, U as UrlFormField, h as ConditionalLogic, A as AnyFormField, i as SubmissionDocument, j as FormDocument } from './types-Bo4lk9BD.js';
+export { B as BUILT_IN_FORM_FIELD_TYPES, k as BaseFormField, l as ConditionalLogicCondition, m as CustomFormField, n as EmailConfig, o as FieldBlockConfig, p as FormAccess, q as FormField, r as FormFieldType, s as FormFieldTypeId, t as FormHookContext, u as FormHooks, v as FormNotification, w as FormNotificationItem, x as FormSubmission, V as ValidationRules, y as isCheckboxFormField, z as isEmailFormField, G as isFileFormField, I as isFormField, J as isFormFieldType, K as isKnownFormField, L as isSelectFormField, M as isTextFormField } from './types-Bo4lk9BD.js';
 import { z } from 'zod';
 import 'react';
 
@@ -936,6 +936,20 @@ declare function validateFormData(data: Record<string, unknown>, fields: AnyForm
  * @param result - Zod safe parse result
  * @returns Object mapping field names to error messages
  */
+/** A field that failed, with the machine code a wire error reports. */
+interface ValidationIssue {
+    path: string;
+    /** `REQUIRED` for an answer that is missing or empty, else `INVALID`. */
+    code: "REQUIRED" | "INVALID";
+    message: string;
+}
+/**
+ * The same failures as a field-to-message map.
+ *
+ * Derived from {@link getValidationIssues} rather than walking the issues a
+ * second time, so the two cannot disagree about which message belongs to a
+ * field or which failure won when one field had several.
+ */
 declare function getValidationErrors(result: z.ZodSafeParseResult<unknown>): Record<string, string>;
 
 /**
@@ -1166,21 +1180,126 @@ interface SubmitFormOptions {
         /** Submitter's user agent string */
         userAgent?: string;
     };
+    /**
+     * The HTTP request this submission arrived on.
+     *
+     * A route calling this helper is its own route, outside everything Nextly
+     * pins a request around, so nothing else can supply it. Without it the write
+     * reaches the submissions hooks looking like a seed or a job, and every rule
+     * scoped to a visitor stands down: the rate limit above all.
+     *
+     * The request rather than an address, because the core resolves the client
+     * from it under this deployment's proxy-trust settings. `metadata.ipAddress`
+     * is a string the caller chose, which is the right shape for the audit column
+     * it fills and the wrong shape for deciding who to throttle.
+     */
+    request?: Request;
+    /**
+     * Whose permissions the reads and the write are judged against.
+     *
+     * Defaults to `system`, so every existing caller behaves as before.
+     */
+    access?: SubmissionAccess;
+    /**
+     * The language the visitor submitted in.
+     *
+     * Decides which translation a picked redirect page is read in, and so which
+     * URL the visitor is sent to: a page whose slug is `thanks` in English and
+     * `merci` in French answered `/thanks` to everyone, because the target was
+     * read with no locale and the default answered. The built-in route takes it
+     * from `?locale=` on the submit URL, the same way core's own routes take a
+     * locale on the wire; a host route passes whatever it resolved for the page
+     * the form was on.
+     *
+     * A code that is not a configured locale reads as the default rather than
+     * failing the submission, which the collection services decide. Absent means
+     * the default, as it always has. The read wildcards (`all`, `*`) are not a
+     * language a visitor can have submitted in and are treated as absent: a read
+     * in "every language" answers a localized URL field with one value per
+     * language, which no URL pattern can be filled from.
+     */
+    locale?: string;
 }
+/**
+ * How this submission reaches the collections it touches.
+ *
+ * `system` is the default and is right for host code: the caller already
+ * decided, and there is no visitor whose permissions could be consulted.
+ *
+ * `public` is for a route serving an anonymous visitor. It keeps the
+ * collection's configured `access` rules in force, so a host that closed
+ * submissions or restricted reading forms is obeyed rather than bypassed. The
+ * former core endpoint ran this way, and elevating a public route to `system`
+ * silently overrode that configuration.
+ */
+type SubmissionAccess = {
+    as: "system";
+} | {
+    as: "public";
+};
+/**
+ * Why a submission ended the way it did.
+ *
+ * `success` alone cannot carry this. An HTTP route has to answer 404 for a slug
+ * nobody used, 409 for a form its author closed and 400 for data that did not
+ * validate, and a boolean plus a human sentence cannot tell those apart without
+ * matching on the sentence.
+ *
+ * `accepted` covers every ending a visitor is told succeeded, INCLUDING the two
+ * that are deliberately indistinguishable from success: a submission the
+ * honeypot flagged, and one the rate limiter refused. A caller must not try to
+ * separate them, which is why they do not appear here as their own names.
+ */
+type SubmitFormOutcome = "accepted" | "no-such-form" | "closed" | "invalid" | "duplicate" | "failed";
 /**
  * Result of form submission.
  */
 interface SubmitFormResult {
     /** Whether the submission was successful */
     success: boolean;
+    /**
+     * Which ending this was, for a caller that has to map it to a status code.
+     *
+     * Required rather than optional, so a return path added later cannot omit it
+     * and leave the HTTP route guessing from the message text.
+     */
+    outcome: SubmitFormOutcome;
     /** The created submission document (on success) */
     submission?: SubmissionDocument;
     /** Error message (on failure) */
     error?: string;
     /** Field-level validation errors */
     validationErrors?: Record<string, string>;
+    /**
+     * The same failures with their machine codes, for a caller building an HTTP
+     * error. `validationErrors` above cannot carry one, so a route reading only
+     * that has to invent a code and reports every blank answer as `INVALID`.
+     */
+    validationIssues?: ValidationIssue[];
     /** Redirect URL (if form configured for redirect on success) */
     redirect?: string;
+    /**
+     * The error that ended a `failed` submission, kept rather than flattened.
+     *
+     * A collection can refuse a write for reasons its host chose: a
+     * `beforeValidate` hook throwing `NextlyError.validation`, a uniqueness
+     * conflict. Those carry their own status and field detail, and reporting them
+     * all as one internal error tells a visitor the server broke when in fact
+     * their submission was answered deliberately.
+     */
+    cause?: unknown;
+    /**
+     * The toast the form's author wrote for a successful submission.
+     *
+     * Carried on the result rather than read from the form again by whoever
+     * presents it: the HTTP route would otherwise have to fetch the form a second
+     * time purely to learn a string this function already had in hand, and a
+     * second read is a second chance to disagree about which form was submitted.
+     *
+     * Present on every `accepted` ending, including the ones a bot caused, so the
+     * message cannot be used to tell an accepted submission from a flagged one.
+     */
+    successMessage?: string;
 }
 /**
  * Context for the submission handler.
@@ -1289,8 +1408,16 @@ declare function getFormSubmissionStats(formSlug: string, context: SubmitFormCon
 /**
  * Spam Detection
  *
- * Implements honeypot and rate limiting spam protection for form submissions.
- * Provides a pluggable approach to spam detection that can be extended.
+ * Honeypot and rate limiting for form submissions.
+ *
+ * The honeypot is a pure read of the submitted payload. The rate limit is not:
+ * it counts, and where the count lives decides whether the limit means
+ * anything. It lives in the deployment's own {@link RateLimitStore}, the one
+ * the REST and auth limiters already share, so `rateLimit.store` is configured
+ * once and all three agree about what they are counting. A store private to
+ * this module would count per process, and on a deployment that spans several
+ * the effective limit becomes `configured x instances` -- a number the operator
+ * never chose, that fails open, and only under load.
  *
  * @module handlers/spam-detection
  * @since 0.1.0
@@ -1376,184 +1503,6 @@ interface SpamCheckResult {
  * ```
  */
 declare function checkSpam(options: SpamCheckOptions): Promise<SpamCheckResult>;
-/**
- * Clean up expired rate limit entries.
- *
- * Call this periodically (e.g., every 5 minutes) to prevent
- * memory leaks from accumulated rate limit entries.
- *
- * @param maxAgeMs - Maximum age of entries to keep (default: 5 minutes)
- * @returns Number of entries removed
- *
- * @example
- * ```typescript
- * // Set up periodic cleanup
- * setInterval(() => {
- *   const removed = cleanupRateLimitStore();
- *   console.log(`Cleaned up ${removed} expired rate limit entries`);
- * }, 5 * 60 * 1000); // Every 5 minutes
- * ```
- */
-declare function cleanupRateLimitStore(maxAgeMs?: number): number;
-/**
- * Get the current size of the rate limit store.
- *
- * Useful for monitoring and debugging.
- *
- * @returns Number of entries in the store
- */
-declare function getRateLimitStoreSize(): number;
-/**
- * Clear all rate limit entries.
- *
- * Useful for testing or resetting state.
- */
-declare function clearRateLimitStore(): void;
-/**
- * Check if a specific IP/form is currently rate limited.
- *
- * @param ipAddress - IP address to check
- * @param formSlug - Form slug
- * @param config - Rate limit configuration
- * @returns Whether the IP is currently rate limited
- */
-declare function isRateLimited(ipAddress: string, formSlug: string, config: {
-    maxSubmissions: number;
-    windowMs: number;
-}): boolean;
-
-/**
- * Webhook Handler
- *
- * Triggers webhook notifications for form events.
- * Webhooks are fired asynchronously and do not block form submission.
- *
- * @module handlers/webhooks
- * @since 0.1.0
- */
-
-/**
- * Webhook payload sent to configured endpoints.
- */
-interface WebhookPayload {
-    /** Event type that triggered the webhook */
-    event: WebhookEvent;
-    /** ISO 8601 timestamp when the event occurred */
-    timestamp: string;
-    /** Form information */
-    form: {
-        id: string;
-        slug: string;
-        name: string;
-    };
-    /** Submission information (full data or minimal based on config) */
-    submission: SubmissionDocument | {
-        id: string;
-        submittedAt: Date;
-    };
-}
-/**
- * Options for triggering webhooks.
- */
-interface TriggerWebhooksOptions {
-    /** Event type */
-    event: WebhookEvent;
-    /** Form document */
-    form: FormDocument;
-    /** Submission document */
-    submission: SubmissionDocument;
-}
-/**
- * Result of a single webhook delivery attempt.
- */
-interface WebhookDeliveryResult {
-    /** Webhook URL */
-    url: string;
-    /** Whether the delivery was successful */
-    success: boolean;
-    /** HTTP status code (if request completed) */
-    statusCode?: number;
-    /** Error message (if delivery failed) */
-    error?: string;
-    /** Time taken in milliseconds */
-    durationMs: number;
-}
-/**
- * Result of triggering webhooks for an event.
- */
-interface TriggerWebhooksResult {
-    /** Number of webhooks triggered */
-    triggered: number;
-    /** Number of successful deliveries */
-    successful: number;
-    /** Number of failed deliveries */
-    failed: number;
-    /** Individual delivery results */
-    results: WebhookDeliveryResult[];
-}
-/**
- * Trigger webhooks for a form event.
- *
- * This function fires all matching webhooks asynchronously and does not
- * block form submission. Failed webhooks are logged but do not cause
- * submission failures.
- *
- * @param options - Trigger options
- * @returns Result of webhook triggering
- *
- * @example
- * ```typescript
- * // After creating a submission
- * const result = await triggerWebhooks({
- *   event: 'submission.created',
- *   form,
- *   submission,
- * });
- *
- * console.log(`Triggered ${result.triggered} webhooks`);
- * console.log(`Successful: ${result.successful}, Failed: ${result.failed}`);
- * ```
- */
-declare function triggerWebhooks(options: TriggerWebhooksOptions): Promise<TriggerWebhooksResult>;
-/**
- * Trigger webhooks without waiting for completion.
- *
- * This is the recommended way to call webhooks from submission handlers
- * as it doesn't block the response. Errors are logged but not thrown.
- *
- * @param options - Trigger options
- * @param logger - Optional logger for error reporting
- *
- * @example
- * ```typescript
- * // In submission handler - fire and forget
- * fireWebhooks(
- *   { event: 'submission.created', form, submission },
- *   pluginContext.logger
- * );
- *
- * // Continue with response immediately
- * return { success: true, submission };
- * ```
- */
-declare function fireWebhooks(options: TriggerWebhooksOptions, logger?: {
-    info?: (message: string, data?: Record<string, unknown>) => void;
-    warn?: (message: string, data?: Record<string, unknown>) => void;
-    error?: (message: string, data?: Record<string, unknown>) => void;
-}): void;
-/**
- * Validate a webhook URL.
- *
- * @param url - URL to validate
- * @returns Whether the URL is valid for webhooks
- */
-declare function isValidWebhookUrl(url: string): boolean;
-/**
- * Get the list of supported webhook events.
- *
- * @returns Array of supported event types
- */
-declare function getSupportedWebhookEvents(): WebhookEvent[];
 
 /**
  * Forms Collection
@@ -1646,4 +1595,4 @@ declare function submissionsCollection(pluginConfig: ResolvedFormBuilderConfig):
 
 declare const formBuilderPlugin: nextly.PluginDefinition;
 
-export { AnyFormField, type CSVExportOptions, CheckboxFormField, type ComparisonOperator, ConditionalLogic, DEFAULT_FORM_SETTINGS, DEFAULT_NOTIFICATION_SETTINGS, DateFormField, EmailFormField, type ExportedJSON, FileFormField, FormBuilderPluginOptions, type FormBuilderPluginResult, FormConfig, FormDocument, type FormFieldOption, FormNotifications, FormSettings, type FormValidationError, type FormValidationErrorCode, type FormValidationResult, HiddenFormField, type JSONExportOptions, type NextlyPlugin, NumberFormField, PhoneFormField, RESERVED_FORM_SLUGS, RadioFormField, ResolvedFormBuilderConfig, SelectFormField, type SpamCheckConfig, type SpamCheckOptions, type SpamCheckResult, SubmissionDocument, type SubmitFormContext, type SubmitFormOptions, type SubmitFormResult, TextFormField, TextareaFormField, TimeFormField, type TriggerWebhooksOptions, type TriggerWebhooksResult, UrlFormField, type WebhookDeliveryResult, WebhookEvent, type WebhookPayload, applyFieldDefaults, applyFormDefaults, assertValidFormConfig, checkSpam, checkbox, cleanupRateLimitStore, clearRateLimitStore, createFormConfig, date, downloadFile, email, evaluateConditions, exportAndDownload, exportToCSV, exportToJSON, file, fireWebhooks, formBuilder, formBuilderPlugin, formatExportValue, formsCollection, generateExportFilename, generateZodSchema, getFormBuilderConfig, getFormSubmissionStats, getRateLimitStoreSize, getSupportedComparisonOperators, getSupportedWebhookEvents, getValidationErrors, hidden, isFormAcceptingSubmissions, isRateLimited, isValidComparisonOperator, isValidWebhookUrl, number, option, phone, pluralize, radio, select, submissionsCollection, submitForm, text, textarea, time, toTitleCase, transformFormData, triggerWebhooks, url, validateFormConfig, validateFormData, validateSubmission };
+export { AnyFormField, type CSVExportOptions, CheckboxFormField, type ComparisonOperator, ConditionalLogic, DEFAULT_FORM_SETTINGS, DEFAULT_NOTIFICATION_SETTINGS, DateFormField, EmailFormField, type ExportedJSON, FileFormField, FormBuilderPluginOptions, type FormBuilderPluginResult, FormConfig, FormDocument, type FormFieldOption, FormNotifications, FormSettings, type FormValidationError, type FormValidationErrorCode, type FormValidationResult, HiddenFormField, type JSONExportOptions, type NextlyPlugin, NumberFormField, PhoneFormField, RESERVED_FORM_SLUGS, RadioFormField, ResolvedFormBuilderConfig, SelectFormField, type SpamCheckConfig, type SpamCheckOptions, type SpamCheckResult, SubmissionDocument, type SubmitFormContext, type SubmitFormOptions, type SubmitFormResult, TextFormField, TextareaFormField, TimeFormField, UrlFormField, applyFieldDefaults, applyFormDefaults, assertValidFormConfig, checkSpam, checkbox, createFormConfig, date, downloadFile, email, evaluateConditions, exportAndDownload, exportToCSV, exportToJSON, file, formBuilder, formBuilderPlugin, formatExportValue, formsCollection, generateExportFilename, generateZodSchema, getFormBuilderConfig, getFormSubmissionStats, getSupportedComparisonOperators, getValidationErrors, hidden, isFormAcceptingSubmissions, isValidComparisonOperator, number, option, phone, pluralize, radio, select, submissionsCollection, submitForm, text, textarea, time, toTitleCase, transformFormData, url, validateFormConfig, validateFormData, validateSubmission };