@cosmicdrift/kumiko-framework 0.94.0 → 0.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.94.0",
+  "version": "0.95.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.94.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.95.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/types/handlers.ts

@@ -7,7 +7,7 @@ import type { Logger } from "../../logging/types";
 import type { Meter, MetricsHandle, Tracer } from "../../observability/types";
 import type { EntityCache } from "../../pipeline/entity-cache";
 import type { SearchAdapter } from "../../search/types";
-import type { TzContext } from "../../time";
+import type { GeoTzProvider, TzContext } from "../../time";
 import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config";
 import type { KumikoEventTypeMap } from "./event-type-map";
 
@@ -288,6 +288,10 @@ export type AppContext = SharedContextFields & {
   readonly triggerName?: string;
   readonly _userId?: string | undefined;
   readonly _handlerType?: string | undefined;
+  /** Optionaler Geo→Zone-Adapter. Wenn gesetzt (via buildServer-context oder
+   *  runProdApp/runDevApp extraContext), reicht der Dispatcher ihn an
+   *  ctx.tz.fromCoordinates / fromAddress weiter. Ohne Provider werfen diese. */
+  readonly geoTzProvider?: GeoTzProvider;
   /** Tenant des aktuellen Pipeline-Calls. Wird vom Dispatcher beim Bauen
    *  des HandlerContext aus `user.tenantId` gespiegelt, damit lifecycle-
    *  pipeline + system-hooks den Wert ohne Zugriff auf user-Object haben.

package/src/pipeline/dispatcher.ts

@@ -544,8 +544,12 @@ export function createDispatcher(
     // `context` can be overridden, but we want the authoritative registry
     // from the dispatcher's own closure to win.
     // ctx.tz ist immer da. Tenant + User-Defaults kommen aus dem
-    // SessionUser sobald die Felder existieren — bis dahin "UTC".
-    const tz = createTzContext();
+    // SessionUser sobald die Felder existieren — bis dahin "UTC". Ein
+    // app-injizierter GeoTzProvider (context.geoTzProvider) speist
+    // ctx.tz.fromCoordinates / fromAddress.
+    const tz = createTzContext(
+      context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {},
+    );
 
     return {
       ...context,

package/src/time/__tests__/geo-tz.test.ts

@@ -0,0 +1,65 @@
+// ctx.tz.fromCoordinates / fromAddress — der GeoTzProvider-Injection-Seam.
+// Das Framework liefert nur Interface + Delegation; ohne Provider wird klar
+// geworfen statt still zu raten.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import type { GeoTzProvider } from "../geo-tz";
+import { ensureTemporalPolyfill } from "../polyfill";
+import { createTzContext } from "../tz-context";
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+});
+
+const BERLIN = { latitude: 52.52, longitude: 13.405 };
+
+describe("ctx.tz — GeoTzProvider seam", () => {
+  test("fromCoordinates delegiert an den Provider (sync)", async () => {
+    const provider: GeoTzProvider = { fromCoordinates: () => "Europe/Berlin" };
+    const tz = createTzContext({ geoTz: provider });
+    expect(await tz.fromCoordinates(BERLIN)).toBe("Europe/Berlin");
+  });
+
+  test("fromCoordinates delegiert an den Provider (async)", async () => {
+    const provider: GeoTzProvider = { fromCoordinates: async () => "Asia/Tokyo" };
+    const tz = createTzContext({ geoTz: provider });
+    expect(await tz.fromCoordinates({ latitude: 35.68, longitude: 139.69 })).toBe("Asia/Tokyo");
+  });
+
+  test("fromCoordinates reicht die Koordinaten unverändert durch", async () => {
+    let seen: { latitude: number; longitude: number } | undefined;
+    const provider: GeoTzProvider = {
+      fromCoordinates: (c) => {
+        seen = c;
+        return "Europe/Berlin";
+      },
+    };
+    await createTzContext({ geoTz: provider }).fromCoordinates(BERLIN);
+    expect(seen).toEqual(BERLIN);
+  });
+
+  test("fromCoordinates wirft ohne Provider", async () => {
+    const tz = createTzContext();
+    await expect(tz.fromCoordinates(BERLIN)).rejects.toThrow(/GeoTzProvider/);
+  });
+
+  test("fromAddress delegiert wenn der Provider es unterstützt", async () => {
+    const provider: GeoTzProvider = {
+      fromCoordinates: () => "UTC",
+      fromAddress: (a) => (a.country === "PT" ? "Europe/Lisbon" : "UTC"),
+    };
+    const tz = createTzContext({ geoTz: provider });
+    expect(await tz.fromAddress({ country: "PT" })).toBe("Europe/Lisbon");
+  });
+
+  test("fromAddress wirft wenn der Provider kein fromAddress hat (offline lat/lng)", async () => {
+    const provider: GeoTzProvider = { fromCoordinates: () => "UTC" };
+    const tz = createTzContext({ geoTz: provider });
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/fromAddress/);
+  });
+
+  test("fromAddress wirft ohne Provider", async () => {
+    const tz = createTzContext();
+    await expect(tz.fromAddress({ country: "PT" })).rejects.toThrow(/GeoTzProvider/);
+  });
+});

package/src/time/geo-tz.ts

@@ -0,0 +1,32 @@
+// GeoTzProvider — optionaler Adapter Geo-Position → IANA-Zone. Das Framework
+// definiert NUR das Interface + den Injection-Seam (ctx.tz.fromCoordinates /
+// fromAddress); eine konkrete Implementation kommt aus einem separaten Paket
+// (z.B. ein geo-tz-basiertes Offline-Paket). v1-Default: kein Provider — die
+// fromCoordinates/fromAddress-Methoden werfen klar statt still falsch zu raten.
+//
+// `fromCoordinates` ist die PRIMÄRE Methode: Offline-geo-tz-Libs lösen
+// lat/lng → Zone (genau, offline, kostenlos) — sie kennen keine Postadressen.
+// `fromAddress` ist optional, für Provider die eine Geocoding-API (Adresse →
+// Zone, online) anbinden. Diese Trennung hält das Interface kompatibel mit
+// beiden Provider-Klassen, statt eine Adress-Form zu erzwingen die der
+// Offline-Fall gar nicht bedienen kann.
+
+export type GeoCoordinates = {
+  readonly latitude: number;
+  readonly longitude: number;
+};
+
+export type GeoAddress = {
+  readonly street?: string;
+  readonly city?: string;
+  readonly region?: string;
+  readonly postalCode?: string;
+  readonly country?: string;
+};
+
+export type GeoTzProvider = {
+  /** Geo-Koordinaten → IANA-Zone (offline lat/lng → tz). */
+  readonly fromCoordinates: (coords: GeoCoordinates) => string | Promise<string>;
+  /** Optional: Postadresse → IANA-Zone (Geocoding-API-Provider). */
+  readonly fromAddress?: (address: GeoAddress) => string | Promise<string>;
+};

package/src/time/index.ts

@@ -7,11 +7,10 @@
 //   - LocatedTimestampJson: API-Boundary-Form { at, tz }
 //   - isValidIanaTimeZone: IANA-Zonennamen-Validierung (type:"tz"-Felder)
 //   - warnIfNonUtcServerTimeZone: Boot-Warnung bei nicht-UTC Prozess-TZ
-//
-// Kommt:
-//   - UI-Komponenten <DateTimeInput>, <LocatedDateTimePicker>, <DateInput>
+//   - GeoTzProvider: optionaler Geo→Zone-Adapter (ctx.tz.fromCoordinates/fromAddress)
 
 export { warnIfNonUtcServerTimeZone } from "./boot-tz-warning";
+export type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 export { isValidIanaTimeZone } from "./iana";
 export { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 export {

package/src/time/tz-context.ts

@@ -14,6 +14,7 @@
 // Stand: beide default auf "UTC" — sobald tenant.timezone +
 // user.timezone Felder existieren, lese ich sie aus dem Request-Context.
 
+import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 
 // JSON-Form für Wall-Clock+TZ — siehe locatedTimestamp(name) Helper in
@@ -52,6 +53,14 @@ export type TzContext = {
 
   /** JSON-Pair { at, tz } → ZonedDateTime (Wall-Clock + IANA). */
   fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
+
+  /** Geo-Koordinaten → IANA-Zone via konfiguriertem GeoTzProvider.
+   *  Wirft wenn kein Provider konfiguriert ist (v1-Default). */
+  fromCoordinates(coords: GeoCoordinates): Promise<string>;
+  /** Postadresse → IANA-Zone via GeoTzProvider. Wirft wenn kein Provider
+   *  konfiguriert ist ODER der Provider kein fromAddress unterstützt (der
+   *  Offline-lat/lng-Provider tut das nicht). */
+  fromAddress(address: GeoAddress): Promise<string>;
 };
 
 export type TzContextOptions = {
@@ -59,6 +68,9 @@ export type TzContextOptions = {
   readonly tenant?: string;
   /** User-Override. Default = tenant. */
   readonly user?: string;
+  /** Optionaler Geo→Zone-Adapter für ctx.tz.fromCoordinates / fromAddress.
+   *  Ohne Provider werfen diese Methoden. */
+  readonly geoTz?: GeoTzProvider;
 };
 
 /**
@@ -70,6 +82,7 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
   const T = getTemporal();
   const tenant = options.tenant ?? "UTC";
   const user = options.user ?? tenant;
+  const geoTz = options.geoTz;
 
   return {
     tenant,
@@ -93,6 +106,22 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
       tz: zdt.timeZoneId,
     }),
     fromLocatedJson: (obj) => T.PlainDateTime.from(obj.at).toZonedDateTime(obj.tz),
+    fromCoordinates: async (coords) => {
+      if (geoTz === undefined) {
+        throw new Error(
+          "ctx.tz.fromCoordinates requires a GeoTzProvider — inject one via the app context (e.g. buildServer({ context: { geoTzProvider } }) or runProdApp({ extraContext: { geoTzProvider } })) or install a provider package.",
+        );
+      }
+      return geoTz.fromCoordinates(coords);
+    },
+    fromAddress: async (address) => {
+      if (geoTz?.fromAddress === undefined) {
+        throw new Error(
+          "ctx.tz.fromAddress requires a GeoTzProvider that implements fromAddress (geocoding). Offline lat/lng providers only support fromCoordinates.",
+        );
+      }
+      return geoTz.fromAddress(address);
+    },
   };
 }