@form-engine-ts/core 2.5.0 → 2.6.0

package/dist/index.d.cts

@@ -1,3 +1,90 @@
+type Result<T, E> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: E;
+};
+type FormVersionStatus = "draft" | "published" | "archived";
+interface FormVersionRecord extends ExtensibleNode {
+    readonly formId: string;
+    readonly version: number;
+    readonly status: FormVersionStatus;
+    readonly schema: FormSchema;
+    readonly revision: number;
+    readonly createdFromVersion?: number;
+    readonly createdAt: string;
+    readonly publishedAt?: string;
+    readonly archivedAt?: string;
+}
+interface FormVersionState {
+    readonly formId: string;
+    readonly draftVersion?: number;
+    readonly publishedVersion?: number;
+    readonly nextVersion: number;
+    readonly revision: number;
+}
+type VersionTransitionError = {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "draft_not_found";
+} | {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+} | {
+    readonly type: "invalid_source_version";
+    readonly requestedVersion: number;
+    readonly publishedVersion?: number;
+} | {
+    readonly type: "version_immutable";
+    readonly status: FormVersionStatus;
+} | {
+    readonly type: "max_version_exceeded";
+    readonly max: number;
+} | {
+    readonly type: "validation_failed";
+    readonly issues: readonly SchemaIssue[];
+};
+interface CloneVersionOptions {
+    readonly maxVersions?: number;
+    readonly expectedRevision?: number;
+    /** Additional known published versions that may be used as a clone source. */
+    readonly allowedSourceVersions?: readonly number[];
+}
+interface PublishDraftOptions {
+    readonly expectedRevision?: number;
+    readonly currentPublishedRecord?: FormVersionRecord;
+    readonly validate?: (schema: FormSchema) => boolean | Promise<boolean> | readonly SchemaIssue[] | Promise<readonly SchemaIssue[]>;
+    readonly publishedAt?: string;
+    /** @deprecated Use publishedAt. */
+    readonly timestamp?: string;
+}
+interface DeleteDraftOptions {
+    readonly expectedRevision?: number;
+}
+interface PublishDraftResult {
+    readonly nextState: FormVersionState;
+    readonly publishedRecord: FormVersionRecord;
+    readonly archivedRecords: readonly FormVersionRecord[];
+    /** @deprecated Read archivedRecords instead. */
+    readonly archivedVersion?: number;
+}
+declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: FormSchema, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly draftSchema: FormSchema;
+}, VersionTransitionError>;
+declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Promise<Result<PublishDraftResult, VersionTransitionError>>;
+declare function createPublishTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: PublishDraftOptions): Promise<Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>>;
+declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+}, VersionTransitionError>;
+declare function assertVersionMutable(status: FormVersionStatus): void;
+
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
 interface FormPolicy {
     readonly allowedFieldTypes?: readonly FieldType[];
@@ -170,6 +257,8 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
+    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
@@ -179,6 +268,22 @@ interface SubmissionPage {
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
 }
+interface VersionTransitionPlan {
+    readonly formId: string;
+    readonly expectedRevision: number;
+    readonly nextRevision: number;
+    readonly draftToCreate?: FormVersionRecord;
+    readonly draftToDeleteVersion?: number;
+    readonly publishedRecordToSave?: FormVersionRecord;
+    readonly archivedRecordsToSave?: readonly FormVersionRecord[];
+    readonly timestamp: string;
+}
+interface VersionedFormStorageAdapter extends FormStorageAdapter {
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
+}
 interface BaseQuestionAggregate {
     readonly fieldId: string;
     readonly answeredCount: number;
@@ -223,6 +328,7 @@ type ChoiceOption = FieldOption;
 interface FormResponse extends ExtensibleNode {
     readonly responseId: string;
     readonly formId: string;
+    readonly formVersion?: number;
     readonly sourceLocale?: string;
     readonly answers: Readonly<Record<string, unknown>>;
     readonly submittedAt: string;
@@ -251,14 +357,25 @@ declare function calculateNumericSummary(responses: readonly FormSubmission[], q
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
 type AccumulatorResponse = FormSubmission | FormResponse;
+type AccumulatorSkipReason = "form_id_mismatch" | "version_mismatch" | "invalid_structure";
+interface AccumulatorReport {
+    readonly processedCount: number;
+    readonly skippedCount: number;
+    readonly skipReasons: readonly {
+        readonly responseId: string;
+        readonly reason: AccumulatorSkipReason;
+    }[];
+}
 interface ResponseAccumulator {
     add(submission: AccumulatorResponse): {
         readonly success: boolean;
+        readonly skipped?: boolean;
         readonly error?: string;
     };
-    addMany(submissions: Iterable<AccumulatorResponse>): void;
+    addMany(submissions: Iterable<AccumulatorResponse>): AccumulatorReport;
     merge(other: ResponseAccumulator): ResponseAccumulator;
     finalize(): FormAnalytics;
+    getReport(): AccumulatorReport;
 }
 interface ResponseAccumulatorOptions {
     readonly mode?: "strict" | "lenient";
@@ -271,13 +388,27 @@ interface CsvExportOptions {
 }
 interface CsvColumnDef {
     readonly header: string;
-    readonly getValue: (submission: FormResponse) => string | number | boolean | null | undefined;
+    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined | Promise<string | number | boolean | null | undefined>;
+}
+interface CsvColumnContext extends FormResponse {
+    readonly submission: FormResponse;
+    readonly formVersion: number;
+    readonly schema: FormSchema;
 }
 interface StreamCsvOptions extends CsvExportOptions {
     readonly columns?: readonly CsvColumnDef[];
     readonly includeDefaultColumns?: boolean;
 }
 declare function exportResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, options?: StreamCsvOptions): AsyncIterable<string>;
+interface NodeWritableStream {
+    write(chunk: Uint8Array): boolean;
+    once(event: "drain", listener: () => void): unknown;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    removeListener(event: "drain", listener: () => void): unknown;
+    removeListener(event: "error", listener: (error: Error) => void): unknown;
+    end(callback: () => void): unknown;
+}
+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;
 
 type FormEventType = "response.submitted" | "schema.updated";
@@ -314,6 +445,7 @@ interface SubmissionCursorValue {
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
     readonly defaultLocale?: string;
@@ -382,73 +514,10 @@ declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTransl
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
 declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
 
-type Result<T, E> = {
-    readonly success: true;
-    readonly value: T;
-} | {
-    readonly success: false;
-    readonly error: E;
-};
-type FormVersionStatus = "draft" | "published" | "archived";
-interface FormVersionRecord {
-    readonly formId: string;
-    readonly version: number;
-    readonly status: FormVersionStatus;
-    readonly schema: FormSchema;
-    readonly createdAt: string;
-    readonly publishedAt?: string;
-    readonly archivedAt?: string;
-}
-interface FormVersionState {
-    readonly formId: string;
-    readonly draftVersion?: number;
-    readonly publishedVersion?: number;
-    readonly nextVersion: number;
-    readonly revision: number;
-}
-type VersionTransitionError = {
-    readonly type: "draft_already_exists";
-    readonly currentDraftVersion: number;
-} | {
-    readonly type: "draft_not_found";
-} | {
-    readonly type: "revision_conflict";
-    readonly expectedRevision: number;
-    readonly actualRevision: number;
-} | {
-    readonly type: "version_immutable";
-    readonly status: FormVersionStatus;
-} | {
-    readonly type: "max_version_exceeded";
-    readonly max: number;
-};
-interface CloneVersionOptions {
-    readonly maxVersions?: number;
-}
-interface PublishDraftOptions {
-    readonly expectedRevision?: number;
-    readonly validate?: (schema: FormSchema) => boolean;
-    /** Supplies deterministic record timestamps while keeping the transition pure. */
-    readonly timestamp?: string;
-}
-declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: FormSchema, options?: CloneVersionOptions): Result<{
-    readonly nextState: FormVersionState;
-    readonly draftSchema: FormSchema;
-}, VersionTransitionError>;
-declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Result<{
-    readonly nextState: FormVersionState;
-    readonly publishedRecord: FormVersionRecord;
-    readonly archivedVersion?: number;
-}, VersionTransitionError>;
-declare function deleteDraft(state: FormVersionState): Result<{
-    readonly nextState: FormVersionState;
-}, VersionTransitionError>;
-declare function assertVersionMutable(status: FormVersionStatus): void;
-
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorResponse, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnDef, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, normalizeSubmissionPageSize, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -1,3 +1,90 @@
+type Result<T, E> = {
+    readonly success: true;
+    readonly value: T;
+} | {
+    readonly success: false;
+    readonly error: E;
+};
+type FormVersionStatus = "draft" | "published" | "archived";
+interface FormVersionRecord extends ExtensibleNode {
+    readonly formId: string;
+    readonly version: number;
+    readonly status: FormVersionStatus;
+    readonly schema: FormSchema;
+    readonly revision: number;
+    readonly createdFromVersion?: number;
+    readonly createdAt: string;
+    readonly publishedAt?: string;
+    readonly archivedAt?: string;
+}
+interface FormVersionState {
+    readonly formId: string;
+    readonly draftVersion?: number;
+    readonly publishedVersion?: number;
+    readonly nextVersion: number;
+    readonly revision: number;
+}
+type VersionTransitionError = {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "draft_not_found";
+} | {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+} | {
+    readonly type: "invalid_source_version";
+    readonly requestedVersion: number;
+    readonly publishedVersion?: number;
+} | {
+    readonly type: "version_immutable";
+    readonly status: FormVersionStatus;
+} | {
+    readonly type: "max_version_exceeded";
+    readonly max: number;
+} | {
+    readonly type: "validation_failed";
+    readonly issues: readonly SchemaIssue[];
+};
+interface CloneVersionOptions {
+    readonly maxVersions?: number;
+    readonly expectedRevision?: number;
+    /** Additional known published versions that may be used as a clone source. */
+    readonly allowedSourceVersions?: readonly number[];
+}
+interface PublishDraftOptions {
+    readonly expectedRevision?: number;
+    readonly currentPublishedRecord?: FormVersionRecord;
+    readonly validate?: (schema: FormSchema) => boolean | Promise<boolean> | readonly SchemaIssue[] | Promise<readonly SchemaIssue[]>;
+    readonly publishedAt?: string;
+    /** @deprecated Use publishedAt. */
+    readonly timestamp?: string;
+}
+interface DeleteDraftOptions {
+    readonly expectedRevision?: number;
+}
+interface PublishDraftResult {
+    readonly nextState: FormVersionState;
+    readonly publishedRecord: FormVersionRecord;
+    readonly archivedRecords: readonly FormVersionRecord[];
+    /** @deprecated Read archivedRecords instead. */
+    readonly archivedVersion?: number;
+}
+declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: FormSchema, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly draftSchema: FormSchema;
+}, VersionTransitionError>;
+declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Promise<Result<PublishDraftResult, VersionTransitionError>>;
+declare function createPublishTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: PublishDraftOptions): Promise<Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>>;
+declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+}, VersionTransitionError>;
+declare function assertVersionMutable(status: FormVersionStatus): void;
+
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
 interface FormPolicy {
     readonly allowedFieldTypes?: readonly FieldType[];
@@ -170,6 +257,8 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
+    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
@@ -179,6 +268,22 @@ interface SubmissionPage {
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
 }
+interface VersionTransitionPlan {
+    readonly formId: string;
+    readonly expectedRevision: number;
+    readonly nextRevision: number;
+    readonly draftToCreate?: FormVersionRecord;
+    readonly draftToDeleteVersion?: number;
+    readonly publishedRecordToSave?: FormVersionRecord;
+    readonly archivedRecordsToSave?: readonly FormVersionRecord[];
+    readonly timestamp: string;
+}
+interface VersionedFormStorageAdapter extends FormStorageAdapter {
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
+}
 interface BaseQuestionAggregate {
     readonly fieldId: string;
     readonly answeredCount: number;
@@ -223,6 +328,7 @@ type ChoiceOption = FieldOption;
 interface FormResponse extends ExtensibleNode {
     readonly responseId: string;
     readonly formId: string;
+    readonly formVersion?: number;
     readonly sourceLocale?: string;
     readonly answers: Readonly<Record<string, unknown>>;
     readonly submittedAt: string;
@@ -251,14 +357,25 @@ declare function calculateNumericSummary(responses: readonly FormSubmission[], q
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
 type AccumulatorResponse = FormSubmission | FormResponse;
+type AccumulatorSkipReason = "form_id_mismatch" | "version_mismatch" | "invalid_structure";
+interface AccumulatorReport {
+    readonly processedCount: number;
+    readonly skippedCount: number;
+    readonly skipReasons: readonly {
+        readonly responseId: string;
+        readonly reason: AccumulatorSkipReason;
+    }[];
+}
 interface ResponseAccumulator {
     add(submission: AccumulatorResponse): {
         readonly success: boolean;
+        readonly skipped?: boolean;
         readonly error?: string;
     };
-    addMany(submissions: Iterable<AccumulatorResponse>): void;
+    addMany(submissions: Iterable<AccumulatorResponse>): AccumulatorReport;
     merge(other: ResponseAccumulator): ResponseAccumulator;
     finalize(): FormAnalytics;
+    getReport(): AccumulatorReport;
 }
 interface ResponseAccumulatorOptions {
     readonly mode?: "strict" | "lenient";
@@ -271,13 +388,27 @@ interface CsvExportOptions {
 }
 interface CsvColumnDef {
     readonly header: string;
-    readonly getValue: (submission: FormResponse) => string | number | boolean | null | undefined;
+    readonly getValue: (context: CsvColumnContext) => string | number | boolean | null | undefined | Promise<string | number | boolean | null | undefined>;
+}
+interface CsvColumnContext extends FormResponse {
+    readonly submission: FormResponse;
+    readonly formVersion: number;
+    readonly schema: FormSchema;
 }
 interface StreamCsvOptions extends CsvExportOptions {
     readonly columns?: readonly CsvColumnDef[];
     readonly includeDefaultColumns?: boolean;
 }
 declare function exportResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, options?: StreamCsvOptions): AsyncIterable<string>;
+interface NodeWritableStream {
+    write(chunk: Uint8Array): boolean;
+    once(event: "drain", listener: () => void): unknown;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    removeListener(event: "drain", listener: () => void): unknown;
+    removeListener(event: "error", listener: (error: Error) => void): unknown;
+    end(callback: () => void): unknown;
+}
+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;
 
 type FormEventType = "response.submitted" | "schema.updated";
@@ -314,6 +445,7 @@ interface SubmissionCursorValue {
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
     readonly defaultLocale?: string;
@@ -382,73 +514,10 @@ declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTransl
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
 declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
 
-type Result<T, E> = {
-    readonly success: true;
-    readonly value: T;
-} | {
-    readonly success: false;
-    readonly error: E;
-};
-type FormVersionStatus = "draft" | "published" | "archived";
-interface FormVersionRecord {
-    readonly formId: string;
-    readonly version: number;
-    readonly status: FormVersionStatus;
-    readonly schema: FormSchema;
-    readonly createdAt: string;
-    readonly publishedAt?: string;
-    readonly archivedAt?: string;
-}
-interface FormVersionState {
-    readonly formId: string;
-    readonly draftVersion?: number;
-    readonly publishedVersion?: number;
-    readonly nextVersion: number;
-    readonly revision: number;
-}
-type VersionTransitionError = {
-    readonly type: "draft_already_exists";
-    readonly currentDraftVersion: number;
-} | {
-    readonly type: "draft_not_found";
-} | {
-    readonly type: "revision_conflict";
-    readonly expectedRevision: number;
-    readonly actualRevision: number;
-} | {
-    readonly type: "version_immutable";
-    readonly status: FormVersionStatus;
-} | {
-    readonly type: "max_version_exceeded";
-    readonly max: number;
-};
-interface CloneVersionOptions {
-    readonly maxVersions?: number;
-}
-interface PublishDraftOptions {
-    readonly expectedRevision?: number;
-    readonly validate?: (schema: FormSchema) => boolean;
-    /** Supplies deterministic record timestamps while keeping the transition pure. */
-    readonly timestamp?: string;
-}
-declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: FormSchema, options?: CloneVersionOptions): Result<{
-    readonly nextState: FormVersionState;
-    readonly draftSchema: FormSchema;
-}, VersionTransitionError>;
-declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Result<{
-    readonly nextState: FormVersionState;
-    readonly publishedRecord: FormVersionRecord;
-    readonly archivedVersion?: number;
-}, VersionTransitionError>;
-declare function deleteDraft(state: FormVersionState): Result<{
-    readonly nextState: FormVersionState;
-}, VersionTransitionError>;
-declare function assertVersionMutable(status: FormVersionStatus): void;
-
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorResponse, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnDef, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, normalizeSubmissionPageSize, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };