openTdataCH · vasile · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025
diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml
@@ -0,0 +1,39 @@
+name: Publish ojp-sdk-next on npm
+
+on:
+  push:
+    tags:
+      - '0.21.*'
+  # allow manual trigger
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Sync lockfile
+        run: npm install --package-lock-only --ignore-scripts
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
+lib
 node_modules
-/lib
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,158 @@
 # CHANGELOG
 
+## 0.21.2 - 22.01.2025
+- updates API - [PR #219](https://github.com/openTdataCH/ojp-js/pull/219)
+  - updates TRR refine params
+  - use latest `ojp-shared-types`
+
+## 0.21.1 - 25.11.2025
+- refactor SDK - [PR #210](https://github.com/openTdataCH/ojp-js/pull/210)
+  - package
+    - bumps minor version to `0.21.x`
+    - declare `ojp-shared-types` as peerDependency
+  - SDK constructor is now private and uses generics to differentiate between OJP versions
+    - use `OJP.SDK.create()` to create a OJP 2.0 instance
+    - or `OJP.SDK.v1()` to create a OJP 1.0
+  - update requests
+    - refactor creation to allow a clear separation between OJP v1 and OJP v2, adds request per OJP version/request type
+    - old static inits are kept, however a new construct mode is recommended
+  ```
+  const ojpSDK = OJP.SDK.create('my_requestor_ref', httpConfig, 'de');
+  const request = ojpSDK.requests.LocationInformationRequest.initWithLocationName('Bern');
+  // instead of
+  // const request = OJP.LocationInformationRequest.initWithLocationName('Bern');
+  ```
+  - update requests (continued)
+    - requests dont conform to XSD schemas anymore, a property `.payload` is used for that
+    - updated requests, added LIR, SER for OJPv1
+    - request fetching + parsing is done now via `await request.fetchResponse(sdkInstance) call`
+    - see more changes in this [short gist](https://gist.github.com/vasile/40399cd2bb390ec7b9eb1fbbe52e5020)
+  - updates XML parser
+    - changed parser, improve handling of the `#text` nodes generated by `fast-xml-parser`
+    - requests dont conform to XSD schemas anymore, a property `.payload` is used for that, therefore no more need for the `MapModelKeepPropertiesXML` lookup hack in `ojp-shared-types` dependency
+
+## 0.20.33 - 23.11.2025
+- use latest `ojp-shared-types` - [PR #215](https://github.com/openTdataCH/ojp-js/pull/215)
+
+## 0.20.32 - 13.11.2025
+- Fix OJPv1 GeneralAttribute - [PR #213](https://github.com/openTdataCH/ojp-js/pull/213)
+  - use new OJP_Types `GeneralAttributeSchema`
+
+## 0.20.31 - 13.11.2025
+- Params Updates - [PR #212](https://github.com/openTdataCH/ojp-js/pull/212)
+  - TR - adds filter helper for `RailSubmode`
+  - Place - adds support for OJP v1 init, adds `initWithOJPv1XMLSchema` static initializer
+  - use latest `ojp-shared-types`
+    - TR restriction mode filter requires now `ptMode`, `personalMode`  arrays
+
+## 0.20.30 - 31.10.2025
+- TR with IndividualTransportOption - [PR #205](https://github.com/openTdataCH/ojp-js/pull/205)
+  - adds `setMaxDurationWalkingTime`method for TR requests with longer walking (at origin / destination)
+  - adds Github workflow for npm publish automation
+
+## 0.20.29 - 16.10.2025
+- use latest `ojp-shared-types` - [PR #201](https://github.com/openTdataCH/ojp-js/pull/201)
+
+## 0.20.28 - 26.09.2025
+- use latest `ojp-shared-types` - [PR #200](https://github.com/openTdataCH/ojp-js/pull/200)
+
+## 0.20.27 - 17.09.2025
+- TR car filter - [add car routing support #190](https://github.com/openTdataCH/ojp-js/issues/190) - [PR #193](https://github.com/openTdataCH/ojp-js/pull/194)
+
+## 0.20.26 - 01.09.2025
+- use latest `ojp-shared-types` - [PR #193](https://github.com/openTdataCH/ojp-js/pull/193)
+
+## 0.20.25 - 20.08.2025
+- use latest `ojp-shared-types` - [PR #191](https://github.com/openTdataCH/ojp-js/pull/191)
+
+## 0.20.24 - 08.07.2025
+- use latest `ojp-shared-types` - [PR #189](https://github.com/openTdataCH/ojp-js/pull/189)
+
+## 0.20.23 - 24.06.2025
+- fix parsing order - [PR #185](https://github.com/openTdataCH/ojp-js/pull/185)
+
+## 0.20.22 - 24.06.2025
+- use latest `ojp-shared-types` - [PR #184](https://github.com/openTdataCH/ojp-js/pull/184)
+
+## 0.20.21 - 12.06.2025
+- LIR filter with PtMode - [PR #182](https://github.com/openTdataCH/ojp-js/pull/182)
+  - use latest `ojp-shared-types` package
+  - updates examples for PtMode filter (TR, LIR)
+
+## 0.20.20 - 11.06.2025
+- updates SDK - [PR #181](https://github.com/openTdataCH/ojp-js/pull/181)
+  - adds TRR, FareRequest initialisers with mock request / response
+  - adds tests for FareRequest
+
+## 0.20.19 - 11.06.2025
+- updates SDK - [PR #180](https://github.com/openTdataCH/ojp-js/pull/180)
+  - updates `ojp-shared-types` (TR params `walkSpeed`)
+
+## 0.20.18 - 06.06.2025
+- Improve serialising - [PR #178](https://github.com/openTdataCH/ojp-js/pull/178)
+  - improve internal `buildXML`, adds `XmlSerializer` for outside SDK serialising objects to XML
+  - harmonise FareRequest response, adds `fetchFareRequestResponse` with `FareDeliverySchema` 
+  - remove `Trip.rawXML` property
+  - updates playground associated app
+
+## 0.20.17 - 02.06.2025
+- harmonise SDK Response - [PR #171](https://github.com/openTdataCH/ojp-js/pull/171)
+  - harmonise SDK response, use `Promise<OJP_Response<OJP_Types.(LIR | TR | SER TIR), Error>>` response type
+  - deprecate older methods (i.e. the ones fetching individual Trip[])
+  - adds tests for SIRI-SX situation models
+
+## 0.20.16 - 29.05.2025
+- adds TripInfoRequest request / response - [PR #170](https://github.com/openTdataCH/ojp-js/pull/170)
+- dynamically build `MapParentArrayTags`, dont rely on `ojp-shared-types` package
+
+## 0.20.15 - 27.05.2025
+- save raw XML for `Trip` - [PR #169](https://github.com/openTdataCH/ojp-js/pull/169)
+
+## 0.20.14 - 14.05.2025
+- export `RequestInfo`
+
+## 0.20.13 - 13.05.2025
+- (re-)adds FareRequest - [PR #167](https://github.com/openTdataCH/ojp-js/pull/167)
+
+## 0.20.11 - 13.05.2025
+- use [ojp-shared-types](https://github.com/openTdataCH/ojp-shared-types) package - [PR #166](https://github.com/openTdataCH/ojp-js/pull/166)
+
+## 0.20.10 - 17.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - [Adds TripRefinementRequest #151](https://github.com/openTdataCH/ojp-js/pull/151)
+  - TR - [Feature/trip response status #152](https://github.com/openTdataCH/ojp-js/pull/152)
+  - TRR TripParam - [Updates TRR #153](https://github.com/openTdataCH/ojp-js/pull/153)
+
+## 0.20.8 - 15.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - [Fix LIR models (Place.Mode) #148](https://github.com/openTdataCH/ojp-js/pull/148)
+
+## 0.20.7 - 14.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - fixed JSON (xml-parsed) traverse, catch case for expected empty arrays
+
+## 0.20.5 - 13.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - use dual builds (CommonJS and ESM) via `tsup`
+
+## 0.20.4 - 12.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - revert to use CJS module style
+
+## 0.20.3 - 12.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - use NodeNext, ESM style
+  - more robust NS parsing
+
+## 0.20.2 - 01.04.2025
+- refactor/next version of the SDK (continued) - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+
+## 0.20.1 - 26.03.2025
+- refactor/next version of the SDK - [PR #139](https://github.com/openTdataCH/ojp-js/pull/139)
+  - OJP 2.0 APIs is now used
+  - [XSD schema](https://vdvde.github.io/OJP/develop/documentation-tables/ojp.html) is used for models
+  - bundle OJP demo app in [examples/ojp-demo-app](./examples/ojp-demo-app)
+
 ## 0.16.3 - 14.03.2025
 - internal change, refactor params/request implementation - [PR #137](https://github.com/openTdataCH/ojp-js/pull/137)
 - adds hack for OJP-SI to allow Trip nodes without Transfer children node - [PR #138](https://github.com/openTdataCH/ojp-js/pull/138)

diff --git a/README.md b/README.md
@@ -2,58 +2,112 @@
 
 The OJP Javascript SDK is a Javascript/Typescript package used for communication with [OJP APIs](https://opentransportdata.swiss/en/cookbook/open-journey-planner-ojp/).
 
-See [Reference](./docs/reference.md) and [examples](./examples/) for usage.
+## Current Development Status
+
+Javascript SDK branches
+
+| Branch | NPM | Demo App | Description |
+|-|-|-|-|
+| [ojp-js#ojp-sdk-legacy](https://github.com/openTdataCH/ojp-js/tree/feature/ojp-sdk-legacy) | [ojp-sdk-legacy](https://www.npmjs.com/package/ojp-sdk-legacy) | <ul><li>[PROD - OJP 2.0](https://opentdatach.github.io/ojp-demo-app/search)</li><li>[BETA - OJP 1.0](https://tools.odpch.ch/beta-ojp-demo/search)</li></ul> | original SDK, contains dual code for OJP `1.0`,`2.0` |
+| [ojp-js#ojp-sdk-next](https://github.com/openTdataCH/ojp-js/tree/feature/ojp-sdk-next) | [ojp-sdk-next](https://www.npmjs.com/package/ojp-sdk-next) - temporarely, long-term will be published under `ojp-sdk` | under development | new SDK code with models derived from XSD schema, this will be the main development reference for OJP JS SDK |
+
+Code / Demo App Implementation
+
+| Code Place | LIR | SER | TR | TIR | FR | TRR | Comments |
+| - | - | - | - | - | - | - | - |
+| `ojp-sdk-legacy` (legacy SDK) | :white_check_mark: | :white_check_mark: | :white_check_mark: | - | - | - | TRR is only available for OJP v2.0 |
+| `ojp-sdk-next` (new SDK) | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |  |
+| DemoApp Beta | `legacy` | `legacy` | `legacy` | `ojp-sdk-next` | `ojp-sdk-next` | `ojp-sdk-next` | `legacy` is the old SDK (OJP v1 and v2, see above) |
+
+- LIR - LocationInformationRequest
+- SER - StopEventRequest
+- TR - TripRequest
+- TIR - TripInfoRequest
+- FR - FareRequest
+- TRR - TripRefineRequest
 
 ## Resources
 
-- OJP Demo App: https://opentdatach.github.io/ojp-demo-app/ - web application this SDK
+- OJP Demo App: https://opentdatach.github.io/ojp-demo-app/ - web application using this SDK
 - [CHANGELOG](./CHANGELOG.md) for latest changes
 - npm `ojp-sdk` package: https://www.npmjs.com/package/ojp-sdk
 
-## Install
-
-Two versions of the OJP APIs can be used:
-- [OJP 1.0](https://opentransportdata.swiss/en/cookbook/open-journey-planner-ojp/) - still supported by `ojp-js` SDK but might receive less support in the future
-- [OJP 2.0](https://opentransportdata.swiss/de/cookbook/ojp2entwicklung/) - next version, see [VDVde/OJP](https://github.com/VDVde/OJP/blob/changes_for_v1.1/README.md) specs
+## Usage 
 
-### OJP 1.0
-The  main branch of `ojp-js` repo is using OJP 1.0 APIs. The releases are published to [npmjs.com](https://www.npmjs.com/package/ojp-sdk) as `ojp-sdk` packages. 
+**Note:** 26.Mar - a different package name is used for test purpose: `ojp-sdk-next`. This package will replace the current `ojp-sdk` package.
 
-- include the `ojp-sdk` package in the `./package.json` dependencies of your project 
+- include [ojp-sdk-next](https://www.npmjs.com/package/ojp-sdk-next), [ojp-shared-types](https://www.npmjs.com/package/ojp-shared-types) packages in the `./package.json` dependencies of the project 
 ```
   "dependencies": {
-    "ojp-sdk": "0.16.3"
+    "ojp-shared-types": "0.1.2",
+    "ojp-sdk-next": "0.21.2",
   }
 ```
 
-### OJP 2.0
-The [ojp-v2](https://github.com/openTdataCH/ojp-js/tree/feature/ojp-v2) branch is used for developing [OJP 2.0](https://opentransportdata.swiss/de/cookbook/ojp2entwicklung/) bindings, 
-- include the `#ojp-v2` branch
-```
-  "dependencies": {
-    "ojp-sdk": "git+https://github.com/openTdataCH/ojp-js.git#feature/ojp-v2"
-  }
-```
+- get an API key from [opentransportdata.swiss](https://api-manager.opentransportdata.swiss/) API manager
 
-## Usage
+- use the SDK, see also [playground.component.ts](./examples/ojp-playground/src/app/playground/playground.component.ts) in examples
 
-- update project dependencies
-```
-$ npm install
 ```
+import * as OJP from 'ojp-sdk-next';
 
-- include OJP SDK in the Typescript / Javascript code
-```
-import * as OJP from 'ojp-sdk'
+// ...
+
+// declare the stage config, PROD example below
+const httpConfig: OJP.HTTPConfig = {
+  url: 'https://api.opentransportdata.swiss/ojp20',
+  authToken: 'TOKEN_FROM_opentransportdata.swiss',
+};
+
+// define a requestorRef that describes the client
+const requestorRef = 'MyExampleTransportApp.v1';
+
+// create the SDK
+const language = 'de'; // de, fr, it, en
+const ojpSDK = OJP.SDK.create(requestorRef, httpConfig, language);
+
+// build LIR by Name
+const searchTerm = 'Bern';
+const request1 = ojpSDK.requests.LocationInformationRequest.initWithLocationName('Bern');
+
+// build LIR by StopRef
+const stopRef = '8507000'; // Bern
+const request2 = ojpSDK.requests.LocationInformationRequest.initWithPlaceRef(stopRef);
+
+// build LIR by BBOX
+// these are equivalent
+let bbox: string | number[] = '7.433259,46.937798,7.475252,46.954805';
+bbox = [7.433259, 46.937798, 7.475252, 46.954805];
+
+const request3 =  ojpSDK.requests.LocationInformationRequest.initWithBBOX(bbox, ['stop']);
+
+// change XML payload if needed
+request1.payload.initialInput ...
+
+// fetch the results
+async myMethod() {
+  // ...
+  const response = await request1.fetchResponse(ojpSDK);
+
+  if (!response.ok) {
+    // handle error
+    console.log(response.error);
+    return;
+  }
+
+  // do something with the value
+  const placeResults = response.value.placeResult ?? [];
+  placeResults.forEach(placeResult => {
+    console.log(placeResult.place.name);
+  });
+}
 ```
 
-- for more details check:
-  - this repo [reference](./docs/reference.md)
-  - this repo [examples](./examples/)
-  - [OJP Demo App](https://github.com/openTdataCH/ojp-demo-app-src) source code
+TBA
+- update [docs](./docs/)
 
 ## License
 
 The project is released under a [MIT license](./LICENSE).
 
-Copyright (c) 2021 - 2024 Open Data Platform Mobility Switzerland - [opentransportdata.swiss](https://opentransportdata.swiss/en/).
+Copyright (c) 2021 - 2025 Open Data Platform Mobility Switzerland - [opentransportdata.swiss](https://opentransportdata.swiss/en/).
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,8 @@
 # OJP JS SDK Documentation
 
+WIP, old pages below
+
+----
+
 - [Architecture](./architecture.md)
 - [Reference](./reference.md)