@nyc-transit-kit/mta 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nyc-transit-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @nyc-transit-kit/mta
+
+Part of `nyc-transit-kit`, an Effect-native Bun toolkit for official NYC and MTA transit data APIs.
+
+See the repository README and docs/api-reference.md for public import paths, CLI commands, and release notes.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nyc-transit-kit/mta",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./datasets": "./src/datasets.ts",
+    "./feeds": "./src/feeds.ts",
+    "./errors": "./src/errors.ts",
+    "./gtfs-realtime": "./src/gtfs-realtime.ts",
+    "./gtfs-static": "./src/gtfs-static.ts",
+    "./open-data": "./src/open-data.ts"
+  },
+  "types": "./src/index.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test ./test"
+  },
+  "dependencies": {
+    "@nyc-transit-kit/contracts": "0.1.0",
+    "@nyc-transit-kit/soda3": "0.1.0",
+    "effect": "4.0.0-beta.83",
+    "gtfs-realtime-bindings": "2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mannyc2/nyc-transit-kit.git",
+    "directory": "packages/mta"
+  },
+  "homepage": "https://github.com/mannyc2/nyc-transit-kit#readme",
+  "bugs": {
+    "url": "https://github.com/mannyc2/nyc-transit-kit/issues"
+  },
+  "keywords": [
+    "bun",
+    "effect",
+    "mta",
+    "nyc",
+    "socrata",
+    "transit"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/datasets.ts

@@ -0,0 +1,27 @@
+import { makeDescriptorRegistry } from "@nyc-transit-kit/contracts/descriptor-registry"
+import { MtaOpenDataDatasetDescriptor } from "@nyc-transit-kit/contracts/mta"
+import * as Schema from "effect/Schema"
+import { mtaOpenDataDescriptorRecords } from "./internal/open-data-descriptor-records"
+
+export const mtaOpenDataDomain = "data.ny.gov"
+
+const decodeDescriptor = Schema.decodeUnknownSync(MtaOpenDataDatasetDescriptor)
+const descriptorRegistry = makeDescriptorRegistry({
+  descriptors: mtaOpenDataDescriptorRecords.map((record) => decodeDescriptor(record)),
+  id: (dataset) => String(dataset.id)
+})
+
+const requireMtaOpenDataDescriptor = (datasetId: string) => {
+  const descriptor = descriptorRegistry.findById(datasetId)
+  if (descriptor === undefined) {
+    throw new Error(`Missing MTA Open Data descriptor: ${datasetId}`)
+  }
+  return descriptor
+}
+
+export const mtaOpenDataCatalogDescriptor = requireMtaOpenDataDescriptor("f462-ka72")
+
+export const mtaOpenDataDatasets: ReadonlyArray<MtaOpenDataDatasetDescriptor> =
+  descriptorRegistry.all
+
+export const findMtaOpenDataDataset = (datasetId: string) => descriptorRegistry.findById(datasetId)

package/src/errors.ts

@@ -0,0 +1,22 @@
+import * as Schema from "effect/Schema"
+
+export class MtaHttpError extends Schema.TaggedErrorClass<MtaHttpError>()("MtaHttpError", {
+  operation: Schema.String,
+  status: Schema.Number,
+  statusText: Schema.String
+}) {}
+
+export class MtaDecodeError extends Schema.TaggedErrorClass<MtaDecodeError>()("MtaDecodeError", {
+  feed: Schema.String,
+  message: Schema.String
+}) {}
+
+export class MtaInvalidInputError extends Schema.TaggedErrorClass<MtaInvalidInputError>()(
+  "MtaInvalidInputError",
+  {
+    operation: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export type MtaError = MtaHttpError | MtaDecodeError | MtaInvalidInputError

package/src/feeds.ts

@@ -0,0 +1,69 @@
+import type { GtfsFeedKind } from "@nyc-transit-kit/contracts/mta"
+import {
+  mtaGtfsRealtimeFeedRecords,
+  mtaGtfsStaticFeedRecords,
+  mtaJsonDirectFeedRecords
+} from "./internal/direct-feed-records"
+
+export type MtaDirectFeedSurface =
+  | "gtfs-static"
+  | "gtfs-realtime"
+  | "service-alerts"
+  | "elevator-escalator"
+  | "bus-time"
+
+export interface MtaDirectFeedDescriptor {
+  readonly id: string
+  readonly name: string
+  readonly surface: MtaDirectFeedSurface
+  readonly url: string
+  readonly description?: string
+}
+
+export interface MtaGtfsStaticFeedDescriptor extends MtaDirectFeedDescriptor {
+  readonly surface: "gtfs-static"
+  readonly mode: "subway" | "rail" | "bus"
+}
+
+export interface MtaGtfsRealtimeFeedDescriptor extends MtaDirectFeedDescriptor {
+  readonly surface: "gtfs-realtime"
+  readonly feed: GtfsFeedKind
+  readonly family: "subway" | "rail" | "alerts"
+}
+
+export interface MtaJsonDirectFeedDescriptor extends MtaDirectFeedDescriptor {
+  readonly surface: "service-alerts" | "elevator-escalator" | "bus-time"
+  readonly format: "json" | "xml"
+  readonly requiresApiKey?: boolean
+}
+
+export const mtaGtfsStaticFeeds = mtaGtfsStaticFeedRecords
+
+export const mtaGtfsRealtimeFeeds = mtaGtfsRealtimeFeedRecords
+
+export const mtaJsonDirectFeeds = mtaJsonDirectFeedRecords
+
+export const mtaDirectFeeds = [
+  ...mtaGtfsStaticFeeds,
+  ...mtaGtfsRealtimeFeeds,
+  ...mtaJsonDirectFeeds
+] satisfies ReadonlyArray<
+  MtaGtfsStaticFeedDescriptor | MtaGtfsRealtimeFeedDescriptor | MtaJsonDirectFeedDescriptor
+>
+
+const normalizedLookupKey = (value: string) => value.trim().toLowerCase()
+
+const findFeed = <Feed extends MtaDirectFeedDescriptor>(
+  feeds: ReadonlyArray<Feed>,
+  key: string
+) => {
+  const normalized = normalizedLookupKey(key)
+  return feeds.find(
+    (feed) =>
+      normalizedLookupKey(feed.id) === normalized || normalizedLookupKey(feed.name) === normalized
+  )
+}
+
+export const findMtaGtfsStaticFeed = (key: string) => findFeed(mtaGtfsStaticFeeds, key)
+
+export const findMtaGtfsRealtimeFeed = (key: string) => findFeed(mtaGtfsRealtimeFeeds, key)

package/src/gtfs-realtime.ts

@@ -0,0 +1,259 @@
+import {
+  type GtfsFeedKind,
+  MtaGtfsRealtimeCaptureRequest,
+  type MtaGtfsRealtimeCaptureRequestInput,
+  MtaGtfsRealtimeCaptureResult,
+  MtaGtfsRealtimeDecodedHeader,
+  MtaGtfsRealtimeDecodedSummary,
+  MtaGtfsRealtimeProbeRequest,
+  type MtaGtfsRealtimeProbeRequestInput,
+  MtaGtfsRealtimeProbeResult
+} from "@nyc-transit-kit/contracts/mta"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import * as HttpClient from "effect/unstable/http/HttpClient"
+import type * as HttpClientError from "effect/unstable/http/HttpClientError"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import * as GtfsRealtimeBindings from "gtfs-realtime-bindings"
+import { MtaDecodeError, MtaHttpError, MtaInvalidInputError } from "./errors"
+
+export type GtfsRealtimeDecoderImplementation = (
+  bytes: Uint8Array,
+  feed: GtfsFeedKind
+) => Effect.Effect<unknown, MtaDecodeError>
+export type { MtaGtfsRealtimeCaptureRequestInput, MtaGtfsRealtimeProbeRequestInput }
+
+const FeedMessage = GtfsRealtimeBindings.transit_realtime.FeedMessage
+const FeedHeaderIncrementality = GtfsRealtimeBindings.transit_realtime.FeedHeader.Incrementality
+
+const hasOwn = (value: object, key: PropertyKey) => Object.hasOwn(value, key)
+
+const errorMessage = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+
+const byteToHex = (byte: number) => byte.toString(16).padStart(2, "0")
+
+const arrayBufferFromBytes = (bytes: Uint8Array) => {
+  const buffer = new ArrayBuffer(bytes.byteLength)
+  new Uint8Array(buffer).set(bytes)
+  return buffer
+}
+
+const shouldRedactSearchParameter = (name: string) => {
+  const lower = name.toLowerCase()
+  return lower.includes("key") || lower.includes("token") || lower.includes("secret")
+}
+
+const redactGtfsRealtimeUrl = (url: string) => {
+  try {
+    const parsed = new URL(url)
+
+    for (const name of parsed.searchParams.keys()) {
+      if (shouldRedactSearchParameter(name)) {
+        parsed.searchParams.set(name, "REDACTED")
+      }
+    }
+
+    return parsed.toString()
+  } catch {
+    return "[invalid-url]"
+  }
+}
+
+const incrementalityName = (
+  value: GtfsRealtimeBindings.transit_realtime.FeedHeader.Incrementality
+) => {
+  if (value === FeedHeaderIncrementality.FULL_DATASET) {
+    return "FULL_DATASET"
+  }
+  if (value === FeedHeaderIncrementality.DIFFERENTIAL) {
+    return "DIFFERENTIAL"
+  }
+  return String(value)
+}
+
+const decodedHeader = (header: GtfsRealtimeBindings.transit_realtime.IFeedHeader) =>
+  MtaGtfsRealtimeDecodedHeader.make({
+    gtfsRealtimeVersion: header.gtfsRealtimeVersion,
+    ...(hasOwn(header, "incrementality")
+      ? {
+          incrementality: incrementalityName(
+            header.incrementality ?? FeedHeaderIncrementality.FULL_DATASET
+          )
+        }
+      : {}),
+    ...(hasOwn(header, "timestamp") && header.timestamp !== undefined && header.timestamp !== null
+      ? { timestamp: Number(header.timestamp) }
+      : {})
+  })
+
+export const decodeGtfsRealtimeBytes = Effect.fn("Mta.decodeGtfsRealtimeBytes")(function* (
+  bytes: Uint8Array,
+  feed: GtfsFeedKind
+) {
+  return yield* Effect.try({
+    try: () => {
+      const raw = FeedMessage.decode(bytes)
+      const entities = raw.entity
+
+      return MtaGtfsRealtimeDecodedSummary.make({
+        feed,
+        entityCount: entities.length,
+        tripUpdateCount: entities.filter(
+          (entity) => entity.tripUpdate !== undefined && entity.tripUpdate !== null
+        ).length,
+        vehiclePositionCount: entities.filter(
+          (entity) => entity.vehicle !== undefined && entity.vehicle !== null
+        ).length,
+        alertCount: entities.filter((entity) => entity.alert !== undefined && entity.alert !== null)
+          .length,
+        header: decodedHeader(raw.header),
+        raw
+      })
+    },
+    catch: (cause) =>
+      MtaDecodeError.make({
+        feed,
+        message: errorMessage(cause)
+      })
+  })
+})
+
+export class GtfsRealtimeDecoder extends Context.Service<
+  GtfsRealtimeDecoder,
+  {
+    readonly decode: GtfsRealtimeDecoderImplementation
+  }
+>()("@nyc-transit-kit/mta/GtfsRealtimeDecoder") {
+  static readonly Live = Layer.succeed(GtfsRealtimeDecoder)({
+    decode: decodeGtfsRealtimeBytes
+  })
+
+  // Test/custom fallback for callers that want to bypass protobuf decoding.
+  static readonly Passthrough = Layer.succeed(GtfsRealtimeDecoder)({
+    decode: (bytes, feed) =>
+      Effect.succeed({
+        feed,
+        byteLength: bytes.byteLength
+      })
+  })
+}
+
+const decodeRealtimeInput =
+  <S extends Schema.Top>(schema: S) =>
+  (input: unknown) =>
+    Schema.decodeUnknownEffect(schema)(input).pipe(
+      Effect.catchTag("SchemaError", (error) =>
+        Effect.fail(
+          MtaInvalidInputError.make({
+            operation: "gtfs-realtime",
+            message: error.message
+          })
+        )
+      )
+    )
+
+const decodeRealtimeProbeRequest = decodeRealtimeInput(MtaGtfsRealtimeProbeRequest)
+const decodeRealtimeCaptureRequest = decodeRealtimeInput(MtaGtfsRealtimeCaptureRequest)
+
+const httpStatusText = (status: number) => `HTTP ${status}`
+
+const mapMtaHttpClientError = (operation: string, error: HttpClientError.HttpClientError) => {
+  const response = error.response
+
+  if (response !== undefined) {
+    return MtaHttpError.make({
+      operation,
+      status: response.status,
+      statusText: httpStatusText(response.status)
+    })
+  }
+
+  return MtaHttpError.make({
+    operation,
+    status: 0,
+    statusText: error.message
+  })
+}
+
+const fetchGtfsRealtimeBytes = Effect.fn("Mta.fetchGtfsRealtimeBytes")(function* (request: {
+  readonly feed: GtfsFeedKind
+  readonly url: string
+}) {
+  const response = yield* HttpClient.execute(HttpClientRequest.get(request.url)).pipe(
+    Effect.mapError((error) => mapMtaHttpClientError("gtfs-realtime", error))
+  )
+
+  if (response.status < 200 || response.status >= 300) {
+    return yield* MtaHttpError.make({
+      operation: "gtfs-realtime",
+      status: response.status,
+      statusText: httpStatusText(response.status)
+    })
+  }
+
+  const buffer = yield* response.arrayBuffer.pipe(
+    Effect.mapError(() =>
+      MtaHttpError.make({
+        operation: "gtfs-realtime",
+        status: response.status,
+        statusText: "Failed to read response body"
+      })
+    )
+  )
+  const bytes = new Uint8Array(buffer)
+
+  return {
+    response,
+    bytes
+  }
+})
+
+const sha256Hex = Effect.fn("Mta.sha256Hex")(function* (bytes: Uint8Array, feed: GtfsFeedKind) {
+  const digest = yield* Effect.tryPromise({
+    try: () => crypto.subtle.digest("SHA-256", arrayBufferFromBytes(bytes)),
+    catch: (cause) =>
+      MtaDecodeError.make({
+        feed,
+        message: `Failed to hash GTFS realtime capture: ${errorMessage(cause)}`
+      })
+  })
+
+  return Array.from(new Uint8Array(digest), byteToHex).join("")
+})
+
+export const probeGtfsRealtime = Effect.fn("Mta.probeGtfsRealtime")(function* (
+  input: MtaGtfsRealtimeProbeRequestInput
+) {
+  const request = yield* decodeRealtimeProbeRequest(input)
+  const decoder = yield* GtfsRealtimeDecoder
+  const { response, bytes } = yield* fetchGtfsRealtimeBytes(request)
+  const decoded = yield* decoder.decode(bytes, request.feed)
+
+  return MtaGtfsRealtimeProbeResult.make({
+    feed: request.feed,
+    ok: response.status >= 200 && response.status < 300,
+    status: response.status,
+    byteLength: bytes.byteLength,
+    decoded
+  })
+})
+
+export const captureGtfsRealtime = Effect.fn("Mta.captureGtfsRealtime")(function* (
+  input: MtaGtfsRealtimeCaptureRequestInput
+) {
+  const request = yield* decodeRealtimeCaptureRequest(input)
+  const { response, bytes } = yield* fetchGtfsRealtimeBytes(request)
+  const sha256 = yield* sha256Hex(bytes, request.feed)
+
+  return MtaGtfsRealtimeCaptureResult.make({
+    feed: request.feed,
+    status: response.status,
+    byteLength: bytes.byteLength,
+    sha256,
+    capturedAt: new Date().toISOString(),
+    url: redactGtfsRealtimeUrl(request.url),
+    bytes
+  })
+})

package/src/gtfs-static.ts

@@ -0,0 +1,117 @@
+import {
+  MtaGtfsStaticFetchRequest,
+  type MtaGtfsStaticFetchRequestInput,
+  MtaGtfsStaticProbeResult
+} from "@nyc-transit-kit/contracts/mta"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient"
+import * as HttpClient from "effect/unstable/http/HttpClient"
+import type * as HttpClientError from "effect/unstable/http/HttpClientError"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import { MtaHttpError, MtaInvalidInputError } from "./errors"
+
+export type { MtaGtfsStaticFetchRequestInput }
+
+export const MtaHttpLive = FetchHttpClient.layer
+
+const decodeStaticFetchRequest = (input: unknown) =>
+  Schema.decodeUnknownEffect(MtaGtfsStaticFetchRequest)(input).pipe(
+    Effect.catchTag("SchemaError", (error) =>
+      Effect.fail(
+        MtaInvalidInputError.make({
+          operation: "gtfs-static",
+          message: error.message
+        })
+      )
+    )
+  )
+
+const httpStatusText = (status: number) => `HTTP ${status}`
+
+const mapMtaHttpClientError = (operation: string, error: HttpClientError.HttpClientError) => {
+  const response = error.response
+
+  if (response !== undefined) {
+    return MtaHttpError.make({
+      operation,
+      status: response.status,
+      statusText: httpStatusText(response.status)
+    })
+  }
+
+  return MtaHttpError.make({
+    operation,
+    status: 0,
+    statusText: error.message
+  })
+}
+
+const toWebResponse = (response: HttpClientResponse.HttpClientResponse) =>
+  Effect.map(
+    Stream.toReadableStreamEffect(response.stream),
+    (body) =>
+      new Response(body, {
+        status: response.status,
+        headers: response.headers
+      })
+  )
+
+const responseContentLength = (response: HttpClientResponse.HttpClientResponse) => {
+  const value = response.headers["content-length"]
+  return value === undefined ? undefined : Number(value)
+}
+
+export const probeGtfsStatic = Effect.fn("Mta.probeGtfsStatic")(function* (
+  input: MtaGtfsStaticFetchRequestInput
+) {
+  const request = yield* decodeStaticFetchRequest(input)
+  const response = yield* HttpClient.execute(HttpClientRequest.head(request.url)).pipe(
+    Effect.mapError((error) => mapMtaHttpClientError("gtfs-static", error))
+  )
+
+  return MtaGtfsStaticProbeResult.make({
+    url: request.url,
+    ok: response.status >= 200 && response.status < 300,
+    status: response.status,
+    contentType: response.headers["content-type"],
+    contentLength: responseContentLength(response)
+  })
+})
+
+export const fetchGtfsStaticResponse = Effect.fn("Mta.fetchGtfsStaticResponse")(function* (
+  input: MtaGtfsStaticFetchRequestInput
+) {
+  const request = yield* decodeStaticFetchRequest(input)
+  const response = yield* HttpClient.execute(HttpClientRequest.get(request.url)).pipe(
+    Effect.mapError((error) => mapMtaHttpClientError("gtfs-static", error))
+  )
+
+  if (response.status < 200 || response.status >= 300) {
+    return yield* MtaHttpError.make({
+      operation: "gtfs-static",
+      status: response.status,
+      statusText: httpStatusText(response.status)
+    })
+  }
+
+  return yield* toWebResponse(response)
+})
+
+export const fetchGtfsStatic = Effect.fn("Mta.fetchGtfsStatic")(function* (
+  input: MtaGtfsStaticFetchRequestInput
+) {
+  const response = yield* fetchGtfsStaticResponse(input)
+
+  return yield* Effect.tryPromise({
+    try: () => response.arrayBuffer(),
+    catch: () =>
+      MtaHttpError.make({
+        operation: "gtfs-static",
+        status: response.status,
+        statusText: "Failed to read response body"
+      })
+  })
+})

package/src/index.ts

@@ -0,0 +1,44 @@
+export const packageName = "@nyc-transit-kit/mta"
+export const gtfsStaticSurface = "gtfs-static"
+export const gtfsRealtimeSurface = "gtfs-realtime"
+export {
+  findMtaOpenDataDataset,
+  mtaOpenDataCatalogDescriptor,
+  mtaOpenDataDatasets,
+  mtaOpenDataDomain
+} from "./datasets"
+export type { MtaError } from "./errors"
+export { MtaDecodeError, MtaHttpError, MtaInvalidInputError } from "./errors"
+export type {
+  MtaDirectFeedDescriptor,
+  MtaDirectFeedSurface,
+  MtaGtfsRealtimeFeedDescriptor,
+  MtaGtfsStaticFeedDescriptor,
+  MtaJsonDirectFeedDescriptor
+} from "./feeds"
+export {
+  findMtaGtfsRealtimeFeed,
+  findMtaGtfsStaticFeed,
+  mtaDirectFeeds,
+  mtaGtfsRealtimeFeeds,
+  mtaGtfsStaticFeeds,
+  mtaJsonDirectFeeds
+} from "./feeds"
+export type {
+  GtfsRealtimeDecoderImplementation,
+  MtaGtfsRealtimeCaptureRequestInput,
+  MtaGtfsRealtimeProbeRequestInput
+} from "./gtfs-realtime"
+export {
+  captureGtfsRealtime,
+  decodeGtfsRealtimeBytes,
+  GtfsRealtimeDecoder,
+  probeGtfsRealtime
+} from "./gtfs-realtime"
+export {
+  fetchGtfsStatic,
+  fetchGtfsStaticResponse,
+  MtaHttpLive,
+  probeGtfsStatic
+} from "./gtfs-static"
+export { queryMtaOpenData } from "./open-data"

package/src/internal/direct-feed-records.ts

@@ -0,0 +1,241 @@
+import type {
+  MtaGtfsRealtimeFeedDescriptor,
+  MtaGtfsStaticFeedDescriptor,
+  MtaJsonDirectFeedDescriptor
+} from "../feeds"
+
+export const mtaGtfsStaticFeedRecords = [
+  {
+    id: "subway-regular",
+    name: "Subway Regular GTFS",
+    surface: "gtfs-static",
+    mode: "subway",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_subway.zip"
+  },
+  {
+    id: "subway-supplemented",
+    name: "Subway Supplemented GTFS",
+    surface: "gtfs-static",
+    mode: "subway",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_supplemented.zip"
+  },
+  {
+    id: "lirr",
+    name: "Long Island Rail Road GTFS",
+    surface: "gtfs-static",
+    mode: "rail",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfslirr.zip"
+  },
+  {
+    id: "metro-north",
+    name: "Metro-North Railroad GTFS",
+    surface: "gtfs-static",
+    mode: "rail",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfsmnr.zip"
+  },
+  {
+    id: "bronx-bus",
+    name: "Bronx Bus GTFS",
+    surface: "gtfs-static",
+    mode: "bus",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_bx.zip"
+  },
+  {
+    id: "brooklyn-bus",
+    name: "Brooklyn Bus GTFS",
+    surface: "gtfs-static",
+    mode: "bus",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_b.zip"
+  },
+  {
+    id: "manhattan-bus",
+    name: "Manhattan Bus GTFS",
+    surface: "gtfs-static",
+    mode: "bus",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_m.zip"
+  },
+  {
+    id: "queens-bus",
+    name: "Queens Bus GTFS",
+    surface: "gtfs-static",
+    mode: "bus",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_q.zip"
+  },
+  {
+    id: "staten-island-bus",
+    name: "Staten Island Bus GTFS",
+    surface: "gtfs-static",
+    mode: "bus",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_si.zip"
+  },
+  {
+    id: "mta-bus-company",
+    name: "MTA Bus Company GTFS",
+    surface: "gtfs-static",
+    mode: "bus",
+    url: "https://rrgtfsfeeds.s3.amazonaws.com/gtfs_busco.zip"
+  }
+] satisfies ReadonlyArray<MtaGtfsStaticFeedDescriptor>
+
+export const mtaGtfsRealtimeFeedRecords = [
+  {
+    id: "subway-ace",
+    name: "Subway A/C/E GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-ace"
+  },
+  {
+    id: "subway-bdfm",
+    name: "Subway B/D/F/M GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-bdfm"
+  },
+  {
+    id: "subway-g",
+    name: "Subway G GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-g"
+  },
+  {
+    id: "subway-jz",
+    name: "Subway J/Z GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-jz"
+  },
+  {
+    id: "subway-nqrw",
+    name: "Subway N/Q/R/W GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-nqrw"
+  },
+  {
+    id: "subway-l",
+    name: "Subway L GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-l"
+  },
+  {
+    id: "subway-1234567",
+    name: "Subway 1/2/3/4/5/6/7 GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs"
+  },
+  {
+    id: "staten-island-railway",
+    name: "Staten Island Railway GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "subway",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fgtfs-si"
+  },
+  {
+    id: "lirr",
+    name: "Long Island Rail Road GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "rail",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/lirr%2Fgtfs-lirr"
+  },
+  {
+    id: "metro-north",
+    name: "Metro-North Railroad GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "trip-updates",
+    family: "rail",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/mnr%2Fgtfs-mnr"
+  },
+  {
+    id: "alerts-all",
+    name: "All MTA Service Alerts GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "alerts",
+    family: "alerts",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/camsys%2Fall-alerts"
+  },
+  {
+    id: "alerts-subway",
+    name: "Subway Service Alerts GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "alerts",
+    family: "alerts",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/camsys%2Fsubway-alerts"
+  },
+  {
+    id: "alerts-bus",
+    name: "Bus Service Alerts GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "alerts",
+    family: "alerts",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/camsys%2Fbus-alerts"
+  },
+  {
+    id: "alerts-lirr",
+    name: "LIRR Service Alerts GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "alerts",
+    family: "alerts",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/camsys%2Flirr-alerts"
+  },
+  {
+    id: "alerts-metro-north",
+    name: "Metro-North Service Alerts GTFS-RT",
+    surface: "gtfs-realtime",
+    feed: "alerts",
+    family: "alerts",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/camsys%2Fmnr-alerts"
+  }
+] satisfies ReadonlyArray<MtaGtfsRealtimeFeedDescriptor>
+
+export const mtaJsonDirectFeedRecords = [
+  {
+    id: "elevator-escalator-current",
+    name: "Elevator/Escalator Status Current JSON",
+    surface: "elevator-escalator",
+    format: "json",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fnyct_ene.json"
+  },
+  {
+    id: "elevator-escalator-upcoming",
+    name: "Elevator/Escalator Status Upcoming JSON",
+    surface: "elevator-escalator",
+    format: "json",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fnyct_ene_upcoming.json"
+  },
+  {
+    id: "elevator-escalator-equipment",
+    name: "Elevator/Escalator Equipment JSON",
+    surface: "elevator-escalator",
+    format: "json",
+    url: "https://api-endpoint.mta.info/Dataservice/mtagtfsfeeds/nyct%2Fnyct_ene_equipments.json"
+  },
+  {
+    id: "bus-time-vehicle-monitoring",
+    name: "Bus Time SIRI Vehicle Monitoring",
+    surface: "bus-time",
+    format: "json",
+    requiresApiKey: true,
+    url: "https://bustime.mta.info/api/siri/vehicle-monitoring.json"
+  },
+  {
+    id: "bus-time-stop-monitoring",
+    name: "Bus Time SIRI Stop Monitoring",
+    surface: "bus-time",
+    format: "json",
+    requiresApiKey: true,
+    url: "https://bustime.mta.info/api/siri/stop-monitoring.json"
+  }
+] satisfies ReadonlyArray<MtaJsonDirectFeedDescriptor>

package/src/internal/open-data-descriptor-records.ts

@@ -0,0 +1,15 @@
+import type { MtaOpenDataDatasetDescriptorInput } from "@nyc-transit-kit/contracts/mta"
+
+export const mtaOpenDataDescriptorRecords = [
+  {
+    id: "f462-ka72",
+    name: "MTA Open Data Catalog",
+    domain: "data.ny.gov",
+    backing: "socrata",
+    description: "MTA Open Data catalog entry surfaced through NYS Open Data.",
+    sourceUrl: "https://data.ny.gov/d/f462-ka72",
+    tags: ["transportation", "transit", "catalog"],
+    adapterStatus: "none",
+    lastVerified: "2026-06-16"
+  }
+] satisfies ReadonlyArray<MtaOpenDataDatasetDescriptorInput>

package/src/open-data.ts

@@ -0,0 +1,23 @@
+import { queryRows } from "@nyc-transit-kit/soda3/client"
+import { mtaOpenDataDomain } from "./datasets"
+
+export const queryMtaOpenData = (input: {
+  readonly datasetId: string
+  readonly query: string
+  readonly page?: {
+    readonly pageNumber: number
+    readonly pageSize: number
+  }
+}) =>
+  input.page === undefined
+    ? queryRows({
+        domain: mtaOpenDataDomain,
+        datasetId: input.datasetId,
+        query: input.query
+      })
+    : queryRows({
+        domain: mtaOpenDataDomain,
+        datasetId: input.datasetId,
+        query: input.query,
+        page: input.page
+      })