Narrow down types and reflect API changes (#2)

* Update to match recent API changes: * Update ban-related fields in line with recent changes * Add meetup_at to APIGameEvent * Narrow down fields in certain types for better IntelliSense * Loosen param types for methods returning API routes to accept string where applicable
TruckersMP · May 17, 2024 · 8651788 · 8651788
1 parent 4edc3c3
commit 8651788
Show file tree

Hide file tree

Showing 10 changed files with 282 additions and 97 deletions.
diff --git a/traffic/v2/index.ts b/traffic/v2/index.ts
@@ -3,7 +3,7 @@ import type { APITrafficServerGameName } from './server';
 export * from './server';
 export * from './traffic';
 
-export const APITrafficVersion = '2';
+export const APITrafficVersion = '2' as const;
 
 export const APITrafficRoutes = {
   /**

diff --git a/traffic/v2/server.ts b/traffic/v2/server.ts
@@ -70,16 +70,30 @@ export interface APITrafficServer {
 /**
  * Response type of the traffic servers API end-point.
  */
-export interface APITrafficServers {
-  /**
-   * Determines whether the service is offline. If this is the case, no servers
-   * and/or traffic information may be provided.
-   */
-  offline: boolean;
+export type APITrafficServers =
+  | {
+      /**
+       * Determines whether the service is offline. If this is the case, no servers
+       * and/or traffic information may be provided.
+       */
+      offline: false;
 
-  /**
-   * A collection of public game servers.
-   * @see https://truckersmp.com/developers/api#operation/get-servers
-   */
-  servers?: APITrafficServer[];
-}
+      /**
+       * A collection of public game servers.
+       * @see https://truckersmp.com/developers/api#operation/get-servers
+       */
+      servers: APITrafficServer[];
+    }
+  | {
+      /**
+       * Determines whether the service is offline. If this is the case, no servers
+       * and/or traffic information may be provided.
+       */
+      offline: true;
+
+      /**
+       * A collection of public game servers.
+       * @see https://truckersmp.com/developers/api#operation/get-servers
+       */
+      servers?: never;
+    };
diff --git a/traffic/v2/traffic.ts b/traffic/v2/traffic.ts
@@ -3,7 +3,12 @@ import type { APITrafficServer } from './server';
 /**
  * The congestion severity of the given location.
  */
-export type APITrafficLocationSeverity = 'Empty' | 'Low' | 'Moderate' | 'Congested' | 'Heavy';
+export type APITrafficLocationSeverity =
+  | 'Empty'
+  | 'Low'
+  | 'Moderate'
+  | 'Congested'
+  | 'Heavy';
 
 /**
  * Information about a traffic location on the map.
@@ -60,21 +65,40 @@ export interface APITrafficServerTop {
 /**
  * Response type for all locations on the game server.
  */
-export interface APITrafficServerTraffic {
-  /**
-   * Determines whether the service is offline. If this is the case, no servers
-   * and/or traffic information may be provided.
-   */
-  offline: boolean;
+export type APITrafficServerTraffic =
+  | {
+      /**
+       * Determines whether the service is offline. If this is the case, no servers
+       * and/or traffic information may be provided.
+       */
+      offline: false;
 
-  /**
-   * Basic information of a TruckersMP server.
-   * @see https://truckersmp.com/developers/api#operation/get-servers
-   */
-  server?: Omit<APITrafficServer, 'urls'>;
+      /**
+       * Basic information of a TruckersMP server.
+       * @see https://truckersmp.com/developers/api#operation/get-servers
+       */
+      server: Omit<APITrafficServer, 'urls'>;
 
-  /**
-   * All locations on the map.
-   */
-  traffic?: APITrafficLocation[];
-}
+      /**
+       * All locations on the map.
+       */
+      traffic: APITrafficLocation[];
+    }
+  | {
+      /**
+       * Determines whether the service is offline. If this is the case, no servers
+       * and/or traffic information may be provided.
+       */
+      offline: true;
+
+      /**
+       * Basic information of a TruckersMP server.
+       * @see https://truckersmp.com/developers/api#operation/get-servers
+       */
+      server?: never;
+
+      /**
+       * All locations on the map.
+       */
+      traffic?: never;
+    };
diff --git a/tsconfig.json b/tsconfig.json
@@ -9,7 +9,8 @@
     "skipLibCheck": true,
     "sourceMap": true,
     "declaration": true,
-    "declarationMap": true
+    "declarationMap": true,
+    "strictNullChecks": true
   },
   "exclude": ["./node_modules"]
 }
diff --git a/web/v2/ban.ts b/web/v2/ban.ts
@@ -26,12 +26,16 @@ export interface APIPlayerBan {
   reason: string;
 
   /**
-   * Name of the admin that banned the user.
+   * @deprecated - v2.21.1.0
+   * Name of the admin that banned the user. This field is no longer provided.
+   * @see https://forum.truckersmp.com/index.php?/topic/112993-website-v221-release/#comment-1111277
    */
-  adminName: string;
+  adminName: 'Game Moderator';
 
   /**
-   * TruckersMP ID for the admin that banned the user.
+   * @deprecated - v2.21.1.0
+   * TruckersMP ID for the admin that banned the user. This field is no longer provided.
+   * @see https://forum.truckersmp.com/index.php?/topic/112993-website-v221-release/#comment-1111277
    */
-  adminID: number;
+  adminID: null;
 }
diff --git a/web/v2/event.ts b/web/v2/event.ts
@@ -61,7 +61,7 @@ export interface APIGameEventType {
   /**
    * The event's type key.
    */
-  key: string;
+  key: 'convoy' | 'truck_show' | 'truck_show_and_convoy';
 
   /**
    * The event's type name.
@@ -241,6 +241,11 @@ export interface APIGameEvent {
    */
   arrive: APIGameEventLocation;
 
+  /**
+   * The date and time the event's meetup is scheduled at (UTC).
+   */
+  meetup_at: string | null;
+
   /**
    * The date and time the event starts at (UTC).
    */
@@ -298,8 +303,11 @@ export interface APIGameEvent {
 
   /**
    * The event's required DLCs.
+   *
+   * - Empty array when no DLCs are required;
+   * - Record<string, string> when DLCs are required, where the key is the Steam app ID and value is the DLC's name.
    */
-  dlcs: Record<string, string>;
+  dlcs: Record<string, string> | [];
 
   /**
    * The relative URL to the event page.

diff --git a/web/v2/index.ts b/web/v2/index.ts
@@ -6,7 +6,7 @@ export * from './rules';
 export * from './server';
 export * from './version';
 
-export const APIWebVersion = '2';
+export const APIWebVersion = '2' as const;
 
 export const APIWebRoutes = {
   /**
@@ -17,7 +17,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APIBan[]>
    */
-  bans(id: bigint) {
+  bans(id: bigint | string) {
     return `/bans/${id}` as const;
   },
 
@@ -39,7 +39,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompany>
    */
-  company(id: string | number) {
+  company(id: number | string) {
     return `/vtc/${id}` as const;
   },
 
@@ -51,7 +51,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APIGameEventSimple[]>
    */
-  companyEvents(companyId: string | number) {
+  companyEvents(companyId: number | string) {
     return `/vtc/${companyId}/events` as const;
   },
 
@@ -64,7 +64,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APIGameEvent>
    */
-  companyEvent(companyId: string | number, eventId: number) {
+  companyEvent(companyId: number | string, eventId: number) {
     return `/vtc/${companyId}/events/${eventId}` as const;
   },
 
@@ -76,7 +76,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompanyMembers>
    */
-  companyMembers(companyId: string | number) {
+  companyMembers(companyId: number | string) {
     return `/vtc/${companyId}/members` as const;
   },
 
@@ -89,7 +89,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompanyMember>
    */
-  companyMember(companyId: string | number, memberId: number) {
+  companyMember(companyId: number | string, memberId: number) {
     return `/vtc/${companyId}/member/${memberId}` as const;
   },
 
@@ -101,7 +101,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompanyNews>
    */
-  companyNews(companyId: string | number) {
+  companyNews(companyId: number | string) {
     return `/vtc/${companyId}/news` as const;
   },
 
@@ -114,7 +114,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompanyNewsEntry>
    */
-  companyNewsEntry(companyId: string | number, newsId: number) {
+  companyNewsEntry(companyId: number | string, newsId: number) {
     return `/vtc/${companyId}/news/${newsId}` as const;
   },
 
@@ -126,7 +126,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompanyRoles>
    */
-  companyRoles(companyId: string | number) {
+  companyRoles(companyId: number | string) {
     return `/vtc/${companyId}/roles` as const;
   },
 
@@ -139,7 +139,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APICompanyRoleEntry>
    */
-  companyRole(companyId: string | number, roleId: number) {
+  companyRole(companyId: number | string, roleId: number) {
     return `/vtc/${companyId}/role/${roleId}` as const;
   },
 
@@ -185,7 +185,7 @@ export const APIWebRoutes = {
    *
    * @returns APIResponse<APIPlayer>
    */
-  player(id: bigint) {
+  player(id: bigint | number) {
     return `/player/${id}` as const;
   },