@duffcloudservices/site-forms 0.1.1 → 0.1.3

package/src/schema/form-definition.schema.json

@@ -6,7 +6,6 @@
   "description": "Portable form definition. This schema is the source of truth for\nboth the portal CRUD APIs and the `.dcs/forms/<formId>.yaml`\nfiles consumed by customer-site builds via `<DcsForm/>`.\n",
   "required": [
     "formId",
-    "title",
     "submission",
     "fields"
   ],
@@ -19,17 +18,8 @@
       "maxLength": 80,
       "example": "contact"
     },
-    "title": {
-      "type": "string",
-      "description": "Human-readable form title shown in the portal and rendered as the form heading.",
-      "minLength": 1,
-      "maxLength": 200,
-      "example": "Contact Us"
-    },
-    "description": {
-      "type": "string",
-      "description": "Optional descriptive text rendered above the fields.",
-      "maxLength": 2000
+    "formKind": {
+      "$ref": "#/definitions/PortalFormKind"
     },
     "submitLabel": {
       "type": "string",
@@ -46,6 +36,9 @@
     "submission": {
       "$ref": "#/definitions/PortalFormSubmissionConfig"
     },
+    "attachmentPolicy": {
+      "$ref": "#/definitions/PortalFormAttachmentPolicy"
+    },
     "steps": {
       "type": "array",
       "description": "Optional multi-step grouping. When omitted, fields render as a single page.",
@@ -77,6 +70,278 @@
     }
   },
   "definitions": {
+    "PortalFormKind": {
+      "type": "string",
+      "description": "High-level form kind used by the visual page editor and submission\npipeline. `freeform` preserves fully editable questionnaires; the\nstandard values provide predictable field roles and routing for common\nsite forms.\n",
+      "enum": [
+        "freeform",
+        "contact",
+        "revenue-contractor",
+        "resume-submission"
+      ],
+      "default": "freeform"
+    },
+    "PortalFormFieldRole": {
+      "type": "string",
+      "description": "Semantic role for a field inside a standard form. Free-form forms may\nomit roles or use `custom`; standard forms use roles so submissions can\nbe surfaced consistently as contact messages, notifications, revenue\ncontractor inquiries, or resume submissions without locking the editor\nout of label/help-text changes.\n",
+      "enum": [
+        "contact-name",
+        "contact-email",
+        "contact-phone",
+        "contact-company",
+        "subject",
+        "message",
+        "summary",
+        "image-attachments",
+        "resume",
+        "consent",
+        "custom"
+      ]
+    },
+    "PortalFormAttachmentPolicy": {
+      "type": "object",
+      "description": "Attachment expectations for standard forms. For\n`revenue-contractor`, image attachments are expected so contractors can\ninclude project photos. For `resume-submission`, the resume field\nshould accept document uploads. Free-form questionnaires can omit this.\n",
+      "properties": {
+        "expected": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the standard flow should prompt for attachments."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether at least one attachment is required."
+        },
+        "maxFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20,
+          "description": "Maximum number of files accepted.",
+          "example": 5
+        },
+        "maxFileSizeBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum size per file in bytes.",
+          "example": 10485760
+        },
+        "accept": {
+          "type": "array",
+          "description": "Accepted MIME types or extensions (for example `image/*`).",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "PublicSiteFormContact": {
+      "type": "object",
+      "description": "Normalized contact identity supplied with a public form submission.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "maxLength": 160
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "maxLength": 255
+        },
+        "phone": {
+          "type": "string",
+          "maxLength": 32
+        },
+        "company": {
+          "type": "string",
+          "maxLength": 160
+        }
+      }
+    },
+    "PublicSiteFormAttachment": {
+      "type": "object",
+      "description": "Metadata for an attachment associated with a public form submission.",
+      "required": [
+        "fileName"
+      ],
+      "properties": {
+        "fileName": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "contentType": {
+          "type": "string",
+          "maxLength": 120
+        },
+        "sizeBytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "storageUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Internal or pre-uploaded storage URL when the binary was uploaded separately."
+        }
+      }
+    },
+    "PublicSiteFormSubmissionRequest": {
+      "type": "object",
+      "description": "JSON request for public managed-form submissions.",
+      "required": [
+        "values"
+      ],
+      "properties": {
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
+        },
+        "pageSlug": {
+          "type": "string",
+          "description": "Optional visual-editor page slug where the form was rendered."
+        },
+        "contact": {
+          "$ref": "#/definitions/PublicSiteFormContact"
+        },
+        "subject": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Contact subject or inquiry title."
+        },
+        "summary": {
+          "type": "string",
+          "maxLength": 4000,
+          "description": "Project, request, or applicant summary for standard flows."
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 4000,
+          "description": "Free-text message supplied by the submitter."
+        },
+        "values": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Field id to submitted value map for the attached PortalFormDefinition."
+        },
+        "attachments": {
+          "type": "array",
+          "description": "Attachment metadata for JSON submissions.",
+          "items": {
+            "$ref": "#/definitions/PublicSiteFormAttachment"
+          }
+        },
+        "source": {
+          "type": "string",
+          "maxLength": 120,
+          "description": "Capture source such as `site-contact-page` or `visual-page-editor`."
+        },
+        "consent": {
+          "type": "boolean",
+          "description": "Whether the submitter consented to follow-up."
+        }
+      }
+    },
+    "PublicSiteFormMultipartSubmissionRequest": {
+      "type": "object",
+      "description": "Multipart request for public managed-form submissions with binary uploads.",
+      "properties": {
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
+        },
+        "pageSlug": {
+          "type": "string"
+        },
+        "values": {
+          "type": "string",
+          "description": "JSON-encoded field id to submitted value map."
+        },
+        "name": {
+          "type": "string",
+          "maxLength": 160
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "maxLength": 255
+        },
+        "phone": {
+          "type": "string",
+          "maxLength": 32
+        },
+        "company": {
+          "type": "string",
+          "maxLength": 160
+        },
+        "subject": {
+          "type": "string",
+          "maxLength": 200
+        },
+        "summary": {
+          "type": "string",
+          "maxLength": 4000
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 4000
+        },
+        "attachments": {
+          "type": "array",
+          "description": "Image or supporting files for standard form submissions.",
+          "items": {
+            "type": "string",
+            "format": "binary"
+          }
+        },
+        "resume": {
+          "type": "string",
+          "format": "binary",
+          "description": "Resume document for `resume-submission` standard forms."
+        },
+        "source": {
+          "type": "string",
+          "maxLength": 120
+        },
+        "consent": {
+          "type": "boolean"
+        }
+      }
+    },
+    "PublicSiteFormSubmissionResponse": {
+      "type": "object",
+      "required": [
+        "id",
+        "status",
+        "submittedAt"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique submission identifier."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "submitted",
+            "accepted",
+            "queued"
+          ]
+        },
+        "submittedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "message": {
+          "type": "string",
+          "description": "Friendly acknowledgement shown to the submitter."
+        },
+        "contactMessageId": {
+          "type": "string",
+          "nullable": true,
+          "description": "Future portal contact-message identifier when surfaced in the portal."
+        },
+        "notificationQueued": {
+          "type": "boolean",
+          "description": "Whether a portal notification/contact-message handoff was queued."
+        }
+      }
+    },
     "PortalFormFieldType": {
       "type": "string",
       "description": "Field type controlling input rendering and validation. Includes\nlayout-only types (`section-heading`, `html-block`) that render\ndecorative content rather than capturing values, and `hidden`\nfor prefilled values not displayed to the user.\n",
@@ -206,6 +471,9 @@
         "type": {
           "$ref": "#/definitions/PortalFormFieldType"
         },
+        "role": {
+          "$ref": "#/definitions/PortalFormFieldRole"
+        },
         "label": {
           "type": "string",
           "description": "Human-readable label rendered above the input.",
@@ -361,7 +629,7 @@
         },
         "subjectTemplate": {
           "type": "string",
-          "description": "Optional subject-line template. Use `{title}` to interpolate\nthe form's title; values are intentionally not interpolated\ninto the subject line for compliance reasons.\n",
+          "description": "Optional subject-line template. Submitted values are intentionally\nnot interpolated into the subject line for compliance reasons.\n",
           "maxLength": 200
         }
       }
@@ -418,7 +686,6 @@
       "description": "List-row projection of a form definition.",
       "required": [
         "formId",
-        "title",
         "fieldCount"
       ],
       "properties": {
@@ -428,14 +695,8 @@
           "pattern": "^[a-z0-9][a-z0-9-]*$",
           "example": "contact"
         },
-        "title": {
-          "type": "string",
-          "description": "Human-readable title.",
-          "example": "Contact Us"
-        },
-        "description": {
-          "type": "string",
-          "description": "Optional descriptive text."
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
         },
         "fieldCount": {
           "type": "integer",
@@ -471,7 +732,6 @@
       "description": "Payload for creating a new form definition.",
       "required": [
         "formId",
-        "title",
         "submission",
         "fields"
       ],
@@ -483,14 +743,8 @@
           "minLength": 1,
           "maxLength": 80
         },
-        "title": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 200
-        },
-        "description": {
-          "type": "string",
-          "maxLength": 2000
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
         },
         "submitLabel": {
           "type": "string",
@@ -503,6 +757,9 @@
         "submission": {
           "$ref": "#/definitions/PortalFormSubmissionConfig"
         },
+        "attachmentPolicy": {
+          "$ref": "#/definitions/PortalFormAttachmentPolicy"
+        },
         "steps": {
           "type": "array",
           "items": {
@@ -528,14 +785,8 @@
           "maxLength": 80,
           "description": "Optional echo of the path formId; must match if provided."
         },
-        "title": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 200
-        },
-        "description": {
-          "type": "string",
-          "maxLength": 2000
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
         },
         "submitLabel": {
           "type": "string",
@@ -548,6 +799,9 @@
         "submission": {
           "$ref": "#/definitions/PortalFormSubmissionConfig"
         },
+        "attachmentPolicy": {
+          "$ref": "#/definitions/PortalFormAttachmentPolicy"
+        },
         "steps": {
           "type": "array",
           "items": {
@@ -580,12 +834,6 @@
           "pattern": "^[a-z0-9][a-z0-9-]*$",
           "minLength": 1,
           "maxLength": 80
-        },
-        "title": {
-          "type": "string",
-          "description": "Optional title override; defaults to `<source title> (copy)`.",
-          "minLength": 1,
-          "maxLength": 200
         }
       }
     },
@@ -628,6 +876,123 @@
           "example": 3
         }
       }
+    },
+    "PortalFormSubmission": {
+      "type": "object",
+      "description": "A single recorded submission against a managed form. PHI fields are\nreplaced with `[REDACTED]` for Medical-category sites, in which case\n`redactedForPhi` is true.\n",
+      "required": [
+        "id",
+        "formId",
+        "siteSlug",
+        "submittedAt",
+        "source",
+        "values",
+        "redactedForPhi"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique submission row key (reverse-chronological)."
+        },
+        "formId": {
+          "type": "string"
+        },
+        "siteSlug": {
+          "type": "string"
+        },
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
+        },
+        "submittedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "source": {
+          "type": "string",
+          "description": "Capture channel (e.g. `web`, `import`)."
+        },
+        "values": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Field id → submitted value map. PHI values are redacted."
+        },
+        "attachments": {
+          "type": "array",
+          "description": "Attachment metadata captured with the submission.",
+          "items": {
+            "$ref": "#/definitions/PublicSiteFormAttachment"
+          }
+        },
+        "leadId": {
+          "type": "string",
+          "nullable": true,
+          "description": "Cross-reference to the lead row created by the legacy capture flow."
+        },
+        "contactMessageId": {
+          "type": "string",
+          "nullable": true,
+          "description": "Future portal contact-message identifier when surfaced in the portal."
+        },
+        "redactedForPhi": {
+          "type": "boolean",
+          "description": "True when one or more values were replaced with the PHI placeholder."
+        },
+        "remoteIp": {
+          "type": "string",
+          "nullable": true
+        },
+        "userAgent": {
+          "type": "string",
+          "nullable": true
+        }
+      }
+    },
+    "PortalFormSubmissionSummary": {
+      "type": "object",
+      "description": "List-view representation of a submission.",
+      "required": [
+        "id",
+        "formId",
+        "submittedAt",
+        "redactedForPhi",
+        "summary"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "formId": {
+          "type": "string"
+        },
+        "formKind": {
+          "$ref": "#/definitions/PortalFormKind"
+        },
+        "submittedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "redactedForPhi": {
+          "type": "boolean"
+        },
+        "summary": {
+          "type": "string",
+          "description": "Short single-line preview suitable for the portal list view."
+        }
+      }
+    },
+    "PortalFormSubmissionListResponse": {
+      "type": "object",
+      "required": [
+        "submissions"
+      ],
+      "properties": {
+        "submissions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PortalFormSubmissionSummary"
+          }
+        }
+      }
     }
   }
 }

package/src/schema/validate.ts

@@ -1,58 +1,58 @@
-/**
- * Validates a loaded form definition against the form-definition JSON
- * Schema emitted by `@dcs/contracts`. Dev-only — failures are logged
- * via `console.warn` rather than thrown so a malformed YAML never
- * takes down a customer site in production.
- *
- * Schema is bundled as a snapshot of
- * `contracts/dist/form-definition.schema.json` to avoid a runtime
- * dependency on the contracts build output.
- */
-import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv'
-import addFormats from 'ajv-formats'
-import schema from './form-definition.schema.json'
-import type { PortalFormDefinition } from '../types'
-
-let validator: ValidateFunction | null = null
-
-function getValidator(): ValidateFunction {
-  if (validator) return validator
-  const ajv = new Ajv({
-    allErrors: true,
-    strict: false,
-    discriminator: false,
-  })
-  addFormats(ajv)
-  validator = ajv.compile(schema as object)
-  return validator
-}
-
-export interface SchemaValidationResult {
-  valid: boolean
-  errors: ErrorObject[]
-}
-
-export function validateFormDefinition(
-  def: PortalFormDefinition | unknown,
-): SchemaValidationResult {
-  const v = getValidator()
-  const valid = v(def) as boolean
-  return { valid, errors: valid ? [] : (v.errors ?? []) }
-}
-
-/** Logs a `console.warn` when invalid, but only when `import.meta.env.DEV`. */
-export function warnIfInvalid(
-  formId: string,
-  def: PortalFormDefinition | unknown,
-  isDev: boolean,
-): SchemaValidationResult {
-  const result = validateFormDefinition(def)
-  if (!result.valid && isDev) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      `[@duffcloudservices/site-forms] Form "${formId}" failed schema validation:`,
-      result.errors,
-    )
-  }
-  return result
-}
+/**
+ * Validates a loaded form definition against the form-definition JSON
+ * Schema emitted by `@dcs/contracts`. Dev-only — failures are logged
+ * via `console.warn` rather than thrown so a malformed YAML never
+ * takes down a customer site in production.
+ *
+ * Schema is bundled as a snapshot of
+ * `contracts/dist/form-definition.schema.json` to avoid a runtime
+ * dependency on the contracts build output.
+ */
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv'
+import addFormats from 'ajv-formats'
+import schema from './form-definition.schema.json'
+import type { PortalFormDefinition } from '../types'
+
+let validator: ValidateFunction | null = null
+
+function getValidator(): ValidateFunction {
+  if (validator) return validator
+  const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    discriminator: false,
+  })
+  addFormats(ajv)
+  validator = ajv.compile(schema as object)
+  return validator
+}
+
+export interface SchemaValidationResult {
+  valid: boolean
+  errors: ErrorObject[]
+}
+
+export function validateFormDefinition(
+  def: PortalFormDefinition | unknown,
+): SchemaValidationResult {
+  const v = getValidator()
+  const valid = v(def) as boolean
+  return { valid, errors: valid ? [] : (v.errors ?? []) }
+}
+
+/** Logs a `console.warn` when invalid, but only when `import.meta.env.DEV`. */
+export function warnIfInvalid(
+  formId: string,
+  def: PortalFormDefinition | unknown,
+  isDev: boolean,
+): SchemaValidationResult {
+  const result = validateFormDefinition(def)
+  if (!result.valid && isDev) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[@duffcloudservices/site-forms] Form "${formId}" failed schema validation:`,
+      result.errors,
+    )
+  }
+  return result
+}

package/src/shims.d.ts

@@ -1,10 +1,10 @@
-declare module '*.vue' {
-  import type { DefineComponent } from 'vue'
-  const component: DefineComponent<{}, {}, unknown>
-  export default component
-}
-
-declare module '*.json' {
-  const value: unknown
-  export default value
-}
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, unknown>
+  export default component
+}
+
+declare module '*.json' {
+  const value: unknown
+  export default value
+}