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

package/dist/index.d.ts

@@ -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,51 +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
@@ -1646,4 +1728,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, type TriggerWebhooksOptions, type TriggerWebhooksResult, UrlFormField, type WebhookDeliveryResult, WebhookEvent, type WebhookPayload, applyFieldDefaults, applyFormDefaults, assertValidFormConfig, checkSpam, checkbox, createFormConfig, date, downloadFile, email, evaluateConditions, exportAndDownload, exportToCSV, exportToJSON, file, fireWebhooks, formBuilder, formBuilderPlugin, formatExportValue, formsCollection, generateExportFilename, generateZodSchema, getFormBuilderConfig, getFormSubmissionStats, getSupportedComparisonOperators, getSupportedWebhookEvents, getValidationErrors, hidden, isFormAcceptingSubmissions, isValidComparisonOperator, isValidWebhookUrl, number, option, phone, pluralize, radio, select, submissionsCollection, submitForm, text, textarea, time, toTitleCase, transformFormData, triggerWebhooks, url, validateFormConfig, validateFormData, validateSubmission };