@updraft-solutions/mcrit-sdk 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# `@updraft-solutions/mcrit-sdk`
+
+Shared TypeScript types, Zod schemas, and pure helpers for the MCRIT
+aviation fleet management platform — consumed by the `mcrit-app` SPA and
+the public `inflight-homepage` site so both speak the same API contract
+and apply the same business logic.
+
+The SDK is **runtime-agnostic and side-effect free**: no Vue, no Nuxt, no
+Pinia, no HTTP client. Just types and pure functions that operate on the
+resource shapes returned by the Laravel API.
+
+---
+
+## Install
+
+```bash
+pnpm add @updraft-solutions/mcrit-sdk
+```
+
+Peer dependency:
+
+```bash
+pnpm add moment-timezone
+```
+
+`moment-timezone` is only required if you use the `format` module. If you
+want German or another non-English label output, also import the matching
+moment locale **once** at your app entry:
+
+```ts
+// e.g. a Nuxt plugin or app/main.ts
+import "moment/locale/de";
+```
+
+---
+
+## Subpath exports
+
+Every helper is tree-shakeable. Import from the narrow subpath you need,
+or from the root if you want everything in one place.
+
+| Subpath | What's inside |
+|---|---|
+| `@updraft-solutions/mcrit-sdk` | Re-exports everything below |
+| `@updraft-solutions/mcrit-sdk/schemas` | Zod schemas for API resources |
+| `@updraft-solutions/mcrit-sdk/types` | Plain TypeScript types (inferred or hand-written) |
+| `@updraft-solutions/mcrit-sdk/money` | Dinero-based fee and price helpers |
+| `@updraft-solutions/mcrit-sdk/courses` | Course variant and total-cost logic |
+| `@updraft-solutions/mcrit-sdk/format` | Date, time, percentage, byte, membership formatters |
+| `@updraft-solutions/mcrit-sdk/crew` | Crew-role constants, predicates, membership helpers |
+| `@updraft-solutions/mcrit-sdk/media` | MIME-type classification + Spatie MediaLibrary mappers |
+| `@updraft-solutions/mcrit-sdk/pagination` | Pagination meta math |
+
+---
+
+## Quick examples
+
+### Schemas & types
+
+```ts
+import { feeSchema, courseSchema } from "@updraft-solutions/mcrit-sdk/schemas";
+import type { Course, Fee } from "@updraft-solutions/mcrit-sdk/types";
+
+const fee = feeSchema.parse(apiResponse);   // runtime validation
+const course: Course = await loadCourse();  // type only
+```
+
+### Money
+
+```ts
+import { parseFee, displayFee, fromCents, formatToEuroString } from "@updraft-solutions/mcrit-sdk/money";
+
+displayFee(fee, "gross");           // → "€ 1.234,56"
+parseFee(fee)?.currentPrice("net"); // → Dinero instance
+formatToEuroString(123456);         // → "€ 1.234,56"
+fromCents(50000).toFormat();        // → "500,00 €"
+```
+
+### Courses
+
+```ts
+import { parseCourse } from "@updraft-solutions/mcrit-sdk/courses";
+
+const variants = parseCourse(course)?.variants("gross") ?? [];
+// [{ variant, fees: ParsedCourseFee[], totalCost: Dinero }, ...]
+
+for (const v of variants) {
+  console.log(v.variant, v.totalCost.toFormat());
+}
+```
+
+`parseCourse` handles fees with pivot data nested under `pivot` OR
+flattened directly on the fee object — both API shapes are accepted.
+
+### Format
+
+```ts
+import {
+  formatDate,
+  formatDateTime,
+  bookingDuration,
+  bytesToHuman,
+  timeUntil,
+} from "@updraft-solutions/mcrit-sdk/format";
+
+formatDate("2026-05-15");                      // "15.05.2026"
+formatDateTime(booking.etdZ, "Europe/Berlin"); // "15.05.2026 09:00"
+bookingDuration(booking);                      // "01:30"
+bytesToHuman(1_572_864);                       // "1.5 MB"
+timeUntil("2026-05-10T12:00:00Z", "de");       // "vor 5 Tagen" (needs moment de locale loaded)
+```
+
+### Crew
+
+```ts
+import {
+  CREW_ROLES,
+  ROLE_ATTRIBUTES,
+  PIC_PRIORITY,
+  isInstructorClassRole,
+  hasMembershipRole,
+  defaultCrewRoleForMembership,
+} from "@updraft-solutions/mcrit-sdk/crew";
+
+PIC_PRIORITY;                                  // ['examiner', 'instructor', 'pilot', 'student']
+isInstructorClassRole("authorizing_instructor"); // true
+defaultCrewRoleForMembership(membership);      // "student" | "instructor" | "pilot"
+```
+
+Mirrors the backend `App\Enums\CrewMemberPosition`. See
+`m-crit-api/docs/features/crew-composition.md` for the full data model.
+
+### Media
+
+```ts
+import {
+  mapMediaConversions,
+  getMediaType,
+  getMediaIcon,
+  getMediaDisplayName,
+} from "@updraft-solutions/mcrit-sdk/media";
+
+const gallery = mapMediaConversions(model.media);
+// [{ href, thumbnail, mediaType, icon, previewable, ... }]
+
+getMediaType("application/pdf");  // "document"
+getMediaIcon("video/mp4");        // "mdi-video"
+
+getMediaDisplayName("image/png");                      // "Bild" (German default)
+getMediaDisplayName("image/png", { image: "Picture" }); // "Picture" (i18n override)
+```
+
+### Pagination
+
+```ts
+import { paginationMeta } from "@updraft-solutions/mcrit-sdk/pagination";
+
+paginationMeta({ page: 2, itemsPerPage: 25 }, 137);
+// { start: 26, end: 50, total: 137 }
+```
+
+---
+
+## API shapes vs `*Like` shapes
+
+The SDK distinguishes two kinds of types:
+
+- **Strict shapes** (`Fee`, `Price`, `Course`, `CourseFee`, ...) are
+  `z.infer<>` of the corresponding Zod schemas — what the API actually
+  returns when fully loaded.
+- **Permissive `*Like` shapes** (`FeeLike`, `PriceLike`, `CourseLike`,
+  `CourseFeeLike`) are accepted by the helpers (`parseFee`,
+  `parseCourse`, `displayFee`, ...) so callers can pass partial or
+  legacy payload shapes without casting.
+
+Use the strict types in your own code; rely on `*Like` only as input to
+SDK helpers.
+
+---
+
+## Local development
+
+This repo is a normal pnpm package. From the SDK root:
+
+```bash
+pnpm install
+pnpm typecheck    # tsc --noEmit
+pnpm build        # tsup → dist/{esm,cjs,d.ts}
+pnpm dev          # tsup --watch
+```
+
+### Inside the MCRIT monorepo
+
+The MCRIT working folder (`mcrit-app`, `inflight-homepage-nuxt-3`, and
+this repo as sibling git checkouts) uses a pnpm workspace at the parent
+folder. With `workspace:*` (or any matching version range) in the
+consuming app's `package.json`, pnpm symlinks this directory into the
+consumer's `node_modules` — edits show up immediately, no publish loop.
+
+If consumers use the `source` export condition (Vite via
+`resolve.conditions: ['source']`), they read `src/*.ts` directly and skip
+the `tsup` build entirely during dev.
+
+### Adding a new helper
+
+1. Pick or create the appropriate subpath under `src/` (e.g. `src/money/`).
+2. Keep the implementation pure — no framework imports, no I/O.
+3. Add the file to the `entry` list in `tsup.config.ts`.
+4. Add the subpath under `exports` in `package.json` (mirror the existing
+   pattern: `source` + `import.types` + `import.default` + `require.types`
+   + `require.default`).
+5. Re-export from `src/index.ts` if it should also be reachable from the
+   root.
+6. `pnpm typecheck && pnpm build` — both must be green.
+
+---
+
+## Releases
+
+Publishes are automated. Push a tag matching `v*` to trigger
+`.github/workflows/publish.yml`:
+
+```bash
+npm version patch          # bumps package.json and creates v0.1.1 commit + tag
+git push && git push --tags
+```
+
+The workflow verifies the tag matches `package.json`, runs
+`pnpm typecheck && pnpm build`, then publishes to npm with provenance.
+
+The `NPM_TOKEN` GitHub repository secret must be configured (an
+"Automation" or "Granular" token from npmjs.com with publish rights to
+`@updraft-solutions/mcrit-sdk`).
+
+---
+
+## License
+
+UNLICENSED — internal Updraft Solutions package. Not for redistribution
+outside MCRIT projects.

package/dist/chunk-2DRKSYW4.cjs

@@ -0,0 +1,99 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/money/index.ts
+var _dinerojs = require('dinero.js'); var _dinerojs2 = _interopRequireDefault(_dinerojs);
+var _lodashes = require('lodash-es');
+_dinerojs2.default.globalLocale = "de-DE";
+function money(amount) {
+  try {
+    let parsed = amount;
+    if (parsed && typeof parsed === "object") {
+      const obj = parsed;
+      if (obj.value && typeof obj.value === "object" && typeof obj.value.amount !== "undefined") {
+        parsed = obj.value.amount;
+      } else if (typeof obj.amount !== "undefined") {
+        parsed = obj.amount;
+      }
+    }
+    const int = parseInt(String(_nullishCoalesce(parsed, () => ( "0"))), 10);
+    if (Number.isNaN(int)) {
+      throw new Error("Invalid amount");
+    }
+    return _dinerojs2.default.call(void 0, { amount: int, currency: "EUR" });
+  } catch (e) {
+    console.error("[mcrit-sdk/money] failed to parse amount:", amount, e);
+    return _dinerojs2.default.call(void 0, { amount: 0, currency: "EUR" });
+  }
+}
+function moneyFormatted(dinero) {
+  return dinero ? dinero.toFormat() : "";
+}
+function parsePrice(price) {
+  if (!price) {
+    return null;
+  }
+  return {
+    ...price,
+    net_total: money(_nullishCoalesce(_optionalChain([price, 'access', _ => _.net_total, 'optionalAccess', _2 => _2.amount]), () => ( 0))),
+    gross_total: money(_nullishCoalesce(_optionalChain([price, 'access', _3 => _3.gross_total, 'optionalAccess', _4 => _4.amount]), () => ( 0)))
+  };
+}
+function priceFor(parsed, netGross) {
+  if (netGross === "net") {
+    return parsed.net_total;
+  }
+  if (netGross === "gross") {
+    return parsed.gross_total;
+  }
+  return parsed;
+}
+function parseFee(fee) {
+  if (!fee) {
+    return null;
+  }
+  return {
+    currentPrice(netGross = null) {
+      const parsed = parsePrice(_nullishCoalesce(fee.price, () => ( null)));
+      return parsed ? priceFor(parsed, netGross) : null;
+    },
+    upcomingPrice(netGross = null) {
+      const now = Date.now();
+      const upcoming = _lodashes.head.call(void 0, 
+        _lodashes.sortBy.call(void 0, 
+          _lodashes.filter.call(void 0, _nullishCoalesce(fee.prices, () => ( [])), (p) => {
+            const t = p.valid_from ? Date.parse(p.valid_from) : NaN;
+            return Number.isFinite(t) && t > now;
+          }),
+          (p) => Date.parse(_nullishCoalesce(p.valid_from, () => ( "")))
+        )
+      );
+      if (!upcoming) {
+        return null;
+      }
+      const parsed = parsePrice(upcoming);
+      return parsed ? priceFor(parsed, netGross) : null;
+    }
+  };
+}
+function displayFee(fee, netGross = "gross", fallback = "Keine Geb\xFChr hinterlegt") {
+  const current = _optionalChain([parseFee, 'call', _5 => _5(fee), 'optionalAccess', _6 => _6.currentPrice, 'call', _7 => _7(netGross)]);
+  if (current && "toFormat" in current) {
+    return current.toFormat();
+  }
+  return fallback;
+}
+function fromCents(amount) {
+  return _dinerojs2.default.call(void 0, { amount, currency: "EUR" });
+}
+function formatToEuroString(amount) {
+  const cents = parseInt(String(_nullishCoalesce(amount, () => ( "0"))), 10);
+  return `\u20AC ${fromCents(Number.isNaN(cents) ? 0 : cents).setLocale("de-DE").toFormat("0,0.00")}`;
+}
+
+
+
+
+
+
+
+
+
+exports.money = money; exports.moneyFormatted = moneyFormatted; exports.parsePrice = parsePrice; exports.parseFee = parseFee; exports.displayFee = displayFee; exports.fromCents = fromCents; exports.formatToEuroString = formatToEuroString;

package/dist/chunk-2M32EOYI.js

@@ -0,0 +1,145 @@
+// src/crew/index.ts
+function hasMembershipRole(membership, roleName) {
+  return membership?.roles?.some((r) => r.name === roleName) ?? false;
+}
+function defaultCrewRoleForMembership(membership) {
+  if (hasMembershipRole(membership, "student")) {
+    return "student";
+  }
+  if (hasMembershipRole(membership, "instructor")) {
+    return "instructor";
+  }
+  return "pilot";
+}
+function createCrewValidator(config) {
+  function attributesOf(role) {
+    return config.positions[role];
+  }
+  function rolesFromCrew(crew) {
+    return crew.map((c) => c.role).filter((r) => typeof r === "string");
+  }
+  function membershipsWithSystemRole(crew, systemRole) {
+    return crew.filter(
+      (c) => c.membership?.roles?.some(
+        (r) => r.name === systemRole && (r.company_id == null || r.company_id === null)
+      )
+    );
+  }
+  function evaluateConstraint(constraint, crew) {
+    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 = [];
+        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 = [];
+      for (const constraint of config.constraints) {
+        const violation = evaluateConstraint(constraint, crew);
+        if (violation !== null) {
+          violations.push(violation);
+        }
+      }
+      return { ok: violations.length === 0, violations };
+    }
+  };
+}
+
+export {
+  hasMembershipRole,
+  defaultCrewRoleForMembership,
+  createCrewValidator
+};