@updraft-solutions/mcrit-sdk 0.14.11 → 0.14.13

package/src/schemas/fbo.spec.ts

@@ -1,15 +1,22 @@
 import { describe, expect, it } from "vitest";
 import {
   fboActivitySchema,
+  fboCompanyGrantSchema,
   fboCompanyMemberSchema,
+  fboCompanySchema,
   fboDutyAffectedSchema,
   fboDutySchema,
   fboDutySeriesResponseSchema,
+  fboFlightDocumentSchema,
   fboFlightSchema,
   fboFlightStatusSchema,
+  fboGrantAbilitySchema,
   fboMaterialiseResultSchema,
+  fboMetaSchema,
   fboOccupationSchema,
   fboOperationsSchema,
+  fboPersonSchema,
+  fboPobSchema,
   fboRecurrenceSchema,
   fboRecurringFlightSchema,
   fboStatisticsSchema,
@@ -361,3 +368,224 @@ describe("fboMaterialiseResultSchema", () => {
     expect(fboMaterialiseResultSchema.parse(payload)).toEqual(payload);
   });
 });
+
+const pobPayload = {
+  crew: true,
+  firstname: "Erika",
+  lastname: "Muster",
+  birth: "1979-04-02",
+  nationality: "DE",
+  document_id: "C01X00T47",
+  document_validity: "2031-04-01",
+};
+
+describe("fboPobSchema", () => {
+  it("parses a fully filled person on board", () => {
+    expect(fboPobSchema.parse(pobPayload).nationality).toBe("DE");
+  });
+
+  it("parses a person whose travel document is not known yet — every field but the names is optional data", () => {
+    const sparse = { ...pobPayload, birth: null, nationality: null, document_id: null, document_validity: null };
+    expect(fboPobSchema.parse(sparse).document_id).toBeNull();
+  });
+
+  it("rejects a missing lastname — the API requires both names on every entry", () => {
+    const { lastname, ...withoutLastname } = pobPayload;
+    expect(fboPobSchema.safeParse(withoutLastname).success).toBe(false);
+  });
+
+  it("rejects crew as a string — the flag decides which table half the declaration lists the person in", () => {
+    expect(fboPobSchema.safeParse({ ...pobPayload, crew: "1" }).success).toBe(false);
+  });
+});
+
+describe("fboPersonSchema", () => {
+  const personPayload = { ...pobPayload, id: 143, is_mine: true, created_at: "2026-08-26T10:00:00.000000Z" };
+
+  it("parses an address-book row the caller owns", () => {
+    const parsed = fboPersonSchema.parse(personPayload);
+    expect(parsed.id).toBe(143);
+    expect(parsed.is_mine).toBe(true);
+  });
+
+  it("parses a row visible only through the company, not owned by the caller", () => {
+    expect(fboPersonSchema.parse({ ...personPayload, is_mine: false }).is_mine).toBe(false);
+  });
+
+  it("rejects a row without an id — a template must be addressable to be edited or deleted", () => {
+    const { id, ...withoutId } = personPayload;
+    expect(fboPersonSchema.safeParse(withoutId).success).toBe(false);
+  });
+});
+
+const documentPayload = {
+  id: 9001,
+  uuid: "6f1b3d5e-0000-4000-8000-000000000042",
+  name: "General Declaration",
+  file_name: "gendec.pdf",
+  mime_type: "application/pdf",
+  size: 84213,
+  collection_name: "documents",
+  ima_file_id: null,
+  download_path: "/companies/34/fbo/flights/44796/documents/9001",
+  created_at: "2026-08-26T10:00:00.000000Z",
+};
+
+describe("fboFlightDocumentSchema", () => {
+  it("parses an uploaded movement document", () => {
+    expect(fboFlightDocumentSchema.parse(documentPayload).download_path).toBe(
+      "/companies/34/fbo/flights/44796/documents/9001",
+    );
+  });
+
+  it("parses an imported row whose source id is stamped as text", () => {
+    expect(fboFlightDocumentSchema.parse({ ...documentPayload, ima_file_id: "104" }).ima_file_id).toBe("104");
+  });
+
+  it("rejects a size sent as a string — the list renders it as a byte count", () => {
+    expect(fboFlightDocumentSchema.safeParse({ ...documentPayload, size: "84213" }).success).toBe(false);
+  });
+});
+
+describe("fboFlightSchema — POB, documents and the customs mail stamp", () => {
+  it("parses a movement whose payload carries none of the three keys — a colleague never receives POB", () => {
+    const parsed = fboFlightSchema.parse(flightPayload);
+    expect(parsed.pobs).toBeUndefined();
+    expect(parsed.documents_count).toBeUndefined();
+    expect(parsed.customs_mail_sent_at).toBeUndefined();
+  });
+
+  it("parses the author's own row: the POB list, the document count and an unsent customs mail", () => {
+    const own = { ...flightPayload, pobs: [pobPayload], documents_count: 2, customs_mail_sent_at: null };
+    const parsed = fboFlightSchema.parse(own);
+    expect(parsed.pobs).toHaveLength(1);
+    expect(parsed.documents_count).toBe(2);
+    expect(parsed.customs_mail_sent_at).toBeNull();
+  });
+
+  it("parses pobs: null — a movement whose list was never filled, or has been purged by retention", () => {
+    expect(fboFlightSchema.parse({ ...flightPayload, pobs: null }).pobs).toBeNull();
+  });
+
+  it("parses a stamped customs mail timestamp", () => {
+    const sent = { ...flightPayload, customs_mail_sent_at: "2026-08-28T09:15:00.000000Z" };
+    expect(fboFlightSchema.parse(sent).customs_mail_sent_at).toBe("2026-08-28T09:15:00.000000Z");
+  });
+
+  it("rejects a POB entry missing its names inside an otherwise valid movement", () => {
+    const bad = { ...flightPayload, pobs: [{ crew: false, firstname: "Erika" }] };
+    expect(fboFlightSchema.safeParse(bad).success).toBe(false);
+  });
+});
+
+/**
+ * Fixtures copied from `CompanyGrantResource`, the FBO meta endpoint and the
+ * attached-companies index, so a schema that drifts from the payload fails
+ * here rather than at runtime in the app.
+ */
+const grantPayload = {
+  id: 12,
+  grantee: { id: 34, name: "Alpha Handling" },
+  target: { id: 35, name: "Bravo Charter" },
+  ability: "duties.view",
+  ability_label: "Dienstpläne einsehen",
+  granted_by: { id: 7, name: "Erika Muster" },
+  created_at: "2026-08-29T09:00:00.000000Z",
+  can: { delete: true },
+};
+
+describe("fboCompanyGrantSchema", () => {
+  it("parses a grant exactly as the register emits it", () => {
+    expect(fboCompanyGrantSchema.parse(grantPayload).ability).toBe("duties.view");
+  });
+
+  it("parses a migrated grant nobody signed — granted_by is null", () => {
+    expect(fboCompanyGrantSchema.parse({ ...grantPayload, granted_by: null }).granted_by).toBeNull();
+  });
+
+  it("parses a side whose company left the FBO domain — the ref is null, not missing", () => {
+    expect(fboCompanyGrantSchema.parse({ ...grantPayload, target: null }).target).toBeNull();
+  });
+
+  it("rejects an ability outside the register's vocabulary", () => {
+    expect(fboCompanyGrantSchema.safeParse({ ...grantPayload, ability: "flights.view" }).success).toBe(false);
+  });
+
+  it("rejects a row without its ability label — the UI has no copy of its own", () => {
+    const { ability_label: _label, ...withoutLabel } = grantPayload;
+    expect(fboCompanyGrantSchema.safeParse(withoutLabel).success).toBe(false);
+  });
+});
+
+describe("fboGrantAbilitySchema", () => {
+  it("accepts the one ability the register knows", () => {
+    expect(fboGrantAbilitySchema.parse("duties.view")).toBe("duties.view");
+  });
+
+  it("rejects an ability the client cannot render", () => {
+    expect(fboGrantAbilitySchema.safeParse("traffic.details").success).toBe(false);
+  });
+});
+
+describe("fboMetaSchema", () => {
+  const metaPayload = {
+    roles: ["fbo", "operator"],
+    root_id: 34,
+    can_decide: true,
+    can_view_own_flights: false,
+    grant_abilities: [{ value: "duties.view", label: "View duty rosters" }],
+    can_manage_grants: true,
+    companies: [{ id: 34, name: "Alpha Handling" }],
+  };
+
+  it("parses the meta payload as the API emits it", () => {
+    const parsed = fboMetaSchema.parse(metaPayload);
+    expect(parsed.grant_abilities?.[0]?.value).toBe("duties.view");
+    expect(parsed.can_manage_grants).toBe(true);
+  });
+
+  it("parses a payload from an API that predates the grant register — only roles is required", () => {
+    const parsed = fboMetaSchema.parse({ roles: [] });
+    expect(parsed.grant_abilities).toBeUndefined();
+    expect(parsed.can_view_own_flights).toBeUndefined();
+  });
+
+  it("rejects a grant ability option the client cannot render", () => {
+    const bad = { ...metaPayload, grant_abilities: [{ value: "duties.edit", label: "Edit" }] };
+    expect(fboMetaSchema.safeParse(bad).success).toBe(false);
+  });
+});
+
+describe("fboCompanySchema", () => {
+  const companyPayload = {
+    id: 35,
+    name: "Bravo Charter",
+    email: "ops@bravo.test",
+    phone: null,
+    description: null,
+    contact_name: "Erika Muster",
+    companyType: "interface",
+    is_ima_imported: true,
+    fbo: { role: "operator", flights_require_approval: true, notify_on_movement: false, has_duties: true, has_airplanes: false },
+    members_count: 4,
+    movements_count: 92,
+    grants_out_count: 1,
+    grants_in_count: 0,
+    can: { update: true, updateIdentity: true },
+  };
+
+  it("parses an attached company with both grant counts", () => {
+    const parsed = fboCompanySchema.parse(companyPayload);
+    expect(parsed.grants_out_count).toBe(1);
+    expect(parsed.grants_in_count).toBe(0);
+  });
+
+  it("parses a payload from an API that does not count grants yet", () => {
+    const { grants_out_count: _out, grants_in_count: _in, ...withoutCounts } = companyPayload;
+    expect(fboCompanySchema.parse(withoutCounts).grants_out_count).toBeUndefined();
+  });
+
+  it("parses a company with no FBO profile at all", () => {
+    expect(fboCompanySchema.parse({ ...companyPayload, fbo: null }).fbo).toBeNull();
+  });
+});

package/src/schemas/fbo.ts

@@ -64,6 +64,62 @@ export const fboRowCanSchema = z.object({
   delete: z.boolean(),
 });
 
+/**
+ * One person on board a movement — the per-element shape of the flight's
+ * `pobs` list and, minus the row identity, of an address-book person.
+ * `birth`/`document_validity` are plain `Y-m-d` dates (no time); `nationality`
+ * is an uppercase ISO-3166-1 alpha-2 code. Every field but the names is
+ * optional data a filer may not have to hand yet.
+ *
+ * Passport data: it is only ever in a payload the API decided the caller may
+ * see (the movement's own author, or a root decider) — never cached to disk
+ * on the client.
+ */
+export const fboPobSchema = z.object({
+  /** Crew member rather than passenger — the customs declaration lists the two apart. */
+  crew: z.boolean(),
+  firstname: z.string(),
+  lastname: z.string(),
+  birth: z.string().nullable(),
+  nationality: z.string().nullable(),
+  document_id: z.string().nullable(),
+  document_validity: z.string().nullable(),
+});
+
+/**
+ * An address-book person — a saved template the POB editor fills a row from,
+ * so a document number never has to be retyped. Same field set as
+ * `fboPobSchema` plus the row's own identity; `is_mine` says whether the
+ * CALLER owns it (theirs to edit or delete) rather than it merely being
+ * visible through the company they are filing at.
+ */
+export const fboPersonSchema = fboPobSchema.extend({
+  id: z.number(),
+  is_mine: z.boolean(),
+  created_at: z.string().nullable(),
+});
+
+/**
+ * A document hanging on a movement — General Declaration, passports, customs
+ * paperwork. `download_path` is a RELATIVE API path, never a fetchable file
+ * URL: the bytes live on a private disk and are streamed back through the
+ * authorised endpoint, so every fetch re-runs the caller's authority.
+ * `ima_file_id` is set only on the rows imported from the predecessor system,
+ * and is a STRING there — the importer stamps the source id as text.
+ */
+export const fboFlightDocumentSchema = z.object({
+  id: z.number(),
+  uuid: z.string().nullable(),
+  name: z.string(),
+  file_name: z.string(),
+  mime_type: z.string().nullable(),
+  size: z.number(),
+  collection_name: z.string(),
+  ima_file_id: z.string().nullable().optional(),
+  download_path: z.string().nullable(),
+  created_at: z.string().nullable(),
+});
+
 export const fboFlightSchema = z.object({
   id: z.number(),
   type: fboFlightTypeSchema,
@@ -104,6 +160,21 @@ export const fboFlightSchema = z.object({
   batch_uuid: z.string().nullable(),
   /** Count of live rows sharing `batch_uuid`; `1` when `batch_uuid` is null. */
   legs_count: z.number(),
+  /**
+   * Persons on board. Own-row tier, stricter than `fbo_notes`: the key is
+   * present only for the movement's own AUTHOR or a root decider — a
+   * colleague reading the same row never receives it. `.optional()` covers
+   * the omitted key, `.nullable()` a movement whose list was never filled
+   * (or has been purged by retention).
+   */
+  pobs: z.array(fboPobSchema).nullable().optional(),
+  /**
+   * How many documents hang on the movement. The files themselves are never
+   * listed here — they are fetched, and authorised, one endpoint deeper.
+   */
+  documents_count: z.number().nullable().optional(),
+  /** When the customs pre-declaration was last mailed; `null` while it never was. */
+  customs_mail_sent_at: z.string().nullable().optional(),
   /**
    * Root tier — present only when the requesting user holds `fbo.flight.decide`
    * for the row's company; absent (key omitted) for everyone else, including
@@ -365,3 +436,102 @@ export const fboMaterialiseResultSchema = z.object({
   skipped_existing: z.number(),
   skipped_closed: z.number(),
 });
+
+/**
+ * What one company may exercise on another company's data inside the same FBO
+ * tree — the vocabulary of the root's grant register. Mirrors the API enum
+ * exactly; a value outside it means the register grew an ability this client
+ * does not know how to render, and failing here is the point.
+ */
+export const fboGrantAbilitySchema = z.enum(["duties.view"]);
+
+/**
+ * One entry of `GET fbo/meta`'s `grant_abilities` — the ability vocabulary
+ * with the label the API already translated, so no client hardcodes copy for
+ * an ability it may not know.
+ */
+export const fboGrantAbilityOptionSchema = z.object({
+  value: fboGrantAbilitySchema,
+  label: z.string(),
+});
+
+/**
+ * A company side of a grant. Rendered as `{id, name}` rather than a full
+ * company payload: a grant is a relation between two companies, not a view of
+ * either. Null only when that company stopped taking part in the FBO domain.
+ */
+export const fboGrantCompanyRefSchema = z.object({
+  id: z.number(),
+  name: z.string().nullable(),
+});
+
+/**
+ * One row of the root's company-grant register — `CompanyGrantResource`.
+ * `granted_by` is null for a grant the migration wrote rather than a person.
+ * `can.delete` is always true on a row that reached the client at all (only
+ * `fbo.company.manage` at the tree root can read the register), but it is
+ * read as a gate like every other row's, never assumed.
+ */
+export const fboCompanyGrantSchema = z.object({
+  id: z.number(),
+  grantee: fboGrantCompanyRefSchema.nullable(),
+  target: fboGrantCompanyRefSchema.nullable(),
+  ability: fboGrantAbilitySchema,
+  ability_label: z.string(),
+  granted_by: z.object({ id: z.number(), name: z.string() }).nullable(),
+  created_at: z.string().nullable(),
+  can: z.object({ delete: z.boolean() }).optional(),
+});
+
+/** `POST companies/{id}/fbo/company-grants` — the register's write shape. */
+export const fboCompanyGrantInputSchema = z.object({
+  grantee_company_id: z.number(),
+  target_company_id: z.number(),
+  ability: fboGrantAbilitySchema,
+});
+
+/**
+ * `GET companies/{id}/fbo/meta` — the FBO vocabulary and the caller's
+ * root-evaluated capabilities, served so no client hardcodes either.
+ *
+ * Every key but `roles` is optional: the endpoint is the one surface an
+ * own-author filer can reach before anything else is known, and it has grown
+ * keys over time — a client pinned to an older API must still parse it.
+ *
+ * `can_view_own_flights` is the TIER, not the bare permission: true only when
+ * this caller's sight of movements is the own-author one (false for a decider
+ * or an operator, who hold the wider `fbo.flight.viewAny`).
+ */
+export const fboMetaSchema = z.object({
+  roles: z.array(z.string()),
+  root_id: z.number().nullable().optional(),
+  can_decide: z.boolean().optional(),
+  can_view_own_flights: z.boolean().optional(),
+  grant_abilities: z.array(fboGrantAbilityOptionSchema).optional(),
+  can_manage_grants: z.boolean().optional(),
+  companies: z.array(fboGrantCompanyRefSchema).optional(),
+});
+
+/**
+ * A company attached to the FBO as its root's admin reads it —
+ * `CompanyResource` under `GET companies/{fbo}/fbo/companies`. The three
+ * counts are aggregates the index adds (`withCount`) and are null on any
+ * payload that did not compute them; `grants_out_count`/`grants_in_count`
+ * are additionally optional, being newer than the surface itself.
+ */
+export const fboCompanySchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().nullable(),
+  phone: z.string().nullable(),
+  description: z.string().nullable(),
+  contact_name: z.string().nullable(),
+  companyType: z.string(),
+  is_ima_imported: z.boolean(),
+  fbo: fboCompanyProfileSchema.nullable(),
+  members_count: z.number().nullable(),
+  movements_count: z.number().nullable(),
+  grants_out_count: z.number().nullable().optional(),
+  grants_in_count: z.number().nullable().optional(),
+  can: z.object({ update: z.boolean(), updateIdentity: z.boolean() }),
+});

package/src/types/fbo.ts

@@ -7,6 +7,9 @@ export type FboGroundServices = z.infer<typeof Fbo.fboGroundServicesSchema>;
 export type FboFlightType = z.infer<typeof Fbo.fboFlightTypeSchema>;
 export type FboFlightStatus = z.infer<typeof Fbo.fboFlightStatusSchema>;
 export type FboOperations = z.infer<typeof Fbo.fboOperationsSchema>;
+export type FboPob = z.infer<typeof Fbo.fboPobSchema>;
+export type FboPerson = z.infer<typeof Fbo.fboPersonSchema>;
+export type FboFlightDocument = z.infer<typeof Fbo.fboFlightDocumentSchema>;
 export type FboFlight = z.infer<typeof Fbo.fboFlightSchema>;
 export type FboOccupation = z.infer<typeof Fbo.fboOccupationSchema>;
 export type FboDuty = z.infer<typeof Fbo.fboDutySchema>;
@@ -33,3 +36,10 @@ export type FboActivityChanges = z.infer<typeof Fbo.fboActivityChangesSchema>;
 export type FboActivity = z.infer<typeof Fbo.fboActivitySchema>;
 export type FboRecurringFlight = z.infer<typeof Fbo.fboRecurringFlightSchema>;
 export type FboMaterialiseResult = z.infer<typeof Fbo.fboMaterialiseResultSchema>;
+export type FboGrantAbility = z.infer<typeof Fbo.fboGrantAbilitySchema>;
+export type FboGrantAbilityOption = z.infer<typeof Fbo.fboGrantAbilityOptionSchema>;
+export type FboGrantCompanyRef = z.infer<typeof Fbo.fboGrantCompanyRefSchema>;
+export type FboCompanyGrant = z.infer<typeof Fbo.fboCompanyGrantSchema>;
+export type FboCompanyGrantInput = z.infer<typeof Fbo.fboCompanyGrantInputSchema>;
+export type FboMeta = z.infer<typeof Fbo.fboMetaSchema>;
+export type FboCompany = z.infer<typeof Fbo.fboCompanySchema>;