ojp-sdk
Version:
OJP (Open Journey Planner) Javascript SDK
1,285 lines (1,259 loc) • 49.7 kB
TypeScript
import * as OJP_Types from 'ojp-shared-types';
/**
* Configuration interface for HTTP requests
*
* This interface defines the structure for configuring HTTP request settings,
* including the target URL and authentication token.
*
* @example
* ```typescript
* const config: HTTPConfig = {
* url: 'https://api.example.com/data',
* authToken: 'Bearer abc123xyz'
* };
* ```
*
* @category Core
*/
interface HTTPConfig {
url: string;
authToken: string | null;
}
/**
* SDK language
*
* @category Core
*/
type Language = 'de' | 'fr' | 'it' | 'en';
/**
* SDK OJP version
*
* @category Interoperability OJP 1.0
*/
type OJP_VERSION = '1.0' | '2.0';
/**
* SDK union type for applications using both OJP versions
*
* @category Interoperability OJP 1.0
*/
type AnySDK = SDK<'1.0'> | SDK<'2.0'>;
/**
* Configuration interface for XML serialization settings
*
* This interface defines the structure for configuring XML serialization behavior,
* including OJP version, default namespace handling, and custom namespace mappings.
*
* @example
* ```typescript
* const config: XML_Config = {
* ojpVersion: '2.0',
* defaultNS: 'ojp',
* mapNS: {
* 'http://www.vdv.de/ojp': 'ojp',
* 'http://www.siri.org.uk/siri': 'siri'
* }
* };
* ```
*
* @category XML Utils
*/
interface XML_Config {
/** The OJP version to use for serialization */
ojpVersion: OJP_VERSION;
/** The default namespace prefix ('ojp', 'siri', or null) */
defaultNS: 'ojp' | 'siri' | null;
/** Mapping of XML namespace URIs to their prefixes */
mapNS: Record<string, string>;
}
/**
* Interface containing request and response information
*
* This interface holds metadata about HTTP requests and responses, including
* timestamps for request/response processing and the actual XML content.
*
* @example
* ```typescript
* const requestInfo: RequestInfo = {
* requestDateTime: new Date(),
* requestXML: '<OJP>...</OJP>',
* responseDateTime: new Date(),
* responseXML: '<OJPResponse>...</OJPResponse>',
* parseDateTime: new Date()
* };
* ```
*
* @category Core
*/
interface RequestInfo {
requestDateTime: Date | null;
requestXML: string | null;
responseDateTime: Date | null;
responseXML: string | null;
parseDateTime: Date | null;
}
/**
* Type definitions for OJP API response types.
*
* Each response type is a union of success and error states, following the pattern:
* - { ok: true; value: T } for successful responses
* - { ok: false; error: E } for failed responses
*
*/
type ResponseOk<T> = {
ok: true;
value: T;
};
type ResponseError<E> = {
ok: false;
error: E;
};
type OJP_Response<T, E> = ResponseOk<T> | ResponseError<E>;
/**
* FR Response (OJP 1.0)
*
* @category Response OJP 1.0
*/
type FareRequestResponse = OJP_Response<OJP_Types.FareDeliverySchema, Error>;
/**
* LIR Response
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPLocationInformationDeliveryStructure }
*
* @category Response
*/
type LocationInformationRequestResponse = OJP_Response<OJP_Types.LocationInformationDeliverySchema, Error>;
/**
* LIR Response (OJP 1.0)
*
* @category Response OJP 1.0
*/
type OJPv1_LocationInformationRequestResponse = OJP_Response<OJP_Types.OJPv1_LocationInformationDeliverySchema, Error>;
/**
* SER Response
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPStopEventDeliveryStructure }
*
* @category Response
*/
type StopEventRequestResponse = OJP_Response<OJP_Types.StopEventDeliverySchema, Error>;
/**
* SER Response (OJP 1.0)
*
* @category Response OJP 1.0
*/
type OJPv1_StopEventRequestResponse = OJP_Response<OJP_Types.OJPv1_StopEventDeliverySchema, Error>;
/**
* TIR Response
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPTripInfoDeliveryStructure }
*
* @category Response
*/
type TripInfoRequestResponse = OJP_Response<OJP_Types.TripInfoDeliverySchema, Error>;
/**
* TIR Response (OJP 1.0)
*
* @category Response OJP 1.0
*/
type OJPv1_TripInfoRequestResponse = OJP_Response<OJP_Types.OJPv1_TripInfoDeliverySchema, Error>;
/**
* TRR Response
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPTripRefineDeliveryStructure }
*
* @category Response
*/
type TripRefineRequestResponse = OJP_Response<OJP_Types.TRR_DeliverySchema, Error>;
/**
* TR Response
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPTripDeliveryStructure }
*
* @category Response
*/
type TripRequestResponse = OJP_Response<OJP_Types.TripDeliverySchema, Error>;
/**
* TR Response (OJP 1.0)
*
* @category Response OJP 1.0
*/
type OJPv1_TripRequestResponse = OJP_Response<OJP_Types.OJPv1_TripDeliverySchema, Error>;
type ResultSpec = {
fetchResponse: unknown;
};
declare abstract class BaseRequest<S extends ResultSpec> {
requestInfo: RequestInfo;
mockRequestXML: string | null;
mockResponseXML: string | null;
protected constructor();
/**
* Creates a new instance of the request class with a mock request XML string
*
* This method is used for testing purposes to simulate API requests with predefined XML payloads.
* When this mock is set, the request will use the provided XML instead of building a new one.
*
* @param mockText - The XML string to use as the mock request
* @returns A new instance of the request class with the mock set
*
* @example
* ```typescript
* const mockRequest = LocationInformationRequest.initWithRequestMock('<OJP>...</OJP>');
* ```
*
* @group Initialization
*/
static initWithRequestMock<T_This extends {
Default(): any;
}>(this: T_This, mockText: string): ReturnType<T_This['Default']>;
/**
* Creates a new instance of the request class with a mock response XML string
*
* This method is used for testing purposes to simulate API responses with predefined XML payloads.
* When this mock is set, the request will use the provided XML response instead of making actual API calls.
*
* @param mockText - The XML string to use as the mock response
* @returns A new instance of the request class with the mock set
*
* @example
* ```typescript
* const mockRequest = LocationInformationRequest.initWithResponseMock('<OJP>...</OJP>');
* ```
*
* @group Initialization
*/
static initWithResponseMock<T_This extends {
Default(): any;
}>(this: T_This, mockText: string): ReturnType<T_This['Default']>;
protected abstract _fetchResponse(sdk: AnySDK): Promise<S['fetchResponse']>;
fetchResponse(sdk: AnySDK): Promise<S['fetchResponse']>;
abstract buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
}
declare abstract class SharedLocationInformationRequest<S extends ResultSpec> extends BaseRequest<S> {
protected static computeGeoRestriction(bboxData: string | number[]): OJP_Types.GeoRestrictionsSchema | null;
}
/**
* LocationInformationRequest (LIR) class
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithLocationName` - use location name, i.e. `Bern`
* - `initWithPlaceRef` - use place ref or literal coordinates (lat, lng)
* - `initWithBBOX` - use bounding box to filter locations
*
* @category Request
*/
declare class LocationInformationRequest extends SharedLocationInformationRequest<{
fetchResponse: LocationInformationRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPLocationInformationRequestStructure OJP LocationInformationRequest XSD Schema}
*/
payload: OJP_Types.LocationInformationRequestSchema;
protected constructor(restrictions: OJP_Types.LIR_RequestParamsSchema | undefined);
private static DefaultRestrictionParams;
private updateRestrictions;
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
* @hidden
*/
static Default(): LocationInformationRequest;
/**
* Inits LIR with location name
*
* @param name string, location name
* @param placeTypes `OJP_Types.PlaceTypeEnum` "stop" | "address" | "poi" | "location" | "topographicPlace"
* @param numberOfResults maximum number of results to return (default: 10)
*
* @group Initialization
*/
static initWithLocationName(name: string, placeTypes?: OJP_Types.PlaceTypeEnum[], numberOfResults?: number): LocationInformationRequest;
/**
* Inits LIR with place ref or literal coords
*
* @param placeRefOrCoords place reference or coordinates string (e.g. `ch:1:sloid:7000:4:7` or `46.94857,7.43683` (latitude, longitude in WGS84))
* @param numberOfResults maximum number of results to return (default: 10)
*
* @group Initialization
*/
static initWithPlaceRef(placeRefOrCoords: string, numberOfResults?: number): LocationInformationRequest;
/**
* Inits LIR with bounding box
*
* @param bboxData bounding box data as string ("minLon,minLat,maxLon,maxLat") or array [minLon, minLat, maxLon, maxLat]
* @param placeTypes `OJP_Types.PlaceTypeEnum` "stop" | "address" | "poi" | "location" | "topographicPlace"
* @param numberOfResults maximum number of results to return (default: 10)
*
* @group Initialization
*/
static initWithBBOX(bboxData: string | number[], placeTypes?: OJP_Types.PlaceTypeEnum[], numberOfResults?: number): LocationInformationRequest;
/**
* Builds the XML request string for the LIR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link DefaultXML_Config} OJP 2.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig?: XML_Config): string;
protected _fetchResponse(sdk: SDK<'2.0'>): Promise<LocationInformationRequestResponse>;
}
declare abstract class SharedStopEventRequest<S extends ResultSpec> extends BaseRequest<S> {
protected static DefaultRequestParams(version?: OJP_VERSION): OJP_Types.SER_RequestParamsSchema;
}
/**
* StopEventRequest (SER) class
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithPlaceRefAndDate` - use PlaceRef ids + date
*
* @category Request
*/
declare class StopEventRequest extends SharedStopEventRequest<{
fetchResponse: StopEventRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPStopEventRequestStructure OJP StopEventRequest XSD Schema}
*/
payload: OJP_Types.StopEventRequestSchema;
protected constructor(location: OJP_Types.SER_RequestLocationSchema, params?: OJP_Types.SER_RequestParamsSchema | undefined);
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
* @hidden
*/
static Default(): StopEventRequest;
/**
* Creates a new StopEventRequest with the given place reference and date
*
* @param placeRefS The stop point reference ID (e.g. "8507000" for Bern)
* @param date The date and time for the stop event request (defaults to current date/time)
* @returns A new StopEventRequest instance
*
* @example
* ```typescript
* const request = StopEventRequest.initWithPlaceRefAndDate('8507000');
* const response = await request.fetch(sdk);
* ```
*
* @group Initialization
*/
static initWithPlaceRefAndDate(placeRefS: string, date?: Date): StopEventRequest;
/**
* Builds the XML request string for the SER
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link DefaultXML_Config} OJP 2.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'2.0'>): Promise<StopEventRequestResponse>;
}
declare abstract class SharedTripInfoRequest<S extends ResultSpec> extends BaseRequest<S> {
protected static DefaultRequestParams(): {
includeCalls?: boolean;
includeService?: boolean;
includeTrackProjection?: boolean;
includePlacesContext?: boolean;
includeSituationsContext?: boolean;
};
}
/**
* TripInfoRequest (TIR) class
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithJourneyRef` - use journey reference and date
*
* @category Request
*/
declare class TripInfoRequest extends SharedTripInfoRequest<{
fetchResponse: TripInfoRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPTripInfoRequestStructure OJP TripInfoRequest XSD Schema}
*/
payload: OJP_Types.TIR_RequestSchema;
protected constructor(journeyRef: string, operatingDayRef: string, params?: OJP_Types.TIR_RequestParamsSchema);
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
* @hidden
*/
static Default(): TripInfoRequest;
/**
* Creates a new TripInfoRequest with the given journey reference and date
*
* @param journeyRef The journey reference ID (e.g. "ch:1:sjyid:100001:2179-001")
* @param journeyDate The date of the journey (defaults to current date)
* @returns A new TripInfoRequest instance
*
* @example
* ```typescript
* const request = TripInfoRequest.initWithJourneyRef('ch:1:sjyid:100001:2179-001');
* const response = await request.fetch(sdk);
* ```
*
* @group Initialization
*/
static initWithJourneyRef(journeyRef: string, journeyDate?: Date): TripInfoRequest;
/**
* Enables track projection in the request payload
*
* This method modifies the request to include track projection data in the response.
* When enabled, the response will contain additional information about the vehicle's
* track and movement patterns.
*
* @example
* ```typescript
* const request = TripInfoRequest.initWithJourneyRef('ch:1:sjyid:100001:2179-001');
* request.enableTrackProjection();
* const response = await request.fetch(sdk);
* ```
*
* @group Request Payload Modification
*/
enableTrackProjection(): void;
/**
* Builds the XML request string for the TIR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link DefaultXML_Config} OJP 2.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'2.0'>): Promise<TripInfoRequestResponse>;
}
type GeoPositionLike = OJP_Types.GeoPositionSchema | number[] | string;
/**
* Represents a geographic position with longitude and latitude coordinate.
*
* @example
* ```typescript
* // Create from coordinates
* const position = new GeoPosition(8.54, 47.37);
*
* // Create from array
* const position = new GeoPosition([8.54, 47.37]);
*
* // Create from string (lat, long)
* const position = new GeoPosition("47.37,8.54");
*
* // Create from GeoPositionSchema
* const position = new GeoPosition({ longitude: 8.54, latitude: 47.37 });
* ```
*
* @category Geo
*/
declare class GeoPosition implements OJP_Types.GeoPositionSchema {
longitude: number;
latitude: number;
properties: Record<string, any>;
constructor(geoPositionArg: GeoPositionLike | number, optionalLatitude?: number | null);
isValid(): boolean;
distanceFrom(pointB: GeoPosition): number;
asLatLngString(roundCoords?: boolean): string;
asLngLat(): [number, number];
asGeoPositionSchema(): OJP_Types.GeoPositionSchema;
}
/**
* @deprecated this class will be removed from SDK
* clients can implement specifc cases conforming to OJP_Types
*
* @hidden
*/
declare class Trip implements OJP_Types.TripSchema {
id: string;
duration: string;
startTime: string;
endTime: string;
transfers: number;
leg: OJP_Types.LegSchema[];
cancelled?: boolean;
delayed?: boolean;
deviation?: boolean;
infeasible?: boolean;
unplanned?: boolean;
private constructor();
static initWithTripXML(rawXML: string): Trip;
}
interface NearbyPlace {
distance: number;
object: Place;
}
/**
* @deprecated this class will be removed from SDK
* clients can implement specifc cases conforming to OJP_Types
*
* @hidden
*/
declare class Place implements OJP_Types.PlaceSchema {
stopPoint?: OJP_Types.StopPointSchema;
stopPlace?: OJP_Types.StopPlaceSchema;
topographicPlace?: OJP_Types.TopographicPlaceSchema;
pointOfInterest?: OJP_Types.PointOfInterestSchema;
address?: OJP_Types.AddressSchema;
name: OJP_Types.InternationalTextSchema;
geoPosition: GeoPosition;
mode: OJP_Types.ModeStructureSchema[];
attribute: OJP_Types.GeneralAttributeSchema[];
placeType: OJP_Types.PlaceTypeEnum | null;
private constructor();
static initWithXMLSchema(placeSchema: OJP_Types.PlaceSchema): Place;
static initWithCoords(geoPositionArg: GeoPositionLike | number, optionalLatitude?: number | null): Place;
static Empty(): Place;
findClosestPlace(otherPlaces: Place[]): NearbyPlace | null;
asStopPlaceRefOrCoords(): string;
}
/**
* @deprecated this class will be removed from SDK
* clients can implement specifc cases conforming to OJP_Types
*
* @hidden
*/
declare class PlaceResult implements OJP_Types.PlaceResultSchema {
place: Place;
complete: boolean;
probability?: number;
private constructor();
static initWithXMLSchema(placeResultSchema: OJP_Types.PlaceResultSchema): PlaceResult;
static initWithXML(nodeXML: string): PlaceResult;
}
/**
* @deprecated this class will be removed from SDK
* clients can implement specifc cases conforming to OJP_Types
*
* @hidden
*/
declare class StopEventResult implements OJP_Types.StopEventResultSchema {
id: string;
stopEvent: OJP_Types.StopEventSchema;
private constructor();
static initWithXML(nodeXML: string): StopEventResult;
}
/**
* TripRefineRequest (TRR) class
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithTrip` - use a Trip OJP XSD schema to refine
*
* @category Request
*/
declare class TripRefineRequest extends BaseRequest<{
fetchResponse: TripRefineRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPTripRefineRequestStructure OJP TripRefineRequest XSD Schema}
*/
payload: OJP_Types.TRR_RequestSchema;
protected constructor(tripResult: OJP_Types.TripResultSchema, refineParams?: OJP_Types.TRR_RequestParamsSchema);
private static DefaultRequestParams;
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
* @hidden
*/
static Default(): TripRefineRequest;
/**
* Creates a new TripRefineRequest with the given Trip OJP XSD Schema
*
* @param trip the trip to be refined as Trip OJP XSD Schema
*
* @group Initialization
*/
static initWithTrip(trip: Trip): TripRefineRequest;
/**
* Builds the XML request string for the TIR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link DefaultXML_Config} OJP 2.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'2.0'>): Promise<TripRefineRequestResponse>;
}
type OJPv1_TaxiModeEnum = 'taxi' | 'others-drive-car';
/**
* TripRequest (TR) class for OJP 1.0
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithPlaceRefsOrCoords` - use place refs or literal coordinates (lat, lng) for origin, destinatio
* - `initWithPlaces` - use Place OJP XSD schema objects
*
* @category Request OJP 1.0
*/
declare class OJPv1_TripRequest extends SharedTripRequest<{
fetchResponse: OJPv1_TripRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request (OJP v1)
*/
payload: OJP_Types.OJPv1_TripRequestSchema;
protected constructor(origin: OJP_Types.OJPv1_PlaceContextSchema, destination: OJP_Types.OJPv1_PlaceContextSchema, via?: OJP_Types.OJPv1_ViaPointSchema[], params?: OJP_Types.OJPv1_TripParamsSchema | null);
private static DefaultRequestParams;
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
*
* @hidden
*/
static Default(): OJPv1_TripRequest;
/**
* Initializes a TripRequest object with either place references or coordinates.
*
* @param originPlaceRefS - The origin place reference string - place reference or coordinate literals (lat, lon WGS84)
* @param destinationPlaceRefS - The destination place reference string - place reference or coordinate literals (lat, lon WGS84)
*
* @group Initialization
*/
static initWithPlaceRefsOrCoords(originPlaceRefS: string, destinationPlaceRefS: string): OJPv1_TripRequest;
/**
* Initializes a TripRequest object with Place OJP schema objects
*
* @param origin - The origin place
* @param destination - The destination place
*
* @group Initialization
*/
static initWithPlaces(origin: Place, destination: Place): OJPv1_TripRequest;
/**
* Updates arrival at destination datetime in the request payload
*
* @group Request Payload Modification
*/
setArrivalDatetime(newDatetime?: Date): void;
/**
* Updates departure from origin datetime in the request payload
*
* @group Request Payload Modification
*/
setDepartureDatetime(newDatetime?: Date): void;
/**
* @group Request Payload Modification
*/
disableLinkProkection(): void;
/**
* @group Request Payload Modification
*/
enableLinkProkection(): void;
/**
* @group Request Payload Modification
*/
setPublicTransportRequest(motFilter: OJP_Types.VehicleModesOfTransportEnum[] | null): void;
/**
* @group Request Payload Modification
*/
setCarRequest(): void;
/**
* This modifier works only in OJP 2.0
*
* @group Request Payload Modification
*/
setRailSubmodes(railSubmodes: OJP_Types.RailSubmodeEnum | OJP_Types.RailSubmodeEnum[]): void;
/**
* This modifier works only in OJP 2.0
*
* @group Request Payload Modification
*/
setMaxDurationWalkingTime(maxDurationMinutes: number | undefined, endpointType: EndpointType): void;
/**
* @group Request Payload Modification
*/
setNumberOfResults(resultsNo: number | null): void;
/**
* @group Request Payload Modification
*/
setNumberOfResultsAfter(resultsNo: number): void;
/**
* @group Request Payload Modification
*/
setNumberOfResultsBefore(resultsNo: number): void;
private computeLegacyTransportMode;
private computeTransportOptions;
private setParamsEndpointExtension;
/**
* @group Request Payload Modification
*/
setOriginDurationDistanceRestrictions(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum, minDuration?: number | null, maxDuration?: number | null, minDistance?: number | null, maxDistance?: number | null): void;
/**
* @group Request Payload Modification
*/
setDestinationDurationDistanceRestrictions(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum, minDuration?: number | null, maxDuration?: number | null, minDistance?: number | null, maxDistance?: number | null): void;
/**
* This modifier works only in OJP 2.0
*
* @group Request Payload Modification
*/
setWalkSpeedDeviation(walkSpeedPercent: number): void;
/**
* @group Request Payload Modification
*/
setViaPlace(place: Place, dwellTime: number | null): void;
/**
* This modifier works only in OJP 2.0
*
* @group Request Payload Modification
*/
setWalkRequest(): void;
/**
* @group Request Payload Modification
*
* @see {@link https://opentransportdata.swiss/de/cookbook/open-journey-planner-ojp/ojptriprequest/#Ueberblick_der_Kombinationsmoeglichkeiten }
*/
setMonomodalRequest(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum): void;
/**
* This modifier works only in OJP 1.0
*
* @group Request Payload Modification
*/
setTaxiRequest(transportMode: OJPv1_TaxiModeEnum, endpointType?: 'origin' | 'destination' | null, minDuration?: number | null, maxDuration?: number | null, minDistance?: number | null, maxDistance?: number | null): void;
/**
* Builds the XML request string for the TR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link XML_BuilderConfigOJPv1} OJP 1.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'1.0'>): Promise<OJPv1_TripRequestResponse>;
}
type EndpointType = 'origin' | 'destination' | 'both';
declare abstract class SharedTripRequest<S extends ResultSpec> extends BaseRequest<S> {
abstract setArrivalDatetime(newDatetime: Date): void;
abstract setDepartureDatetime(newDatetime: Date): void;
abstract setPublicTransportRequest(motFilter: OJP_Types.VehicleModesOfTransportEnum[] | null): void;
abstract setCarRequest(): void;
abstract setRailSubmodes(railSubmodes: OJP_Types.RailSubmodeEnum | OJP_Types.RailSubmodeEnum[]): void;
abstract setMaxDurationWalkingTime(maxDurationMinutes: number | undefined, endpointType: EndpointType): void;
abstract enableLinkProkection(): void;
abstract disableLinkProkection(): void;
abstract setNumberOfResults(resultsNo: number | null): void;
abstract setNumberOfResultsAfter(resultsNo: number): void;
abstract setNumberOfResultsBefore(resultsNo: number): void;
abstract setWalkSpeedDeviation(walkSpeedPercent: number): void;
abstract setOriginDurationDistanceRestrictions(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum, minDuration: number | null, maxDuration: number | null, minDistance: number | null, maxDistance: number | null): void;
abstract setDestinationDurationDistanceRestrictions(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum, minDuration: number | null, maxDuration: number | null, minDistance: number | null, maxDistance: number | null): void;
abstract setViaPlace(place: Place, dwellTime: number | null): void;
abstract setWalkRequest(): void;
abstract setMonomodalRequest(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum): void;
abstract setTaxiRequest(transportMode: OJPv1_TaxiModeEnum, endpointType: 'origin' | 'destination' | null, minDuration: number | null, maxDuration: number | null, minDistance: number | null, maxDistance: number | null): void;
}
/**
* TripRequest (TR) class
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithPlaceRefsOrCoords` - use place refs or literal coordinates (lat, lng) for origin, destinatio
* - `initWithPlaces` - use Place OJP XSD schema objects
*
* @category Request
*/
declare class TripRequest extends SharedTripRequest<{
fetchResponse: TripRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
* @see {@link https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html#type_ojp__OJPTripRequestStructure OJP TripRequest XSD Schema}
*/
payload: OJP_Types.TripRequestSchema;
protected constructor(origin: OJP_Types.PlaceContextSchema, destination: OJP_Types.PlaceContextSchema, via?: OJP_Types.ViaPointSchema[], params?: OJP_Types.TripParamsSchema | null);
private static DefaultRequestParams;
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
* @hidden
*/
static Default(): TripRequest;
/**
* Initializes a TripRequest object with either place references or coordinates.
*
* @param originPlaceRefS - The origin place reference string - place reference or coordinate literals (lat, lon WGS84)
* @param destinationPlaceRefS - The destination place reference string - place reference or coordinate literals (lat, lon WGS84)
*
* @group Initialization
*/
static initWithPlaceRefsOrCoords(originPlaceRefS: string, destinationPlaceRefS: string): TripRequest;
/**
* Initializes a TripRequest object with Place OJP schema objects
*
* @param origin - The origin place
* @param destination - The destination place
*
* @group Initialization
*/
static initWithPlaces(origin: Place, destination: Place): TripRequest;
/**
* Updates arrival at destination datetime in the request payload
*
* @group Request Payload Modification
*/
setArrivalDatetime(newDatetime?: Date): void;
/**
* Updates departure from origin datetime in the request payload
*
* @group Request Payload Modification
*/
setDepartureDatetime(newDatetime?: Date): void;
/**
* @group Request Payload Modification
*/
setPublicTransportRequest(motFilter?: OJP_Types.VehicleModesOfTransportEnum[] | null): void;
/**
* @group Request Payload Modification
*/
disableLinkProkection(): void;
/**
* @group Request Payload Modification
*/
enableLinkProkection(): void;
/**
* @group Request Payload Modification
*/
setCarRequest(): void;
/**
* @group Request Payload Modification
*/
setMaxDurationWalkingTime(maxDurationMinutes?: number | undefined, endpointType?: EndpointType): void;
/**
* see https://vdvde.github.io/OJP/develop/documentation-tables/siri.html#type_siri__RailSubmodesOfTransportEnumeration
*
* @group Request Payload Modification
*/
setRailSubmodes(railSubmodes: OJP_Types.RailSubmodeEnum | OJP_Types.RailSubmodeEnum[]): void;
/**
* @group Request Payload Modification
*/
setNumberOfResults(resultsNo: number | null): void;
/**
* @group Request Payload Modification
*/
setNumberOfResultsAfter(resultsNo: number): void;
/**
* @group Request Payload Modification
*/
setNumberOfResultsBefore(resultsNo: number): void;
private setEndpointDurationDistanceRestrictions;
/**
* @group Request Payload Modification
*/
setOriginDurationDistanceRestrictions(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum, minDuration?: number | null, maxDuration?: number | null, minDistance?: number | null, maxDistance?: number | null): void;
/**
* @group Request Payload Modification
*/
setDestinationDurationDistanceRestrictions(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum, minDuration?: number | null, maxDuration?: number | null, minDistance?: number | null, maxDistance?: number | null): void;
/**
* @group Request Payload Modification
*/
setWalkSpeedDeviation(walkSpeedPercent: number): void;
/**
* @group Request Payload Modification
*/
setViaPlace(place: Place, dwellTime: number | null): void;
/**
* @group Request Payload Modification
*/
setWalkRequest(): void;
/**
* This modifier works only in OJP 1.0
*
* @group Request Payload Modification
*/
setMonomodalRequest(operationMode: OJP_Types.PersonalModesOfOperationEnum, transportMode: OJP_Types.PersonalModesEnum): void;
/**
* This modifier works only in OJP 1.0
*
* @group Request Payload Modification
*/
setTaxiRequest(transportMode: OJPv1_TaxiModeEnum, endpointType?: 'origin' | 'destination' | null, minDuration?: number | null, maxDuration?: number | null, minDistance?: number | null, maxDistance?: number | null): void;
/**
* Builds the XML request string for the TIR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link DefaultXML_Config} OJP 2.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'2.0'>): Promise<TripRequestResponse>;
}
/**
* FareRequest (FR) class for OJP 1.0
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithOJPv1Trips` - use Trip OJP 1.0 schema items
*
* @category Request OJP 1.0
*/
declare class OJPv1_FareRequest extends BaseRequest<{
fetchResponse: FareRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request (OJP v1)
*/
payload: OJP_Types.FareRequestSchema[];
protected constructor(items: OJP_Types.FareRequestSchema[]);
private static DefaultRequestParams;
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
*
* @hidden
*/
static Default(): OJPv1_FareRequest;
private static cleanTripForFareRequest;
/**
* Inits FR with OJP 1.0 Trip schema items
*
* @param trips array of OJP_Types.OJPv1_TripSchema
*
* @group Initialization
*/
static initWithOJPv1Trips(trips: OJP_Types.OJPv1_TripSchema[]): OJPv1_FareRequest;
/**
* Builds the XML request string for the FR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link XML_BuilderConfigOJPv1} OJP 1.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'1.0'>): Promise<FareRequestResponse>;
}
/**
* LocationInformationRequest (LIR) class for OJP 1.0
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithLocationName` - use location name, i.e. `Bern`
* - `initWithPlaceRef` - use place ref or literal coordinates (lat, lng)
* - `initWithBBOX` - use bounding box to filter locations
*
* @category Request OJP 1.0
*/
declare class OJPv1_LocationInformationRequest extends SharedLocationInformationRequest<{
fetchResponse: OJPv1_LocationInformationRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request (OJP v1)
*/
payload: OJP_Types.OJPv1_LocationInformationRequestSchema;
protected constructor(restrictions: OJP_Types.OJPv1_LIR_RequestParamsSchema);
private static DefaultRestrictionParams;
private updateRestrictions;
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
*
* @hidden
*/
static Default(): OJPv1_LocationInformationRequest;
/**
* Inits LIR with location name
*
* @param name string, location name
* @param placeTypes `OJP_Types.PlaceTypeEnum` "stop" | "address" | "poi" | "location" | "topographicPlace"
* @param numberOfResults maximum number of results to return (default: 10)
*
* @group Initialization
*/
static initWithLocationName(name: string, placeTypes?: OJP_Types.PlaceTypeEnum[], numberOfResults?: number): OJPv1_LocationInformationRequest;
/**
* Inits LIR with place ref or literal coords
*
* @param placeRefOrCoords place reference or coordinates string (e.g. `ch:1:sloid:7000:4:7` or `46.94857,7.43683` (latitude, longitude in WGS84))
* @param numberOfResults maximum number of results to return (default: 10)
*
* @group Initialization
*/
static initWithPlaceRef(placeRefOrCoords: string, numberOfResults?: number): OJPv1_LocationInformationRequest;
/**
* Inits LIR with bounding box
*
* @param bboxData bounding box data as string ("minLon,minLat,maxLon,maxLat") or array [minLon, minLat, maxLon, maxLat]
* @param placeTypes `OJP_Types.PlaceTypeEnum` "stop" | "address" | "poi" | "location" | "topographicPlace"
* @param numberOfResults maximum number of results to return (default: 10)
*
* @group Initialization
*/
static initWithBBOX(bboxData: string | number[], placeTypes?: OJP_Types.PlaceTypeEnum[], numberOfResults?: number): OJPv1_LocationInformationRequest;
/**
* Builds the XML request string for the LIR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link XML_BuilderConfigOJPv1} OJP 1.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig?: XML_Config): string;
protected _fetchResponse(sdk: SDK<'1.0'>): Promise<OJPv1_LocationInformationRequestResponse>;
}
/**
* StopEventRequest (SER) class for OJP 1.0
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithPlaceRefAndDate` - use PlaceRef ids + date
*
* @category Request OJP 1.0
*/
declare class OJPv1_StopEventRequest extends SharedStopEventRequest<{
fetchResponse: OJPv1_StopEventRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
*/
payload: OJP_Types.OJPv1_StopEventRequestSchema;
protected constructor(location: OJP_Types.OJPv1_PlaceContextSchema, params?: OJP_Types.SER_RequestParamsSchema | undefined);
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
*
* @hidden
*/
static Default(): OJPv1_StopEventRequest;
/**
* Creates a new StopEventRequest with the given place reference and date
*
* @param placeRefS The stop point reference ID (e.g. "8507000" for Bern)
* @param date The date and time for the stop event request (defaults to current date/time)
*
* @group Initialization
*/
static initWithPlaceRefAndDate(placeRefS: string, date?: Date): OJPv1_StopEventRequest;
/**
* Builds the XML request string for the SER
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link XML_BuilderConfigOJPv1} OJP 1.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'1.0'>): Promise<OJPv1_StopEventRequestResponse>;
}
/**
* TripInfoRequest (TIR) class for OJP 1.0
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* - `initWithJourneyRef` - use journey reference and date
*
* @category Request OJP 1.0
*/
declare class OJPv1_TripInfoRequest extends SharedTripInfoRequest<{
fetchResponse: OJPv1_TripInfoRequestResponse;
}> {
/**
* The payload object that gets serialized to XML for the request
*
*/
payload: OJP_Types.TIR_RequestSchema;
protected constructor(journeyRef: string, operatingDayRef: string, params?: OJP_Types.TIR_RequestParamsSchema);
/**
* Used by BaseRequest methods (i.e. `initWithRequestMock`, `initWithResponseMock`
*
* @hidden
*/
static Default(): OJPv1_TripInfoRequest;
/**
* Creates a new TripInfoRequest with the given journey reference and date
*
* @param journeyRef The journey reference ID (e.g. "ch:1:sjyid:100001:2179-001")
* @param journeyDate The date of the journey (defaults to current date)
*
* @group Initialization
*/
static initWithJourneyRef(journeyRef: string, journeyDate?: Date): OJPv1_TripInfoRequest;
enableTrackProjection(): void;
/**
* Builds the XML request string for the TIR
*
* @param language The language to use for the request (e.g. "en", "de")
* @param requestorRef The requestor reference identifier
* @param xmlConfig XML configuration options for building the request, default {@link XML_BuilderConfigOJPv1} OJP 1.0
* @returns A formatted XML string representing the Location Information Request
*/
buildRequestXML(language: Language, requestorRef: string, xmlConfig: XML_Config): string;
protected _fetchResponse(sdk: SDK<'1.0'>): Promise<OJPv1_TripInfoRequestResponse>;
}
declare class EmptyRequest {
static init(): void;
}
declare const builders: {
readonly '1.0': {
readonly FareRequest: typeof OJPv1_FareRequest;
readonly LocationInformationRequest: typeof OJPv1_LocationInformationRequest;
readonly StopEventRequest: typeof OJPv1_StopEventRequest;
readonly TripInfoRequest: typeof OJPv1_TripInfoRequest;
readonly TripRefineRequest: typeof EmptyRequest;
readonly TripRequest: typeof OJPv1_TripRequest;
};
readonly '2.0': {
readonly FareRequest: typeof EmptyRequest;
readonly LocationInformationRequest: typeof LocationInformationRequest;
readonly StopEventRequest: typeof StopEventRequest;
readonly TripInfoRequest: typeof TripInfoRequest;
readonly TripRefineRequest: typeof TripRefineRequest;
readonly TripRequest: typeof TripRequest;
};
};
type Builders = typeof builders;
type RequestKey = keyof Builders['2.0'];
type ClassFor<V extends OJP_VERSION, K extends RequestKey> = Builders[V][K];
/**
* SDK main class
*
* Instances are created via static methods below. Direct construction is intentionally disabled.
*
* ### Creation
* - `OJP.SDK.create( ... )` for OJPv2 instance
* - `OJP.SDK.v1( ... )` for legacy (OJPv1) instance
*
* @category Core
*/
declare class SDK<V extends OJP_VERSION = '2.0'> {
readonly version: OJP_VERSION;
requestorRef: string;
httpConfig: HTTPConfig;
language: Language;
private constructor();
/**
* Create OJPv2 SDK
*
* @param requestorRef string used for sending `<RequestorRef>` to OJP backend, be careful not to use a too much generic value
* @param httpConfig see {@link HTTPConfig | `HTTPConfig`}
*
* @group Initialization
*/
static create(requestorRef: string, httpConfig: HTTPConfig, language?: Language): SDK<'2.0'>;
/**
* Create OJPv1 SDK
*
* @param requestorRef string used for sending `RequestorRef` to OJP backend, be careful not to use a too much generic value
* @param httpConfig see {@link HTTPConfig | `HTTPConfig`}
*
* @group Initialization
*/
static v1(requestorRef: string, httpConfig: HTTPConfig, language?: Language): SDK<'1.0'>;
/**
* Used by applications consuming both (OJPv1, OJPv2) SDK where the request class is infered from the main SDK constructor.
*
* - `const mySDK: OJP.SDK<'2.0'> | OJP.SDK<'1.0'> = ...`
* - `mySDK.requests.LocationInformationRequest` will be either `OJP.LocationInformationRequest` or `OJP.OJPv1_LocationInformationRequest` class types
*
* @hidden
*/
get requests(): {
[K in RequestKey]: ClassFor<V, K>;
};
}
/**
* SDK current version
*
* @category Core
*/
declare const SDK_VERSION = "0.23.4";
/**
* Default XML configuration for serialization with 'ojp' as the default namespace
*
* @category XML Utils
*/
declare const DefaultXML_Config: XML_Config;
/**
* XML configuration for OJP version 1.0 with 'siri' as the default namespace
*
* @category XML Utils
*/
declare const XML_BuilderConfigOJPv1: XML_Config;
/**
* XML configuration for OJP version 1.0 with 'ojp' as the default namespace
*
* @category XML Utils
*/
declare const XML_ParserConfigOJPv1: XML_Config;
/** @internal */
declare class DateHelpers {
static formatDate(d: Date): string;
static formatTimeHHMM(d?: Date): string;
static computeDelayMinutes(timetableTimeS: Date | string, estimatedTimeS: Date | string | null): number | null;
}
/**
* Serializes JavaScript objects to XML format with configurable options.
*
* The XmlSerializer provides methods to convert JavaScript objects into XML strings
* using a configurable XML configuration. It includes automatic tag name transformation
* to handle different naming conventions.
*
* @example
* ```typescript
* // Basic usage
* const serializer = new XmlSerializer();
* const xmlString = serializer.serialize({
* name: "John",
* age: 30
* }, "person");
*
* // With custom configuration
* const customConfig = {
* indent: ' ',
* newline: '\n'
* };
* const serializerWithConfig = new XmlSerializer(customConfig);
* ```
*
* @category XML Utils
*/
declare class XmlSerializer {
xmlConfig: XML_Config;
constructor(xmlConfig?: XML_Config);
/**
* Serializes a JavaScript object to XML format
*
* @param obj - The object to serialize
* @param wrapperNodeName - The name of the root XML element
* @returns XML string representation of the object
*
* @example
* ```typescript
* const serializer = new XmlSerializer();
* const xml = serializer.serialize({
* firstName: "John",
* lastName: "Doe"
* }, "person");
* // Returns: '<person><firstName>John</firstName><lastName>Doe</lastName></person>'
* ```
*
*/
serialize(obj: Record<string, any>, wrapperNodeName: string): string;
/**
* Transforms a tag name to camelCase format for XML serialization
*
* This method handles special cases like OJP prefixes and preserves uppercase-only tags.
* It converts hyphenated or underscored names to camelCase while ensuring the first
* character is lowercase.
*
* @param tagName - The original tag name to transform
* @returns Transformed tag name in camelCase format
*
* @example
* ```typescript
* // Transform various tag name formats
* XmlSerializer.transformTagName('OJP_Feature'); // Returns: 'OJP_Feature'
* XmlSerializer.transformTagName('FIRST_NAME'); // Returns: 'FIRST_NAME'
* XmlSerializer.transformTagName('first-name'); // Returns: 'firstName'
* XmlSerializer.transformTagName('user_name'); // Returns: 'userName'
* ```
*/
static transformTagName(tagName: string): string;
}
export { type AnySDK, DateHelpers, DefaultXML_Config, type FareRequestResponse, GeoPosition, type HTTPConfig, type Language, LocationInformationRequest, type LocationInformationRequestResponse, type OJP_VERSION, OJPv1_FareRequest, OJPv1_LocationInformationRequest, type OJPv1_LocationInformationRequestResponse, OJPv1_StopEventRequest, type OJPv1_StopEventRequestResponse, OJPv1_TripInfoRequest, type OJPv1_TripInfoRequestResponse, OJPv1_TripRequest, type OJPv1_TripRequestResponse, Place, PlaceResult, type RequestInfo, SDK, SDK_VERSION, StopEventRequest, type StopEventRequestResponse, StopEventResult, Trip, TripInfoRequest, type TripInfoRequestResponse, TripRefineRequest, type TripRefineRequestResponse, TripRequest, type TripRequestResponse, XML_BuilderConfigOJPv1, XML_ParserConfigOJPv1, XmlSerializer };