hvv-client 0.0.0

package/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true

package/.eslintignore

@@ -0,0 +1 @@
+build/

package/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./node_modules/gts/"
+}

package/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>

package/.idea/jsLinters/eslint.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="EslintConfiguration">
+    <option name="fix-on-save" value="true" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/hvv-client.iml" filepath="$PROJECT_DIR$/.idea/hvv-client.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/prettier.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PrettierConfiguration">
+    <option name="myConfigurationMode" value="AUTOMATIC" />
+    <option name="myRunOnSave" value="true" />
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/.prettierrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  ...require('gts/.prettierrc.json')
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "hvv-client",
+  "version": "0.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "lint": "gts lint",
+    "clean": "gts clean",
+    "compile": "tsc",
+    "fix": "gts fix",
+    "prepare": "npm run compile",
+    "pretest": "npm run compile",
+    "posttest": "npm run lint"
+  },
+  "dependencies": {
+    "crypto-js": "^4.2.0",
+    "date-fns": "^4.1.0",
+    "date-fns-tz": "^3.2.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/node": "^22.7.5",
+    "gts": "^6.0.2",
+    "typescript": "^5.6.3"
+  },
+  "private": false
+}

package/src/client/hvvClient.ts

@@ -0,0 +1,206 @@
+import {ZodSchema} from 'zod';
+import hmacSHA1 from 'crypto-js/hmac-sha1';
+import Base64 from 'crypto-js/enc-base64';
+
+import {HvvClientOptions} from './hvvClientOptions';
+import {RoutePointStation, RoutePointStationSimple} from '../models/routePoint';
+import {Filter} from '../models/filter';
+import {Service} from '../models/service';
+import {StationDepartureInfo} from '../models/stationDepartureInfo';
+import {dateConverter} from '../converters/date.converter';
+import {gtiDepartureListResponseSchema} from '../validators/apiResponse/gtiDepartureList';
+import {lineDepartureConverter} from '../converters/lineDepartureConverter';
+import {routePointConverter} from '../converters/routePoint.converter';
+import {Coordinate} from '../models/coordinate';
+import {gtiCheckNameCoordinatesResponseSchema} from '../validators/apiResponse/gtiCheckName';
+
+type AllHvvClientOptions = Required<HvvClientOptions>;
+
+const defaultOptions: AllHvvClientOptions = {
+  user: '',
+  key: '',
+  version: 59,
+  host: 'https://gti.geofox.de',
+};
+
+export class HvvClient {
+  private readonly options: AllHvvClientOptions;
+
+  public constructor(options: HvvClientOptions) {
+    this.options = {
+      ...defaultOptions,
+      ...options,
+    };
+  }
+
+  /**
+   *
+   */
+  public async getNearbyStations({
+    coordinate,
+    maxDistanceMeters = 800,
+    returnTariffDetails = false,
+  }: {
+    coordinate: Coordinate;
+    maxDistanceMeters: number;
+    returnTariffDetails?: boolean;
+  }): Promise<{
+    stations: {
+      routePoint: RoutePointStation;
+      distanceMeters: number;
+      walkingDistanceMinutes: number;
+    }[];
+  }> {
+    const body = {
+      theName: {
+        type: 'STATION',
+        coordinate: {
+          x: coordinate.long,
+          y: coordinate.lat,
+        },
+      },
+      maxDistance: maxDistanceMeters,
+      coordinateType: 'EPSG_4326',
+      tariffDetails: returnTariffDetails,
+      allowTypeSwitch: false,
+    };
+
+    return await this.makeRequest({
+      endpoint: 'checkName',
+      body,
+      validator: gtiCheckNameCoordinatesResponseSchema,
+      converter: data => {
+        // filter stations
+        const filtered = data.results.filter(item => {
+          return item.type === 'STATION';
+        });
+
+        return {
+          stations: filtered.map(result => ({
+            routePoint: routePointConverter.stationToDto(result),
+            distanceMeters: result.distance,
+            walkingDistanceMinutes: result.time,
+          })),
+        };
+      },
+    });
+  }
+
+  /**
+   * Get departures of a given station.
+   */
+  public async getDepartures({
+    stations,
+    time,
+    filters,
+    serviceFilters,
+    realtime = true,
+    maxResults = 4,
+    maxOffsetMinutes = 60,
+    allStationsInChangingNode = true,
+    returnFilters = false,
+  }: {
+    stations: RoutePointStationSimple[];
+    time: Date;
+    filters?: Filter[];
+    serviceFilters?: Service[];
+    realtime?: boolean;
+    maxResults?: number;
+    maxOffsetMinutes?: number;
+    allStationsInChangingNode?: boolean;
+    returnFilters?: boolean;
+  }): Promise<{departures: StationDepartureInfo[]}> {
+    const body: Record<string, unknown> = {
+      stations: stations.map(routePointConverter.dtoToGti),
+      time: dateConverter.dateToGtiTime(time),
+      maxList: maxResults,
+      maxTimeOffset: maxOffsetMinutes,
+      allStationsInChangingNode: allStationsInChangingNode,
+      returnFilters: returnFilters,
+      useRealtime: realtime,
+    };
+
+    if (filters !== undefined) {
+      body.filter = filters;
+    }
+    if (serviceFilters !== undefined) {
+      body.serviceTypes = serviceFilters;
+    }
+
+    return await this.makeRequest({
+      endpoint: 'departureList',
+      body,
+      validator: gtiDepartureListResponseSchema,
+      converter: data => {
+        const departures = data.departures.map(departure => ({
+          stationId: departure.station?.id ?? null,
+          departure: lineDepartureConverter.toDto(departure, time),
+        }));
+
+        return {
+          departures: departures,
+          // TODO: other fields?
+        };
+      },
+    });
+  }
+
+  // ---
+
+  private async makeRequest<ValidatorOutput, ConverterOutput>({
+    endpoint,
+    body,
+    validator,
+    converter,
+  }: {
+    endpoint: string;
+    body: Record<string, unknown>;
+    validator: ZodSchema<ValidatorOutput>;
+    converter: (data: ValidatorOutput) => ConverterOutput;
+  }): Promise<ConverterOutput> {
+    const fullBody = {
+      version: this.options.version,
+      ...body,
+    };
+
+    const headers = {
+      ...this.getAuthHeaders(fullBody),
+      'Content-Type': 'application/json',
+    };
+
+    console.log('full API request body', fullBody);
+
+    const response = await fetch(
+      `${this.options.host}/gti/public/${endpoint}`,
+      {
+        method: 'POST',
+        body: JSON.stringify(fullBody),
+        headers,
+      },
+    );
+
+    const responseBody = await response.json();
+
+    console.dir(responseBody);
+
+    const {success, data, error} = validator.safeParse(responseBody);
+
+    if (!success) {
+      // eslint-disable-next-line no-debugger
+      debugger;
+      throw error;
+    }
+
+    return converter(data);
+  }
+
+  private getAuthHeaders(requestBody: Record<string, unknown>) {
+    const hmac = hmacSHA1(JSON.stringify(requestBody), this.options.key);
+    const signature = Base64.stringify(hmac);
+
+    return {
+      'geofox-auth-user': this.options.user,
+      'geofox-auth-signature': signature,
+    };
+  }
+}

package/src/client/hvvClientOptions.ts

@@ -0,0 +1,6 @@
+export type HvvClientOptions = {
+  user: string;
+  key: string;
+  version?: number;
+  host?: string;
+};

package/src/converters/attributes.converter.ts

@@ -0,0 +1,13 @@
+import {GtiAttribute} from '../validators/gtiAttribute';
+import {Attribute} from '../models/attribute';
+
+export const attributeConverter = {
+  toDto(gti: GtiAttribute): Attribute {
+    return {
+      id: gti.id ?? null,
+      isPlanned: gti.isPlanned,
+      value: gti.value,
+      types: gti.types,
+    };
+  },
+};

package/src/converters/date.converter.ts

@@ -0,0 +1,96 @@
+import {format, toZonedTime, fromZonedTime} from 'date-fns-tz';
+import {addSeconds} from 'date-fns';
+import {TimeRealtime} from '../models/timeRealtime';
+import {TimeRange} from '../models/timeRange';
+
+export type GtiTime = {date: string; time: string};
+export type GtiTimeRange = {begin: string; end: string};
+
+const GTI_TIMEZONE = 'Europe/Berlin';
+
+export const dateConverter = {
+  /**
+   * Converts a Date into the DateTime object required by the Geofox API (GTI).
+   * @param date
+   */
+  dateToGtiTime(date: Date): GtiTime {
+    // Geofox dates must always be in german timezone as it does not accept ISO dates.
+    // Figure out german timezone and respect that when converting to GtiTime.
+
+    // convert to germany time
+    const germanyTime = toZonedTime(date, GTI_TIMEZONE);
+
+    const gti = {
+      date: format(germanyTime, 'dd.MM.y'),
+      time: format(germanyTime, 'HH:mm'),
+    };
+
+    return gti;
+  },
+
+  /**
+   * Converts a date into a `DateTime` string used by the Geofox API.
+   * This is not a standard ISO string, as the docs require a timezone offset at the end.
+   * The default `.toISOString()` generates something like:
+   * `2024-11-02T09:58:00.000Z`, however the Geofox API expects something like
+   * `2024-11-02T09:58:00.000+0000`
+   * @param date
+   */
+  dateToApiDateTime(date: Date): string {
+    const isoString = date.toISOString();
+    // remove last letter from isoString
+    return isoString.slice(0, -1) + '+0000';
+  },
+
+  apiDateTimeToDate(apiDateTime: string): Date {
+    return new Date(apiDateTime);
+  },
+
+  gtiTimeToDate(gtiTime: GtiTime): Date {
+    const dateParts = gtiTime.date.split('.');
+
+    const germanyTime = new Date(
+      `${dateParts[2]}-${dateParts[1]}-${dateParts[0]}T${gtiTime.time}`,
+    );
+    const utc = fromZonedTime(germanyTime, GTI_TIMEZONE);
+
+    return utc;
+  },
+
+  gtiTimeRangeToDto(gtiTimeRange: GtiTimeRange): TimeRange {
+    const fromDateGermanyTime = new Date(gtiTimeRange.begin);
+    const toDateGermanyTime = new Date(gtiTimeRange.end);
+
+    return {
+      from: fromZonedTime(fromDateGermanyTime, GTI_TIMEZONE),
+      to: fromZonedTime(toDateGermanyTime, GTI_TIMEZONE),
+    };
+  },
+
+  gtiTimeRealtimeCancelToDto(
+    gtiTime: GtiTime,
+    delaySeconds: number | null,
+    isCancelled: boolean,
+  ): TimeRealtime {
+    const planned = dateConverter.gtiTimeToDate(gtiTime);
+
+    return {
+      planned,
+      actual: isCancelled ? null : addSeconds(planned, delaySeconds ?? 0),
+      delaySeconds,
+    };
+  },
+
+  apiTimeRealtimeToDto(
+    apiDateTime: string,
+    delaySeconds: number | null,
+  ): TimeRealtime {
+    const planned = dateConverter.apiDateTimeToDate(apiDateTime);
+
+    return {
+      planned,
+      actual: addSeconds(planned, delaySeconds ?? 0),
+      delaySeconds,
+    };
+  },
+};

package/src/converters/line.converter.ts

@@ -0,0 +1,90 @@
+import {
+  GtiService,
+  GtiSimpleServiceType,
+  isGtiServicePublicTransport,
+} from '../validators/gtiService';
+import {GtiDirection} from '../validators/gtiDirection';
+import {Line} from '../models/line';
+
+function getLineImageUrl(lineId: string): string {
+  return `https://cloud.geofox.de/icon/line?height=28&lineKey=${lineId}`;
+}
+
+/**
+ * Converter for a `Line`.
+ *
+ * In Geofox, this is called a `Service`.
+ */
+export const lineConverter = {
+  toDto(gti: GtiService): Line {
+    const base = {
+      name: gti.name,
+    };
+
+    if (isGtiServicePublicTransport(gti)) {
+      switch (gti.type.simpleType) {
+        case GtiSimpleServiceType.BUS:
+          return {
+            ...base,
+            type: 'bus',
+            direction: gti.direction,
+            directionType:
+              gti.directionId === GtiDirection.FORWARDS
+                ? 'forward'
+                : 'backward',
+            id: gti.id,
+            iconUrl: getLineImageUrl(gti.id),
+          };
+        case GtiSimpleServiceType.TRAIN:
+          return {
+            ...base,
+            type: 'train',
+            direction: gti.direction,
+            directionType:
+              gti.directionId === GtiDirection.FORWARDS
+                ? 'forward'
+                : 'backward',
+            id: gti.id,
+            iconUrl: getLineImageUrl(gti.id),
+          };
+        case GtiSimpleServiceType.SHIP:
+          return {
+            ...base,
+            type: 'ship',
+            direction: gti.direction,
+            directionType:
+              gti.directionId === GtiDirection.FORWARDS
+                ? 'forward'
+                : 'backward',
+            id: gti.id,
+            iconUrl: getLineImageUrl(gti.id),
+          };
+      }
+    }
+
+    switch (gti.type.simpleType) {
+      case GtiSimpleServiceType.BICYCLE:
+        return {
+          ...base,
+          type: 'bicycle',
+        };
+      case GtiSimpleServiceType.FOOTPATH:
+        return {
+          ...base,
+          type: 'footwalk',
+        };
+      case GtiSimpleServiceType.CHANGE:
+        return {
+          ...base,
+          type: 'changeStation',
+        };
+      case GtiSimpleServiceType.CHANGE_SAME_PLATFORM:
+        return {
+          ...base,
+          type: 'changePlatform',
+        };
+    }
+
+    throw new Error(`unknown line type: ${gti.type.simpleType}`);
+  },
+};

package/src/converters/lineDepartureConverter.ts

@@ -0,0 +1,42 @@
+import {addMinutes, addSeconds} from 'date-fns';
+
+import {lineConverter} from './line.converter';
+
+import {GtiDeparture} from '../validators/gtiDeparture';
+import {LineDeparture} from '../models/lineDeparture';
+import {isLinePublicTransport} from '../models/line';
+import {attributeConverter} from './attributes.converter';
+
+export const lineDepartureConverter = {
+  toDto(gti: GtiDeparture, referenceTime: Date): LineDeparture {
+    const isCancelled = gti.cancelled ?? false;
+    const delaySeconds = gti.delay ?? null;
+    const planned = addMinutes(referenceTime, gti.timeOffset);
+    const actual = isCancelled ? null : addSeconds(planned, delaySeconds ?? 0);
+
+    const line = lineConverter.toDto({
+      directionId: gti.directionId, // for some reason the directionId is not in the line object for this request...
+      ...gti.line,
+    });
+    if (!isLinePublicTransport(line)) {
+      throw new Error('Invalid line: not public transport');
+    }
+
+    return {
+      line,
+      departure: {
+        planned,
+        actual,
+        delaySeconds,
+      },
+      departurePlatformPlanned: gti.platform ?? null,
+      departurePlatformActual: gti.realtimePlatform ?? null,
+      attributes: (gti.attributes ?? []).map(att =>
+        attributeConverter.toDto(att),
+      ),
+      isExtra: gti.extra ?? false,
+      isCancelled,
+      uniqueServiceId: gti.serviceId,
+    };
+  },
+};