@10x-media/form-builder 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/actions/runActions.js

@@ -0,0 +1,43 @@
+import { makeRenderBody } from "./body/serializeBody.js";
+//#region src/actions/runActions.ts
+/**
+* Run each configured action, isolating failures: a throwing action is captured as a failed result
+* and never breaks the others or the caller.
+*/
+const runActions = async (args) => {
+	const { actions, registry, richText, ...ctx } = args;
+	const renderBody = makeRenderBody({
+		values: ctx.values,
+		descriptors: ctx.descriptors,
+		form: ctx.form,
+		req: ctx.req,
+		richText
+	});
+	const results = [];
+	for (const instance of actions) {
+		const definition = registry.get(instance.blockType);
+		if (!definition) continue;
+		try {
+			await definition.run({
+				...ctx,
+				renderBody,
+				config: instance
+			});
+			results.push({
+				type: instance.blockType,
+				ok: true
+			});
+		} catch (error) {
+			results.push({
+				type: instance.blockType,
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	return results;
+};
+//#endregion
+export { runActions };
+
+//# sourceMappingURL=runActions.js.map

package/dist/actions/runActions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runActions.js","names":[],"sources":["../../src/actions/runActions.ts"],"sourcesContent":["import type { RichTextBodyOption } from './body/serializeBody'\nimport { makeRenderBody } from './body/serializeBody'\nimport type { ActionRunArgs } from './defineAction'\nimport type { ActionRegistry } from './registry'\n\n/** A stored action instance from the form's `actions` blocks array. */\nexport type ActionInstance = { blockType: string; [key: string]: unknown }\n\nexport type ActionResult = { type: string; ok: boolean; error?: string }\n\nexport type RunActionsArgs = Omit<ActionRunArgs, 'config' | 'renderBody'> & {\n\tactions: ActionInstance[]\n\tregistry: ActionRegistry\n\trichText?: RichTextBodyOption\n}\n\n/**\n * Run each configured action, isolating failures: a throwing action is captured as a failed result\n * and never breaks the others or the caller.\n */\nexport const runActions = async (args: RunActionsArgs): Promise<ActionResult[]> => {\n\tconst { actions, registry, richText, ...ctx } = args\n\tconst renderBody = makeRenderBody({\n\t\tvalues: ctx.values,\n\t\tdescriptors: ctx.descriptors,\n\t\tform: ctx.form,\n\t\treq: ctx.req,\n\t\trichText,\n\t})\n\tconst results: ActionResult[] = []\n\tfor (const instance of actions) {\n\t\tconst definition = registry.get(instance.blockType)\n\t\tif (!definition) {\n\t\t\tcontinue\n\t\t}\n\t\ttry {\n\t\t\tawait definition.run({ ...ctx, renderBody, config: instance })\n\t\t\tresults.push({ type: instance.blockType, ok: true })\n\t\t} catch (error) {\n\t\t\tresults.push({\n\t\t\t\ttype: instance.blockType,\n\t\t\t\tok: false,\n\t\t\t\terror: error instanceof Error ? error.message : String(error),\n\t\t\t})\n\t\t}\n\t}\n\treturn results\n}\n"],"mappings":";;;;;;AAoBA,MAAa,aAAa,OAAO,SAAkD;CAClF,MAAM,EAAE,SAAS,UAAU,UAAU,GAAG,QAAQ;CAChD,MAAM,aAAa,eAAe;EACjC,QAAQ,IAAI;EACZ,aAAa,IAAI;EACjB,MAAM,IAAI;EACV,KAAK,IAAI;EACT;CACD,CAAC;CACD,MAAM,UAA0B,CAAC;CACjC,KAAK,MAAM,YAAY,SAAS;EAC/B,MAAM,aAAa,SAAS,IAAI,SAAS,SAAS;EAClD,IAAI,CAAC,YACJ;EAED,IAAI;GACH,MAAM,WAAW,IAAI;IAAE,GAAG;IAAK;IAAY,QAAQ;GAAS,CAAC;GAC7D,QAAQ,KAAK;IAAE,MAAM,SAAS;IAAW,IAAI;GAAK,CAAC;EACpD,SAAS,OAAO;GACf,QAAQ,KAAK;IACZ,MAAM,SAAS;IACf,IAAI;IACJ,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAC7D,CAAC;EACF;CACD;CACA,OAAO;AACR"}

package/dist/actions/sign.d.ts

@@ -0,0 +1,7 @@
+//#region src/actions/sign.d.ts
+declare const SIGNATURE_HEADER = "X-Form-Signature";
+/** HMAC-SHA256 over `body`, hex-encoded, wrapped in the versioned header value (`v1=<hex>`). */
+declare const signPayload: (body: string, secret: string) => string;
+//#endregion
+export { SIGNATURE_HEADER, signPayload };
+//# sourceMappingURL=sign.d.ts.map

package/dist/actions/sign.js

@@ -0,0 +1,9 @@
+import { createHmac } from "node:crypto";
+//#region src/actions/sign.ts
+const SIGNATURE_HEADER = "X-Form-Signature";
+/** HMAC-SHA256 over `body`, hex-encoded, wrapped in the versioned header value (`v1=<hex>`). */
+const signPayload = (body, secret) => `v1=${createHmac("sha256", secret).update(body).digest("hex")}`;
+//#endregion
+export { SIGNATURE_HEADER, signPayload };
+
+//# sourceMappingURL=sign.js.map

package/dist/actions/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","names":[],"sources":["../../src/actions/sign.ts"],"sourcesContent":["import { createHmac } from 'node:crypto'\n\n// Distinct from @10x-media/webhooks' `X-Webhook-Signature` (which signs `timestamp.body`): this action signs the body alone, so a separate header prevents a consumer mistaking the two verification schemes.\nexport const SIGNATURE_HEADER = 'X-Form-Signature'\n\n/** HMAC-SHA256 over `body`, hex-encoded, wrapped in the versioned header value (`v1=<hex>`). */\nexport const signPayload = (body: string, secret: string): string =>\n\t`v1=${createHmac('sha256', secret).update(body).digest('hex')}`\n"],"mappings":";;AAGA,MAAa,mBAAmB;;AAGhC,MAAa,eAAe,MAAc,WACzC,MAAM,WAAW,UAAU,MAAM,EAAE,OAAO,IAAI,EAAE,OAAO,KAAK"}

package/dist/actions/task.js

@@ -0,0 +1,87 @@
+import { asFieldTranslate } from "../translations/server.js";
+import { FORMS_SLUG } from "../collections/forms.js";
+import { FORM_SUBMISSIONS_SLUG } from "../collections/formSubmissions.js";
+import { runActions } from "./runActions.js";
+//#region src/actions/task.ts
+const ACTIONS_TASK_SLUG = "form-builder-actions";
+const asActions = (value) => Array.isArray(value) ? value : [];
+const asValues = (value) => Array.isArray(value) ? value : [];
+const asDescriptors = (value) => Array.isArray(value) ? value : [];
+/**
+* Load the form and submission by id and run the form's actions through the shared, failure-isolating
+* `runActions`. Tolerates a missing form or submission (the row may have been deleted between enqueue and
+* run) by returning early. Used by both the queued task handler and the inline fallback.
+*/
+const runActionsForSubmission = async (args) => {
+	const { input, registry, payload, req, richText } = args;
+	const submission = await payload.findByID({
+		collection: FORM_SUBMISSIONS_SLUG,
+		id: input.submissionId,
+		depth: 0,
+		overrideAccess: true,
+		req
+	}).catch(() => null);
+	if (!submission) return [];
+	const locale = typeof submission.locale === "string" ? submission.locale : req?.locale ?? "en";
+	const form = await payload.findByID({
+		collection: FORMS_SLUG,
+		id: input.formId,
+		depth: 0,
+		overrideAccess: true,
+		locale,
+		req
+	}).catch(() => null);
+	if (!form) return [];
+	const t = asFieldTranslate(req?.i18n?.t ?? ((key) => key));
+	const results = await runActions({
+		actions: asActions(form.actions),
+		registry,
+		richText,
+		form: {
+			id: form.id,
+			title: typeof form.title === "string" ? form.title : void 0
+		},
+		submissionId: submission.id,
+		values: asValues(submission.values),
+		descriptors: asDescriptors(submission.descriptors),
+		payload,
+		req,
+		locale,
+		t
+	});
+	for (const result of results) if (!result.ok) payload.logger?.error(`@10x-media/form-builder: action "${result.type}" failed for submission ${String(submission.id)}: ${result.error ?? "unknown error"}`);
+	return results;
+};
+/** Native Payload jobs task that runs a submission's post-submit actions out of band. */
+const buildActionsTask = (registry, richText) => ({
+	slug: ACTIONS_TASK_SLUG,
+	inputSchema: [{
+		name: "formId",
+		type: "text",
+		required: true
+	}, {
+		name: "submissionId",
+		type: "text",
+		required: true
+	}],
+	handler: async ({ input, req }) => {
+		await runActionsForSubmission({
+			input,
+			registry,
+			payload: req.payload,
+			req,
+			richText
+		});
+		return { output: {} };
+	}
+});
+/** Register the actions task on `config.jobs.tasks`, creating the jobs config if absent. */
+const registerActionsTask = (config, registry, richText) => {
+	config.jobs ??= {};
+	config.jobs.tasks ??= [];
+	config.jobs.tasks.push(buildActionsTask(registry, richText));
+};
+//#endregion
+export { ACTIONS_TASK_SLUG, registerActionsTask, runActionsForSubmission };
+
+//# sourceMappingURL=task.js.map

package/dist/actions/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","names":[],"sources":["../../src/actions/task.ts"],"sourcesContent":["import type { Config, Payload, PayloadRequest, TaskConfig, TypedLocale } from 'payload'\nimport { FORM_SUBMISSIONS_SLUG } from '../collections/formSubmissions'\nimport { FORMS_SLUG } from '../collections/forms'\nimport type { Translate } from '../fields/types'\nimport type { SubmissionDescriptor, SubmissionValue } from '../submissions/types'\nimport { asFieldTranslate } from '../translations/server'\nimport type { RichTextBodyOption } from './body/serializeBody'\nimport type { ActionRegistry } from './registry'\nimport type { ActionInstance, ActionResult } from './runActions'\nimport { runActions } from './runActions'\n\nexport const ACTIONS_TASK_SLUG = 'form-builder-actions'\n\n/** Input the dispatch path enqueues; the handler re-loads everything else from the DB. */\nexport type ActionsTaskInput = { formId: number | string; submissionId: number | string }\n\nconst asActions = (value: unknown): ActionInstance[] =>\n\tArray.isArray(value) ? (value as ActionInstance[]) : []\n\nconst asValues = (value: unknown): SubmissionValue[] =>\n\tArray.isArray(value) ? (value as SubmissionValue[]) : []\n\nconst asDescriptors = (value: unknown): SubmissionDescriptor[] =>\n\tArray.isArray(value) ? (value as SubmissionDescriptor[]) : []\n\n/**\n * Load the form and submission by id and run the form's actions through the shared, failure-isolating\n * `runActions`. Tolerates a missing form or submission (the row may have been deleted between enqueue and\n * run) by returning early. Used by both the queued task handler and the inline fallback.\n */\nexport const runActionsForSubmission = async (args: {\n\tinput: ActionsTaskInput\n\tregistry: ActionRegistry\n\tpayload: Payload\n\treq?: PayloadRequest\n\trichText?: RichTextBodyOption\n}): Promise<ActionResult[]> => {\n\tconst { input, registry, payload, req, richText } = args\n\tconst submission = await payload\n\t\t.findByID({\n\t\t\tcollection: FORM_SUBMISSIONS_SLUG,\n\t\t\tid: input.submissionId,\n\t\t\tdepth: 0,\n\t\t\toverrideAccess: true,\n\t\t\treq,\n\t\t})\n\t\t.catch(() => null)\n\tif (!submission) {\n\t\treturn []\n\t}\n\n\t// The submission's own stored locale (set from req.locale at submit) is authoritative, so the form\n\t// is loaded at it. A localized action config, notably the emailTeam `to`, then resolves to the\n\t// submission's locale even on the queued path, where the job runner's req may carry a different\n\t// (or no) locale than the visitor who submitted.\n\tconst locale = typeof submission.locale === 'string' ? submission.locale : (req?.locale ?? 'en')\n\n\tconst form = await payload\n\t\t.findByID({\n\t\t\tcollection: FORMS_SLUG,\n\t\t\tid: input.formId,\n\t\t\tdepth: 0,\n\t\t\toverrideAccess: true,\n\t\t\t// Cast: the stored locale is a plain string; a host's concrete locale union is unknowable from\n\t\t\t// the plugin, and an unrecognized code just falls back on read, so this narrows (zero runtime\n\t\t\t// delta) to satisfy a host whose `findByID` locale is a real union.\n\t\t\tlocale: locale as TypedLocale,\n\t\t\treq,\n\t\t})\n\t\t.catch(() => null)\n\tif (!form) {\n\t\treturn []\n\t}\n\n\tconst t: Translate = asFieldTranslate(req?.i18n?.t ?? ((key: string) => key))\n\n\tconst results = await runActions({\n\t\tactions: asActions(form.actions),\n\t\tregistry,\n\t\trichText,\n\t\tform: { id: form.id, title: typeof form.title === 'string' ? form.title : undefined },\n\t\tsubmissionId: submission.id,\n\t\tvalues: asValues(submission.values),\n\t\tdescriptors: asDescriptors(submission.descriptors),\n\t\tpayload,\n\t\treq,\n\t\tlocale,\n\t\tt,\n\t})\n\t// A failed action (SMTP down, webhook non-2xx, missing adapter) is isolated per action; surface it\n\t// so a silently undelivered email/webhook is visible instead of the submission looking successful.\n\tfor (const result of results) {\n\t\tif (!result.ok) {\n\t\t\tpayload.logger?.error(\n\t\t\t\t`@10x-media/form-builder: action \"${result.type}\" failed for submission ${String(submission.id)}: ${result.error ?? 'unknown error'}`\n\t\t\t)\n\t\t}\n\t}\n\treturn results\n}\n\n/** Native Payload jobs task that runs a submission's post-submit actions out of band. */\nexport const buildActionsTask = (\n\tregistry: ActionRegistry,\n\trichText?: RichTextBodyOption\n): TaskConfig =>\n\t({\n\t\tslug: ACTIONS_TASK_SLUG,\n\t\tinputSchema: [\n\t\t\t{ name: 'formId', type: 'text', required: true },\n\t\t\t{ name: 'submissionId', type: 'text', required: true },\n\t\t],\n\t\thandler: async ({ input, req }) => {\n\t\t\tawait runActionsForSubmission({\n\t\t\t\tinput: input as ActionsTaskInput,\n\t\t\t\tregistry,\n\t\t\t\tpayload: req.payload,\n\t\t\t\treq,\n\t\t\t\trichText,\n\t\t\t})\n\t\t\treturn { output: {} }\n\t\t},\n\t}) as TaskConfig\n\n/** Register the actions task on `config.jobs.tasks`, creating the jobs config if absent. */\nexport const registerActionsTask = (\n\tconfig: Config,\n\tregistry: ActionRegistry,\n\trichText?: RichTextBodyOption\n): void => {\n\tconfig.jobs ??= {}\n\tconfig.jobs.tasks ??= []\n\tconfig.jobs.tasks.push(buildActionsTask(registry, richText))\n}\n"],"mappings":";;;;;AAWA,MAAa,oBAAoB;AAKjC,MAAM,aAAa,UAClB,MAAM,QAAQ,KAAK,IAAK,QAA6B,CAAC;AAEvD,MAAM,YAAY,UACjB,MAAM,QAAQ,KAAK,IAAK,QAA8B,CAAC;AAExD,MAAM,iBAAiB,UACtB,MAAM,QAAQ,KAAK,IAAK,QAAmC,CAAC;;;;;;AAO7D,MAAa,0BAA0B,OAAO,SAMf;CAC9B,MAAM,EAAE,OAAO,UAAU,SAAS,KAAK,aAAa;CACpD,MAAM,aAAa,MAAM,QACvB,SAAS;EACT,YAAY;EACZ,IAAI,MAAM;EACV,OAAO;EACP,gBAAgB;EAChB;CACD,CAAC,EACA,YAAY,IAAI;CAClB,IAAI,CAAC,YACJ,OAAO,CAAC;CAOT,MAAM,SAAS,OAAO,WAAW,WAAW,WAAW,WAAW,SAAU,KAAK,UAAU;CAE3F,MAAM,OAAO,MAAM,QACjB,SAAS;EACT,YAAY;EACZ,IAAI,MAAM;EACV,OAAO;EACP,gBAAgB;EAIR;EACR;CACD,CAAC,EACA,YAAY,IAAI;CAClB,IAAI,CAAC,MACJ,OAAO,CAAC;CAGT,MAAM,IAAe,iBAAiB,KAAK,MAAM,OAAO,QAAgB,IAAI;CAE5E,MAAM,UAAU,MAAM,WAAW;EAChC,SAAS,UAAU,KAAK,OAAO;EAC/B;EACA;EACA,MAAM;GAAE,IAAI,KAAK;GAAI,OAAO,OAAO,KAAK,UAAU,WAAW,KAAK,QAAQ,KAAA;EAAU;EACpF,cAAc,WAAW;EACzB,QAAQ,SAAS,WAAW,MAAM;EAClC,aAAa,cAAc,WAAW,WAAW;EACjD;EACA;EACA;EACA;CACD,CAAC;CAGD,KAAK,MAAM,UAAU,SACpB,IAAI,CAAC,OAAO,IACX,QAAQ,QAAQ,MACf,oCAAoC,OAAO,KAAK,0BAA0B,OAAO,WAAW,EAAE,EAAE,IAAI,OAAO,SAAS,iBACrH;CAGF,OAAO;AACR;;AAGA,MAAa,oBACZ,UACA,cAEC;CACA,MAAM;CACN,aAAa,CACZ;EAAE,MAAM;EAAU,MAAM;EAAQ,UAAU;CAAK,GAC/C;EAAE,MAAM;EAAgB,MAAM;EAAQ,UAAU;CAAK,CACtD;CACA,SAAS,OAAO,EAAE,OAAO,UAAU;EAClC,MAAM,wBAAwB;GACtB;GACP;GACA,SAAS,IAAI;GACb;GACA;EACD,CAAC;EACD,OAAO,EAAE,QAAQ,CAAC,EAAE;CACrB;AACD;;AAGD,MAAa,uBACZ,QACA,UACA,aACU;CACV,OAAO,SAAS,CAAC;CACjB,OAAO,KAAK,UAAU,CAAC;CACvB,OAAO,KAAK,MAAM,KAAK,iBAAiB,UAAU,QAAQ,CAAC;AAC5D"}

package/dist/aggregation/aggregateResponses.d.ts

@@ -0,0 +1,40 @@
+import { FormFieldInstance } from "../submissions/types.js";
+import { FieldAggregation, SubmissionStatusFilter } from "./types.js";
+import { Payload, PayloadRequest } from "payload";
+
+//#region src/aggregation/aggregateResponses.d.ts
+type AggregateFormResponsesArgs = {
+  payload: Payload;
+  formId: number | string; /** Field machine names to aggregate. Defaults to every field that declares options (enumerable). */
+  fields?: string[]; /** Submission status to count. Defaults to `complete`. */
+  status?: SubmissionStatusFilter;
+  req?: PayloadRequest; /** Safety cap on submissions scanned; beyond it the result is flagged `truncated`. Default 10000. */
+  maxSubmissions?: number; /** Page size for the submission scan. Default 500. */
+  pageSize?: number;
+  /**
+   * Source-resolved options by field name (an option-source poll's results field). They replace
+   * the instance's authored options for bucket seeding, order, and labels, and mark the field
+   * enumerable for the default field selection.
+   */
+  resolvedOptions?: Record<string, {
+    value: string;
+    label: string;
+  }[]>;
+};
+/** True when a field declares non-empty options (a choice field safe to aggregate publicly). */
+declare const fieldHasOptions: (field: FormFieldInstance) => boolean;
+/**
+ * Aggregate submission responses for a form. Loads the form for current labels + option order, then pages
+ * `payload.find` over its submissions (JSON `values` cannot be GROUP BY'd portably across Mongo + Postgres,
+ * so we scan + reduce in JS, cross-DB-identically). Bounded by `maxSubmissions`; beyond it the result is
+ * `truncated`. Returns one `FieldAggregation` per requested field (or per enumerable field by default).
+ */
+declare const aggregateFormResponses: (args: AggregateFormResponsesArgs) => Promise<FieldAggregation[]>;
+type AggregateFieldResponsesArgs = Omit<AggregateFormResponsesArgs, 'fields'> & {
+  field: string;
+};
+/** Single-field convenience over `aggregateFormResponses`. Returns the field's aggregation, or null if absent. */
+declare const aggregateFieldResponses: (args: AggregateFieldResponsesArgs) => Promise<FieldAggregation | null>;
+//#endregion
+export { AggregateFieldResponsesArgs, AggregateFormResponsesArgs, aggregateFieldResponses, aggregateFormResponses, fieldHasOptions };
+//# sourceMappingURL=aggregateResponses.d.ts.map

package/dist/aggregation/aggregateResponses.js

@@ -0,0 +1,80 @@
+import { isNamedField } from "../fields/fieldKey.js";
+import { instanceOptionsOf } from "../fields/instanceOptions.js";
+import { aggregateRowsForFields } from "./aggregateRows.js";
+import { FORMS_SLUG } from "../collections/forms.js";
+import { FORM_SUBMISSIONS_SLUG } from "../collections/formSubmissions.js";
+//#region src/aggregation/aggregateResponses.ts
+/** True when a field declares non-empty options (a choice field safe to aggregate publicly). */
+const fieldHasOptions = (field) => instanceOptionsOf(field) !== void 0;
+const metaFor = (field, resolved) => ({
+	field: field.name,
+	label: field.label ?? field.name,
+	fieldType: field.blockType,
+	options: resolved && resolved.length > 0 ? resolved : instanceOptionsOf(field)
+});
+/**
+* Aggregate submission responses for a form. Loads the form for current labels + option order, then pages
+* `payload.find` over its submissions (JSON `values` cannot be GROUP BY'd portably across Mongo + Postgres,
+* so we scan + reduce in JS, cross-DB-identically). Bounded by `maxSubmissions`; beyond it the result is
+* `truncated`. Returns one `FieldAggregation` per requested field (or per enumerable field by default).
+*/
+const aggregateFormResponses = async (args) => {
+	const { payload, formId, fields, status = "complete", req, maxSubmissions = 1e4, pageSize = 500, resolvedOptions } = args;
+	const form = await payload.findByID({
+		collection: FORMS_SLUG,
+		id: formId,
+		depth: 0,
+		overrideAccess: true,
+		req
+	}).catch(() => null);
+	if (!form || !Array.isArray(form.fields)) return [];
+	const instances = form.fields;
+	const selected = fields ? instances.filter((field) => isNamedField(field) && fields.includes(field.name)) : instances.filter((field) => isNamedField(field) && (instanceOptionsOf(field) !== void 0 || (resolvedOptions?.[field.name]?.length ?? 0) > 0));
+	if (selected.length === 0) return [];
+	const metas = selected.map((field) => metaFor(field, resolvedOptions?.[field.name]));
+	const where = { and: [{ form: { equals: formId } }, ...status === "all" ? [] : [{ status: { equals: status } }]] };
+	const rows = [];
+	let page = 1;
+	let truncated = false;
+	for (;;) {
+		const result = await payload.find({
+			collection: FORM_SUBMISSIONS_SLUG,
+			where,
+			limit: pageSize,
+			page,
+			depth: 0,
+			overrideAccess: true,
+			req,
+			select: {
+				values: true,
+				descriptors: true
+			}
+		});
+		for (const doc of result.docs) {
+			if (rows.length >= maxSubmissions) {
+				truncated = true;
+				break;
+			}
+			rows.push({
+				values: doc.values,
+				descriptors: doc.descriptors
+			});
+		}
+		if (truncated || !result.hasNextPage) break;
+		page += 1;
+	}
+	return aggregateRowsForFields(rows, metas, truncated);
+};
+/** Single-field convenience over `aggregateFormResponses`. Returns the field's aggregation, or null if absent. */
+const aggregateFieldResponses = async (args) => {
+	const { field, ...rest } = args;
+	const [result] = await aggregateFormResponses({
+		...rest,
+		fields: [field]
+	});
+	return result ?? null;
+};
+//#endregion
+export { aggregateFieldResponses, aggregateFormResponses, fieldHasOptions };
+
+//# sourceMappingURL=aggregateResponses.js.map

package/dist/aggregation/aggregateResponses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregateResponses.js","names":[],"sources":["../../src/aggregation/aggregateResponses.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { FORM_SUBMISSIONS_SLUG } from '../collections/formSubmissions'\nimport { FORMS_SLUG } from '../collections/forms'\nimport { isNamedField, type NamedFormFieldInstance } from '../fields/fieldKey'\nimport { instanceOptionsOf } from '../fields/instanceOptions'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { aggregateRowsForFields } from './aggregateRows'\nimport type { AggregationRow, FieldAggregation, FieldMeta, SubmissionStatusFilter } from './types'\n\nexport type AggregateFormResponsesArgs = {\n\tpayload: Payload\n\tformId: number | string\n\t/** Field machine names to aggregate. Defaults to every field that declares options (enumerable). */\n\tfields?: string[]\n\t/** Submission status to count. Defaults to `complete`. */\n\tstatus?: SubmissionStatusFilter\n\treq?: PayloadRequest\n\t/** Safety cap on submissions scanned; beyond it the result is flagged `truncated`. Default 10000. */\n\tmaxSubmissions?: number\n\t/** Page size for the submission scan. Default 500. */\n\tpageSize?: number\n\t/**\n\t * Source-resolved options by field name (an option-source poll's results field). They replace\n\t * the instance's authored options for bucket seeding, order, and labels, and mark the field\n\t * enumerable for the default field selection.\n\t */\n\tresolvedOptions?: Record<string, { value: string; label: string }[]>\n}\n\n/** True when a field declares non-empty options (a choice field safe to aggregate publicly). */\nexport const fieldHasOptions = (field: FormFieldInstance): boolean =>\n\tinstanceOptionsOf(field) !== undefined\n\nconst metaFor = (\n\tfield: NamedFormFieldInstance,\n\tresolved?: { value: string; label: string }[]\n): FieldMeta => ({\n\tfield: field.name,\n\tlabel: field.label ?? field.name,\n\tfieldType: field.blockType,\n\toptions: resolved && resolved.length > 0 ? resolved : instanceOptionsOf(field),\n})\n\n/**\n * Aggregate submission responses for a form. Loads the form for current labels + option order, then pages\n * `payload.find` over its submissions (JSON `values` cannot be GROUP BY'd portably across Mongo + Postgres,\n * so we scan + reduce in JS, cross-DB-identically). Bounded by `maxSubmissions`; beyond it the result is\n * `truncated`. Returns one `FieldAggregation` per requested field (or per enumerable field by default).\n */\nexport const aggregateFormResponses = async (\n\targs: AggregateFormResponsesArgs\n): Promise<FieldAggregation[]> => {\n\tconst {\n\t\tpayload,\n\t\tformId,\n\t\tfields,\n\t\tstatus = 'complete',\n\t\treq,\n\t\tmaxSubmissions = 10000,\n\t\tpageSize = 500,\n\t\tresolvedOptions,\n\t} = args\n\tconst form = await payload\n\t\t.findByID({ collection: FORMS_SLUG, id: formId, depth: 0, overrideAccess: true, req })\n\t\t.catch(() => null)\n\tif (!form || !Array.isArray(form.fields)) {\n\t\treturn []\n\t}\n\tconst instances = form.fields as FormFieldInstance[]\n\tconst selected = fields\n\t\t? instances.filter(\n\t\t\t\t(field): field is NamedFormFieldInstance =>\n\t\t\t\t\tisNamedField(field) && fields.includes(field.name)\n\t\t\t)\n\t\t: instances.filter(\n\t\t\t\t(field): field is NamedFormFieldInstance =>\n\t\t\t\t\tisNamedField(field) &&\n\t\t\t\t\t(instanceOptionsOf(field) !== undefined ||\n\t\t\t\t\t\t(resolvedOptions?.[field.name]?.length ?? 0) > 0)\n\t\t\t)\n\tif (selected.length === 0) {\n\t\treturn []\n\t}\n\tconst metas = selected.map((field) => metaFor(field, resolvedOptions?.[field.name]))\n\n\tconst statusWhere = status === 'all' ? [] : [{ status: { equals: status } }]\n\tconst where = { and: [{ form: { equals: formId } }, ...statusWhere] }\n\n\tconst rows: AggregationRow[] = []\n\tlet page = 1\n\tlet truncated = false\n\tfor (;;) {\n\t\tconst result = await payload.find({\n\t\t\tcollection: FORM_SUBMISSIONS_SLUG,\n\t\t\twhere,\n\t\t\tlimit: pageSize,\n\t\t\tpage,\n\t\t\tdepth: 0,\n\t\t\toverrideAccess: true,\n\t\t\treq,\n\t\t\tselect: { values: true, descriptors: true },\n\t\t})\n\t\tfor (const doc of result.docs as AggregationRow[]) {\n\t\t\t// Check before pushing so `truncated` means \"matching rows were left out\", not \"the cap was reached\n\t\t\t// exactly\": a form with precisely `maxSubmissions` responses is complete, not a sample.\n\t\t\tif (rows.length >= maxSubmissions) {\n\t\t\t\ttruncated = true\n\t\t\t\tbreak\n\t\t\t}\n\t\t\trows.push({ values: doc.values, descriptors: doc.descriptors })\n\t\t}\n\t\tif (truncated || !result.hasNextPage) {\n\t\t\tbreak\n\t\t}\n\t\tpage += 1\n\t}\n\n\treturn aggregateRowsForFields(rows, metas, truncated)\n}\n\nexport type AggregateFieldResponsesArgs = Omit<AggregateFormResponsesArgs, 'fields'> & {\n\tfield: string\n}\n\n/** Single-field convenience over `aggregateFormResponses`. Returns the field's aggregation, or null if absent. */\nexport const aggregateFieldResponses = async (\n\targs: AggregateFieldResponsesArgs\n): Promise<FieldAggregation | null> => {\n\tconst { field, ...rest } = args\n\tconst [result] = await aggregateFormResponses({ ...rest, fields: [field] })\n\treturn result ?? null\n}\n"],"mappings":";;;;;;;AA8BA,MAAa,mBAAmB,UAC/B,kBAAkB,KAAK,MAAM,KAAA;AAE9B,MAAM,WACL,OACA,cACgB;CAChB,OAAO,MAAM;CACb,OAAO,MAAM,SAAS,MAAM;CAC5B,WAAW,MAAM;CACjB,SAAS,YAAY,SAAS,SAAS,IAAI,WAAW,kBAAkB,KAAK;AAC9E;;;;;;;AAQA,MAAa,yBAAyB,OACrC,SACiC;CACjC,MAAM,EACL,SACA,QACA,QACA,SAAS,YACT,KACA,iBAAiB,KACjB,WAAW,KACX,oBACG;CACJ,MAAM,OAAO,MAAM,QACjB,SAAS;EAAE,YAAY;EAAY,IAAI;EAAQ,OAAO;EAAG,gBAAgB;EAAM;CAAI,CAAC,EACpF,YAAY,IAAI;CAClB,IAAI,CAAC,QAAQ,CAAC,MAAM,QAAQ,KAAK,MAAM,GACtC,OAAO,CAAC;CAET,MAAM,YAAY,KAAK;CACvB,MAAM,WAAW,SACd,UAAU,QACT,UACA,aAAa,KAAK,KAAK,OAAO,SAAS,MAAM,IAAI,CACnD,IACC,UAAU,QACT,UACA,aAAa,KAAK,MACjB,kBAAkB,KAAK,MAAM,KAAA,MAC5B,kBAAkB,MAAM,OAAO,UAAU,KAAK,EAClD;CACF,IAAI,SAAS,WAAW,GACvB,OAAO,CAAC;CAET,MAAM,QAAQ,SAAS,KAAK,UAAU,QAAQ,OAAO,kBAAkB,MAAM,KAAK,CAAC;CAGnF,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,OAAO,EAAE,GAAG,GADhC,WAAW,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,OAAO,EAAE,CAAC,CACT,EAAE;CAEpE,MAAM,OAAyB,CAAC;CAChC,IAAI,OAAO;CACX,IAAI,YAAY;CAChB,SAAS;EACR,MAAM,SAAS,MAAM,QAAQ,KAAK;GACjC,YAAY;GACZ;GACA,OAAO;GACP;GACA,OAAO;GACP,gBAAgB;GAChB;GACA,QAAQ;IAAE,QAAQ;IAAM,aAAa;GAAK;EAC3C,CAAC;EACD,KAAK,MAAM,OAAO,OAAO,MAA0B;GAGlD,IAAI,KAAK,UAAU,gBAAgB;IAClC,YAAY;IACZ;GACD;GACA,KAAK,KAAK;IAAE,QAAQ,IAAI;IAAQ,aAAa,IAAI;GAAY,CAAC;EAC/D;EACA,IAAI,aAAa,CAAC,OAAO,aACxB;EAED,QAAQ;CACT;CAEA,OAAO,uBAAuB,MAAM,OAAO,SAAS;AACrD;;AAOA,MAAa,0BAA0B,OACtC,SACsC;CACtC,MAAM,EAAE,OAAO,GAAG,SAAS;CAC3B,MAAM,CAAC,UAAU,MAAM,uBAAuB;EAAE,GAAG;EAAM,QAAQ,CAAC,KAAK;CAAE,CAAC;CAC1E,OAAO,UAAU;AAClB"}

package/dist/aggregation/aggregateRows.d.ts

@@ -0,0 +1,10 @@
+import { AggregationRow, FieldAggregation, FieldMeta } from "./types.js";
+
+//#region src/aggregation/aggregateRows.d.ts
+/** Aggregate one field across rows: respondent-denominated counts + percentages, option-ordered. */
+declare const aggregateRowForField: (rows: AggregationRow[], meta: FieldMeta, truncated: boolean) => FieldAggregation;
+/** Aggregate several fields across the same set of rows. */
+declare const aggregateRowsForFields: (rows: AggregationRow[], metas: FieldMeta[], truncated: boolean) => FieldAggregation[];
+//#endregion
+export { aggregateRowForField, aggregateRowsForFields };
+//# sourceMappingURL=aggregateRows.d.ts.map

package/dist/aggregation/aggregateRows.js

@@ -0,0 +1,64 @@
+//#region src/aggregation/aggregateRows.ts
+const round1 = (n) => Math.round(n * 10) / 10;
+/** The grouping keys a single answer contributes: [] for empty, one per element for arrays, else one. */
+const valueKeys = (value) => {
+	if (value == null || value === "") return [];
+	if (Array.isArray(value)) return value.filter((entry) => entry != null && entry !== "").map((entry) => String(entry));
+	return [String(value)];
+};
+/** Merge every row's descriptor snapshot for one field into a value -> label map (last write wins). */
+const snapshotLabels = (rows, field) => {
+	const labels = /* @__PURE__ */ new Map();
+	for (const row of rows) for (const descriptor of row.descriptors ?? []) if (descriptor.field === field && descriptor.optionLabels) for (const [value, label] of Object.entries(descriptor.optionLabels)) labels.set(value, label);
+	return labels;
+};
+/** Aggregate one field across rows: respondent-denominated counts + percentages, option-ordered. */
+const aggregateRowForField = (rows, meta, truncated) => {
+	const counts = /* @__PURE__ */ new Map();
+	const order = [];
+	for (const option of meta.options ?? []) {
+		counts.set(option.value, 0);
+		order.push(option.value);
+	}
+	const snapshots = snapshotLabels(rows, meta.field);
+	let total = 0;
+	for (const row of rows) {
+		const keys = valueKeys((row.values ?? []).find((entry) => entry.field === meta.field)?.value);
+		if (keys.length === 0) continue;
+		total += 1;
+		for (const key of keys) {
+			if (!counts.has(key)) {
+				counts.set(key, 0);
+				order.push(key);
+			}
+			counts.set(key, (counts.get(key) ?? 0) + 1);
+		}
+	}
+	const optionValues = new Set((meta.options ?? []).map((option) => option.value));
+	const leftovers = order.filter((value) => !optionValues.has(value)).sort((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0));
+	const ordered = [...(meta.options ?? []).map((option) => option.value), ...leftovers];
+	const optionLabelByValue = new Map((meta.options ?? []).map((option) => [option.value, option.label]));
+	const buckets = ordered.map((value) => {
+		const count = counts.get(value) ?? 0;
+		return {
+			value,
+			label: optionLabelByValue.get(value) ?? snapshots.get(value) ?? value,
+			count,
+			percentage: total > 0 ? round1(count / total * 100) : 0
+		};
+	});
+	return {
+		field: meta.field,
+		label: meta.label,
+		fieldType: meta.fieldType,
+		total,
+		buckets,
+		truncated
+	};
+};
+/** Aggregate several fields across the same set of rows. */
+const aggregateRowsForFields = (rows, metas, truncated) => metas.map((meta) => aggregateRowForField(rows, meta, truncated));
+//#endregion
+export { aggregateRowForField, aggregateRowsForFields };
+
+//# sourceMappingURL=aggregateRows.js.map

package/dist/aggregation/aggregateRows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregateRows.js","names":[],"sources":["../../src/aggregation/aggregateRows.ts"],"sourcesContent":["import type { AggregationBucket, AggregationRow, FieldAggregation, FieldMeta } from './types'\n\nconst round1 = (n: number): number => Math.round(n * 10) / 10\n\n/** The grouping keys a single answer contributes: [] for empty, one per element for arrays, else one. */\nconst valueKeys = (value: unknown): string[] => {\n\tif (value == null || value === '') {\n\t\treturn []\n\t}\n\tif (Array.isArray(value)) {\n\t\treturn value.filter((entry) => entry != null && entry !== '').map((entry) => String(entry))\n\t}\n\treturn [String(value)]\n}\n\n/** Merge every row's descriptor snapshot for one field into a value -> label map (last write wins). */\nconst snapshotLabels = (rows: AggregationRow[], field: string): Map<string, string> => {\n\tconst labels = new Map<string, string>()\n\tfor (const row of rows) {\n\t\tfor (const descriptor of row.descriptors ?? []) {\n\t\t\tif (descriptor.field === field && descriptor.optionLabels) {\n\t\t\t\tfor (const [value, label] of Object.entries(descriptor.optionLabels)) {\n\t\t\t\t\tlabels.set(value, label)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\treturn labels\n}\n\n/** Aggregate one field across rows: respondent-denominated counts + percentages, option-ordered. */\nexport const aggregateRowForField = (\n\trows: AggregationRow[],\n\tmeta: FieldMeta,\n\ttruncated: boolean\n): FieldAggregation => {\n\tconst counts = new Map<string, number>()\n\tconst order: string[] = []\n\tfor (const option of meta.options ?? []) {\n\t\tcounts.set(option.value, 0)\n\t\torder.push(option.value)\n\t}\n\tconst snapshots = snapshotLabels(rows, meta.field)\n\tlet total = 0\n\tfor (const row of rows) {\n\t\tconst answer = (row.values ?? []).find((entry) => entry.field === meta.field)\n\t\tconst keys = valueKeys(answer?.value)\n\t\tif (keys.length === 0) {\n\t\t\tcontinue\n\t\t}\n\t\ttotal += 1\n\t\tfor (const key of keys) {\n\t\t\tif (!counts.has(key)) {\n\t\t\t\tcounts.set(key, 0)\n\t\t\t\torder.push(key)\n\t\t\t}\n\t\t\tcounts.set(key, (counts.get(key) ?? 0) + 1)\n\t\t}\n\t}\n\n\tconst optionValues = new Set((meta.options ?? []).map((option) => option.value))\n\tconst leftovers = order\n\t\t.filter((value) => !optionValues.has(value))\n\t\t.sort((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0))\n\tconst ordered = [...(meta.options ?? []).map((option) => option.value), ...leftovers]\n\n\tconst optionLabelByValue = new Map(\n\t\t(meta.options ?? []).map((option) => [option.value, option.label])\n\t)\n\tconst buckets: AggregationBucket[] = ordered.map((value) => {\n\t\tconst count = counts.get(value) ?? 0\n\t\treturn {\n\t\t\tvalue,\n\t\t\tlabel: optionLabelByValue.get(value) ?? snapshots.get(value) ?? value,\n\t\t\tcount,\n\t\t\tpercentage: total > 0 ? round1((count / total) * 100) : 0,\n\t\t}\n\t})\n\n\treturn {\n\t\tfield: meta.field,\n\t\tlabel: meta.label,\n\t\tfieldType: meta.fieldType,\n\t\ttotal,\n\t\tbuckets,\n\t\ttruncated,\n\t}\n}\n\n/** Aggregate several fields across the same set of rows. */\nexport const aggregateRowsForFields = (\n\trows: AggregationRow[],\n\tmetas: FieldMeta[],\n\ttruncated: boolean\n): FieldAggregation[] => metas.map((meta) => aggregateRowForField(rows, meta, truncated))\n"],"mappings":";AAEA,MAAM,UAAU,MAAsB,KAAK,MAAM,IAAI,EAAE,IAAI;;AAG3D,MAAM,aAAa,UAA6B;CAC/C,IAAI,SAAS,QAAQ,UAAU,IAC9B,OAAO,CAAC;CAET,IAAI,MAAM,QAAQ,KAAK,GACtB,OAAO,MAAM,QAAQ,UAAU,SAAS,QAAQ,UAAU,EAAE,EAAE,KAAK,UAAU,OAAO,KAAK,CAAC;CAE3F,OAAO,CAAC,OAAO,KAAK,CAAC;AACtB;;AAGA,MAAM,kBAAkB,MAAwB,UAAuC;CACtF,MAAM,yBAAS,IAAI,IAAoB;CACvC,KAAK,MAAM,OAAO,MACjB,KAAK,MAAM,cAAc,IAAI,eAAe,CAAC,GAC5C,IAAI,WAAW,UAAU,SAAS,WAAW,cAC5C,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,WAAW,YAAY,GAClE,OAAO,IAAI,OAAO,KAAK;CAK3B,OAAO;AACR;;AAGA,MAAa,wBACZ,MACA,MACA,cACsB;CACtB,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,UAAU,KAAK,WAAW,CAAC,GAAG;EACxC,OAAO,IAAI,OAAO,OAAO,CAAC;EAC1B,MAAM,KAAK,OAAO,KAAK;CACxB;CACA,MAAM,YAAY,eAAe,MAAM,KAAK,KAAK;CACjD,IAAI,QAAQ;CACZ,KAAK,MAAM,OAAO,MAAM;EAEvB,MAAM,OAAO,WADG,IAAI,UAAU,CAAC,GAAG,MAAM,UAAU,MAAM,UAAU,KAAK,KAC3C,GAAG,KAAK;EACpC,IAAI,KAAK,WAAW,GACnB;EAED,SAAS;EACT,KAAK,MAAM,OAAO,MAAM;GACvB,IAAI,CAAC,OAAO,IAAI,GAAG,GAAG;IACrB,OAAO,IAAI,KAAK,CAAC;IACjB,MAAM,KAAK,GAAG;GACf;GACA,OAAO,IAAI,MAAM,OAAO,IAAI,GAAG,KAAK,KAAK,CAAC;EAC3C;CACD;CAEA,MAAM,eAAe,IAAI,KAAK,KAAK,WAAW,CAAC,GAAG,KAAK,WAAW,OAAO,KAAK,CAAC;CAC/E,MAAM,YAAY,MAChB,QAAQ,UAAU,CAAC,aAAa,IAAI,KAAK,CAAC,EAC1C,MAAM,GAAG,OAAO,OAAO,IAAI,CAAC,KAAK,MAAM,OAAO,IAAI,CAAC,KAAK,EAAE;CAC5D,MAAM,UAAU,CAAC,IAAI,KAAK,WAAW,CAAC,GAAG,KAAK,WAAW,OAAO,KAAK,GAAG,GAAG,SAAS;CAEpF,MAAM,qBAAqB,IAAI,KAC7B,KAAK,WAAW,CAAC,GAAG,KAAK,WAAW,CAAC,OAAO,OAAO,OAAO,KAAK,CAAC,CAClE;CACA,MAAM,UAA+B,QAAQ,KAAK,UAAU;EAC3D,MAAM,QAAQ,OAAO,IAAI,KAAK,KAAK;EACnC,OAAO;GACN;GACA,OAAO,mBAAmB,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK;GAChE;GACA,YAAY,QAAQ,IAAI,OAAQ,QAAQ,QAAS,GAAG,IAAI;EACzD;CACD,CAAC;CAED,OAAO;EACN,OAAO,KAAK;EACZ,OAAO,KAAK;EACZ,WAAW,KAAK;EAChB;EACA;EACA;CACD;AACD;;AAGA,MAAa,0BACZ,MACA,OACA,cACwB,MAAM,KAAK,SAAS,qBAAqB,MAAM,MAAM,SAAS,CAAC"}

package/dist/aggregation/resolveResultsRequest.d.ts

@@ -0,0 +1,61 @@
+import { FieldAggregation } from "./types.js";
+import { Payload, PayloadRequest } from "payload";
+
+//#region src/aggregation/resolveResultsRequest.d.ts
+type FormResultsAccessArgs = {
+  req: PayloadRequest; /** The loaded forms document (depth 0). Untyped beyond `id`: hosts read their own fields (e.g. `form.tenant`). */
+  form: {
+    id: number | string;
+  } & Record<string, unknown>;
+};
+/**
+ * Host seam gating anonymous results reads, evaluated after the form is loaded and before anything
+ * is aggregated. Multi-tenant recipe: compare `form.tenant` against the tenant derived from `req`
+ * (host header, cookie, or auth context) and return `false` for a cross-tenant read. Authenticated
+ * callers bypass this seam (they are admin-trusted, like the rest of the results endpoint).
+ */
+type FormResultsAccess = (args: FormResultsAccessArgs) => boolean | Promise<boolean>;
+type ResolveResultsRequestArgs = {
+  payload: Payload;
+  formId: number | string | undefined; /** The requested field (query param). */
+  field?: string; /** Whether the caller is authenticated (an admin/user). */
+  isAuthed: boolean;
+  req?: PayloadRequest; /** Optional host seam for anonymous reads; absent means plugin-default gating only. */
+  access?: FormResultsAccess;
+  /**
+   * Poll-eligible field types (registry-derived). When set, an anonymous read of an
+   * option-source poll also requires the results field's instance to be one of these types,
+   * so legacy or db-written docs pointing at a free-text field can never expose stored
+   * answers as leftover result buckets.
+   */
+  eligibleTypes?: readonly string[];
+};
+type ResolveResultsRequestResult = {
+  status: number;
+  body: {
+    results: FieldAggregation[];
+  } | {
+    errors: {
+      message: string;
+    }[];
+  };
+};
+/**
+ * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all
+ * enumerable fields) and bypass the `access` seam; for a poll-enabled form they also get the results
+ * field's effective options injected so sourced/resolver-backed polls render labels (best-effort, a
+ * resolve failure degrades to raw values rather than blocking the trusted read). Anonymous callers are
+ * allowed only when the form's poll is enabled, the poll's `resultsVisibility` permits it (`afterVote`:
+ * any time; `afterClose`: only once `closesAt` has passed), and the optional host `access` seam
+ * approves; and then only for the configured `poll.resultsField`, and only if that field is enumerable
+ * so a misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. A
+ * static poll is enumerable through its authored options; a poll whose options come from an
+ * `optionSource` or the field type's own `resolveOptions` resolves them here (registry via
+ * `config.custom`, per-request cache), gated by `eligibleTypes` and enumerable only when resolution
+ * yields any, with the resolved options driving bucket order and labels. Resolution failure fails
+ * closed (503) on the anonymous path. Returns only aggregate counts, never raw submissions.
+ */
+declare const resolveFormResultsRequest: (args: ResolveResultsRequestArgs) => Promise<ResolveResultsRequestResult>;
+//#endregion
+export { FormResultsAccess, FormResultsAccessArgs, ResolveResultsRequestArgs, ResolveResultsRequestResult, resolveFormResultsRequest };
+//# sourceMappingURL=resolveResultsRequest.d.ts.map

package/dist/aggregation/resolveResultsRequest.js

@@ -0,0 +1,113 @@
+import { isPollClosed, pollConfigOf } from "../form/pollState.js";
+import { aggregateFormResponses, fieldHasOptions } from "./aggregateResponses.js";
+import { resolvePollOutcome } from "../poll/resolvePollOutcome.js";
+import { shouldAutoResolvePoll } from "../poll/closeJob.js";
+import { resolveEffectivePollOptions } from "../poll/effectivePollOptions.js";
+import { FORMS_SLUG } from "../collections/forms.js";
+//#region src/aggregation/resolveResultsRequest.ts
+const forbidden = {
+	status: 403,
+	body: { errors: [{ message: "Forbidden" }] }
+};
+const unavailable = {
+	status: 503,
+	body: { errors: [{ message: "Poll options unavailable" }] }
+};
+/**
+* Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all
+* enumerable fields) and bypass the `access` seam; for a poll-enabled form they also get the results
+* field's effective options injected so sourced/resolver-backed polls render labels (best-effort, a
+* resolve failure degrades to raw values rather than blocking the trusted read). Anonymous callers are
+* allowed only when the form's poll is enabled, the poll's `resultsVisibility` permits it (`afterVote`:
+* any time; `afterClose`: only once `closesAt` has passed), and the optional host `access` seam
+* approves; and then only for the configured `poll.resultsField`, and only if that field is enumerable
+* so a misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. A
+* static poll is enumerable through its authored options; a poll whose options come from an
+* `optionSource` or the field type's own `resolveOptions` resolves them here (registry via
+* `config.custom`, per-request cache), gated by `eligibleTypes` and enumerable only when resolution
+* yields any, with the resolved options driving bucket order and labels. Resolution failure fails
+* closed (503) on the anonymous path. Returns only aggregate counts, never raw submissions.
+*/
+const resolveFormResultsRequest = async (args) => {
+	const { payload, formId, field, isAuthed, req, access, eligibleTypes } = args;
+	if (formId == null) return {
+		status: 400,
+		body: { errors: [{ message: "Missing form id" }] }
+	};
+	const form = await payload.findByID({
+		collection: FORMS_SLUG,
+		id: formId,
+		depth: 0,
+		overrideAccess: true,
+		req
+	}).catch(() => null);
+	if (!form) return {
+		status: 404,
+		body: { errors: [{ message: "Not found" }] }
+	};
+	if (shouldAutoResolvePoll(form)) await resolvePollOutcome({
+		payload,
+		formId,
+		req
+	}).catch(() => void 0);
+	let fields;
+	let resolvedOptions;
+	if (isAuthed) {
+		fields = field ? [field] : void 0;
+		const poll = pollConfigOf(form.poll);
+		const resultsField = typeof poll?.resultsField === "string" && poll.resultsField.length > 0 ? poll.resultsField : void 0;
+		if (form.pollEnabled === true && resultsField && (!field || field === resultsField)) {
+			const options = await resolveEffectivePollOptions({
+				payload,
+				req,
+				form
+			}).catch(() => []);
+			if (options.length > 0) resolvedOptions = { [resultsField]: options };
+		}
+	} else {
+		const poll = pollConfigOf(form.poll);
+		if (form.pollEnabled !== true || !poll) return forbidden;
+		if (poll.resultsVisibility === "afterClose" && !isPollClosed(poll)) return forbidden;
+		if (access) {
+			if (!(req ? await access({
+				req,
+				form
+			}) : false)) return forbidden;
+		}
+		const publicField = typeof poll.resultsField === "string" && poll.resultsField.length > 0 ? poll.resultsField : void 0;
+		if (!publicField) return forbidden;
+		if (field && field !== publicField) return forbidden;
+		const instance = (Array.isArray(form.fields) ? form.fields : []).find((entry) => entry.name === publicField);
+		if (!instance) return forbidden;
+		const hasSource = typeof poll.optionSource === "string" && poll.optionSource.length > 0;
+		const authored = fieldHasOptions(instance);
+		if ((hasSource || !authored) && eligibleTypes && !eligibleTypes.includes(instance.blockType)) return forbidden;
+		let options;
+		try {
+			options = await resolveEffectivePollOptions({
+				payload,
+				req,
+				form
+			});
+		} catch {
+			return unavailable;
+		}
+		if (options.length === 0) return forbidden;
+		resolvedOptions = { [publicField]: options };
+		fields = [publicField];
+	}
+	return {
+		status: 200,
+		body: { results: await aggregateFormResponses({
+			payload,
+			formId,
+			fields,
+			req,
+			resolvedOptions
+		}) }
+	};
+};
+//#endregion
+export { resolveFormResultsRequest };
+
+//# sourceMappingURL=resolveResultsRequest.js.map

package/dist/aggregation/resolveResultsRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveResultsRequest.js","names":[],"sources":["../../src/aggregation/resolveResultsRequest.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { FORMS_SLUG } from '../collections/forms'\nimport { isPollClosed, pollConfigOf } from '../form/pollState'\nimport { type PollFormLike, shouldAutoResolvePoll } from '../poll/closeJob'\nimport type { PollOption } from '../poll/definePollOptionSource'\nimport { resolveEffectivePollOptions } from '../poll/effectivePollOptions'\nimport { resolvePollOutcome } from '../poll/resolvePollOutcome'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { aggregateFormResponses, fieldHasOptions } from './aggregateResponses'\nimport type { FieldAggregation } from './types'\n\nexport type FormResultsAccessArgs = {\n\treq: PayloadRequest\n\t/** The loaded forms document (depth 0). Untyped beyond `id`: hosts read their own fields (e.g. `form.tenant`). */\n\tform: { id: number | string } & Record<string, unknown>\n}\n\n/**\n * Host seam gating anonymous results reads, evaluated after the form is loaded and before anything\n * is aggregated. Multi-tenant recipe: compare `form.tenant` against the tenant derived from `req`\n * (host header, cookie, or auth context) and return `false` for a cross-tenant read. Authenticated\n * callers bypass this seam (they are admin-trusted, like the rest of the results endpoint).\n */\nexport type FormResultsAccess = (args: FormResultsAccessArgs) => boolean | Promise<boolean>\n\nexport type ResolveResultsRequestArgs = {\n\tpayload: Payload\n\tformId: number | string | undefined\n\t/** The requested field (query param). */\n\tfield?: string\n\t/** Whether the caller is authenticated (an admin/user). */\n\tisAuthed: boolean\n\treq?: PayloadRequest\n\t/** Optional host seam for anonymous reads; absent means plugin-default gating only. */\n\taccess?: FormResultsAccess\n\t/**\n\t * Poll-eligible field types (registry-derived). When set, an anonymous read of an\n\t * option-source poll also requires the results field's instance to be one of these types,\n\t * so legacy or db-written docs pointing at a free-text field can never expose stored\n\t * answers as leftover result buckets.\n\t */\n\teligibleTypes?: readonly string[]\n}\n\nexport type ResolveResultsRequestResult = {\n\tstatus: number\n\tbody: { results: FieldAggregation[] } | { errors: { message: string }[] }\n}\n\nconst forbidden: ResolveResultsRequestResult = {\n\tstatus: 403,\n\tbody: { errors: [{ message: 'Forbidden' }] },\n}\n\n// 503 over 403 for a failed option-source resolve: the form and its poll config are already\n// publicly readable, so \"temporarily unavailable\" leaks nothing new, matches the submission\n// path's precedent, and does not mislabel a transient server fault as an authorization denial.\nconst unavailable: ResolveResultsRequestResult = {\n\tstatus: 503,\n\tbody: { errors: [{ message: 'Poll options unavailable' }] },\n}\n\n/**\n * Authorize and resolve a poll/survey results request. Authed callers may aggregate any field (or all\n * enumerable fields) and bypass the `access` seam; for a poll-enabled form they also get the results\n * field's effective options injected so sourced/resolver-backed polls render labels (best-effort, a\n * resolve failure degrades to raw values rather than blocking the trusted read). Anonymous callers are\n * allowed only when the form's poll is enabled, the poll's `resultsVisibility` permits it (`afterVote`:\n * any time; `afterClose`: only once `closesAt` has passed), and the optional host `access` seam\n * approves; and then only for the configured `poll.resultsField`, and only if that field is enumerable\n * so a misconfigured `resultsField` pointing at a free-text or PII field can never be dumped publicly. A\n * static poll is enumerable through its authored options; a poll whose options come from an\n * `optionSource` or the field type's own `resolveOptions` resolves them here (registry via\n * `config.custom`, per-request cache), gated by `eligibleTypes` and enumerable only when resolution\n * yields any, with the resolved options driving bucket order and labels. Resolution failure fails\n * closed (503) on the anonymous path. Returns only aggregate counts, never raw submissions.\n */\nexport const resolveFormResultsRequest = async (\n\targs: ResolveResultsRequestArgs\n): Promise<ResolveResultsRequestResult> => {\n\tconst { payload, formId, field, isAuthed, req, access, eligibleTypes } = args\n\tif (formId == null) {\n\t\treturn { status: 400, body: { errors: [{ message: 'Missing form id' }] } }\n\t}\n\tconst form = await payload\n\t\t.findByID({ collection: FORMS_SLUG, id: formId, depth: 0, overrideAccess: true, req })\n\t\t.catch(() => null)\n\tif (!form) {\n\t\treturn { status: 404, body: { errors: [{ message: 'Not found' }] } }\n\t}\n\n\t// No-runner safety net: when a closed poll's `mostVoted`/`source` outcome was never auto-resolved\n\t// (no wired job runner fired the close task), a results read heals it. Idempotent and gate-neutral,\n\t// it runs on the already-loaded form via overrideAccess and writes only through the outcome hook, so\n\t// it cannot relax the anonymous authorization below. A failure degrades silently to the normal path.\n\tif (shouldAutoResolvePoll(form as PollFormLike)) {\n\t\tawait resolvePollOutcome({ payload, formId, req }).catch(() => undefined)\n\t}\n\n\tlet fields: string[] | undefined\n\tlet resolvedOptions: Record<string, { value: string; label: string }[]> | undefined\n\tif (isAuthed) {\n\t\tfields = field ? [field] : undefined\n\t\t// Label a poll's results field for admins: resolve its effective options (a source, the\n\t\t// field type's own resolver, or authored options) and inject them so a sourced/resolved poll\n\t\t// shows labels instead of raw stored values, and so an all-fields read still surfaces a\n\t\t// resolver-backed field that carries no authored options. Best-effort: a resolver/source\n\t\t// failure degrades to raw values rather than blocking the trusted read (the anonymous path\n\t\t// below fails closed instead). Only run when the read would actually surface the results field.\n\t\tconst poll = pollConfigOf(form.poll)\n\t\tconst resultsField =\n\t\t\ttypeof poll?.resultsField === 'string' && poll.resultsField.length > 0\n\t\t\t\t? poll.resultsField\n\t\t\t\t: undefined\n\t\tif (form.pollEnabled === true && resultsField && (!field || field === resultsField)) {\n\t\t\tconst options: PollOption[] = await resolveEffectivePollOptions({\n\t\t\t\tpayload,\n\t\t\t\treq,\n\t\t\t\tform,\n\t\t\t}).catch(() => [])\n\t\t\tif (options.length > 0) {\n\t\t\t\tresolvedOptions = { [resultsField]: options }\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst poll = pollConfigOf(form.poll)\n\t\tif (form.pollEnabled !== true || !poll) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (poll.resultsVisibility === 'afterClose' && !isPollClosed(poll)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (access) {\n\t\t\t// No req means the seam cannot be evaluated; fail closed rather than skip a configured gate.\n\t\t\t// The concrete generated Form doc has no index signature; the seam's Record<string, unknown>\n\t\t\t// is the ergonomic host-facing contract, so widen the doc to it here.\n\t\t\tconst allowed = req\n\t\t\t\t? await access({ req, form: form as unknown as FormResultsAccessArgs['form'] })\n\t\t\t\t: false\n\t\t\tif (!allowed) {\n\t\t\t\treturn forbidden\n\t\t\t}\n\t\t}\n\t\tconst publicField =\n\t\t\ttypeof poll.resultsField === 'string' && poll.resultsField.length > 0\n\t\t\t\t? poll.resultsField\n\t\t\t\t: undefined\n\t\tif (!publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tif (field && field !== publicField) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst instances = Array.isArray(form.fields) ? (form.fields as FormFieldInstance[]) : []\n\t\tconst instance = instances.find((entry) => entry.name === publicField)\n\t\tif (!instance) {\n\t\t\treturn forbidden\n\t\t}\n\t\tconst hasSource = typeof poll.optionSource === 'string' && poll.optionSource.length > 0\n\t\tconst authored = fieldHasOptions(instance)\n\t\t// Options that don't come from the author's own literal `options` list (a source or a\n\t\t// field-typed resolver) require the results field to be a poll-eligible type, so a legacy or\n\t\t// db-written doc pointing `resultsField` at a free-text field can never dump raw answers as\n\t\t// leftover buckets. A static authored poll is a choice field already, so it keeps serving.\n\t\tif ((hasSource || !authored) && eligibleTypes && !eligibleTypes.includes(instance.blockType)) {\n\t\t\treturn forbidden\n\t\t}\n\t\tlet options: PollOption[]\n\t\ttry {\n\t\t\toptions = await resolveEffectivePollOptions({ payload, req, form })\n\t\t} catch {\n\t\t\treturn unavailable\n\t\t}\n\t\tif (options.length === 0) {\n\t\t\treturn forbidden\n\t\t}\n\t\tresolvedOptions = { [publicField]: options }\n\t\tfields = [publicField]\n\t}\n\n\tconst results = await aggregateFormResponses({ payload, formId, fields, req, resolvedOptions })\n\treturn { status: 200, body: { results } }\n}\n"],"mappings":";;;;;;;AAiDA,MAAM,YAAyC;CAC9C,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;AAC5C;AAKA,MAAM,cAA2C;CAChD,QAAQ;CACR,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,2BAA2B,CAAC,EAAE;AAC3D;;;;;;;;;;;;;;;;AAiBA,MAAa,4BAA4B,OACxC,SAC0C;CAC1C,MAAM,EAAE,SAAS,QAAQ,OAAO,UAAU,KAAK,QAAQ,kBAAkB;CACzE,IAAI,UAAU,MACb,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,kBAAkB,CAAC,EAAE;CAAE;CAE1E,MAAM,OAAO,MAAM,QACjB,SAAS;EAAE,YAAY;EAAY,IAAI;EAAQ,OAAO;EAAG,gBAAgB;EAAM;CAAI,CAAC,EACpF,YAAY,IAAI;CAClB,IAAI,CAAC,MACJ,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,YAAY,CAAC,EAAE;CAAE;CAOpE,IAAI,sBAAsB,IAAoB,GAC7C,MAAM,mBAAmB;EAAE;EAAS;EAAQ;CAAI,CAAC,EAAE,YAAY,KAAA,CAAS;CAGzE,IAAI;CACJ,IAAI;CACJ,IAAI,UAAU;EACb,SAAS,QAAQ,CAAC,KAAK,IAAI,KAAA;EAO3B,MAAM,OAAO,aAAa,KAAK,IAAI;EACnC,MAAM,eACL,OAAO,MAAM,iBAAiB,YAAY,KAAK,aAAa,SAAS,IAClE,KAAK,eACL,KAAA;EACJ,IAAI,KAAK,gBAAgB,QAAQ,iBAAiB,CAAC,SAAS,UAAU,eAAe;GACpF,MAAM,UAAwB,MAAM,4BAA4B;IAC/D;IACA;IACA;GACD,CAAC,EAAE,YAAY,CAAC,CAAC;GACjB,IAAI,QAAQ,SAAS,GACpB,kBAAkB,GAAG,eAAe,QAAQ;EAE9C;CACD,OAAO;EACN,MAAM,OAAO,aAAa,KAAK,IAAI;EACnC,IAAI,KAAK,gBAAgB,QAAQ,CAAC,MACjC,OAAO;EAER,IAAI,KAAK,sBAAsB,gBAAgB,CAAC,aAAa,IAAI,GAChE,OAAO;EAER,IAAI;OAOC,EAHY,MACb,MAAM,OAAO;IAAE;IAAW;GAAiD,CAAC,IAC5E,QAEF,OAAO;EAAA;EAGT,MAAM,cACL,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS,IACjE,KAAK,eACL,KAAA;EACJ,IAAI,CAAC,aACJ,OAAO;EAER,IAAI,SAAS,UAAU,aACtB,OAAO;EAGR,MAAM,YADY,MAAM,QAAQ,KAAK,MAAM,IAAK,KAAK,SAAiC,CAAC,GAC5D,MAAM,UAAU,MAAM,SAAS,WAAW;EACrE,IAAI,CAAC,UACJ,OAAO;EAER,MAAM,YAAY,OAAO,KAAK,iBAAiB,YAAY,KAAK,aAAa,SAAS;EACtF,MAAM,WAAW,gBAAgB,QAAQ;EAKzC,KAAK,aAAa,CAAC,aAAa,iBAAiB,CAAC,cAAc,SAAS,SAAS,SAAS,GAC1F,OAAO;EAER,IAAI;EACJ,IAAI;GACH,UAAU,MAAM,4BAA4B;IAAE;IAAS;IAAK;GAAK,CAAC;EACnE,QAAQ;GACP,OAAO;EACR;EACA,IAAI,QAAQ,WAAW,GACtB,OAAO;EAER,kBAAkB,GAAG,cAAc,QAAQ;EAC3C,SAAS,CAAC,WAAW;CACtB;CAGA,OAAO;EAAE,QAAQ;EAAK,MAAM,EAAE,SAAA,MADR,uBAAuB;GAAE;GAAS;GAAQ;GAAQ;GAAK;EAAgB,CAAC,EACxD;CAAE;AACzC"}