@updraft-solutions/mcrit-sdk 0.3.1 → 0.5.0

package/src/schemas/models.ts

@@ -11,6 +11,8 @@ import {
   zNetGross,
   zPhpMoneyObject,
 } from "./common";
+import { equipmentSchema } from "./equipment";
+import { courseCheckSyllabusSchema } from "./training";
 
 export const baseMembershipSchema = z.object({
   type: z.literal("membership"),
@@ -88,33 +90,58 @@ export const feeSchema = BaseModel.extend({
   id: z.number(),
   price: priceSchema.optional(),
   prices: z.array(priceSchema).optional(),
-  provider: z.string().optional(),
+  provider: z.string().nullable().optional(),
   company_id: z.number().optional(),
   company: companySchema.optional(),
   ident: z.string().optional(),
   category: z.string().optional(),
-  subcategory: z.string().optional(),
+  subcategory: z.string().nullable().optional(),
   title: z.string().optional(),
+  internal_title: z.string().nullable().optional(),
+  // internal_title falling back to title, resolved server-side.
+  display_title: z.string().optional(),
+  // Course-derived fees (source course + which course fee spawned them).
+  source_course_id: z.number().nullable().optional(),
+  source_key: z.string().nullable().optional(),
+  is_derived: z.boolean().optional(),
   relation: z
     .array(z.enum(["booking", "flightLog", "invoice", "instructor"]))
+    .nullable()
     .optional(),
-  payment_per: z.string().optional(),
-  can: z
-    .object({
-      update: zNullableBool,
-      delete: zNullableBool,
-    })
-    .optional(),
+  payment_per: z.string().nullable().optional(),
+  can: z.record(z.string(), zNullableBool).optional(),
   course_count: z.number().optional(),
+  // feeables-pivot fields, present when the fee is serialized through an
+  // attachment (course/enrollment listings).
   count: z.number().optional(),
-  variant: z.string().optional(),
+  variant: z.string().nullable().optional(),
   is_optional: z.boolean().optional(),
+  sort_order: z.number().nullable().optional(),
+  is_initial_payment: z.boolean().optional(),
+  feeables: z
+    .array(
+      z.object({
+        feeable_id: z.number(),
+        feeable_type: z.string(),
+        count: z.number().nullable(),
+        variant: z.string().nullable(),
+        is_optional: z.boolean().nullable(),
+        is_initial_payment: z.boolean().nullable(),
+        sort_order: z.number().nullable(),
+      }),
+    )
+    .optional(),
   input_value: z.number().optional(),
   net_gross: zNetGross,
   tax_percentage: z.string().optional(),
   valid_from: z.string(),
 });
 
+export const feeCategoryOptionsSchema = z.object({
+  categories: z.array(z.string()),
+  subcategories: z.record(z.string(), z.array(z.string())),
+});
+
 export const courseFeeSchema = feeSchema.extend({
   count: z.number().optional(),
   variant: z.string().optional(),
@@ -265,11 +292,19 @@ export const userQualificationSchema = z.object({
 });
 
 export const airportSchema = z.object({
-  type: z.literal("airport"),
+  // Aligned with what AirportResource actually serializes: `type` and
+  // `country` are absent on minified payloads (e.g. booking waypoint
+  // airports); coordinates + municipality/iso_country ride along on the
+  // full shape.
+  type: z.literal("airport").optional(),
   id: z.number(),
   ident: z.string(),
   name: z.string(),
-  country: z.string(),
+  country: z.string().optional(),
+  municipality: z.string().nullable().optional(),
+  iso_country: z.string().nullable().optional(),
+  latitude_deg: z.number().nullable().optional(),
+  longitude_deg: z.number().nullable().optional(),
 });
 
 export const recurringFlightSchema = z.object({
@@ -340,7 +375,7 @@ export const extendedAirplaneSchema = airplaneSchema.extend({
   VFRNight: z.boolean().optional(),
   IFR: z.boolean().optional(),
   IFRKnownIcing: z.boolean().optional(),
-  equipment: z.array(z.any()).optional(),
+  equipment: z.array(equipmentSchema).optional(),
   contact: contactAttributeSchema.optional(),
   hints: z
     .object({
@@ -387,6 +422,26 @@ export const availSchema = z.object({
     .optional(),
 });
 
+// Ordered via-airport on a booking's route (BookingResource `waypoints`).
+// Airports arrive minified (no `type` literal), hence the dedicated shape.
+// Distinct from the nav-fix `waypointSchema` further down — do not merge.
+export const bookingWaypointSchema = z.object({
+  sequence: z.number(),
+  airport_id: z.number(),
+  airport: z
+    .object({
+      id: z.number(),
+      ident: z.string(),
+      name: z.string(),
+      municipality: z.string().nullable().optional(),
+      iso_country: z.string().nullable().optional(),
+      latitude_deg: z.number().nullable().optional(),
+      longitude_deg: z.number().nullable().optional(),
+    })
+    .nullable()
+    .optional(),
+});
+
 export const bookingSchema = BaseModel.extend({
   type: z.literal("booking"),
   ifr: z.boolean().default(false),
@@ -403,6 +458,15 @@ export const bookingSchema = BaseModel.extend({
   destination_airport_id: z.number().optional(),
   departure_airport: airportSchema.optional(),
   destination_airport: airportSchema.optional(),
+  waypoints: z.array(bookingWaypointSchema).optional(),
+  // Flat, always-present home timezone on BookingResource.
+  company_timezone: z.string().nullable().optional(),
+  // Slim per-booking training-record status, present when the backend
+  // eager-loaded `trainingRecord` (enrollment bookings surfaces).
+  training_record_status: z
+    .enum(["draft", "awaiting_signatures", "signed"])
+    .nullable()
+    .optional(),
   next_booking_id: z.number().nullable().optional(),
   previous_booking_id: z.number().nullable().optional(),
   maintenance: z.number().optional(),
@@ -797,6 +861,15 @@ export const expenseSchema = z.object({
     .optional(),
 });
 
+// Company-scoped tag (shared pool across taggable models — see
+// m-crit-api docs/features/tags.md).
+export const tagSchema = z.object({
+  type: z.literal("tag").optional(),
+  id: z.number(),
+  name: z.string(),
+  color: z.string().nullable().optional(),
+});
+
 export const courseSchema = z.object({
   type: z.literal("course"),
   id: z.number(),
@@ -813,15 +886,25 @@ export const courseSchema = z.object({
   aircraft_required: z.boolean().default(false),
   qualification_id: z.number().nullable().optional(),
   qualification: qualificationSchema.optional(),
+  is_archived: z.boolean().optional(),
+  archived_at: z.string().nullable().optional(),
+  category: z.string().nullable().optional(),
+  title: z.string().nullable().optional(),
+  subtitle: z.string().nullable().optional(),
+  content: z.string().nullable().optional(),
+  footer: z.string().nullable().optional(),
+  // Syllabus assignment pointers: `syllabus_id` drives the Übersicht,
+  // `booking_form_syllabus_id` the per-flight Ausbildungsnachweis.
+  syllabus_id: z.number().nullable().optional(),
+  booking_form_syllabus_id: z.number().nullable().optional(),
+  // Present only when the backend eager-loaded `checkSyllabi`.
+  check_syllabi: z.array(courseCheckSyllabusSchema).optional(),
+  tags: z.array(tagSchema).optional(),
   created_at: z.string(),
   updated_at: z.string(),
-  can: z
-    .object({
-      update: zNullableBool,
-      delete: zNullableBool,
-      enroll: zNullableBool,
-    })
-    .optional(),
+  // Loose record on purpose: gates are policy-reflected server-side and
+  // grow over time (useAssistant, …) — same convention as companySchema.
+  can: z.record(z.string(), zNullableBool).optional(),
 });
 
 /**
@@ -854,20 +937,19 @@ export const courseEnrollmentSchema = z.object({
   comments: z.string().nullable().optional(),
   initial_payment_generated: z.boolean().optional(),
   initial_payment_removable: z.boolean().optional(),
+  // Element-driven training progress (see m-crit-api
+  // docs/features/training-tracking.md).
+  tracked_training_elements_count: z.number().optional(),
+  progress_source: z.enum(["training_elements", "milestones"]).optional(),
   metrics: courseEnrollmentMetricsSchema.optional(),
   created_at: z.string(),
   updated_at: z.string(),
   course: courseSchema.optional(),
   membership: membershipSchema.optional(),
   mentor: userSchema.optional(),
-  can: z
-    .object({
-      view: zNullableBool,
-      update: zNullableBool,
-      delete: zNullableBool,
-      complete: zNullableBool,
-    })
-    .optional(),
+  // Loose record on purpose: gates are policy-reflected server-side and
+  // grow over time (updateTraining, manageInitialPayment, …).
+  can: z.record(z.string(), zNullableBool).optional(),
 });
 
 export const eventSchema = z.object({

package/src/schemas/newsletter.ts

@@ -0,0 +1,362 @@
+import { z } from "zod";
+
+/*
+|------------------------------------------------------------------------
+| Block schemas
+|------------------------------------------------------------------------
+|
+| v1 supports heading / paragraph / button / divider. Paragraph content
+| is stored as TipTap JSON on `doc` so variable tokens survive
+| sanitisation. The server converts `variable` nodes to `{{name}}` at
+| render time.
+*/
+
+export enum NewsletterBlockType {
+  Heading = "heading",
+  Paragraph = "paragraph",
+  Button = "button",
+  Divider = "divider",
+}
+
+export const TipTapNodeSchema: z.ZodType<TipTapNode> = z.lazy(() =>
+  z.object({
+    type: z.string(),
+    attrs: z.record(z.any()).optional(),
+    content: z.array(TipTapNodeSchema).optional(),
+    marks: z.array(z.record(z.any())).optional(),
+    text: z.string().optional(),
+  }),
+);
+
+export interface TipTapNode {
+  type: string;
+  attrs?: Record<string, unknown>;
+  content?: TipTapNode[];
+  marks?: Array<Record<string, unknown>>;
+  text?: string;
+}
+
+const Align = z.enum(["left", "center", "right"]).optional();
+
+export const HeadingBlockSchema = z.object({
+  key: z.string(),
+  type: z.literal(NewsletterBlockType.Heading),
+  level: z.number().int().min(1).max(3).default(1),
+  text: z.string(),
+  align: Align,
+});
+
+export const ParagraphBlockSchema = z.object({
+  key: z.string(),
+  type: z.literal(NewsletterBlockType.Paragraph),
+  doc: TipTapNodeSchema,
+  align: Align,
+});
+
+export const ButtonBlockSchema = z.object({
+  key: z.string(),
+  type: z.literal(NewsletterBlockType.Button),
+  label: z.string(),
+  url: z.string(),
+  align: Align,
+  color: z.string().optional(),
+});
+
+export const DividerBlockSchema = z.object({
+  key: z.string(),
+  type: z.literal(NewsletterBlockType.Divider),
+  thickness: z.number().int().min(1).max(10).optional(),
+  color: z.string().optional(),
+});
+
+export const NewsletterBlockSchema = z.discriminatedUnion("type", [
+  HeadingBlockSchema,
+  ParagraphBlockSchema,
+  ButtonBlockSchema,
+  DividerBlockSchema,
+]);
+
+export type HeadingBlock = z.infer<typeof HeadingBlockSchema>;
+export type ParagraphBlock = z.infer<typeof ParagraphBlockSchema>;
+export type ButtonBlock = z.infer<typeof ButtonBlockSchema>;
+export type DividerBlock = z.infer<typeof DividerBlockSchema>;
+export type NewsletterBlock = z.infer<typeof NewsletterBlockSchema>;
+
+/*
+|------------------------------------------------------------------------
+| Category
+|------------------------------------------------------------------------
+*/
+
+export const NewsletterCategorySchema = z.object({
+  type: z.literal("newsletter_category").optional(),
+  id: z.number(),
+  key: z.string(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  is_mandatory: z.boolean(),
+  is_active: z.boolean(),
+  sort_order: z.number().int(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+
+export type NewsletterCategory = z.infer<typeof NewsletterCategorySchema>;
+
+/*
+|------------------------------------------------------------------------
+| Template
+|------------------------------------------------------------------------
+*/
+
+const UserBasicSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    email: z.string().optional(),
+  })
+  .nullable();
+
+export const NewsletterTemplateSchemaSchema = z.object({
+  blocks: z.array(NewsletterBlockSchema),
+  variables_used: z.array(z.string()).optional(),
+});
+
+export type NewsletterTemplateDoc = z.infer<typeof NewsletterTemplateSchemaSchema>;
+
+export const NewsletterTemplateSchema = z.object({
+  type: z.literal("newsletter_template").optional(),
+  id: z.number(),
+  company_id: z.number().nullable(),
+  is_system: z.boolean().optional(),
+  newsletter_category_id: z.number(),
+  category: NewsletterCategorySchema.nullish(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable().optional(),
+  subject: z.string(),
+  preheader: z.string().nullable().optional(),
+  schema: NewsletterTemplateSchemaSchema,
+  schema_version: z.number().int(),
+  is_active: z.boolean(),
+  created_by: z.number().nullable().optional(),
+  creator: UserBasicSchema.optional(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+
+export type NewsletterTemplate = z.infer<typeof NewsletterTemplateSchema>;
+
+export const CreateNewsletterTemplateInputSchema = z.object({
+  newsletter_category_id: z.number(),
+  name: z.string().min(1),
+  slug: z.string().optional(),
+  description: z.string().nullable().optional(),
+  subject: z.string().min(1),
+  preheader: z.string().nullable().optional(),
+  schema: NewsletterTemplateSchemaSchema,
+  is_active: z.boolean().optional(),
+});
+
+export type CreateNewsletterTemplateInput = z.infer<typeof CreateNewsletterTemplateInputSchema>;
+export type UpdateNewsletterTemplateInput = Partial<CreateNewsletterTemplateInput>;
+
+/*
+|------------------------------------------------------------------------
+| Audience
+|------------------------------------------------------------------------
+*/
+
+export enum AudienceBucketType {
+  AllUsers = "all_users",
+  CompanyUsers = "company_users",
+  RoleMembers = "role_members",
+}
+
+export const AllUsersBucketSchema = z.object({ type: z.literal(AudienceBucketType.AllUsers) });
+export const CompanyUsersBucketSchema = z.object({
+  type: z.literal(AudienceBucketType.CompanyUsers),
+  company_ids: z.array(z.number()).min(1),
+});
+export const RoleMembersBucketSchema = z.object({
+  type: z.literal(AudienceBucketType.RoleMembers),
+  role_ids: z.array(z.number()).min(1),
+});
+
+export const AudienceBucketSchema = z.discriminatedUnion("type", [
+  AllUsersBucketSchema,
+  CompanyUsersBucketSchema,
+  RoleMembersBucketSchema,
+]);
+
+export const NewsletterAudienceSchema = z.object({
+  version: z.literal(1),
+  include: z.array(AudienceBucketSchema).min(1),
+  exclude: z
+    .object({
+      emails: z.array(z.string().email()).optional(),
+      user_ids: z.array(z.number()).optional(),
+    })
+    .optional(),
+});
+
+export type AudienceBucket = z.infer<typeof AudienceBucketSchema>;
+export type NewsletterAudience = z.infer<typeof NewsletterAudienceSchema>;
+
+/**
+ * Company-admin audience rule: the role selection is the sole determinant.
+ * No roles selected → the whole company (company_users). One or more roles
+ * → only those role-holders (role_members), and the company-wide bucket is
+ * dropped so the send-time union (ResolveCampaignAudienceAction) cannot
+ * widen the audience back to everyone.
+ */
+export function companyAudienceInclude(
+  companyId: number,
+  roleIds: number[],
+): AudienceBucket[] {
+  return roleIds.length > 0
+    ? [{ type: AudienceBucketType.RoleMembers, role_ids: roleIds }]
+    : [{ type: AudienceBucketType.CompanyUsers, company_ids: [companyId] }];
+}
+
+/*
+|------------------------------------------------------------------------
+| Campaign
+|------------------------------------------------------------------------
+*/
+
+export enum NewsletterCampaignStatus {
+  Draft = "draft",
+  Scheduled = "scheduled",
+  Sending = "sending",
+  Sent = "sent",
+  Failed = "failed",
+  Cancelled = "cancelled",
+}
+
+export const NewsletterCampaignSchema = z.object({
+  type: z.literal("newsletter_campaign").optional(),
+  id: z.number(),
+  company_id: z.number().nullable(),
+  is_system: z.boolean().optional(),
+  newsletter_template_id: z.number().nullable(),
+  template: NewsletterTemplateSchema.partial().nullish(),
+  newsletter_category_id: z.number(),
+  category: NewsletterCategorySchema.nullish(),
+  name: z.string(),
+  subject: z.string(),
+  preheader: z.string().nullable().optional(),
+  schema_snapshot: NewsletterTemplateSchemaSchema,
+  variables: z.record(z.string()).nullable().optional(),
+  audience_definition: NewsletterAudienceSchema,
+  status: z.nativeEnum(NewsletterCampaignStatus),
+  scheduled_at: z.string().nullable().optional(),
+  started_at: z.string().nullable().optional(),
+  finished_at: z.string().nullable().optional(),
+  cancelled_at: z.string().nullable().optional(),
+  counts: z.object({
+    queued: z.number().nullable(),
+    sent: z.number(),
+    failed: z.number(),
+    bounced: z.number(),
+    complained: z.number(),
+  }),
+  sent_by_user_id: z.number().nullable().optional(),
+  sent_by: UserBasicSchema.optional(),
+  can: z
+    .object({
+      update: z.boolean(),
+      schedule: z.boolean(),
+      send: z.boolean(),
+      cancel: z.boolean(),
+      test_send: z.boolean(),
+      delete: z.boolean(),
+    })
+    .partial()
+    .optional(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+
+export type NewsletterCampaign = z.infer<typeof NewsletterCampaignSchema>;
+
+export const CreateNewsletterCampaignInputSchema = z.object({
+  newsletter_template_id: z.number().nullable().optional(),
+  newsletter_category_id: z.number().optional(),
+  name: z.string().min(1),
+  subject: z.string().optional(),
+  preheader: z.string().nullable().optional(),
+  schema_snapshot: NewsletterTemplateSchemaSchema.optional(),
+  variables: z.record(z.string()).optional(),
+  audience_definition: NewsletterAudienceSchema,
+});
+
+export type CreateNewsletterCampaignInput = z.infer<typeof CreateNewsletterCampaignInputSchema>;
+export type UpdateNewsletterCampaignInput = Partial<CreateNewsletterCampaignInput>;
+
+/*
+|------------------------------------------------------------------------
+| Recipient
+|------------------------------------------------------------------------
+*/
+
+export enum NewsletterRecipientStatus {
+  Queued = "queued",
+  Sent = "sent",
+  Failed = "failed",
+  Bounced = "bounced",
+  Complained = "complained",
+  Suppressed = "suppressed",
+  OptedOut = "opted_out",
+}
+
+export const NewsletterCampaignRecipientSchema = z.object({
+  type: z.literal("newsletter_campaign_recipient").optional(),
+  id: z.number(),
+  newsletter_campaign_id: z.number(),
+  user_id: z.number().nullable(),
+  user: UserBasicSchema.optional(),
+  email: z.string(),
+  status: z.nativeEnum(NewsletterRecipientStatus),
+  error: z.string().nullable().optional(),
+  message_id: z.string().nullable().optional(),
+  queued_at: z.string().nullable().optional(),
+  sent_at: z.string().nullable().optional(),
+  bounced_at: z.string().nullable().optional(),
+  complained_at: z.string().nullable().optional(),
+});
+
+export type NewsletterCampaignRecipient = z.infer<typeof NewsletterCampaignRecipientSchema>;
+
+/*
+|------------------------------------------------------------------------
+| Preference (per-user per-category)
+|------------------------------------------------------------------------
+*/
+
+export const NewsletterPreferenceRowSchema = z.object({
+  category_id: z.number(),
+  category_key: z.string(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  is_mandatory: z.boolean(),
+  opted_in: z.boolean(),
+});
+
+export type NewsletterPreferenceRow = z.infer<typeof NewsletterPreferenceRowSchema>;
+
+/*
+|------------------------------------------------------------------------
+| Variable allowlist (must mirror backend NewsletterBlocksValidator)
+|------------------------------------------------------------------------
+*/
+
+export const ALLOWED_NEWSLETTER_VARIABLES = [
+  "user.name",
+  "user.first_name",
+  "user.email",
+  "company.name",
+  "unsubscribe_url",
+] as const;
+
+export type AllowedNewsletterVariable = (typeof ALLOWED_NEWSLETTER_VARIABLES)[number];

package/src/schemas/todo.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+export const TodoActionSchema = z.object({
+  type: z.enum(["open_dialog", "navigate"]),
+  target: z.string(),
+  params: z.record(z.any()).optional(),
+});
+
+export const TodoKey = z.enum([
+  "fill_form",
+  "sign_form",
+  "review_form",
+  "log_booking",
+  "add_address",
+  "add_required_documents",
+  "fill_training_record",
+  "sign_training_record",
+]);
+
+export const TodoSchema = z.object({
+  key: TodoKey,
+  ref_type: z.string(),
+  ref_id: z.number(),
+  title: z.string(),
+  subtitle: z.string().nullable().optional(),
+  due_date: z.string().nullable().optional(),
+  is_overdue: z.boolean().default(false),
+  priority: z.enum(["low", "normal", "high"]).default("normal"),
+  company_id: z.number().nullable().optional(),
+  action: TodoActionSchema,
+  meta: z.record(z.any()).optional(),
+});
+
+export type Todo = z.infer<typeof TodoSchema>;
+export type TodoAction = z.infer<typeof TodoActionSchema>;
+
+/**
+ * Shape of one entry in `meta.accepted_alternatives` on
+ * `add_required_documents` todos — the other templates of the requirement's
+ * OR bucket that would satisfy it equally (backend:
+ * MissingDocumentTodoSource::selectOrAlternative()).
+ */
+export interface TodoAcceptedAlternative {
+  form_template_id: number;
+  form_template_name: string | null;
+}