Merge pull request #328 from IQSS/release/1.0.0

g-saracca · web-flow · commit 7f3e9eb3fe0b · 2025-07-03T19:50:09.000-03:00
Update develop branch with release branch changes
diff --git 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
@@ -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/.npmrc.example b/.npmrc.example
@@ -0,0 +1,3 @@
+# NPM Package Registry
+//registry.npmjs.org/:_authToken=<YOUR_NPM_AUTH_TOKEN>
+@iqss:registry=https://registry.npmjs.org/
diff --git 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
@@ -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
diff --git 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 `<current_package_version>-pr<pr_number>.<commit_hash>`, 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 `<current_package_version>-alpha.<number>`, 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/making-releases.md b/docs/making-releases.md
@@ -0,0 +1,118 @@
+# Making Releases
+
+- [Introduction](#introduction)
+- [Regular or Hotfix?](#regular-or-hotfix)
+- [Create Github Issue and Release Branch](#create-github-issue-and-release-branch)
+- [Update the version](#update-the-version)
+- [Merge "release branch" into "main"](#merge-release-branch-into-main)
+- [Publish the Dataverse Client Javascript package](#publish-the-dataverse-client-javascript-package)
+- [Create a Draft Release on GitHub and Tag the Version](#create-a-draft-release-on-github-and-tag-the-version)
+- [Merge "release branch" into "develop"](#merge-release-branch-into-develop)
+- [Delete "release branch"](#delete-release-branch)
+
+## Introduction
+
+This document is about releasing a new version of dataverse-client-javascript.
+
+## Regular or Hotfix?
+
+Early on, make sure it’s clear what type of release this is. The steps below describe making both regular releases and hotfix releases. Suppose the current version is 1.0.0.
+
+- Regular
+  - e.g. 1.1.0 (minor)
+  - e.g. 2.0.0 (major)
+- Hotfix
+  - e.g. 1.1.1 (patch)
+
+## Create Github Issue and Release Branch
+
+First of all create an issue on Github to prepare the release, name it Release vX.X.X .
+
+On your local, create the release branch from the latest from develop and name it release/X.X.X .
+
+## Update the version
+
+To update the version run the command `npm version <X.X.X> --no-git-tag-version`. So if we are releasing version `3.5.0` the command will be:
+
+```shell
+npm version 3.5.0 --no-git-tag-version
+```
+
+This command will update the version in the `package.json` and `package-lock.json`.
+
+If everything looks good, you can push the changes to the repository.
+
+## Merge "release branch" into "main"
+
+Create a pull request to merge the `release` branch into the `main` branch.
+Once important tests have passed (unit, functional, integration), merge the pull request (skipping code review is ok).
+
+## Publish the Dataverse Client Javascript package
+
+Once the release branch has been merged, switch to the `main` branch on your local machine and update it to ensure you have the latest changes.
+
+Dataverse Client Javascript is [published](https://www.npmjs.com/package/@iqss/dataverse-client-javascript) to the npm Package Registry. Below are the steps for publishing a new version.
+
+1.  **Build the package**
+
+    Now we need to build the package by running `npm run build`, after that you will see a `dist` folder in the root of the project. If you are not sure that folder was there already you can delete it and run the build command again.
+
+2.  **Publish the package**
+
+    As the version number is already updated and we build the package, now we can publish the package running the next command:
+
+    ```shell
+    npm publish --access public
+    ```
+
+    This command will publish the package to the npm registry.
+
+    Remember that you need a valid npm token to publish the package and be part of the @iqss organization on npm.
+
+    Get a new token from the npm website and update the `.npmrc` file with the new token. If you don't have yet an `.npmrc` file, go to the project directory root, duplicate `.npmrc.example`, saving the copy as `.npmrc`.
+
+    Open the `.npmrc` file and replace `YOUR_NPM_TOKEN ` with your actual npm token.
+
+    ```plaintext
+    //registry.npmjs.org/:\_authToken=<YOUR_NPM_AUTH_TOKEN>
+    @iqss:registry=https://registry.npmjs.org/
+    ```
+
+3.  **Review the new version in the npm registry**
+
+    After publishing the package, you can review the new version in the [npm registry](https://www.npmjs.com/package/@iqss/dataverse-client-javascript?activeTab=versions).
+
+    The new version should be available in the npm registry.
+
+## Create a Draft Release on GitHub and Tag the Version
+
+After merging the `release` branch into the `main` branch, you should create a release on GitHub and tag the version.
+
+Go to https://github.com/IQSS/dataverse-client-javascript/releases/new to start creating a draft release.
+
+- Under "Choose a tag" you will be creating a new tag. Have it start with a "v" such as v3.5.0. Click "Create new tag on publish".
+
+- Under "Target", choose "main".
+
+- Under "Release title" use the same name as the tag such as v3.5.0.
+
+- Add a description of the changes included in this release. You should include a link to the recently published npm version and summarize the key updates, fixes, or features.
+
+- Click "Save draft" because we do not want to publish the release yet.
+
+At this point you can send around the draft release for any final feedback. Make corrections to the draft, if necessary. Publish once everything is ok.
+
+## Merge "release branch" into "develop"
+
+After merging the release branch into `main`, ensure the develop branch is updated with the latest changes.
+
+Create a pull request to merge the `release` branch into `develop` branch also.
+
+## Delete "release branch"
+
+Once the release process is complete and the `release` branch has been merged into both `main` and `develop`, you can safely delete the `release` branch to keep the repository clean.
+
+- Delete the branch locally from your repository.
+- Delete the branch remotely from the remote repository.
+
+This ensures that the `release` branch is no longer present in either your local or remote repositories.
diff --git a/docs/usage.md 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(<DATAVERSE_API_BASE_URL>, DataverseApiAuthMechanism.API_KEY, <DATAVERSE_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
diff --git a/package.json b/package.json
diff --git a/src/core/infra/repositories/apiConfigBuilders.ts b/src/core/infra/repositories/apiConfigBuilders.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# NPM Package Registry`
	`2`	`+//registry.npmjs.org/:_authToken=<YOUR_NPM_AUTH_TOKEN>`
	`3`	`+@iqss:registry=https://registry.npmjs.org/`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Contributing to js-dataverse`
	`1`	`+# Contributing to dataverse-client-javascript`
`2`	`2`
`3`	`3`	`First of all thank you very much for your interest in contributing to this project!`
`4`	`4`