@updraft-solutions/mcrit-sdk 0.1.0

package/src/format/index.ts

@@ -0,0 +1,265 @@
+import moment from "moment-timezone";
+
+const DEFAULT_TZ = "UTC";
+
+/**
+ * Note on German locale: the SDK does not eagerly load `moment/locale/de`.
+ * Consumers that want German formatting should import it once at their
+ * app entry: `import "moment/locale/de"`. Otherwise `timeUntil` and other
+ * locale-dependent functions will fall back to English.
+ */
+
+/** Predefined moment format strings, frozen so callers can reference them safely. */
+export const DATE_FORMATS = Object.freeze({
+  DATE: "DD.MM.YYYY",
+  TIME: "HH:mm",
+  TIME_TZ: "HH:mm z",
+  DATETIME: "DD.MM.YYYY HH:mm",
+  DATETIME_TZ: "DD.MM.YYYY HH:mm z",
+  YEAR: "YYYY",
+  DAY: "DD",
+  MONTH_SHORT: "MMM",
+} as const);
+
+export const TIME_FORMATS = Object.freeze({
+  TIME: "HH:mm",
+  TIME_WITH_SECONDS: "HH:mm:ss",
+} as const);
+
+export type DateFormat = (typeof DATE_FORMATS)[keyof typeof DATE_FORMATS];
+export type TimeFormat = (typeof TIME_FORMATS)[keyof typeof TIME_FORMATS];
+
+function isValidDate(date: unknown): boolean {
+  return moment(date as moment.MomentInput).isValid();
+}
+
+function isValidDateStrict(date: unknown): boolean {
+  return (
+    typeof date === "string" &&
+    /^\d{4}-\d{2}-\d{2}$/.test(date) &&
+    moment(date, "YYYY-MM-DD", true).isValid()
+  );
+}
+
+/**
+ * Format a strict `YYYY-MM-DD` date string with the given moment format.
+ * Returns `""` for invalid input.
+ */
+export function formatDate(
+  date: string | null | undefined,
+  format: string = DATE_FORMATS.DATE,
+  locale: string = "de",
+): string {
+  if (!isValidDateStrict(date)) {
+    return "";
+  }
+  return moment(date as string, "YYYY-MM-DD").locale(locale).format(format);
+}
+
+/**
+ * Normalize an `HH:mm[:ss]`-ish string into a chosen format. Pads
+ * components and clamps each to its valid range.
+ */
+export function formatTime(
+  time: string | null | undefined,
+  format: string = TIME_FORMATS.TIME,
+): string {
+  if (typeof time !== "string" || !time) {
+    return "";
+  }
+
+  const parts = time
+    .trim()
+    .split(/[:.\s]/)
+    .map(Number)
+    .filter((n) => !Number.isNaN(n));
+
+  const [hh = 0, mm = 0, ss = 0] = parts;
+  const safeHH = Math.min(Math.max(hh, 0), 23);
+  const safeMM = Math.min(Math.max(mm, 0), 59);
+  const safeSS = Math.min(Math.max(ss, 0), 59);
+  const pad = (n: number) => n.toString().padStart(2, "0");
+
+  if (format === TIME_FORMATS.TIME) {
+    return `${pad(safeHH)}:${pad(safeMM)}`;
+  }
+  return `${pad(safeHH)}:${pad(safeMM)}:${pad(safeSS)}`;
+}
+
+/**
+ * Format an ISO date-time string or Date in a specific timezone+locale.
+ * Returns `""` for invalid input.
+ */
+export function formatDateTime(
+  dateTime: string | Date | null | undefined,
+  timezone: string = DEFAULT_TZ,
+  format: string = DATE_FORMATS.DATETIME,
+  locale: string = "de",
+): string {
+  if (!dateTime || !isValidDate(dateTime)) {
+    return "";
+  }
+  return moment(dateTime).locale(locale).tz(timezone).format(format);
+}
+
+export function bytesToHuman(bytes: number | null | undefined): string {
+  if (!bytes || bytes === 0) {
+    return "0 Bytes";
+  }
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${parseFloat((bytes / 2 ** (i * 10)).toFixed(2))} ${sizes[i]}`;
+}
+
+export function monthString(date: string | Date | null | undefined): string {
+  return date ? moment(date).format("MMMM YYYY") : "";
+}
+
+export function getMonthFromDate(date: string | Date | null | undefined): string {
+  return date ? moment(date).format("MMM") : "";
+}
+
+export function yearString(
+  date: string | Date | null | undefined,
+  timezone: string = DEFAULT_TZ,
+): string {
+  return date ? moment(date).tz(timezone).format("YYYY") : "";
+}
+
+export function percentage(value: number | string | null | undefined): string {
+  if (value === null || value === undefined) {
+    return "-";
+  }
+  return `${parseFloat(String(value)).toFixed(2)}%`;
+}
+
+export interface MembershipStatusBadge {
+  text: string;
+  color: string;
+}
+
+export function membershipStatus(value: string | null | undefined): MembershipStatusBadge {
+  switch (value?.toLowerCase()) {
+    case "confirmed":
+      return { text: "Aktiv", color: "success" };
+    case "denied":
+      return { text: "Inaktiv", color: "error" };
+    case "pending":
+      return { text: "In Bearbeitung", color: "warning" };
+    default:
+      return { text: "Unbekannter Status", color: "default" };
+  }
+}
+
+export function dayString(
+  date: string | Date | null | undefined,
+  timezone: string = DEFAULT_TZ,
+): string {
+  return date ? moment(date).tz(timezone).format("DD") : "";
+}
+
+export function dateString(
+  date: string | Date | null | undefined,
+  timezone: string = DEFAULT_TZ,
+): string {
+  return date ? moment(date).tz(timezone).format("DD.MM.YYYY") : "";
+}
+
+export function dateTimeString(
+  date: string | Date | null | undefined,
+  timezone: string = DEFAULT_TZ,
+  includeTimezone: boolean = false,
+): string | null {
+  if (!date) {
+    return null;
+  }
+  let formatted = moment(date).tz(timezone).format("DD.MM.YYYY HH:mm");
+  if (includeTimezone) {
+    formatted += ` ${moment(date).tz(timezone).format("z")}`;
+  }
+  return formatted;
+}
+
+export function timeString(
+  date: string | Date | null | undefined,
+  timezone: string = DEFAULT_TZ,
+  includeTimezone: boolean = false,
+): string {
+  if (!date) {
+    return "";
+  }
+  let formatted = moment(date).tz(timezone).format("HH:mm");
+  if (includeTimezone) {
+    formatted += ` ${moment(date).tz(timezone).format("z")}`;
+  }
+  return formatted;
+}
+
+export function timeUntil(
+  dateTime: string | Date | null | undefined,
+  locale: string = "de",
+): string {
+  if (!dateTime) {
+    return "";
+  }
+  return moment(dateTime).locale(locale).fromNow();
+}
+
+export function minutesFormatted(minutes: number | null | undefined): string {
+  if (minutes == null) {
+    return "";
+  }
+  const sign = minutes < 0 ? "-" : "";
+  const abs = Math.abs(minutes);
+  const hours = Math.floor(abs / 60);
+  const remaining = abs % 60;
+  return `${sign}${hours < 10 ? "0" : ""}${hours}:${`0${remaining}`.slice(-2)}`;
+}
+
+export interface CrewMember {
+  name?: string;
+  role?: string;
+}
+
+export function crewObjectToString(
+  crew: CrewMember[] | string | null | undefined,
+  { includeRoles = false }: { includeRoles?: boolean } = {},
+): string {
+  if (!crew) {
+    return "No Crew";
+  }
+  if (typeof crew === "string") {
+    return crew;
+  }
+  const names = crew
+    .map((member) => {
+      if (includeRoles && member.role) {
+        return `${member.name} (${member.role})`;
+      }
+      return member.name;
+    })
+    .filter((n): n is string => Boolean(n))
+    .join(", ");
+  return names.length === 0 ? "No Crew" : names;
+}
+
+export function timeDiffInDays(
+  startDateTime: string | Date | null | undefined,
+  endDateTime: string | Date | null | undefined,
+): string | null {
+  if (!startDateTime || !endDateTime) {
+    return null;
+  }
+  const diff = moment(endDateTime).diff(moment(startDateTime), "days");
+  return diff ? `+${diff}` : null;
+}
+
+export interface BookingTimespan {
+  etdZ: string | Date;
+  etaZ: string | Date;
+}
+
+export function bookingDuration(booking: BookingTimespan): string {
+  const minutes = moment(booking.etaZ).diff(moment(booking.etdZ), "minutes");
+  return `${`0${Math.floor(minutes / 60)}`.slice(-2)}:${`0${minutes % 60}`.slice(-2)}`;
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+export * from "./schemas/index.js";
+export {
+  // types/models.ts — re-export only type aliases (not conflicting with schema values)
+  type User,
+  type Company,
+  type MediaCollection,
+  type BaseMembership,
+  type Membership,
+  type Airplane,
+  type ExtendedAirplane,
+  type AirplanePermission,
+  type LandingFee,
+  type AircraftRating,
+  type UserAircraftRating,
+  type UserQualification,
+  type Airport,
+  type RecurringFlight,
+  type CourseFee,
+  type Price,
+  type MaintenanceEvent,
+  type MaintenanceStatus,
+  type MaintenanceEventEstimation,
+  type Avail,
+  type Alert,
+  type Booking,
+  type Document,
+  type DocumentType,
+  type DocumentRequirement,
+  type DocumentRequirementGroup,
+  type DocumentRequirementGroupAssignment,
+  type DocumentComplianceStatus,
+  type DocumentShare,
+  type AllowedDocumentType,
+  type FlightLog,
+  type ScheduledFlight,
+  type Landing,
+  type ApproachType,
+  type Waypoint,
+  type Invoice,
+  type Expense,
+  type ExpenseItem,
+  type SpecialFlight,
+  type PrePaidPackage,
+  type Qualification,
+  type Course,
+  type CourseEnrollment,
+  type Event,
+  type Ticket,
+  type Post,
+  type Comment,
+  type CreateCommentInput,
+  type UpdateCommentInput,
+  type Address,
+  type Runway,
+  type Role,
+  type Setting,
+  // types/api.ts
+  type DataWrappedResponse,
+  type PaginatedResponse,
+  type Resource,
+  type ToggleFavoriteResponse,
+  // types/compliance.ts
+  type ComplianceRequirement,
+  type ComplianceRequirementGroup,
+  type ComplianceGroup,
+  type ComplianceSummary,
+  type ComplianceData,
+  type ComplianceResponse,
+} from "./types/index.js";
+
+export * from "./money/index.js";
+export * from "./courses/index.js";
+export * from "./format/index.js";
+export * from "./crew/index.js";
+export * from "./media/index.js";
+export * from "./pagination/index.js";

package/src/media/index.ts

@@ -0,0 +1,224 @@
+/**
+ * Media conversion + classification helpers for spatie/laravel-medialibrary
+ * payloads. All functions are pure and locale-agnostic.
+ */
+
+/** Header conversion keys produced by the backend. */
+export const HeaderConversion = {
+  Dense: "header_dense",
+  Large: "header_large",
+} as const;
+
+/** Image conversion keys. */
+export const ImageConversion = {
+  GalleryMedium: "gallery_medium",
+  GalleryFull: "gallery_large",
+  Thumb: "thumb",
+} as const;
+
+/** Document conversion keys. */
+export const DocumentConversion = {
+  Preview: "document_preview",
+} as const;
+
+/** Thumbnail conversion keys. */
+export const ThumbnailConversion = {
+  Square: "thumb",
+} as const;
+
+/** Avatar conversion keys. */
+export const AvatarConversion = {
+  Square: "thumb",
+} as const;
+
+export const MediaType = {
+  IMAGE: "image",
+  DOCUMENT: "document",
+  VIDEO: "video",
+  AUDIO: "audio",
+  UNKNOWN: "unknown",
+} as const;
+
+export type MediaTypeValue = (typeof MediaType)[keyof typeof MediaType];
+
+export const MimeTypes = {
+  IMAGES: [
+    "image/jpeg",
+    "image/jpg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/svg+xml",
+    "image/bmp",
+    "image/tiff",
+  ],
+  DOCUMENTS: [
+    "application/pdf",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.ms-excel",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "text/plain",
+    "text/csv",
+    "application/rtf",
+  ],
+  VIDEOS: [
+    "video/mp4",
+    "video/webm",
+    "video/ogg",
+    "video/avi",
+    "video/mov",
+    "video/wmv",
+    "video/flv",
+    "video/x-matroska",
+  ],
+  AUDIO: ["audio/mpeg", "audio/wav", "audio/ogg", "audio/aac", "audio/flac", "audio/mp3"],
+} as const;
+
+/** Map a MIME type to its broad category. */
+export function getMediaType(mimeType: string | null | undefined): MediaTypeValue {
+  if (!mimeType) {
+    return MediaType.UNKNOWN;
+  }
+  const mt = mimeType as (typeof MimeTypes.IMAGES)[number];
+  if (MimeTypes.IMAGES.includes(mt as never)) return MediaType.IMAGE;
+  if (MimeTypes.DOCUMENTS.includes(mt as never)) return MediaType.DOCUMENT;
+  if (MimeTypes.VIDEOS.includes(mt as never)) return MediaType.VIDEO;
+  if (MimeTypes.AUDIO.includes(mt as never)) return MediaType.AUDIO;
+  return MediaType.UNKNOWN;
+}
+
+/** Pick a specific MDI icon name for a document MIME type. */
+export function getDocumentIcon(mimeType: string | null | undefined): string {
+  switch (mimeType) {
+    case "application/pdf":
+      return "mdi-file-pdf-box";
+    case "application/msword":
+    case "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+      return "mdi-file-word";
+    case "application/vnd.ms-excel":
+    case "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":
+      return "mdi-file-excel";
+    case "application/vnd.ms-powerpoint":
+    case "application/vnd.openxmlformats-officedocument.presentationml.presentation":
+      return "mdi-file-powerpoint";
+    case "text/plain":
+      return "mdi-file-document";
+    case "text/csv":
+      return "mdi-file-delimited";
+    default:
+      return "mdi-file";
+  }
+}
+
+/** Pick an MDI icon name for any media MIME type. */
+export function getMediaIcon(mimeType: string | null | undefined): string {
+  const t = getMediaType(mimeType);
+  switch (t) {
+    case MediaType.IMAGE:
+      return "mdi-image";
+    case MediaType.VIDEO:
+      return "mdi-video";
+    case MediaType.AUDIO:
+      return "mdi-music";
+    case MediaType.DOCUMENT:
+      return getDocumentIcon(mimeType);
+    default:
+      return "mdi-file";
+  }
+}
+
+/** True if the media type can be previewed inline (images, video, audio). */
+export function canPreview(mimeType: string | null | undefined): boolean {
+  const t = getMediaType(mimeType);
+  return t === MediaType.IMAGE || t === MediaType.VIDEO || t === MediaType.AUDIO;
+}
+
+/**
+ * Localized label for a media type. Pass `labels` to override (for i18n).
+ * Defaults to German since that's the only locale currently in use in MCRIT.
+ */
+export function getMediaDisplayName(
+  mimeType: string | null | undefined,
+  labels: Partial<Record<MediaTypeValue, string>> = {},
+): string {
+  const defaults: Record<MediaTypeValue, string> = {
+    image: "Bild",
+    video: "Video",
+    audio: "Audio",
+    document: "Dokument",
+    unknown: "Datei",
+  };
+  const t = getMediaType(mimeType);
+  return labels[t] ?? defaults[t];
+}
+
+/** Permissive Media shape — accepts spatie/laravel-medialibrary payloads. */
+export interface MediaLike {
+  url?: string;
+  mime_type?: string;
+  file_name?: string;
+  name?: string;
+  size?: number;
+  alt?: string;
+  description?: string;
+  title?: string;
+  conversions?: Record<string, string>;
+}
+
+export interface MappedMedia {
+  href: string | undefined;
+  src: string | undefined;
+  thumbnail: string | undefined;
+  documentPreview: string | null;
+  mediaType: MediaTypeValue;
+  mimeType: string | undefined;
+  icon: string;
+  previewable: boolean;
+  fileName: string | undefined;
+  size: number | undefined;
+  alt: string | undefined;
+  title: string | undefined;
+  original: MediaLike;
+}
+
+function mapSingle(m: MediaLike): MappedMedia {
+  const galleryFull = m?.conversions?.[ImageConversion.GalleryFull] ?? m?.url;
+  const thumb = m?.conversions?.[ImageConversion.Thumb] ?? m?.url;
+  const documentPreview = m?.conversions?.[DocumentConversion.Preview] ?? null;
+
+  return {
+    href: galleryFull,
+    src: galleryFull,
+    thumbnail: thumb,
+    documentPreview,
+    mediaType: getMediaType(m?.mime_type),
+    mimeType: m?.mime_type,
+    icon: getMediaIcon(m?.mime_type),
+    previewable: canPreview(m?.mime_type),
+    fileName: m?.file_name ?? m?.name,
+    size: m?.size,
+    alt: m?.alt ?? m?.description ?? m?.file_name,
+    title: m?.title ?? m?.description ?? m?.file_name,
+    original: m,
+  };
+}
+
+/**
+ * Normalize a media field (single object or array) into a uniform array
+ * of gallery-ready entries with conversions resolved. Returns `[]` for
+ * `null`/`undefined`.
+ */
+export function mapMediaConversions(
+  media: MediaLike | MediaLike[] | null | undefined,
+): MappedMedia[] {
+  if (!media) {
+    return [];
+  }
+  if (Array.isArray(media)) {
+    return media.map(mapSingle);
+  }
+  return [mapSingle(media)];
+}