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/.github/workflows/deploy_alpha.yml b/.github/workflows/deploy_alpha.yml index 5a442fe7..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 "^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.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/2.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="2.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/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/README.md b/README.md index c88d7b79..4421abdf 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/main/docs/useCases.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/main/CONTRIBUTING.md) section. + +## License + +This project is open source and available under the [MIT License](https://github.com/IQSS/dataverse-client-javascript/blob/main/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..fc000d18 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 `-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 `-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. diff --git a/package-lock.json b/package-lock.json index 0db7602f..eb71e76e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { - "name": "js-dataverse", - "version": "2.0.0", + "name": "@iqss/dataverse-client-javascript", + "version": "1.0.1", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "js-dataverse", - "version": "2.0.0", + "name": "@iqss/dataverse-client-javascript", + "version": "1.0.1", "license": "MIT", "dependencies": { "@types/node": "^18.15.11", diff --git a/package.json b/package.json index 15eee168..a84ecf9b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { - "name": "js-dataverse", - "version": "2.0.0", + "name": "@iqss/dataverse-client-javascript", + "version": "1.0.1", "description": "Dataverse API wrapper package for JavaScript/TypeScript-based applications", "main": "./dist/index.js", "types": "./dist/index.d.ts", 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