@form-engine-ts/core 5.1.0 → 6.0.0

package/README.md

@@ -56,6 +56,11 @@ translation adapter runs.
 `ja_JP`, and returns `null` for invalid tags. Schema validation, sanitization, locale policy checks, and translation
 slot lookup use this same normalization so equivalent locale spellings cannot bypass constraints.
 
+Submissions use `values` as their canonical answer property. `toFormSubmissionWire` and
+`fromFormSubmissionWire` preserve the optional submission `locale` across validated wire payloads. Legacy payloads with
+`answers` are isolated under `LegacyFormSubmission` and `fromLegacyFormSubmission` in the compatibility namespace.
+`serializeSubmissionError` and `deserializeSubmissionError` provide the JSON boundary for `FormSubmissionError`.
+
 Fields can use a `displayRule` with nested `all`/`any` condition groups and `show` or `hide` actions. Supported
 operators include equality, containment, emptiness, and numeric comparisons; the legacy `displayCondition` and
 `not_empty` forms remain supported. `submissionSettings` can enable pre-submit confirmation and select its

package/dist/index.cjs

@@ -51,6 +51,7 @@ __export(index_exports, {
   decodeSubmissionCursor: () => decodeSubmissionCursor,
   decodeTextAnswerCursor: () => decodeTextAnswerCursor,
   deleteDraft: () => deleteDraft,
+  deserializeSubmissionError: () => deserializeSubmissionError,
   dispatchWebhook: () => dispatchWebhook,
   encodeStorageSubmissionCursor: () => encodeStorageSubmissionCursor,
   encodeStorageTextAnswerCursor: () => encodeStorageTextAnswerCursor,
@@ -59,6 +60,8 @@ __export(index_exports, {
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
   exportResponsesToCsvStream: () => exportResponsesToCsvStream,
+  fromFormSubmissionWire: () => fromFormSubmissionWire,
+  fromLegacyFormSubmission: () => fromLegacyFormSubmission,
   getTranslationStatus: () => getTranslationStatus,
   isDisplayConditionGroupSatisfied: () => isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
@@ -80,6 +83,7 @@ __export(index_exports, {
   resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
   selectVisibleAnswers: () => selectVisibleAnswers,
+  serializeSubmissionError: () => serializeSubmissionError,
   toFormSubmissionWire: () => toFormSubmissionWire,
   transformFieldType: () => transformFieldType,
   validateAnswers: () => validateAnswers,
@@ -1478,7 +1482,7 @@ function aggregateResponses(schema, submissions) {
 function responseValues(submission) {
   if (typeof submission !== "object" || submission === null) return void 0;
   if ("values" in submission) return submission.values;
-  return "answers" in submission ? submission.answers : void 0;
+  return submission.answers;
 }
 function responseIdentifier(submission) {
   if (typeof submission !== "object" || submission === null) return "<unknown>";
@@ -1674,14 +1678,17 @@ function serializeValue(value) {
 }
 function asFormResponse(submission) {
   if (!("values" in submission)) return submission;
+  const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+    Object.entries(submission.metadata).filter((entry) => entry[1] !== void 0)
+  );
   return {
     responseId: submission.id,
     formId: submission.formId,
-    sourceLocale: submission.locale,
+    ...submission.locale === void 0 ? {} : { sourceLocale: submission.locale },
     formVersion: submission.formVersion,
     answers: submission.values,
     submittedAt: submission.submittedAt,
-    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...metadata === void 0 ? {} : { metadata },
     ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
   };
 }
@@ -1826,6 +1833,21 @@ function exportResponsesToCsv(schema, responses, options = {}) {
   return options.useBom ?? options.withBom ?? true ? `\uFEFF${csv}` : csv;
 }
 
+// src/compat/legacy.ts
+var fromLegacyFormSubmission = (legacy) => {
+  const { id, formId, formVersion, answers, locale, metadata, submittedAt, schemaRevision } = legacy;
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...answers },
+    ...locale === void 0 ? {} : { locale },
+    metadata,
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+};
+
 // src/errors.ts
 var FormSubmissionError = class extends Error {
   payload;
@@ -1838,6 +1860,8 @@ var FormSubmissionError = class extends Error {
     return this.payload;
   }
 };
+var serializeSubmissionError = (error) => error.toJSON();
+var deserializeSubmissionError = (json) => new FormSubmissionError(json);
 
 // src/events.ts
 function bytesToHex(bytes) {
@@ -2421,14 +2445,17 @@ async function paginateWithFilter(params) {
   return { items: collected, hasMore: false, totalScannedCount };
 }
 function asFormResponse2(submission) {
+  const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+    Object.entries(submission.metadata).filter((entry) => entry[1] !== void 0)
+  );
   return {
     responseId: submission.id,
     formId: submission.formId,
     formVersion: submission.formVersion,
-    sourceLocale: submission.locale,
+    ...submission.locale === void 0 ? {} : { sourceLocale: submission.locale },
     answers: submission.values,
     submittedAt: submission.submittedAt,
-    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+    ...metadata === void 0 ? {} : { metadata }
   };
 }
 async function* iterateSubmissionPages(adapter, formId, queryOptions = {}, options = {}) {
@@ -2656,6 +2683,7 @@ var FormSubmissionWireSchema = import_zod.z.object({
   formId: import_zod.z.string().min(1),
   formVersion: import_zod.z.number().int().positive(),
   values: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
+  locale: import_zod.z.string().min(1).optional(),
   metadata: FormSubmissionMetadataSchema,
   submittedAt: import_zod.z.string().datetime(),
   schemaRevision: import_zod.z.number().int().optional()
@@ -2842,18 +2870,32 @@ function isFormValue(value) {
   return value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 function toFormSubmissionWire(submission) {
-  const { id, formId, formVersion, values, answers, metadata, submittedAt, schemaRevision } = submission;
-  const targetValues = values ?? answers ?? {};
+  const { id, formId, formVersion, values, locale, metadata, submittedAt, schemaRevision } = submission;
   return {
     id,
     formId,
     formVersion,
-    values: { ...targetValues },
+    values: { ...values },
+    ...locale === void 0 ? {} : { locale },
     metadata: { ...metadata ?? {} },
     submittedAt,
     ...schemaRevision === void 0 ? {} : { schemaRevision }
   };
 }
+function fromFormSubmissionWire(wire) {
+  const { id, formId, formVersion, values, locale, metadata, submittedAt, schemaRevision } = wire;
+  const canonicalMetadata = { ...metadata };
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...values },
+    ...locale === void 0 ? {} : { locale },
+    metadata: canonicalMetadata,
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+}
 function createSubmission(schemaOrInput, values, options) {
   if ("answers" in schemaOrInput) {
     const input = schemaOrInput;
@@ -2873,7 +2915,6 @@ function createSubmission(schemaOrInput, values, options) {
       formVersion: input.formVersion,
       locale: "",
       values: Object.freeze(cloneValues(toFormValues(answers))),
-      answers,
       metadata: input.metadata,
       submittedAt,
       ...input.schemaRevision === void 0 ? {} : { schemaRevision: input.schemaRevision }
@@ -2900,7 +2941,6 @@ function createSubmission(schemaOrInput, values, options) {
     formVersion: schema.version,
     locale: options.locale,
     values: Object.freeze(cloneValues(visibleValues)),
-    answers: Object.freeze({ ...visibleValues }),
     submittedAt: options.submittedAt,
     ...options.metadata === void 0 ? {} : { metadata: Object.freeze({ ...options.metadata }) },
     ...options.translationMetadata === void 0 ? {} : { translationMetadata: Object.freeze({ ...options.translationMetadata }) }
@@ -3793,6 +3833,7 @@ async function commitVersionTransition(options) {
   decodeSubmissionCursor,
   decodeTextAnswerCursor,
   deleteDraft,
+  deserializeSubmissionError,
   dispatchWebhook,
   encodeStorageSubmissionCursor,
   encodeStorageTextAnswerCursor,
@@ -3801,6 +3842,8 @@ async function commitVersionTransition(options) {
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
+  fromFormSubmissionWire,
+  fromLegacyFormSubmission,
   getTranslationStatus,
   isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied,
@@ -3822,6 +3865,7 @@ async function commitVersionTransition(options) {
   resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
+  serializeSubmissionError,
   toFormSubmissionWire,
   transformFieldType,
   validateAnswers,

package/dist/index.d.cts

@@ -370,14 +370,12 @@ type AnswerValidationResult = {
     readonly valid: false;
     readonly issues: readonly ValidationIssue[];
 };
-interface FormSubmissionBase extends ExtensibleNode {
+interface FormSubmissionBase extends Pick<ExtensibleNode, "translationMetadata"> {
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
-    readonly locale: string;
+    readonly locale?: string;
     readonly values: FormValues;
-    /** Alias used by API-facing consumers; values remains the canonical v4 field. */
-    readonly answers?: Readonly<Record<string, unknown>>;
     readonly submittedAt: string;
     readonly schemaRevision?: number;
 }
@@ -391,7 +389,8 @@ interface FormSubmissionWire<TMeta extends BaseSubmissionMetadata = BaseSubmissi
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
-    readonly values: Record<string, unknown>;
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
     readonly metadata: TMeta;
     readonly submittedAt: string;
     readonly schemaRevision?: number;
@@ -677,6 +676,19 @@ interface NodeWritableStream {
 declare function pipeResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, writable: WritableStream<Uint8Array> | NodeWritableStream, options?: StreamCsvOptions): Promise<void>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
+/** Submission shape used by pre-v4 clients and migration-only code. */
+interface LegacyFormSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly id: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+    readonly metadata: TMeta;
+    readonly submittedAt: string;
+    readonly schemaRevision?: number;
+}
+declare const fromLegacyFormSubmission: <TMeta extends BaseSubmissionMetadata>(legacy: LegacyFormSubmission<TMeta>) => FormSubmission<TMeta>;
+
 interface SensitiveDataFinding {
     readonly fieldId: string;
     readonly type: string;
@@ -715,6 +727,8 @@ declare class FormSubmissionError extends Error {
     constructor(payload: FormSubmissionSerializedError);
     toJSON(): FormSubmissionSerializedError;
 }
+declare const serializeSubmissionError: (error: FormSubmissionError) => FormSubmissionSerializedError;
+declare const deserializeSubmissionError: (json: FormSubmissionSerializedError) => FormSubmissionError;
 
 type FormEventType = "response.submitted" | "schema.updated";
 interface FormEvent<T = unknown> {
@@ -867,6 +881,7 @@ declare const FormSubmissionWireSchema: z.ZodObject<{
     formId: z.ZodString;
     formVersion: z.ZodNumber;
     values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    locale: z.ZodOptional<z.ZodString>;
     metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     submittedAt: z.ZodString;
     schemaRevision: z.ZodOptional<z.ZodNumber>;
@@ -881,6 +896,9 @@ interface CreateSubmissionOptions<TMeta extends BaseSubmissionMetadata = BaseSub
 }
 declare function toFormSubmissionWire<TMeta extends BaseSubmissionMetadata>(submission: FormSubmission<TMeta>): FormSubmissionWire<TMeta>;
 declare function toFormSubmissionWire(submission: FormSubmission): FormSubmissionWire;
+declare function fromFormSubmissionWire<TMeta extends BaseSubmissionMetadata>(wire: FormSubmissionWire<TMeta>): FormSubmission<TMeta>;
+declare function fromFormSubmissionWire(wire: FormSubmissionWireSchemaType): FormSubmission;
+declare function fromFormSubmissionWire(wire: FormSubmissionWire): FormSubmission;
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions<TMeta>): FormSubmission<TMeta>;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(input: CreateSubmissionInput<TMeta>): FormSubmission<TMeta>;
@@ -1007,4 +1025,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AggregationReport, type AggregationSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvColumnDefinition, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, FormSubmissionError, FormSubmissionMetadataSchema, type FormSubmissionSerializedError, type FormSubmissionSettings, type FormSubmissionWire, FormSubmissionWireSchema, type FormSubmissionWireSchemaType, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyTranslationMetadata, type LocaleOption, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceDetailedKey, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, toFormSubmissionWire, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AggregationReport, type AggregationSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvColumnDefinition, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, FormSubmissionError, FormSubmissionMetadataSchema, type FormSubmissionSerializedError, type FormSubmissionSettings, type FormSubmissionWire, FormSubmissionWireSchema, type FormSubmissionWireSchemaType, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyFormSubmission, type LegacyTranslationMetadata, type LocaleOption, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceDetailedKey, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, deserializeSubmissionError, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, fromFormSubmissionWire, fromLegacyFormSubmission, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, serializeSubmissionError, toFormSubmissionWire, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };

package/dist/index.d.ts

@@ -370,14 +370,12 @@ type AnswerValidationResult = {
     readonly valid: false;
     readonly issues: readonly ValidationIssue[];
 };
-interface FormSubmissionBase extends ExtensibleNode {
+interface FormSubmissionBase extends Pick<ExtensibleNode, "translationMetadata"> {
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
-    readonly locale: string;
+    readonly locale?: string;
     readonly values: FormValues;
-    /** Alias used by API-facing consumers; values remains the canonical v4 field. */
-    readonly answers?: Readonly<Record<string, unknown>>;
     readonly submittedAt: string;
     readonly schemaRevision?: number;
 }
@@ -391,7 +389,8 @@ interface FormSubmissionWire<TMeta extends BaseSubmissionMetadata = BaseSubmissi
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
-    readonly values: Record<string, unknown>;
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
     readonly metadata: TMeta;
     readonly submittedAt: string;
     readonly schemaRevision?: number;
@@ -677,6 +676,19 @@ interface NodeWritableStream {
 declare function pipeResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, writable: WritableStream<Uint8Array> | NodeWritableStream, options?: StreamCsvOptions): Promise<void>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
+/** Submission shape used by pre-v4 clients and migration-only code. */
+interface LegacyFormSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly id: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+    readonly metadata: TMeta;
+    readonly submittedAt: string;
+    readonly schemaRevision?: number;
+}
+declare const fromLegacyFormSubmission: <TMeta extends BaseSubmissionMetadata>(legacy: LegacyFormSubmission<TMeta>) => FormSubmission<TMeta>;
+
 interface SensitiveDataFinding {
     readonly fieldId: string;
     readonly type: string;
@@ -715,6 +727,8 @@ declare class FormSubmissionError extends Error {
     constructor(payload: FormSubmissionSerializedError);
     toJSON(): FormSubmissionSerializedError;
 }
+declare const serializeSubmissionError: (error: FormSubmissionError) => FormSubmissionSerializedError;
+declare const deserializeSubmissionError: (json: FormSubmissionSerializedError) => FormSubmissionError;
 
 type FormEventType = "response.submitted" | "schema.updated";
 interface FormEvent<T = unknown> {
@@ -867,6 +881,7 @@ declare const FormSubmissionWireSchema: z.ZodObject<{
     formId: z.ZodString;
     formVersion: z.ZodNumber;
     values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    locale: z.ZodOptional<z.ZodString>;
     metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     submittedAt: z.ZodString;
     schemaRevision: z.ZodOptional<z.ZodNumber>;
@@ -881,6 +896,9 @@ interface CreateSubmissionOptions<TMeta extends BaseSubmissionMetadata = BaseSub
 }
 declare function toFormSubmissionWire<TMeta extends BaseSubmissionMetadata>(submission: FormSubmission<TMeta>): FormSubmissionWire<TMeta>;
 declare function toFormSubmissionWire(submission: FormSubmission): FormSubmissionWire;
+declare function fromFormSubmissionWire<TMeta extends BaseSubmissionMetadata>(wire: FormSubmissionWire<TMeta>): FormSubmission<TMeta>;
+declare function fromFormSubmissionWire(wire: FormSubmissionWireSchemaType): FormSubmission;
+declare function fromFormSubmissionWire(wire: FormSubmissionWire): FormSubmission;
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions<TMeta>): FormSubmission<TMeta>;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(input: CreateSubmissionInput<TMeta>): FormSubmission<TMeta>;
@@ -1007,4 +1025,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AggregationReport, type AggregationSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvColumnDefinition, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, FormSubmissionError, FormSubmissionMetadataSchema, type FormSubmissionSerializedError, type FormSubmissionSettings, type FormSubmissionWire, FormSubmissionWireSchema, type FormSubmissionWireSchemaType, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyTranslationMetadata, type LocaleOption, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceDetailedKey, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, toFormSubmissionWire, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AggregationReport, type AggregationSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvColumnDefinition, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, FormSubmissionError, FormSubmissionMetadataSchema, type FormSubmissionSerializedError, type FormSubmissionSettings, type FormSubmissionWire, FormSubmissionWireSchema, type FormSubmissionWireSchemaType, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyFormSubmission, type LegacyTranslationMetadata, type LocaleOption, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceDetailedKey, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, deserializeSubmissionError, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, fromFormSubmissionWire, fromLegacyFormSubmission, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, serializeSubmissionError, toFormSubmissionWire, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };

package/dist/index.js

@@ -1386,7 +1386,7 @@ function aggregateResponses(schema, submissions) {
 function responseValues(submission) {
   if (typeof submission !== "object" || submission === null) return void 0;
   if ("values" in submission) return submission.values;
-  return "answers" in submission ? submission.answers : void 0;
+  return submission.answers;
 }
 function responseIdentifier(submission) {
   if (typeof submission !== "object" || submission === null) return "<unknown>";
@@ -1582,14 +1582,17 @@ function serializeValue(value) {
 }
 function asFormResponse(submission) {
   if (!("values" in submission)) return submission;
+  const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+    Object.entries(submission.metadata).filter((entry) => entry[1] !== void 0)
+  );
   return {
     responseId: submission.id,
     formId: submission.formId,
-    sourceLocale: submission.locale,
+    ...submission.locale === void 0 ? {} : { sourceLocale: submission.locale },
     formVersion: submission.formVersion,
     answers: submission.values,
     submittedAt: submission.submittedAt,
-    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...metadata === void 0 ? {} : { metadata },
     ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
   };
 }
@@ -1734,6 +1737,21 @@ function exportResponsesToCsv(schema, responses, options = {}) {
   return options.useBom ?? options.withBom ?? true ? `\uFEFF${csv}` : csv;
 }
 
+// src/compat/legacy.ts
+var fromLegacyFormSubmission = (legacy) => {
+  const { id, formId, formVersion, answers, locale, metadata, submittedAt, schemaRevision } = legacy;
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...answers },
+    ...locale === void 0 ? {} : { locale },
+    metadata,
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+};
+
 // src/errors.ts
 var FormSubmissionError = class extends Error {
   payload;
@@ -1746,6 +1764,8 @@ var FormSubmissionError = class extends Error {
     return this.payload;
   }
 };
+var serializeSubmissionError = (error) => error.toJSON();
+var deserializeSubmissionError = (json) => new FormSubmissionError(json);
 
 // src/events.ts
 function bytesToHex(bytes) {
@@ -2329,14 +2349,17 @@ async function paginateWithFilter(params) {
   return { items: collected, hasMore: false, totalScannedCount };
 }
 function asFormResponse2(submission) {
+  const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+    Object.entries(submission.metadata).filter((entry) => entry[1] !== void 0)
+  );
   return {
     responseId: submission.id,
     formId: submission.formId,
     formVersion: submission.formVersion,
-    sourceLocale: submission.locale,
+    ...submission.locale === void 0 ? {} : { sourceLocale: submission.locale },
     answers: submission.values,
     submittedAt: submission.submittedAt,
-    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+    ...metadata === void 0 ? {} : { metadata }
   };
 }
 async function* iterateSubmissionPages(adapter, formId, queryOptions = {}, options = {}) {
@@ -2564,6 +2587,7 @@ var FormSubmissionWireSchema = z.object({
   formId: z.string().min(1),
   formVersion: z.number().int().positive(),
   values: z.record(z.string(), z.unknown()),
+  locale: z.string().min(1).optional(),
   metadata: FormSubmissionMetadataSchema,
   submittedAt: z.string().datetime(),
   schemaRevision: z.number().int().optional()
@@ -2750,18 +2774,32 @@ function isFormValue(value) {
   return value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 function toFormSubmissionWire(submission) {
-  const { id, formId, formVersion, values, answers, metadata, submittedAt, schemaRevision } = submission;
-  const targetValues = values ?? answers ?? {};
+  const { id, formId, formVersion, values, locale, metadata, submittedAt, schemaRevision } = submission;
   return {
     id,
     formId,
     formVersion,
-    values: { ...targetValues },
+    values: { ...values },
+    ...locale === void 0 ? {} : { locale },
     metadata: { ...metadata ?? {} },
     submittedAt,
     ...schemaRevision === void 0 ? {} : { schemaRevision }
   };
 }
+function fromFormSubmissionWire(wire) {
+  const { id, formId, formVersion, values, locale, metadata, submittedAt, schemaRevision } = wire;
+  const canonicalMetadata = { ...metadata };
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...values },
+    ...locale === void 0 ? {} : { locale },
+    metadata: canonicalMetadata,
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+}
 function createSubmission(schemaOrInput, values, options) {
   if ("answers" in schemaOrInput) {
     const input = schemaOrInput;
@@ -2781,7 +2819,6 @@ function createSubmission(schemaOrInput, values, options) {
       formVersion: input.formVersion,
       locale: "",
       values: Object.freeze(cloneValues(toFormValues(answers))),
-      answers,
       metadata: input.metadata,
       submittedAt,
       ...input.schemaRevision === void 0 ? {} : { schemaRevision: input.schemaRevision }
@@ -2808,7 +2845,6 @@ function createSubmission(schemaOrInput, values, options) {
     formVersion: schema.version,
     locale: options.locale,
     values: Object.freeze(cloneValues(visibleValues)),
-    answers: Object.freeze({ ...visibleValues }),
     submittedAt: options.submittedAt,
     ...options.metadata === void 0 ? {} : { metadata: Object.freeze({ ...options.metadata }) },
     ...options.translationMetadata === void 0 ? {} : { translationMetadata: Object.freeze({ ...options.translationMetadata }) }
@@ -3700,6 +3736,7 @@ export {
   decodeSubmissionCursor,
   decodeTextAnswerCursor,
   deleteDraft,
+  deserializeSubmissionError,
   dispatchWebhook,
   encodeStorageSubmissionCursor,
   encodeStorageTextAnswerCursor,
@@ -3708,6 +3745,8 @@ export {
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
+  fromFormSubmissionWire,
+  fromLegacyFormSubmission,
   getTranslationStatus,
   isDisplayConditionGroupSatisfied,
   isDisplayConditionSatisfied,
@@ -3729,6 +3768,7 @@ export {
   resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
+  serializeSubmissionError,
   toFormSubmissionWire,
   transformFieldType,
   validateAnswers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "5.1.0",
+  "version": "6.0.0",
   "publishConfig": {
     "access": "public"
   },