@updraft-solutions/mcrit-sdk 0.4.0 → 0.6.0

package/src/schemas/form-template.ts

@@ -0,0 +1,416 @@
+import { z } from "zod";
+
+// Field types enum - matches backend FormFieldType
+export enum FormFieldType {
+  Text = "text",
+  Textarea = "textarea",
+  Number = "number",
+  Date = "date",
+  Time = "time",
+  Duration = "duration",
+  Select = "select",
+  MultiSelect = "multi_select",
+  Checkbox = "checkbox",
+  Radio = "radio",
+  RatingScale = "rating_scale",
+  Signature = "signature",
+  PassFail = "pass_fail",
+  MembershipSelect = "membership_select",
+  InstructorSelect = "instructor_select",
+  AirplaneSelect = "airplane_select",
+  CourseSelect = "course_select",
+  MembershipSignature = "membership_signature",
+  FileUpload = "file_upload",
+  // Select with built-in mass unit options (kg/lbs/t) — see app/utils/massUnits.ts
+  MassUnitSelect = "mass_unit_select",
+  // Display-only text block (contract clauses, instructions). Carries its text in
+  // `content`, stores no value, never an input.
+  StaticText = "static_text",
+}
+
+// Submission status enum - matches backend FormSubmissionStatus
+export enum FormSubmissionStatus {
+  Draft = "draft",
+  AwaitingSignatures = "awaiting_signatures",
+  Submitted = "submitted",
+  Approved = "approved",
+  Rejected = "rejected",
+}
+
+// Submission origin - matches backend FormSubmissionSource
+export enum FormSubmissionSource {
+  Voluntary = "voluntary",
+  Onboarding = "onboarding",
+  AdHocRequest = "ad_hoc_request",
+}
+
+// Schema field label (i18n)
+export const FieldLabelSchema = z.object({
+  de: z.string().optional(),
+  en: z.string(),
+  no: z.string().optional(),
+});
+
+// Conditional visibility
+export const ShowWhenSchema = z.object({
+  field: z.string(),
+  operator: z.enum(["eq", "neq", "in", "not_in", "gt", "lt", "gte", "lte"]),
+  value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]),
+});
+
+// Schema field definition
+export const SchemaFieldSchema = z.object({
+  key: z.string(),
+  type: z.nativeEnum(FormFieldType),
+  // Optional because static_text fields use `content` instead of `label`.
+  label: FieldLabelSchema.optional(),
+  // Display-only text for static_text fields (i18n), rendered with line breaks.
+  content: FieldLabelSchema.optional(),
+  required: z.boolean().optional().default(false),
+  validation: z.record(z.any()).optional(),
+  options: z.record(z.any()).optional(),
+  col_span: z.number().min(1).max(12).optional(),
+  order: z.number(),
+  show_when: ShowWhenSchema.optional(),
+  // Signature fields only: auto-binds the designated signer to the membership_id stored in the
+  // referenced field (no manual designation needed).
+  signer_membership_field: z.string().optional(),
+  // Signature fields only: group designation — any member holding this permission at the
+  // template's company may sign (e.g. "formSubmission.signAsCompany" for the company signature).
+  signer_permission: z.string().optional(),
+  // Signature fields only: bind the signer to the membership the form is attached to
+  // ("submittable") — the person the form is about signs, with no picker.
+  signer_source: z.string().optional(),
+  // Text fields only: server-side party prefill (company.name|address,
+  // member.name|address). Resolved & frozen into data at issuance — render
+  // read-only; the backend rejects edits to these keys.
+  prefill_source: z.string().optional(),
+});
+
+// Schema section definition
+export const SchemaSectionSchema = z.object({
+  key: z.string(),
+  title: z.string(),
+  order: z.number(),
+  fields: z.array(SchemaFieldSchema),
+});
+
+// Full template schema
+export const TemplateSchemaSchema = z.object({
+  sections: z.array(SchemaSectionSchema),
+});
+
+// User basic schema for relationships
+const UserBasicSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    email: z.string().optional(),
+  })
+  .nullable();
+
+// Form Template
+export const FormTemplateSchema = z.object({
+  type: z.literal("form_template"),
+  id: z.number(),
+  company_id: z.number().nullable(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable(),
+  schema: TemplateSchemaSchema,
+  schema_version: z.number(),
+  pdf_view: z.string().nullable(),
+  requires_review: z.boolean(),
+  is_active: z.boolean(),
+  is_singleton: z.boolean().optional().default(false),
+  // Sign-only: submissions skip the draft phase (issued straight into
+  // awaiting_signatures) and auto-submit once all signatures are collected.
+  is_sign_only: z.boolean().optional().default(false),
+  // Requirable: this company template may be referenced by requirement groups
+  // (a compliance document), vs a workflow form. System templates are always
+  // requirable. Defaults false.
+  is_requirable: z.boolean().optional().default(false),
+  is_onboarding: z.boolean().optional().default(false),
+  // Array of system role keys this onboarding template applies to.
+  // null/missing = applies to every member at the company.
+  onboarding_role_keys: z.array(z.string()).nullable().optional(),
+  // System templates: platform-provided, super-admin maintained, no owning
+  // company. Cannot be assigned/filled until merge Phase 2.
+  is_system: z.boolean().optional().default(false),
+  // Scope of a system template: null/"user" = a personal qualification;
+  // "aircraft" = an aircraft document (e.g. weight report) excluded from the
+  // user qualification picker.
+  applies_to: z.string().nullable().optional(),
+  // When true, submissions carry an expires_at (content validity, e.g. a
+  // medical's expiry). Distinct from due_date (deadline to fill).
+  has_expiry: z.boolean().optional().default(false),
+  default_notification_days: z.number().nullable().optional(),
+  created_by: z.number().nullable(),
+  creator: UserBasicSchema.optional(),
+  assignments: z.array(z.any()).optional(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+// Form Template Assignment
+export const FormTemplateAssignmentSchema = z.object({
+  type: z.literal("form_template_assignment"),
+  id: z.number(),
+  form_template_id: z.number(),
+  assignable_type: z.string(),
+  assignable_id: z.number(),
+  target_type: z.string(),
+  // `trigger` is soft-deprecated — column kept as a future escape hatch but no
+  // handler reads it and the UI no longer surfaces it. See docs/features/forms.md.
+  trigger: z.string().nullable(),
+  sort_order: z.number(),
+  form_template: FormTemplateSchema.optional(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+// Signature row from the polymorphic signatures table; each carries its own audit packet.
+export const SignatureSchema = z.object({
+  type: z.literal("signature").optional(),
+  id: z.number(),
+  signable_type: z.string().optional(),
+  signable_id: z.number().optional(),
+  field_key: z.string(),
+  status: z.enum(["pending", "signed", "revoked"]),
+  required_signer_membership_id: z.number().nullable(),
+  required_signer_name: z.string().nullable().optional(),
+  // Group designation: any member holding this permission at the template's
+  // company may sign (e.g. "formSubmission.signAsCompany").
+  required_signer_permission: z.string().nullable().optional(),
+  signed_by_user_id: z.number().nullable(),
+  signed_by_membership_id: z.number().nullable(),
+  signed_by_name: z.string().nullable().optional(),
+  is_current_user_designated: z.boolean().optional().default(false),
+  signed_at: z.string().nullable(),
+  image: z.string().nullable(),
+  data_hash: z.string().nullable(),
+  schema_version: z.number().nullable(),
+  schema_hash: z.string().nullable(),
+  consent_text_hash: z.string().nullable(),
+  auth_method: z.string().nullable(),
+  auth_verified_at: z.string().nullable(),
+  ip_address: z.string().nullable(),
+  user_agent: z.string().nullable(),
+  geo_country: z.string().nullable(),
+  signing_event_id: z.string().nullable(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+
+// Spatie MediaResource subset used by file_upload fields.
+export const SubmissionFileSchema = z.object({
+  id: z.number(),
+  file_name: z.string(),
+  size: z.number(),
+  mime_type: z.string().nullable().optional(),
+  url: z.string().nullable().optional(),
+  conversions: z.record(z.string(), z.string().nullable()).optional(),
+});
+
+// Form Submission Share — a user-owned submission shared with a company
+// (replaces the legacy document-shares model in merge Phase 3b). Base shape
+// without the nested submission so it can be embedded on FormSubmission
+// itself (`shares` — the owner sees all of them on their own listing).
+export const FormSubmissionShareBaseSchema = z.object({
+  type: z.literal("form_submission_share").optional(),
+  id: z.number(),
+  form_submission_id: z.number(),
+  company_id: z.number(),
+  shared_by: z.number(),
+  company: z
+    .object({
+      id: z.number(),
+      name: z.string(),
+    })
+    .optional(),
+  created_at: z.string(),
+});
+
+// Form Submission
+export const FormSubmissionSchema = z.object({
+  type: z.literal("form_submission"),
+  id: z.number(),
+  form_template_id: z.number(),
+  schema_version: z.number(),
+  schema_snapshot: TemplateSchemaSchema,
+  submittable_type: z.string(),
+  submittable_id: z.number(),
+  // Who/what the submission is about — shown in the dialog header. Present
+  // when the backend loaded the submittable relation.
+  submittable_summary: z
+    .object({
+      type: z.string(),
+      id: z.number(),
+      name: z.string().nullable(),
+      email: z.string().nullable(),
+    })
+    .nullable()
+    .optional(),
+  submitted_by: z.number(),
+  data: z.record(z.any()),
+  data_resolved_names: z.record(z.string(), z.string()).optional().default({}),
+  required_signers: z.record(z.string(), z.number()).nullable().optional(),
+  signatures: z.array(SignatureSchema).optional(),
+  status: z.nativeEnum(FormSubmissionStatus),
+  submitted_at: z.string().nullable(),
+  reviewed_by: z.number().nullable(),
+  reviewed_at: z.string().nullable(),
+  review_comment: z.string().nullable(),
+  is_final: z.boolean().optional().default(false),
+  is_mutable: z.boolean().optional().default(false),
+  is_signable: z.boolean().optional().default(false),
+  has_signature_fields: z.boolean().optional().default(false),
+  all_signatures_collected: z.boolean().optional().default(true),
+  // Server-evaluated policy decisions per gate (delete, revertToDraft, update, …),
+  // read via hasModelPermission(submission, '<gate>'). Null when the fetch didn't
+  // request permissions; populated when it passes permissions[form_submission].
+  can: z.record(z.boolean().nullable()).optional().default({}),
+  // Request envelope for pre-issued drafts (onboarding / ad-hoc admin request).
+  // Voluntary submissions leave note/due_date/requester null.
+  source: z
+    .nativeEnum(FormSubmissionSource)
+    .optional()
+    .default(FormSubmissionSource.Voluntary),
+  due_date: z.string().nullable().optional(),
+  note: z.string().nullable().optional(),
+  requested_by_user_id: z.number().nullable().optional(),
+  is_overdue: z.boolean().optional().default(false),
+  days_until_due: z.number().nullable().optional(),
+  // Content validity (has_expiry templates only). ISO datetime.
+  expires_at: z.string().nullable().optional(),
+  notification_days_before: z.number().nullable().optional(),
+  notifications_enabled: z.boolean().optional().default(true),
+  is_expired: z.boolean().optional().default(false),
+  // { field_key: media | null } for every file_upload field in the snapshot.
+  files: z.record(z.string(), SubmissionFileSchema.nullable()).optional(),
+  form_template: FormTemplateSchema.optional(),
+  submitter: UserBasicSchema.optional(),
+  reviewer: UserBasicSchema.optional(),
+  requester: UserBasicSchema.optional(),
+  // Shares of this (user-owned) submission. Present on listings that
+  // eager-load them — the owner sees all, recipient staff only their own
+  // companies' rows (viewer-scoped in the backend resource).
+  shares: z.array(FormSubmissionShareBaseSchema).optional(),
+  created_at: z.string(),
+  updated_at: z.string(),
+});
+
+// Full share shape — `form_submission` is nested on the my-shares /
+// company-inbox listings.
+export const FormSubmissionShareSchema = FormSubmissionShareBaseSchema.extend({
+  form_submission: FormSubmissionSchema.optional(),
+});
+
+// Cross-link source metadata. Present on rows surfaced through the
+// enrollment ← booking link; null when the row belongs to the queried
+// submittable directly. See backend GetRequiredFormsForModel.
+// Full crew of the source booking, incl. virtual roles (authorizing
+// instructor) — role values are backend CrewMemberPosition snake_case.
+export const RequiredFormViaCrewSchema = z.object({
+  name: z.string().nullable(),
+  role: z.string(),
+  is_pic: z.boolean(),
+});
+
+export const RequiredFormViaSchema = z.object({
+  type: z.literal("booking"),
+  booking_id: z.number(),
+  etdZ: z.string().nullable(),
+  route_display: z.string().nullable(),
+  airplane_registration: z.string().nullable(),
+  crew: z.array(RequiredFormViaCrewSchema).optional().default([]),
+});
+
+// Required form (convenience endpoint response)
+export const RequiredFormSchema = z.object({
+  template: FormTemplateSchema,
+  assignment: FormTemplateAssignmentSchema,
+  // Latest submission (back-compat for callers that haven't migrated to the array).
+  submission: FormSubmissionSchema.nullable(),
+  // All submissions for this (template, submittable), newest first. For singleton templates
+  // length is 0 or 1; non-singleton templates can grow over time.
+  submissions: z.array(FormSubmissionSchema).optional().default([]),
+  is_complete: z.boolean(),
+  via: RequiredFormViaSchema.nullable().optional(),
+});
+
+// Type exports
+export type FieldLabel = z.infer<typeof FieldLabelSchema>;
+export type ShowWhen = z.infer<typeof ShowWhenSchema>;
+export type SchemaField = z.infer<typeof SchemaFieldSchema>;
+export type SchemaSection = z.infer<typeof SchemaSectionSchema>;
+export type TemplateSchema = z.infer<typeof TemplateSchemaSchema>;
+export type FormTemplate = z.infer<typeof FormTemplateSchema>;
+export type FormTemplateAssignment = z.infer<
+  typeof FormTemplateAssignmentSchema
+>;
+export type FormSubmission = z.infer<typeof FormSubmissionSchema>;
+export type FormSubmissionShare = z.infer<typeof FormSubmissionShareSchema>;
+export type FormSubmissionShareBase = z.infer<
+  typeof FormSubmissionShareBaseSchema
+>;
+export type SubmissionFile = z.infer<typeof SubmissionFileSchema>;
+export type RequiredForm = z.infer<typeof RequiredFormSchema>;
+export type RequiredFormVia = z.infer<typeof RequiredFormViaSchema>;
+export type RequiredFormViaCrew = z.infer<typeof RequiredFormViaCrewSchema>;
+export type Signature = z.infer<typeof SignatureSchema>;
+
+// Input types
+export interface CreateFormTemplateInput {
+  name: string;
+  slug?: string;
+  description?: string | null;
+  schema: TemplateSchema;
+  pdf_view?: string | null;
+  requires_review?: boolean;
+  is_active?: boolean;
+  is_singleton?: boolean;
+  is_sign_only?: boolean;
+  is_onboarding?: boolean;
+  onboarding_role_keys?: string[] | null;
+  has_expiry?: boolean;
+  default_notification_days?: number | null;
+}
+
+export interface UpdateFormTemplateInput {
+  name?: string;
+  slug?: string;
+  description?: string | null;
+  schema?: TemplateSchema;
+  pdf_view?: string | null;
+  requires_review?: boolean;
+  is_active?: boolean;
+  is_singleton?: boolean;
+  is_sign_only?: boolean;
+  is_onboarding?: boolean;
+  onboarding_role_keys?: string[] | null;
+  has_expiry?: boolean;
+  default_notification_days?: number | null;
+}
+
+export interface CreateFormTemplateAssignmentInput {
+  assignable_type: "course" | "company";
+  assignable_id: number;
+  target_type: "course_enrollment" | "booking" | "membership";
+  // @deprecated trigger is accepted by the backend for back-compat but no
+  // handler reads it. UI does not send it. Kept on the input shape only.
+  trigger?: "on_completion" | "on_creation" | "before_solo" | "manual" | null;
+  sort_order?: number;
+}
+
+export interface CreateFormSubmissionInput {
+  form_template_id: number;
+  data: Record<string, unknown>;
+  expires_at?: string | null;
+  notification_days_before?: number | null;
+}
+
+export interface ReviewFormSubmissionInput {
+  decision: "approved" | "rejected";
+  review_comment?: string | null;
+}

package/src/schemas/index.ts

@@ -1,6 +1,12 @@
 export * from "./common";
 export * from "./models";
 export * from "./faq";
-export * from "./fee";
 export * from "./safety-report";
 export * from "./report";
+export * from "./form-template";
+export * from "./training";
+export * from "./course-milestone";
+export * from "./equipment";
+export * from "./newsletter";
+export * from "./location-map";
+export * from "./todo";

package/src/schemas/location-map.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+
+// Minimal GeoJSON types (we don't depend on @types/geojson directly).
+
+export type GeoJsonGeometry =
+  | { type: "Point"; coordinates: number[] }
+  | { type: "MultiPoint"; coordinates: number[][] }
+  | { type: "LineString"; coordinates: number[][] }
+  | { type: "MultiLineString"; coordinates: number[][][] }
+  | { type: "Polygon"; coordinates: number[][][] }
+  | { type: "MultiPolygon"; coordinates: number[][][][] };
+
+export interface GeoJsonFeature<P = Record<string, unknown>> {
+  type: "Feature";
+  id?: number | string;
+  geometry: GeoJsonGeometry;
+  properties: P | null;
+}
+
+export interface GeoJsonFeatureCollection<P = Record<string, unknown>> {
+  type: "FeatureCollection";
+  features: GeoJsonFeature<P>[];
+}
+
+// ── Enums (mirror backend) ──
+
+export enum LocationMapKind {
+  Facility = "facility",
+  TrainingArea = "training_area",
+  Parking = "parking",
+  Procedural = "procedural",
+}
+
+export enum LocationFeatureVisibility {
+  Public = "public",
+  Members = "members",
+}
+
+export const ALLOWED_GEOMETRY_TYPES = [
+  "Point",
+  "MultiPoint",
+  "LineString",
+  "MultiLineString",
+  "Polygon",
+  "MultiPolygon",
+] as const;
+
+export type AllowedGeometryType = (typeof ALLOWED_GEOMETRY_TYPES)[number];
+
+// ── Viewport ──
+
+export const ViewportSchema = z.object({
+  center_lng: z.number().min(-180).max(180),
+  center_lat: z.number().min(-90).max(90),
+  zoom: z.number().min(0).max(24),
+  pitch: z.number().min(0).max(85).optional(),
+  bearing: z.number().min(-360).max(360).optional(),
+});
+
+export type Viewport = z.infer<typeof ViewportSchema>;
+
+// ── Geometry (loose GeoJSON-compatible) ──
+
+export const GeometrySchema = z.object({
+  type: z.enum(ALLOWED_GEOMETRY_TYPES),
+  coordinates: z.array(z.unknown()),
+});
+
+// ── LocationMap ──
+
+export interface LocationMap {
+  type: "location_map";
+  id: number;
+  company_id: number;
+  name: string;
+  slug: string;
+  kind: string;
+  description: string | null;
+  default_viewport: Viewport | null;
+  is_active: boolean;
+  created_by: number | null;
+  creator?: { id: number; firstname?: string; lastname?: string } | null;
+  features?: LocationMapFeature[];
+  created_at: string;
+  updated_at: string;
+}
+
+export const CreateLocationMapSchema = z.object({
+  name: z.string().min(1).max(255),
+  slug: z.string().min(1).max(255).optional(),
+  kind: z.string().max(64).optional(),
+  description: z.string().nullable().optional(),
+  default_viewport: ViewportSchema.nullable().optional(),
+  is_active: z.boolean().optional(),
+});
+export type CreateLocationMapInput = z.infer<typeof CreateLocationMapSchema>;
+
+export const UpdateLocationMapSchema = CreateLocationMapSchema.partial();
+export type UpdateLocationMapInput = z.infer<typeof UpdateLocationMapSchema>;
+
+// ── LocationMapFeature ──
+
+export interface LocationMapFeature {
+  type: "location_map_feature";
+  id: number;
+  location_map_id: number;
+  name: string | null;
+  kind: string;
+  visibility: LocationFeatureVisibility | string;
+  geometry: GeoJsonGeometry;
+  geometry_type: AllowedGeometryType | string;
+  properties: Record<string, unknown>;
+  display_order: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export const CreateLocationMapFeatureSchema = z.object({
+  name: z.string().max(255).nullable().optional(),
+  kind: z.string().min(1).max(64),
+  visibility: z.nativeEnum(LocationFeatureVisibility).optional(),
+  geometry: GeometrySchema,
+  properties: z.record(z.string(), z.unknown()).nullable().optional(),
+  display_order: z.number().int().min(0).optional(),
+});
+export type CreateLocationMapFeatureInput = z.infer<
+  typeof CreateLocationMapFeatureSchema
+>;
+
+export const UpdateLocationMapFeatureSchema =
+  CreateLocationMapFeatureSchema.partial().extend({
+    geometry: GeometrySchema.optional(),
+  });
+export type UpdateLocationMapFeatureInput = z.infer<
+  typeof UpdateLocationMapFeatureSchema
+>;
+
+// ── Bulk import ──
+
+export const ImportFeaturesSchema = z.object({
+  type: z.literal("FeatureCollection"),
+  features: z
+    .array(
+      z.object({
+        type: z.literal("Feature"),
+        geometry: GeometrySchema,
+        properties: z.record(z.string(), z.unknown()).nullable().optional(),
+      }),
+    )
+    .min(1)
+    .max(500),
+  defaults: z
+    .object({
+      kind: z.string().max(64).optional(),
+      visibility: z.nativeEnum(LocationFeatureVisibility).optional(),
+    })
+    .optional(),
+});
+export type ImportFeaturesInput = z.infer<typeof ImportFeaturesSchema>;
+
+// ── Viewer (GeoJSON FeatureCollection returned by API) ──
+
+export interface LocationMapGeoJsonProperties {
+  id: number;
+  name: string | null;
+  kind: string;
+  visibility: string;
+  display_order: number;
+  [key: string]: unknown;
+}
+
+export type LocationMapGeoJson =
+  GeoJsonFeatureCollection<LocationMapGeoJsonProperties>;
+export type LocationMapFeatureGeoJson =
+  GeoJsonFeature<LocationMapGeoJsonProperties>;