@updraft-solutions/mcrit-sdk 0.1.0

package/src/courses/index.ts

@@ -0,0 +1,202 @@
+import type { Dinero as DineroType } from "dinero.js";
+import { groupBy } from "lodash-es";
+
+import type { FeeLike, NetGross, ParsedPrice } from "../money/index.js";
+import { money, parseFee } from "../money/index.js";
+
+// Re-export commonly used money types so SDK consumers can import everything
+// they need from a single `@updraft-solutions/mcrit-sdk/courses` path.
+export type { NetGross, FeeLike, PriceLike, ParsedFee, ParsedPrice } from "../money/index.js";
+
+/**
+ * Permissive input shape for {@link parseCourse}. Course fees in
+ * different parts of the API are sometimes returned with pivot data
+ * nested in `pivot`, sometimes flattened on the fee object itself —
+ * this type supports both, and an optional nested `fee` field for the
+ * eager-loaded fee resource.
+ */
+export interface CourseFeeLike extends FeeLike {
+  pivot?: {
+    count?: number;
+    variant?: string | null;
+    is_optional?: boolean;
+    sort_order?: number;
+  };
+  count?: number;
+  variant?: string | null;
+  is_optional?: boolean;
+  sort_order?: number;
+  fee?: FeeLike;
+}
+
+/**
+ * Permissive input shape for {@link parseCourse}.
+ */
+export interface CourseLike {
+  id?: number;
+  fees?: CourseFeeLike[];
+  [key: string]: unknown;
+}
+
+export interface ParsedCourseFee {
+  fee: CourseFeeLike;
+  count: number;
+  variant: string;
+  isOptional: boolean;
+  sortOrder: number;
+  unitPrice: DineroType | null;
+  lineTotal: DineroType | null;
+  title: string;
+  hasUpcomingPrice: boolean;
+  upcomingPrice: DineroType | null;
+  upcomingPriceValidFrom: string | null;
+}
+
+export interface CourseVariant {
+  variant: string;
+  fees: ParsedCourseFee[];
+  totalCost: DineroType;
+}
+
+export interface ParsedCourse {
+  totalCost(netGross?: NetGross): DineroType | null;
+  feesWithCost(netGross?: NetGross): ParsedCourseFee[];
+  variants(netGross?: NetGross): CourseVariant[];
+}
+
+const DEFAULT_VARIANT = "default";
+
+function getPivotData(courseFee: CourseFeeLike) {
+  return {
+    count: courseFee.pivot?.count ?? courseFee.count ?? 1,
+    variant: courseFee.pivot?.variant ?? courseFee.variant ?? null,
+    isOptional: courseFee.pivot?.is_optional ?? courseFee.is_optional ?? false,
+    sortOrder: courseFee.pivot?.sort_order ?? courseFee.sort_order ?? 0,
+  };
+}
+
+function getFeeData(courseFee: CourseFeeLike): FeeLike {
+  return courseFee.fee ?? courseFee;
+}
+
+function getCourseFeeTitle(courseFee: CourseFeeLike): string {
+  const feeData = getFeeData(courseFee);
+  if (feeData.title) {
+    return feeData.title;
+  }
+  if (feeData.ident) {
+    return feeData.ident;
+  }
+  if (courseFee.id) {
+    return `Fee #${courseFee.id}`;
+  }
+  return "Unknown fee";
+}
+
+function sortBySortOrder<T extends { sortOrder: number }>(items: T[]): T[] {
+  return [...items].sort((a, b) => a.sortOrder - b.sortOrder);
+}
+
+function calculateTotal(parsedFees: ParsedCourseFee[]): DineroType {
+  return parsedFees.reduce<DineroType>(
+    (total, pf) => (pf.lineTotal ? total.add(pf.lineTotal) : total),
+    money(0),
+  );
+}
+
+function asDinero(price: DineroType | ParsedPrice | null): DineroType | null {
+  if (!price) {
+    return null;
+  }
+  if ("multiply" in price && typeof price.multiply === "function") {
+    return price as DineroType;
+  }
+  return null;
+}
+
+function parseCourseFee(courseFee: CourseFeeLike, netGross: NetGross): ParsedCourseFee {
+  const feeData = getFeeData(courseFee);
+  const pivotData = getPivotData(courseFee);
+  const parsed = parseFee(feeData);
+
+  const unitPrice = asDinero(parsed?.currentPrice(netGross) ?? null);
+  const lineTotal = unitPrice ? unitPrice.multiply(pivotData.count) : null;
+
+  const upcomingRaw = parsed?.upcomingPrice(null) ?? null;
+  const hasUpcomingPrice = upcomingRaw !== null;
+  const upcomingParsed = upcomingRaw && !("multiply" in upcomingRaw)
+    ? (upcomingRaw as ParsedPrice)
+    : null;
+  const upcomingPrice = upcomingParsed
+    ? (netGross === "net" ? upcomingParsed.net_total : upcomingParsed.gross_total)
+    : null;
+
+  return {
+    fee: courseFee,
+    count: pivotData.count,
+    variant: pivotData.variant || DEFAULT_VARIANT,
+    isOptional: pivotData.isOptional,
+    sortOrder: pivotData.sortOrder,
+    unitPrice,
+    lineTotal,
+    title: getCourseFeeTitle(courseFee),
+    hasUpcomingPrice,
+    upcomingPrice,
+    upcomingPriceValidFrom: upcomingParsed?.valid_from ?? null,
+  };
+}
+
+export function parseCourse(course: CourseLike | null | undefined): ParsedCourse | null {
+  if (!course) {
+    return null;
+  }
+
+  return {
+    totalCost(netGross: NetGross = "gross") {
+      const fees = course.fees ?? [];
+      if (fees.length === 0) {
+        return null;
+      }
+      const parsed = fees.map((f) => parseCourseFee(f, netGross));
+      const total = calculateTotal(parsed);
+      return total.getAmount() === 0 ? null : total;
+    },
+
+    feesWithCost(netGross: NetGross = "gross") {
+      const fees = course.fees ?? [];
+      return sortBySortOrder(fees.map((f) => parseCourseFee(f, netGross)));
+    },
+
+    variants(netGross: NetGross = "gross") {
+      const fees = course.fees ?? [];
+      if (fees.length === 0) {
+        return [];
+      }
+
+      const parsed = fees.map((f) => parseCourseFee(f, netGross));
+      const grouped = groupBy(parsed, (pf) => pf.variant);
+      const commonFees = grouped[DEFAULT_VARIANT] ?? [];
+
+      if (Object.keys(grouped).length === 1 && commonFees.length > 0) {
+        return [
+          {
+            variant: DEFAULT_VARIANT,
+            fees: sortBySortOrder(commonFees),
+            totalCost: calculateTotal(commonFees),
+          },
+        ];
+      }
+
+      return Object.entries(grouped)
+        .filter(([variant]) => variant !== DEFAULT_VARIANT)
+        .map(([variant, variantFees]) => {
+          const all = sortBySortOrder([...variantFees, ...commonFees]);
+          return {
+            variant,
+            fees: all,
+            totalCost: calculateTotal(all),
+          };
+        });
+    },
+  };
+}

package/src/crew/index.ts

@@ -0,0 +1,255 @@
+/**
+ * Crew configuration consumer for the MCRIT SDK.
+ *
+ * No crew-role data lives in this module — the canonical source is the
+ * backend `App\Crew\CrewConfiguration`, served via `GET /meta/crew`.
+ * Apps fetch the config once at boot, hand it to `createCrewValidator`,
+ * and use the returned validator to drive UI feedback on a live crew
+ * list.
+ */
+
+export interface PositionAttributes {
+  picPriority: number | null;
+  isOnBoard: boolean;
+  isInstructorClass: boolean;
+  isTrainingRole: boolean;
+}
+
+export interface PositionDefinition extends PositionAttributes {
+  name: string;
+}
+
+export type Constraint =
+  | { kind: "single_pic" }
+  | { kind: "min_members"; min: number }
+  | {
+      kind: "when_crew_contains_role_requires_one_of";
+      when_role: string;
+      required_roles: string[];
+      message_key: string | null;
+    }
+  | {
+      kind: "when_any_membership_has_system_role_requires_one_of";
+      system_role: string;
+      required_roles: string[];
+      message_key: string | null;
+    };
+
+export type ConstraintKind = Constraint["kind"];
+
+export interface CrewConfig {
+  version: number;
+  positions: Record<string, PositionDefinition>;
+  pic_priority: string[];
+  constraints: Constraint[];
+}
+
+export interface MembershipRoleHolder {
+  roles?: { name: string; company_id?: number | null }[] | null;
+}
+
+/**
+ * True iff the membership holds the given *system* (global, company-less)
+ * role. Pure helper that operates on the membership payload's `roles`
+ * array — unrelated to the per-flight crew validator.
+ */
+export function hasMembershipRole(
+  membership: MembershipRoleHolder | null | undefined,
+  roleName: string,
+): boolean {
+  return membership?.roles?.some((r) => r.name === roleName) ?? false;
+}
+
+/**
+ * UX nicety: smart-default the crew-position dropdown when adding a new
+ * crew member, based on the membership's system roles. Returns the crew
+ * position string ("student" / "instructor" / "pilot"). Not a validation
+ * rule and intentionally divorced from the validator — adding a new
+ * default mapping only requires changing this one function.
+ */
+export function defaultCrewRoleForMembership(
+  membership: MembershipRoleHolder | null | undefined,
+): string {
+  if (hasMembershipRole(membership, "student")) {
+    return "student";
+  }
+  if (hasMembershipRole(membership, "instructor")) {
+    return "instructor";
+  }
+  return "pilot";
+}
+
+export interface CrewEntry {
+  role: string;
+  membership_id?: number | null;
+  membership?: MembershipRoleHolder | null;
+}
+
+export interface Violation {
+  kind: ConstraintKind;
+  message_key: string | null;
+  details?: Record<string, unknown>;
+}
+
+export type PicResolution =
+  | { type: "ok"; index: number; role: string }
+  | { type: "tie"; role: string }
+  | { type: "none" };
+
+export interface CrewValidator {
+  /** True iff the named role exists in the config and is `isOnBoard`. */
+  isOnBoardRole(role: string): boolean;
+  isInstructorClassRole(role: string): boolean;
+  isPicEligibleRole(role: string): boolean;
+  /** Resolves the single PIC by walking `config.pic_priority`. */
+  resolvePic(crew: readonly CrewEntry[]): PicResolution;
+  /** Returns every constraint violation found in the composition. */
+  evaluate(crew: readonly CrewEntry[]): { ok: boolean; violations: Violation[] };
+}
+
+/**
+ * Build a validator over a specific crew configuration. The validator is
+ * pure and stateless beyond the config it closed over; safe to share
+ * across components.
+ */
+export function createCrewValidator(config: CrewConfig): CrewValidator {
+  function attributesOf(role: string): PositionAttributes | undefined {
+    return config.positions[role];
+  }
+
+  function rolesFromCrew(crew: readonly CrewEntry[]): string[] {
+    return crew.map((c) => c.role).filter((r): r is string => typeof r === "string");
+  }
+
+  function membershipsWithSystemRole(
+    crew: readonly CrewEntry[],
+    systemRole: string,
+  ): readonly CrewEntry[] {
+    return crew.filter((c) =>
+      c.membership?.roles?.some(
+        (r) => r.name === systemRole && (r.company_id == null || r.company_id === null),
+      ),
+    );
+  }
+
+  function evaluateConstraint(
+    constraint: Constraint,
+    crew: readonly CrewEntry[],
+  ): Violation | null {
+    switch (constraint.kind) {
+      case "single_pic": {
+        if (crew.length === 0) {
+          return null;
+        }
+        const roles = rolesFromCrew(crew);
+        for (const eligibleRole of config.pic_priority) {
+          const matches = roles.filter((r) => r === eligibleRole).length;
+          if (matches === 1) {
+            return null;
+          }
+          if (matches > 1) {
+            return {
+              kind: constraint.kind,
+              message_key: "crew.multiple_same_pic_role",
+              details: { role: eligibleRole },
+            };
+          }
+        }
+        return {
+          kind: constraint.kind,
+          message_key: "crew.no_eligible_pic",
+        };
+      }
+
+      case "min_members": {
+        if (crew.length >= constraint.min) {
+          return null;
+        }
+        return {
+          kind: constraint.kind,
+          message_key: "crew.min_members",
+          details: { min: constraint.min, actual: crew.length },
+        };
+      }
+
+      case "when_crew_contains_role_requires_one_of": {
+        const roles = rolesFromCrew(crew);
+        if (!roles.includes(constraint.when_role)) {
+          return null;
+        }
+        const satisfied = constraint.required_roles.some((r) => roles.includes(r));
+        if (satisfied) {
+          return null;
+        }
+        return {
+          kind: constraint.kind,
+          message_key: constraint.message_key,
+          details: {
+            when_role: constraint.when_role,
+            required_roles: constraint.required_roles,
+          },
+        };
+      }
+
+      case "when_any_membership_has_system_role_requires_one_of": {
+        const flagged = membershipsWithSystemRole(crew, constraint.system_role);
+        if (flagged.length === 0) {
+          return null;
+        }
+        const roles = rolesFromCrew(crew);
+        const satisfied = constraint.required_roles.some((r) => roles.includes(r));
+        if (satisfied) {
+          return null;
+        }
+        return {
+          kind: constraint.kind,
+          message_key: constraint.message_key,
+          details: {
+            system_role: constraint.system_role,
+            required_roles: constraint.required_roles,
+            membership_ids: flagged.map((c) => c.membership_id).filter((id) => id != null),
+          },
+        };
+      }
+    }
+  }
+
+  return {
+    isOnBoardRole: (role) => attributesOf(role)?.isOnBoard ?? false,
+    isInstructorClassRole: (role) => attributesOf(role)?.isInstructorClass ?? false,
+    isPicEligibleRole: (role) => attributesOf(role)?.picPriority != null,
+
+    resolvePic(crew) {
+      if (crew.length === 0) {
+        return { type: "none" };
+      }
+      const roles = rolesFromCrew(crew);
+      for (const eligibleRole of config.pic_priority) {
+        const indexes: number[] = [];
+        roles.forEach((r, i) => {
+          if (r === eligibleRole) {
+            indexes.push(i);
+          }
+        });
+        if (indexes.length === 1) {
+          return { type: "ok", index: indexes[0]!, role: eligibleRole };
+        }
+        if (indexes.length > 1) {
+          return { type: "tie", role: eligibleRole };
+        }
+      }
+      return { type: "none" };
+    },
+
+    evaluate(crew) {
+      const violations: Violation[] = [];
+      for (const constraint of config.constraints) {
+        const violation = evaluateConstraint(constraint, crew);
+        if (violation !== null) {
+          violations.push(violation);
+        }
+      }
+      return { ok: violations.length === 0, violations };
+    },
+  };
+}

package/src/crew/vue.ts

@@ -0,0 +1,70 @@
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from "vue";
+
+import { createCrewValidator } from "./index.js";
+import type {
+  CrewConfig,
+  CrewEntry,
+  CrewValidator,
+  PicResolution,
+  Violation,
+} from "./index.js";
+
+export interface UseCrewValidatorResult {
+  /** The validator instance (null while config hasn't loaded yet). */
+  validator: ComputedRef<CrewValidator | null>;
+  /** PIC walk result over the current crew. */
+  pic: ComputedRef<PicResolution>;
+  /** Every constraint violation in the current crew. */
+  violations: ComputedRef<Violation[]>;
+  /** True iff PIC resolves cleanly AND no violations are present. */
+  isValid: ComputedRef<boolean>;
+  /** True iff the role exists in the config and is on-board. */
+  isOnBoardRole: (role: string) => boolean;
+  /** True iff the role is an instructor variant. */
+  isInstructorClassRole: (role: string) => boolean;
+  /** True iff the role can hold PIC. */
+  isPicEligibleRole: (role: string) => boolean;
+}
+
+/**
+ * Reactive Vue composable over an SDK `CrewValidator`. Pass the live
+ * crew array and the (possibly-loading) crew config; outputs update as
+ * either reference changes.
+ *
+ * `configRef` may be null while the app is fetching `/meta/crew`; the
+ * computed properties cleanly degrade to a `none` PIC and empty
+ * violations during that window.
+ */
+export function useCrewValidator(
+  crewRef: MaybeRefOrGetter<readonly CrewEntry[] | null | undefined>,
+  configRef: MaybeRefOrGetter<CrewConfig | null | undefined>,
+): UseCrewValidatorResult {
+  const validator = computed<CrewValidator | null>(() => {
+    const cfg = toValue(configRef);
+    return cfg ? createCrewValidator(cfg) : null;
+  });
+
+  const crew = computed<readonly CrewEntry[]>(() => toValue(crewRef) ?? []);
+
+  const pic = computed<PicResolution>(() =>
+    validator.value ? validator.value.resolvePic(crew.value) : { type: "none" },
+  );
+
+  const violations = computed<Violation[]>(() =>
+    validator.value ? validator.value.evaluate(crew.value).violations : [],
+  );
+
+  const isValid = computed<boolean>(
+    () => violations.value.length === 0 && pic.value.type === "ok",
+  );
+
+  return {
+    validator,
+    pic,
+    violations,
+    isValid,
+    isOnBoardRole: (role) => validator.value?.isOnBoardRole(role) ?? false,
+    isInstructorClassRole: (role) => validator.value?.isInstructorClassRole(role) ?? false,
+    isPicEligibleRole: (role) => validator.value?.isPicEligibleRole(role) ?? false,
+  };
+}