@lssm/lib.contracts-runtime-core 3.0.1

package/dist/native/forms-platform.js

@@ -0,0 +1,429 @@
+// src/forms-platform-types.ts
+class FormsPlatformError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FormsPlatformError";
+  }
+}
+
+// src/forms-platform-utils.ts
+import {
+  compileFormDocument,
+  validateFormDocument
+} from "@lssm/lib.contracts-spec/forms";
+function requireFormDefinition(definition, scope) {
+  const matches = definition?.owner.product === scope.product && definition.owner.tenantRef === scope.tenantRef && definition.owner.workspaceRef === scope.workspaceRef && definition.owner.ownerRef === scope.ownerRef;
+  if (!definition || !matches) {
+    throw new FormsPlatformError("FORM_NOT_FOUND", "Form definition was not found in the caller scope");
+  }
+  return definition;
+}
+function validateRuntimeFormDocument(document) {
+  const issues = validateFormDocument(document);
+  if (issues.length) {
+    throw new FormsPlatformError("INVALID_FORM_DOCUMENT", issues.map((issue) => issue.message).join("; "));
+  }
+  compileFormDocument(document);
+}
+function formAssuranceMeetsRequirement(assurance, requirement) {
+  if (requirement === "none")
+    return true;
+  if (requirement === "either")
+    return assurance !== "anonymous";
+  if (requirement === "both")
+    return assurance === "both";
+  return assurance === requirement || assurance === "both";
+}
+function resolveFormResponseStatus(document, assurance) {
+  if (formAssuranceMeetsRequirement(assurance, document.verification.requirement)) {
+    return "completed";
+  }
+  return document.verification.unverifiedDisposition === "pending-hidden" ? "pending-verification" : "completed-unverified";
+}
+function resolveFormLocale(document, candidates) {
+  const supported = new Set(document.content.enabledLocales.map((locale) => locale.toLowerCase()));
+  for (const candidate of candidates) {
+    if (!candidate)
+      continue;
+    const normalized = candidate.trim().toLowerCase();
+    const exact = document.content.enabledLocales.find((locale) => locale.toLowerCase() === normalized);
+    if (supported.has(normalized) && exact)
+      return exact;
+    const language = normalized.split("-")[0];
+    const match = document.content.enabledLocales.find((locale) => locale.toLowerCase().split("-")[0] === language);
+    if (match)
+      return match;
+  }
+  return document.content.defaultLocale;
+}
+
+// src/forms-platform-management.ts
+function createFormsManagementService(dependencies) {
+  const emit = async (key, payload) => dependencies.emit?.(key, payload);
+  return {
+    async create(scope, document) {
+      validateRuntimeFormDocument(document);
+      const now = dependencies.now();
+      const definition = {
+        id: dependencies.id("definition"),
+        owner: scope,
+        status: "draft",
+        draft: document,
+        draftVersion: 1,
+        createdAt: now,
+        updatedAt: now
+      };
+      await dependencies.store.insertDefinition(definition);
+      await emit("forms.definition.created", {
+        definitionId: definition.id,
+        occurredAt: now
+      });
+      return definition;
+    },
+    async saveDraft(scope, definitionId, expectedVersion, document) {
+      validateRuntimeFormDocument(document);
+      const current = requireFormDefinition(await dependencies.store.getDefinition(scope, definitionId), scope);
+      if (current.status === "archived") {
+        throw new FormsPlatformError("FORM_ARCHIVED", "Archived forms cannot be edited");
+      }
+      const next = {
+        ...current,
+        draft: document,
+        draftVersion: expectedVersion + 1,
+        updatedAt: dependencies.now()
+      };
+      if (!await dependencies.store.updateDefinition(next, expectedVersion)) {
+        throw new FormsPlatformError("DRAFT_CONFLICT", "The form draft changed; reload before saving");
+      }
+      await emit("forms.draft.saved", {
+        definitionId,
+        occurredAt: next.updatedAt
+      });
+      return next;
+    },
+    async publish(scope, definitionId, expectedVersion) {
+      return dependencies.store.transaction(async (store) => {
+        const current = requireFormDefinition(await store.getDefinition(scope, definitionId), scope);
+        if (current.draftVersion !== expectedVersion) {
+          throw new FormsPlatformError("DRAFT_CONFLICT", "The form draft changed before publish");
+        }
+        validateRuntimeFormDocument(current.draft);
+        const previous = current.publishedRevisionId ? await store.getRevision(current.publishedRevisionId) : undefined;
+        const publishedAt = dependencies.now();
+        const revision = {
+          id: dependencies.id("revision"),
+          definitionId,
+          revision: (previous?.revision ?? 0) + 1,
+          document: structuredClone(current.draft),
+          digest: await dependencies.digest(JSON.stringify(current.draft)),
+          publishedAt
+        };
+        const definition = {
+          ...current,
+          status: "published",
+          publishedRevisionId: revision.id,
+          publicToken: current.publicToken ?? dependencies.publicToken(),
+          updatedAt: publishedAt
+        };
+        await store.insertRevision(revision);
+        if (!await store.updateDefinition(definition, expectedVersion)) {
+          throw new FormsPlatformError("DRAFT_CONFLICT", "The form changed during publish");
+        }
+        await emit("forms.definition.published", {
+          definitionId,
+          revisionId: revision.id,
+          occurredAt: publishedAt
+        });
+        return { definition, revision };
+      });
+    },
+    async close(scope, definitionId) {
+      const current = requireFormDefinition(await dependencies.store.getDefinition(scope, definitionId), scope);
+      if (current.status !== "published") {
+        throw new FormsPlatformError("FORM_NOT_PUBLISHED", "Only a published form can be closed");
+      }
+      const next = {
+        ...current,
+        status: "closed",
+        updatedAt: dependencies.now()
+      };
+      await dependencies.store.updateDefinition(next);
+      await emit("forms.definition.closed", {
+        definitionId,
+        occurredAt: next.updatedAt
+      });
+      return next;
+    },
+    async archive(scope, definitionId) {
+      const current = requireFormDefinition(await dependencies.store.getDefinition(scope, definitionId), scope);
+      if (current.status === "archived")
+        return current;
+      const next = {
+        ...current,
+        status: "archived",
+        updatedAt: dependencies.now()
+      };
+      await dependencies.store.updateDefinition(next);
+      await emit("forms.definition.archived", {
+        definitionId,
+        occurredAt: next.updatedAt
+      });
+      return next;
+    }
+  };
+}
+
+// src/forms-platform-submission.ts
+import {
+  buildZodWithRelations,
+  compileFormDocument as compileFormDocument2,
+  FORM_AI_FULL_DATA_CONSENT_NOTICE_VERSION
+} from "@lssm/lib.contracts-spec/forms";
+function validateCanonicalFormAnswers(document, answers) {
+  const questionsById = new Map(document.questions.map((question) => [question.id, question]));
+  const portableFieldNames = new Set(Object.keys(document.formSpec?.modelFields ?? {}));
+  const unknownIds = Object.keys(answers).filter((id) => !questionsById.has(id) && !portableFieldNames.has(id));
+  if (unknownIds.length) {
+    throw new FormsPlatformError("INVALID_RESPONSE", `Unknown question IDs: ${unknownIds.join(", ")}`);
+  }
+  for (const question of document.questions) {
+    if (!["single-choice", "multi-select", "dropdown"].includes(question.kind))
+      continue;
+    const value = answers[question.id];
+    if (value == null)
+      continue;
+    const allowed = new Set(question.options?.map((option) => option.value));
+    const valid = question.kind === "multi-select" ? Array.isArray(value) && value.every((item) => typeof item === "string" && allowed.has(item)) : typeof value === "string" && allowed.has(value);
+    if (!valid)
+      throw new FormsPlatformError("INVALID_RESPONSE", `Answer for ${question.id} is not a declared option`);
+  }
+  const runtimeAnswers = Object.fromEntries(Object.entries(answers).map(([id, value]) => [
+    questionsById.get(id)?.name ?? id,
+    value
+  ]));
+  const result = buildZodWithRelations(compileFormDocument2(document)).safeParse(runtimeAnswers);
+  if (!result.success) {
+    throw new FormsPlatformError("INVALID_RESPONSE", `Response does not match the published form: ${String(result.error)}`);
+  }
+}
+function publicDocument(document) {
+  const {
+    kind,
+    version,
+    id,
+    titleKey,
+    descriptionKey,
+    content,
+    questions,
+    pages,
+    verification,
+    formSpec,
+    ai,
+    beforeDestination,
+    afterDestination
+  } = document;
+  return structuredClone({
+    kind,
+    version,
+    id,
+    titleKey,
+    descriptionKey,
+    content,
+    questions,
+    pages,
+    verification,
+    formSpec,
+    ai: {
+      mode: ai.mode,
+      dataMode: ai.dataMode,
+      ...ai.dataMode === "full-with-consent" ? {
+        consentNoticeVersion: FORM_AI_FULL_DATA_CONSENT_NOTICE_VERSION
+      } : {}
+    },
+    beforeDestination,
+    afterDestination
+  });
+}
+async function resolveAssurance(dependencies, evidenceRef, definitionId, publicToken) {
+  if (!evidenceRef)
+    return "anonymous";
+  if (!dependencies.resolveAssurance) {
+    throw new FormsPlatformError("VERIFICATION_UNAVAILABLE", "Verification evidence cannot be resolved");
+  }
+  return dependencies.resolveAssurance(evidenceRef, definitionId, publicToken);
+}
+function createFormsSubmissionService(dependencies) {
+  return {
+    async getPublic(publicToken, localeCandidates) {
+      const definition = await dependencies.store.getDefinitionByPublicToken(publicToken);
+      if (!definition || definition.status !== "published" || !definition.publishedRevisionId) {
+        throw new FormsPlatformError("FORM_NOT_FOUND", "Published form was not found");
+      }
+      const revision = await dependencies.store.getRevision(definition.publishedRevisionId, { publicToken });
+      if (!revision) {
+        throw new FormsPlatformError("REVISION_NOT_FOUND", "Published form revision was not found");
+      }
+      return {
+        definitionId: definition.id,
+        revisionId: revision.id,
+        revision: revision.revision,
+        document: publicDocument(revision.document),
+        locale: resolveFormLocale(revision.document, localeCandidates)
+      };
+    },
+    async submit(input) {
+      const definition = await dependencies.store.getDefinitionByPublicToken(input.publicToken);
+      if (!definition || definition.status !== "published") {
+        throw new FormsPlatformError("FORM_NOT_FOUND", "Form is not accepting responses");
+      }
+      const revision = await dependencies.store.getRevision(input.revisionId, {
+        publicToken: input.publicToken
+      });
+      if (!revision || revision.definitionId !== definition.id) {
+        throw new FormsPlatformError("REVISION_MISMATCH", "Response revision does not match the public session");
+      }
+      validateCanonicalFormAnswers(revision.document, input.answers);
+      const assurance = await resolveAssurance(dependencies, input.verificationEvidenceRef, definition.id, input.publicToken);
+      if (revision.document.verification.timing === "before" && !formAssuranceMeetsRequirement(assurance, revision.document.verification.requirement)) {
+        throw new FormsPlatformError("VERIFICATION_REQUIRED", "Verification is required before submission");
+      }
+      const now = dependencies.now();
+      const response = {
+        id: dependencies.id("response"),
+        definitionId: definition.id,
+        revisionId: revision.id,
+        locale: resolveFormLocale(revision.document, [input.locale]),
+        status: resolveFormResponseStatus(revision.document, assurance),
+        authorAssurance: assurance,
+        answers: structuredClone(input.answers),
+        createdAt: now,
+        updatedAt: now,
+        submittedAt: now
+      };
+      const stored = await dependencies.store.insertResponseIdempotently(response, input.publicToken, input.idempotencyKey);
+      if (!stored.inserted)
+        return stored.response;
+      await dependencies.emit?.("forms.response.submitted", {
+        definitionId: response.definitionId,
+        revisionId: response.revisionId,
+        responseId: response.id,
+        occurredAt: now
+      });
+      return stored.response;
+    }
+  };
+}
+
+// src/forms-platform-csv-columns.ts
+import { flattenPortableFormFields } from "@lssm/lib.contracts-spec/forms";
+function formCsvColumns(document) {
+  const questionNames = new Set(document.questions.map(({ name }) => name));
+  const questions = document.questions.map(questionColumn);
+  const portableSensitive = new Set(document.formSpec?.policy?.pii ?? []);
+  const allFields = flattenPortableFormFields(document.formSpec?.fields ?? []);
+  const portable = Object.entries(document.formSpec?.modelFields ?? {}).flatMap(([name, modelField]) => {
+    if (questionNames.has(name))
+      return [];
+    const field = allFields.find((candidate) => candidate.name === name);
+    return [
+      {
+        id: name,
+        labelKey: field?.labelI18n ?? name,
+        sensitive: portableSensitive.has(name) || [...portableSensitive].some((path) => path.startsWith(`${name}.`)) || field?.kind === "email" || field?.kind === "phone" || modelField.type === "email" || modelField.type === "phone"
+      }
+    ];
+  });
+  return [...questions, ...portable];
+}
+function questionColumn(question) {
+  return {
+    id: question.id,
+    labelKey: question.labelKey,
+    sensitive: question.sensitive === true || question.kind === "email" || question.kind === "phone"
+  };
+}
+
+// src/forms-platform-csv.ts
+var RESPONSE_EXTENSIONS_COLUMN = "response_extensions:AI follow-ups";
+function csvCell(value) {
+  const raw = Array.isArray(value) ? value.every((item) => typeof item !== "object") ? value.join(";") : JSON.stringify(value) : value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+  const protectedValue = /^[\s]*[=+\-@]/.test(raw) ? `'${raw}` : raw;
+  return `"${protectedValue.replaceAll('"', '""')}"`;
+}
+function csvRow(values) {
+  return `${values.map(csvCell).join(",")}\r
+`;
+}
+function responseRow(revision, response, options) {
+  if (response.revisionId !== revision.id) {
+    throw new Error("CSV responses must belong to the exported revision");
+  }
+  const columns = formCsvColumns(revision.document);
+  const baseIds = new Set(columns.map(({ id }) => id));
+  const extensions = Object.fromEntries(Object.entries(response.answers).filter(([id]) => !baseIds.has(id)));
+  return [
+    response.id,
+    response.status,
+    response.locale,
+    response.submittedAt ?? "",
+    ...columns.map((column) => {
+      const mayIncludeSensitive = options.includeSensitive && options.sensitiveGrant?.authorized;
+      if (!mayIncludeSensitive && column.sensitive) {
+        return "[REDACTED]";
+      }
+      return response.answers[column.id];
+    }),
+    options.includeSensitive && options.sensitiveGrant?.authorized ? extensions : "[REDACTED]"
+  ];
+}
+function csvHeaders(revision, locale) {
+  const resolved = resolveFormLocale(revision.document, [locale]);
+  const catalog = revision.document.content.catalogs[resolved] ?? {};
+  return [
+    "response_id",
+    "status",
+    "locale",
+    "submitted_at",
+    ...formCsvColumns(revision.document).map((column) => `${column.id}:${catalog[column.labelKey] ?? column.labelKey}`),
+    RESPONSE_EXTENSIONS_COLUMN
+  ];
+}
+function serializeFormResponsesCsv(revision, responses, options = {}) {
+  return `\uFEFF${csvRow(csvHeaders(revision, options.locale))}${responses.map((response) => csvRow(responseRow(revision, response, options))).join("")}`;
+}
+async function* streamFormResponsesCsv(revision, responses, options = {}) {
+  yield `\uFEFF${csvRow(csvHeaders(revision, options.locale))}`;
+  for await (const response of responses) {
+    yield csvRow(responseRow(revision, response, options));
+  }
+}
+// src/forms-platform-navigation.ts
+import {
+  evalPredicate
+} from "@lssm/lib.contracts-spec/forms";
+function resolveNextFormPage(document, currentPageId, answers) {
+  const currentIndex = document.pages.findIndex((page) => page.id === currentPageId);
+  if (currentIndex < 0) {
+    throw new FormsPlatformError("PAGE_NOT_FOUND", "Current form page does not exist");
+  }
+  const rule = document.pages[currentIndex]?.nextPageRules?.find((candidate) => evalPredicate(answers, candidate.when));
+  return rule?.nextPageId ?? document.pages[currentIndex]?.defaultNextPageId ?? document.pages[currentIndex + 1]?.id;
+}
+
+// src/forms-platform.ts
+function createFormsPlatformService(dependencies) {
+  return {
+    ...createFormsManagementService(dependencies),
+    ...createFormsSubmissionService(dependencies)
+  };
+}
+export {
+  FormsPlatformError,
+  createFormsPlatformService,
+  resolveFormLocale,
+  resolveNextFormPage,
+  serializeFormResponsesCsv,
+  streamFormResponsesCsv
+};