feat: enhance location handling and localization; improve fallback mechanisms and unify type definitions

libs/api/src/index.ts

@@ -2,6 +2,7 @@ export * from './lib/base-api';
 export * from './lib/query-and-mutation';
 export * from './lib/session';
 export * from './lib/features/licensing';
+export * from './lib/features/location';
 export * from './lib/features/seafarer';
 export * from './lib/features/vessel';
 export { baseQueryWithReauth, configureTokenRefresh } from './lib/base-api/base-query-with-reauth';

libs/api/src/lib/features/licensing/licensing.helpers.ts

@@ -183,7 +183,13 @@ export function localized(value: Bilingual | undefined, language = 'en'): string
   if (!value) return '';
   // `||` not `??`: an empty Amharic string is "not translated", not a value —
   // editors save `am: ''` freely (ExamPage, CertificationPage, LocationForm).
-  return (language === 'am' ? value.am : value.en) || value.en || value.am || '';
+  //
+  // Keyed by the active language rather than an en/am ternary, so a locale the
+  // backend stores but the UI does not yet offer a switcher for (`om`, `so` on
+  // location names) still resolves once it does. English then Amharic remain
+  // the fallbacks, in that order.
+  const active = value[language as keyof Bilingual];
+  return active || value.en || value.am || '';
 }
 
 /**

libs/api/src/lib/features/licensing/licensing.types.ts

@@ -4,7 +4,18 @@
 // seafarer domain, and two copies would drift.
 import type { SeafarerDepartment } from '../seafarer/seafarer.types';
 
-export type Bilingual = { en?: string; am?: string };
+/**
+ * A backend `LocaleValidationDto`. Named for the two locales the UI offers, but
+ * carries every locale the column stores — location names are seeded with `om`
+ * (Finfinnee) and `so` too, and a type that declared only en/am made those
+ * unreachable through the typed client.
+ */
+export type Bilingual = {
+  en?: string;
+  am?: string;
+  om?: string;
+  so?: string;
+};
 
 /**
  * The application status vocabulary. Single source of truth for both apps —

libs/api/src/lib/features/location/index.ts

@@ -0,0 +1 @@
+export * from './location.types';

libs/api/src/lib/features/location/location.types.ts

@@ -0,0 +1,47 @@
+/** Shared location contract — mirrors the `iam.locations` tree in emaapi. */
+
+import type { Bilingual } from '../licensing/licensing.types';
+
+/**
+ * One node of the location tree.
+ *
+ * Both apps read the same `/locations` route, so the model lives here rather
+ * than in each app's own feature folder — the two hand-maintained copies had
+ * already drifted (the portal's lacked `locationType`, `children` and the
+ * timestamps, and its query accepted no `parentId` filter even though the
+ * backend supports one).
+ *
+ * `names` is `Bilingual`, the backend's `LocaleValidationDto`: seeded location
+ * names carry `om` and `so` alongside `en`/`am`, which the previous
+ * `{ en, am }` pair made unreachable.
+ */
+export interface Location {
+  id: string;
+  code: string;
+  names: Bilingual;
+  locationTypeId: string;
+  parentId: string | null;
+  locationType?: LocationType;
+  children?: Location[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * A level in the tree. `level` orders them (City 1 → Sub-city 2 → Woreda 3 →
+ * Kebele 4); `code` is what both sides key behaviour off, so it is the field to
+ * match on rather than the display name.
+ */
+export interface LocationType {
+  id: string;
+  code: string;
+  names: Bilingual;
+  level: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface ListResponse<T> {
+  count: number;
+  items: T[];
+}