mta-js 1.0.0 → 1.0.1

package/README.md

@@ -16,6 +16,41 @@ await mta.alerts.current({ mode: "subway" });
 await mta.stops.near({ lat, lon, modes: ["subway", "bus"] });
 ```
 
+## Hosted API
+
+Pass an `apiKey` to use the hosted MTA API instead of calling MTA feeds and local
+static GTFS directly. The public method names stay the same, but requests are sent
+to `https://www.mtaapi.dev/api/v1` with the key attached.
+
+```ts
+import { MTA } from "mta-js";
+
+const mta = new MTA({
+  apiKey: process.env.MTA_API_KEY,
+});
+
+await mta.subway.arrivals({ stopId: "A27", route: "A" });
+await mta.bus.arrivals({ stopId: "308214", route: "M23" });
+await mta.bus.vehicles({ route: "M23", limit: 5 });
+await mta.alerts.current({ mode: "subway" });
+await mta.stops.near({
+  lat: 40.7356,
+  lon: -73.9804,
+  modes: ["subway", "bus"],
+  route: "M23",
+  includeRoutes: true,
+});
+```
+
+Use `apiBaseUrl` to point at a preview, staging, or self-hosted compatible API:
+
+```ts
+const mta = new MTA({
+  apiKey: process.env.MTA_API_KEY,
+  apiBaseUrl: "https://staging.example.com",
+});
+```
+
 ## Database
 
 Realtime feeds only become useful after they are joined back to static GTFS stops, routes, and trips. Today, `databaseUrl` points to a SQLite database used by `bun:sqlite`.
@@ -315,6 +350,14 @@ mta.static.importSeed(
 );
 ```
 
+## Roadmap
+
+- Expand the package beyond NYC MTA into a normalized US metro SDK while keeping the existing MTA API stable.
+- Prioritize large systems with documented APIs and realtime data first: MBTA (Boston), WMATA (DC), CTA (Chicago), and BART (Bay Area).
+- Add adapters for mid-tier systems that expose GTFS, GTFS Realtime, or partial APIs, including SEPTA, LA Metro, and MARTA.
+- Model agency-specific quirks behind shared concepts like arrivals, vehicles, service alerts, route-aware nearby stops, static GTFS import, and hosted API access.
+- Track smaller agencies separately because support quality varies: some only publish static GTFS, some have buried realtime feeds, and some have no public API surface.
+
 ## Development
 
 ```sh

package/index.ts

@@ -21,6 +21,7 @@ import type {
   GtfsImportSummary,
   MTAEndpoints,
   MTAOptions,
+  NearbyStop,
   Route,
   Stop,
   StopsNearQuery,
@@ -41,6 +42,8 @@ export class MTA {
 
   readonly fetch: typeof fetch;
   readonly now: () => Date;
+  readonly apiKey?: string;
+  readonly apiBaseUrl: string;
   readonly busTimeKey?: string;
   readonly endpoints: MTAEndpoints;
   readonly options: MTAOptions;
@@ -52,6 +55,8 @@ export class MTA {
     this.options = options;
     this.fetch = options.fetch ?? fetch;
     this.now = options.now ?? (() => new Date());
+    this.apiKey = options.apiKey;
+    this.apiBaseUrl = options.apiBaseUrl ?? "https://www.mtaapi.dev";
     this.busTimeKey = options.busTimeKey;
     this.realtimeCacheTtlMs = options.realtimeCacheTtlMs ?? 15_000;
     this.endpoints = {
@@ -114,6 +119,28 @@ export class MTA {
     }
     return feed;
   }
+
+  hostedApiEnabled() {
+    return Boolean(this.apiKey);
+  }
+
+  async hostedJson<T>(path: string, query: object = {}): Promise<T> {
+    if (!this.apiKey) {
+      throw new Error("mta-js hosted API calls require an apiKey.");
+    }
+
+    const url = urlWithParams(
+      new URL(path, this.apiBaseUrl).toString(),
+      serializeHostedQuery(query),
+    );
+
+    return fetchJson(this.fetch, url, {
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "x-api-key": this.apiKey,
+      },
+    }) as Promise<T>;
+  }
 }
 
 class DatabaseClient {
@@ -135,6 +162,10 @@ class DatabaseClient {
   }
 
   async status(): Promise<DatabaseStatus> {
+    if (this.mta.hostedApiEnabled()) {
+      return this.mta.hostedJson<DatabaseStatus>("/api/v1/database/status");
+    }
+
     await this.mta.ready();
     return this.mta.static.status();
   }
@@ -206,6 +237,10 @@ class SubwayClient {
     limit?: number;
     includeRaw?: boolean;
   }): Promise<Arrival[]> {
+    if (this.mta.hostedApiEnabled()) {
+      return this.mta.hostedJson<Arrival[]>("/api/v1/subway/arrivals", query);
+    }
+
     await this.mta.ready();
     const routeIds = query.route ? [normalizeRouteId(query.route)] : Object.keys(this.mta.endpoints.subwayFeeds);
     const feeds = [...new Set(routeIds.map((route) => this.feedForRoute(route)))];
@@ -288,6 +323,10 @@ class BusClient {
   constructor(private readonly mta: MTA) {}
 
   async arrivals(query: BusArrivalQuery): Promise<Arrival[]> {
+    if (this.mta.hostedApiEnabled()) {
+      return this.mta.hostedJson<Arrival[]>("/api/v1/bus/arrivals", query);
+    }
+
     await this.mta.ready();
     const key = this.requireKey();
     const body = await fetchJson(
@@ -332,6 +371,10 @@ class BusClient {
   }
 
   async vehicles(query: BusVehicleQuery = {}): Promise<Vehicle[]> {
+    if (this.mta.hostedApiEnabled()) {
+      return this.mta.hostedJson<Vehicle[]>("/api/v1/bus/vehicles", query);
+    }
+
     await this.mta.ready();
     const key = this.requireKey();
     const body = await fetchJson(
@@ -378,6 +421,10 @@ class AlertsClient {
   constructor(private readonly mta: MTA) {}
 
   async current(query: AlertQuery = {}): Promise<Alert[]> {
+    if (this.mta.hostedApiEnabled()) {
+      return this.mta.hostedJson<Alert[]>("/api/v1/alerts", query);
+    }
+
     await this.mta.ready();
     const feed = await this.mta.realtimeFeed(this.mta.endpoints.alerts);
     const alerts: Alert[] = [];
@@ -419,7 +466,11 @@ class AlertsClient {
 class StopsClient {
   constructor(private readonly mta: MTA) {}
 
-  near(query: StopsNearQuery): Promise<Stop[]> {
+  near(query: StopsNearQuery): Promise<NearbyStop[]> {
+    if (this.mta.hostedApiEnabled()) {
+      return this.mta.hostedJson<NearbyStop[]>("/api/v1/stops/near", query);
+    }
+
     return this.mta.ready().then(() => {
       for (const mode of query.modes ?? []) {
         if (!this.mta.static.hasStaticData(mode)) throw new StaticDataMissingError(mode);
@@ -429,6 +480,26 @@ class StopsClient {
   }
 }
 
+function serializeHostedQuery(query: object) {
+  const params: Record<string, string | number | boolean | undefined> = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (
+      value === undefined ||
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      params[key] = value;
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      params[key] = value.join(",");
+    }
+  }
+  return params;
+}
+
 function normalizeRouteId(route: string) {
   return route.toUpperCase().trim();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mta-js",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A TypeScript client for MTA realtime and static GTFS data.",
   "license": "MIT",
   "repository": {

package/src/http.ts

@@ -8,15 +8,18 @@ export async function fetchArrayBuffer(fetchImpl: typeof fetch, url: string) {
   return response.arrayBuffer();
 }
 
-export async function fetchJson(fetchImpl: typeof fetch, url: string) {
-  const response = await fetchImpl(url);
+export async function fetchJson(fetchImpl: typeof fetch, url: string, init?: RequestInit) {
+  const response = await fetchImpl(url, init);
   if (!response.ok) {
     throw new FeedError(`MTA API request failed: ${response.status} ${response.statusText}`, response);
   }
   return response.json() as Promise<unknown>;
 }
 
-export function urlWithParams(base: string, params: Record<string, string | number | undefined>) {
+export function urlWithParams(
+  base: string,
+  params: Record<string, string | number | boolean | undefined>,
+) {
   const url = new URL(base);
   for (const [key, value] of Object.entries(params)) {
     if (value !== undefined && value !== "") {

package/src/types.ts

@@ -3,6 +3,8 @@ export type TransitMode = "subway" | "bus" | "lirr" | "metro-north";
 export type Direction = "north" | "south" | "east" | "west" | "unknown";
 
 export interface MTAOptions {
+  apiKey?: string;
+  apiBaseUrl?: string;
   busTimeKey?: string;
   databaseUrl?: string;
   databaseAuthToken?: string;
@@ -118,6 +120,14 @@ export interface Stop {
   mode?: TransitMode;
 }
 
+export type NearbyStop = Stop & {
+  distanceMeters?: number;
+  servedRoutes?: Route[];
+  routeMatch?: boolean;
+  routeHeadsigns?: string[];
+  note?: string;
+};
+
 export interface Arrival {
   mode: TransitMode;
   route: Route;
@@ -196,6 +206,8 @@ export interface StopsNearQuery {
   lat: number;
   lon: number;
   modes?: TransitMode[];
+  route?: string;
+  includeRoutes?: boolean;
   radiusMeters?: number;
   limit?: number;
 }