docs: update README and add usage documentation; remove installation guide

Author: g-saracca

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).

docs/installation.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<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 `2.1.0-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.

docs/localDevelopment.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.