From fc62010428235acef999b6cda388a2568b95f0f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Mon, 30 Jun 2025 17:52:24 -0300 Subject: [PATCH 1/7] docs: replace references to js-dataverse with current package naming --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/ISSUE_TEMPLATE/feature_request.md | 2 +- CONTRIBUTING.md | 2 +- package-lock.json | 4 ++-- package.json | 2 +- src/core/infra/repositories/apiConfigBuilders.ts | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 128e80d8..22229f6a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -6,7 +6,7 @@ ## What did you expect to happen? -## Which version of js-dataverse are you using? +## Which version of dataverse-client-javascript are you using? ## Any related open or closed issues to this bug report? diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 79818922..56162374 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -4,6 +4,6 @@ ## What existing behavior do you want changed? -## Any brand new behavior do you want to add to js-dataverse? +## Any brand new behavior do you want to add to dataverse-client-javascript? ## Any open or closed issues related to this feature request? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 432eb098..44a7f046 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to js-dataverse +# Contributing to dataverse-client-javascript First of all thank you very much for your interest in contributing to this project! diff --git a/package-lock.json b/package-lock.json index 0db7602f..fed98650 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "js-dataverse", + "name": "@iqss/dataverse-client-javascript", "version": "2.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "js-dataverse", + "name": "@iqss/dataverse-client-javascript", "version": "2.0.0", "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 15eee168..bcfedaf3 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "js-dataverse", + "name": "@iqss/dataverse-client-javascript", "version": "2.0.0", "description": "Dataverse API wrapper package for JavaScript/TypeScript-based applications", "main": "./dist/index.js", diff --git a/src/core/infra/repositories/apiConfigBuilders.ts b/src/core/infra/repositories/apiConfigBuilders.ts index 3952cd49..c245c58e 100644 --- a/src/core/infra/repositories/apiConfigBuilders.ts +++ b/src/core/infra/repositories/apiConfigBuilders.ts @@ -30,7 +30,7 @@ export const buildRequestConfig = ( /* We set { withCredentials: true } to send the JSESSIONID cookie in the requests for API authentication. This is required, along with the session auth feature flag enabled in the backend, to be able to authenticate using the JSESSIONID cookie. - Auth mechanisms like this are configurable to set the one that fits the particular use case of js-dataverse. (For the SPA MVP, it is the session cookie API auth). + Auth mechanisms like this are configurable to set the one that fits the particular use case of dataverse-client-javascript. (For the SPA MVP, it is the session cookie API auth). */ requestConfig.withCredentials = true break From 1918a84584bc4d203db9b72bd64d836a3c5f92b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Mon, 30 Jun 2025 18:08:19 -0300 Subject: [PATCH 2/7] docs: update README and add usage documentation; remove installation guide --- README.md | 54 ++++++++++++++--- docs/installation.md | 124 --------------------------------------- docs/localDevelopment.md | 18 ++++++ docs/usage.md | 45 ++++++++++++++ 4 files changed, 109 insertions(+), 132 deletions(-) delete mode 100644 docs/installation.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index c88d7b79..d5bfab15 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,49 @@ -# js-dataverse +## Dataverse JavaScript Client -[![npm](https://img.shields.io/npm/v/js-dataverse.svg)](https://www.npmjs.com/package/js-dataverse) +![NPM Version](https://img.shields.io/npm/v/%40iqss%2Fdataverse-client-javascript) -A JavaScript/TypeScript API wrapper for [Dataverse](http://guides.dataverse.org/en/latest/api/). +The Dataverse JavaScript Client is an open-source package that provides a set of use-case-driven functions to interact with the [Dataverse API](http://guides.dataverse.org/en/latest/api/). Designed around Domain-Driven Design (DDD) principles, this package offers a structured, high-level interface to perform actions like retrieving datasets, managing collections, uploading files, and more. -- [Installation](./docs/installation.md) -- [Use Cases](./docs/useCases.md) -- [Local Development](./docs/localDevelopment.md) -- [Contributing](./CONTRIBUTING.md) -- [License](./LICENSE) +This package is part of the Dataverse Frontend ecosystem and is intended to be used by applications or services that integrate with the Dataverse platform. + +## Features + +- **Use case-centric API functions** – Organized around domain-specific actions like `getDataset`, `createCollection`, or `restrictFile`. +- **TypeScript-first** – All use cases include strong typings for inputs and outputs, improving developer experience. + +## Installation + +Install the package via npm: + +```bash +npm install @iqss/dataverse-client-javascript +``` + +## Usage + +```typescript +import { getDataset } from '@iqss/dataverse-client-javascript' + +/* ... */ + +const datasetIdentifier = 'doi:10.77777/FK2/AAAAAA' +const datasetVersion = '1.0' + +getDataset.execute(datasetIdentifier, datasetVersion).then((dataset: Dataset) => { + /* ... */ +}) + +/* ... */ +``` + +For detailed information about available use cases see [Use Cases Docs](https://github.com/IQSS/dataverse-client-javascript/blob/develop/docs/useCases.md). + +For detailed information about usage see [Usage Docs](https://github.com/IQSS/dataverse-client-javascript/blob/develop/docs/usage.md). + +## Contributing + +Want to add a new use case or improve an existing one? Please check the [Contributing](https://github.com/IQSS/dataverse-client-javascript/blob/develop/CONTRIBUTING.md) section. + +## License + +This project is open source and available under the [MIT License](https://github.com/IQSS/dataverse-client-javascript/blob/develop/LICENSE). diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 8148653c..00000000 --- a/docs/installation.md +++ /dev/null @@ -1,124 +0,0 @@ -# Installation - -Recommended versions node >=16 and npm >=8. - -## Getting Started with the Stable Version - -A stable 1.x version of this package is available as `js-dataverse` at https://www.npmjs.com/package/js-dataverse - -Install the package stable version using npm: - -```bash -npm install js-dataverse -``` - -## Getting Started with the Development Version - -An unstable 2.x version of this package with breaking changes is under development. - -Until a 2.0 version is officially released, it can be installed from https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript - -Two different versions are being pushed to the GitHub Packages registry: - -1. **PR-Generated Versions**: - - - These versions are generated from pull request commits. - - They follow the structure `2.0.0-pr.`, where `pr_number` is the number of the pull request, and `commit_hash` is the specific commit hash from the PR branch. - - These versions are unstable and correspond to the state of the package during the pull request. - -2. **Develop Alpha Versions**: - - These versions are generated on every commit made to the `develop` branch, ideally after each pull request is merged. - - They follow the structure `2.0.0-alpha.`, where `number` is an incremental value that starts at 1 and increases with each build. - - These versions are also unstable and represent the latest work in progress on the `develop` branch. - -### Create a `.npmrc` file and add a token - -To install the [@iqss/dataverse-client-javascript](https://github.com/IQSS/dataverse-client-javascript/pkgs/npm/dataverse-client-javascript) -from the GitHub registry, follow these steps to create an `.npmrc` file in the root of your project using your GitHub token. - -1. **Create `.npmrc`** in your project's root directory. - - ```bash - touch .npmrc - ``` - -2. **Replace the Token** - - Open the newly created `.npmrc` file and replace `YOUR_GITHUB_TOKEN` with your actual GitHub token. - - ```plaintext - legacy-peer-deps=true - - //npm.pkg.github.com/:_authToken= - @iqss:registry=https://npm.pkg.github.com/ - ``` - -#### How to Get a GitHub Token - -If you don't have a GitHub token yet, follow these steps: - -1. Go to your GitHub account settings. - -2. Navigate to "Developer settings" -> "Personal access tokens." - -3. Click "Personal access tokens" -> "Tokens (classic)" -> "Generate new token (classic)". - -4. Give the token a name and select the "read:packages" scope. - -5. Copy the generated token. - -6. Replace `YOUR_GITHUB_AUTH_TOKEN` in the `.npmrc` file with the copied token. - -Now, you should be able to install the Dataverse JavaScript client using npm. - -### Install the package - -Install the package development version using npm: - -```bash -npm install @iqss/dataverse-client-javascript -``` - -## Initialization - -In order for the package to connect to the Dataverse API, there is an `APIConfig` object that should be initialized to set the preferred authentication mechanism with the associated credentials for connecting to the Dataverse API. - -Currently, the supported authentication mechanisms are: - -- **API Key**: The recommended authentication mechanism. The API Key should correspond to a particular Dataverse user account. - -- **Session Cookie**: This is an experimental feature primarily designed for Dataverse SPA development. To use this mechanism, you must enable the corresponding feature flag in the Dataverse installation (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism and instead use API Key authentication. - -It is recommended to globally initialize the `ApiConfig` object from the consuming application, as the configuration will be read on every API call made by the package's use cases. - -For example, in a React application, we can globally initialize the `ApiConfig` object in the `App` file, like this: - -```typescript -ApiConfig.init(, DataverseApiAuthMechanism.API_KEY, ) - -function App() { - /* Yor App code */ -} - -export default App -``` - -The same example but with example values set: - -```typescript -ApiConfig.init( - 'http://localhost:8000/api/v1', - DataverseApiAuthMechanism.API_KEY, - 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' -) - -function App() { - /* Yor App code */ -} - -export default App -``` - -We can initialize the `ApiConfig` object as an unauthenticated user, by setting `undefined` as the API Key value. - -This will allow use cases that do not require authentication to be successfully executed, but those that do require authentication will fail. diff --git a/docs/localDevelopment.md b/docs/localDevelopment.md index 3508b83c..515d95ce 100644 --- a/docs/localDevelopment.md +++ b/docs/localDevelopment.md @@ -117,3 +117,21 @@ Fix linting checks on the code: ```bash npm run lint:fix ``` + +## Development Versions of this package + +Two different versions are being pushed to the GitHub Packages registry: + +1. **PR-Generated Versions**: + + - These versions are generated from pull request commits. + - They follow the structure `2.1.0-pr.`, where `pr_number` is the number of the pull request, and `commit_hash` is the specific commit hash from the PR branch. + - These versions are unstable and correspond to the state of the package during the pull request. + +2. **Develop Alpha Versions**: + - These versions are generated on every commit made to the `develop` branch, ideally after each pull request is merged. + - They follow the structure `2.1.0-alpha.`, where `number` is an incremental value that starts at 1 and increases with each build. + - These versions are also unstable and represent the latest work in progress on the `develop` branch. + +These versions are great for developing a new SPA frontend feature integration. +For instance, if you create a new use case in this repository and want to integrate the UI in the [dataverse-frontend repository](https://github.com/IQSS/dataverse-frontend), you can use the PR-Generated Version. If the changes have already been merged, the Alpha Version will contain the new use case. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..ae8bdde5 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,45 @@ +## Initialization + +In order for the package to connect to the Dataverse API, there is an `APIConfig` object that should be initialized to set the preferred authentication mechanism with the associated credentials for connecting to the Dataverse API. + +Currently, the supported authentication mechanisms are: + +- **API Key**: The recommended authentication mechanism. The API Key should correspond to a particular Dataverse user account. + +- **Bearer Token**: This mechanism is currently under development and testing. We've selected it for the upcoming Dataverse SPA and will provide more information in a future release once it becomes a standard. + +- **Session Cookie**: This is an experimental feature primarily designed for Dataverse SPA development. To use this mechanism, you must enable the corresponding feature flag in the Dataverse installation (See https://guides.dataverse.org/en/latest/installation/config.html?#feature-flags). It is recommended not to use this mechanism and instead use API Key authentication. + +It is recommended to globally initialize the `ApiConfig` object from the consuming application, as the configuration will be read on every API call made by the package's use cases. + +For example, in a React application, we can globally initialize the `ApiConfig` object in the `App` file, like this: + +```typescript +ApiConfig.init(, DataverseApiAuthMechanism.API_KEY, ) + +function App() { + /* Yor App code */ +} + +export default App +``` + +The same example but with example values set: + +```typescript +ApiConfig.init( + 'http://localhost:8000/api/v1', + DataverseApiAuthMechanism.API_KEY, + 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' +) + +function App() { + /* Yor App code */ +} + +export default App +``` + +We can initialize the `ApiConfig` object as an unauthenticated user, by setting `undefined` as the API Key value. + +This will allow use cases that do not require authentication to be successfully executed, but those that do require authentication will fail. From 73c79e79e251821e3ed8b7625c3c3dfb5472872f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Mon, 30 Jun 2025 18:17:52 -0300 Subject: [PATCH 3/7] docs: update links in README to point to main branch --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d5bfab15..4421abdf 100644 --- a/README.md +++ b/README.md @@ -36,14 +36,14 @@ getDataset.execute(datasetIdentifier, datasetVersion).then((dataset: Dataset) => /* ... */ ``` -For detailed information about available use cases see [Use Cases Docs](https://github.com/IQSS/dataverse-client-javascript/blob/develop/docs/useCases.md). +For detailed information about available use cases see [Use Cases Docs](https://github.com/IQSS/dataverse-client-javascript/blob/main/docs/useCases.md). -For detailed information about usage see [Usage Docs](https://github.com/IQSS/dataverse-client-javascript/blob/develop/docs/usage.md). +For detailed information about usage see [Usage Docs](https://github.com/IQSS/dataverse-client-javascript/blob/main/docs/usage.md). ## Contributing -Want to add a new use case or improve an existing one? Please check the [Contributing](https://github.com/IQSS/dataverse-client-javascript/blob/develop/CONTRIBUTING.md) section. +Want to add a new use case or improve an existing one? Please check the [Contributing](https://github.com/IQSS/dataverse-client-javascript/blob/main/CONTRIBUTING.md) section. ## License -This project is open source and available under the [MIT License](https://github.com/IQSS/dataverse-client-javascript/blob/develop/LICENSE). +This project is open source and available under the [MIT License](https://github.com/IQSS/dataverse-client-javascript/blob/main/LICENSE). From 01c60f30d41567bad5158348bcbb7323f2888f64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Wed, 2 Jul 2025 12:53:03 -0300 Subject: [PATCH 4/7] chore: revert version to 1.0.0 as package name has changed --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index fed98650..bb6696f2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@iqss/dataverse-client-javascript", - "version": "2.0.0", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@iqss/dataverse-client-javascript", - "version": "2.0.0", + "version": "1.0.0", "license": "MIT", "dependencies": { "@types/node": "^18.15.11", diff --git a/package.json b/package.json index bcfedaf3..dbaf2bea 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@iqss/dataverse-client-javascript", - "version": "2.0.0", + "version": "1.0.0", "description": "Dataverse API wrapper package for JavaScript/TypeScript-based applications", "main": "./dist/index.js", "types": "./dist/index.d.ts", From 329764fec2c0db09872b920ebd54698d51e66c61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Wed, 2 Jul 2025 12:56:42 -0300 Subject: [PATCH 5/7] chore: update versioning in github deploy workflows --- .github/workflows/deploy_alpha.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy_alpha.yml b/.github/workflows/deploy_alpha.yml index 5a442fe7..a097799b 100644 --- a/.github/workflows/deploy_alpha.yml +++ b/.github/workflows/deploy_alpha.yml @@ -72,16 +72,16 @@ jobs: run: | echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > ~/.npmrc - LATEST_VERSION=$(npm show @IQSS/dataverse-client-javascript versions --registry=https://npm.pkg.github.com/ --json | jq -r '.[]' | grep "^2.0.0-alpha." | sort -V | tail -n 1) + LATEST_VERSION=$(npm show @IQSS/dataverse-client-javascript versions --registry=https://npm.pkg.github.com/ --json | jq -r '.[]' | grep "^1.0.0-alpha." | sort -V | tail -n 1) if [ -z "$LATEST_VERSION" ]; then NEW_INCREMENTAL_NUMBER=1 else - CURRENT_INCREMENTAL_NUMBER=$(echo $LATEST_VERSION | sed 's/2.0.0-alpha.//') + CURRENT_INCREMENTAL_NUMBER=$(echo $LATEST_VERSION | sed 's/1.0.0-alpha.//') NEW_INCREMENTAL_NUMBER=$((CURRENT_INCREMENTAL_NUMBER + 1)) fi - NEW_VERSION="2.0.0-alpha.${NEW_INCREMENTAL_NUMBER}" + NEW_VERSION="1.0.0-alpha.${NEW_INCREMENTAL_NUMBER}" echo "Latest version: $LATEST_VERSION" echo "New version: $NEW_VERSION" From cb4c9b57c8a06c504e24b39f8e5219ba6ab0e83c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Wed, 2 Jul 2025 13:24:36 -0300 Subject: [PATCH 6/7] fix: update versioning structure in local development documentation --- docs/localDevelopment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/localDevelopment.md b/docs/localDevelopment.md index 515d95ce..fc000d18 100644 --- a/docs/localDevelopment.md +++ b/docs/localDevelopment.md @@ -125,12 +125,12 @@ Two different versions are being pushed to the GitHub Packages registry: 1. **PR-Generated Versions**: - These versions are generated from pull request commits. - - They follow the structure `2.1.0-pr.`, where `pr_number` is the number of the pull request, and `commit_hash` is the specific commit hash from the PR branch. + - They follow the structure `-pr.`, where `pr_number` is the number of the pull request, and `commit_hash` is the specific commit hash from the PR branch. - These versions are unstable and correspond to the state of the package during the pull request. 2. **Develop Alpha Versions**: - These versions are generated on every commit made to the `develop` branch, ideally after each pull request is merged. - - They follow the structure `2.1.0-alpha.`, where `number` is an incremental value that starts at 1 and increases with each build. + - They follow the structure `-alpha.`, where `number` is an incremental value that starts at 1 and increases with each build. - These versions are also unstable and represent the latest work in progress on the `develop` branch. These versions are great for developing a new SPA frontend feature integration. From 1c4abec49fce3d88b0e5564fbdfb9e5d2cdc2a03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Germ=C3=A1n=20Saracca?= Date: Wed, 2 Jul 2025 13:55:33 -0300 Subject: [PATCH 7/7] chore: increase patch version --- .github/workflows/deploy_alpha.yml | 6 +++--- package-lock.json | 4 ++-- package.json | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/deploy_alpha.yml b/.github/workflows/deploy_alpha.yml index a097799b..703edba0 100644 --- a/.github/workflows/deploy_alpha.yml +++ b/.github/workflows/deploy_alpha.yml @@ -72,16 +72,16 @@ jobs: run: | echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" > ~/.npmrc - LATEST_VERSION=$(npm show @IQSS/dataverse-client-javascript versions --registry=https://npm.pkg.github.com/ --json | jq -r '.[]' | grep "^1.0.0-alpha." | sort -V | tail -n 1) + LATEST_VERSION=$(npm show @IQSS/dataverse-client-javascript versions --registry=https://npm.pkg.github.com/ --json | jq -r '.[]' | grep "^1.0.1-alpha." | sort -V | tail -n 1) if [ -z "$LATEST_VERSION" ]; then NEW_INCREMENTAL_NUMBER=1 else - CURRENT_INCREMENTAL_NUMBER=$(echo $LATEST_VERSION | sed 's/1.0.0-alpha.//') + CURRENT_INCREMENTAL_NUMBER=$(echo $LATEST_VERSION | sed 's/1.0.1-alpha.//') NEW_INCREMENTAL_NUMBER=$((CURRENT_INCREMENTAL_NUMBER + 1)) fi - NEW_VERSION="1.0.0-alpha.${NEW_INCREMENTAL_NUMBER}" + NEW_VERSION="1.0.1-alpha.${NEW_INCREMENTAL_NUMBER}" echo "Latest version: $LATEST_VERSION" echo "New version: $NEW_VERSION" diff --git a/package-lock.json b/package-lock.json index bb6696f2..eb71e76e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@iqss/dataverse-client-javascript", - "version": "1.0.0", + "version": "1.0.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@iqss/dataverse-client-javascript", - "version": "1.0.0", + "version": "1.0.1", "license": "MIT", "dependencies": { "@types/node": "^18.15.11", diff --git a/package.json b/package.json index dbaf2bea..a84ecf9b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@iqss/dataverse-client-javascript", - "version": "1.0.0", + "version": "1.0.1", "description": "Dataverse API wrapper package for JavaScript/TypeScript-based applications", "main": "./dist/index.js", "types": "./dist/index.d.ts",