npm package: @quable/quable-pim-js
Description: A Quable PIM API JavaScript library designed to facilitate the interaction with Quable PIM. It enables data retrieval and simplifies the process of creating and managing products for data integration.
Author: Quable
Latest version: 3.0.0

# QUABLE PIM JS

### @quable/quable-pim-js

![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)

This library offers a convenient method for interacting with the Quable PIM API. It offers a high-level abstraction of the API, simplifying tasks such as creating, reading, updating, and deleting documents, classifications, and other data.

## Benefits

- **Easy to use:** The client provides a high-level abstraction over the Quable PIM API, simplifying common tasks.

- **Well documented:** The client is well-documented, featuring examples and comprehensive documentation for all its features.

- **Complete:** The client supports all the major endpoint of the Quable PIM API, including documents, variants, links, assets, classifications, and webhooks.

- **Up-to-date:** The client is regularly updated to support the latest features and changes to the Quable PIM API.

- **The PIM Data Aggregator**: This module enhances data extraction capabilities by offering advanced methods to extract, format, and aggregate documents on multi-level joins.

## Getting started

### Requirements

1. You must [download and install Node.js](https://nodejs.org/en/download/) if you don't already have it.

2. You must have a [Quable PIM instance](https://www.quable.com/en/) for testing if you don't have one.

### Installing

The library can be installed through NPM or Yarn:

```bash
yarn  add  @quable/quable-pim-js
```

or

```bash
npm  install  @quable/quable-pim-js
```

### Usage

You must get your `<instance-name>` from your Quable PIM access URL: `https://<instance-name>.quable.com`.

For the API Token, you can retrieve it from your PIM in **Administration -> API Token**.

#### 1 - Initialize the client

Once your client is initialized, you can access the REST API, GraphQL API, or PDA (Pim Data Aggregator) through the `API` namespace.

```js
import { QuablePimClient } from '@quable/quable-pim-js';

const client = new QuablePimClient({
  instanceName: '<instance-name>',
  apiToken: '<api-token>',
});
```

#### 2 - REST API Methods

##### Get all your documents

The provided code snippet demonstrates how to retrieve multiple documents with various filters. This allows you to obtain a collection of documents that meet specific criteria:

```js
const documents = await client.API.REST.Document.getAll({
  limit: 10,
  id: ['10668000', 'PEBYF09B', '10551000-01'],
  active: true,
  dateModified: {
    before: '2023-10-16',
    strictly_after: '2023-12-01',
  },
});
```

##### Create new document

The provided code demonstrates the creation of a new document of type **product**, the document is created with the specified attributes under the classification **default_collection**.

```ts
const createdDocument = await client.API.REST.Document.create({
  classification: {
    id: 'default_collection',
  },
  documentType: {
    id: 'product',
  },
  attributes: {
    product_name: {
      en_US: 'T-shirt',
    },
  },
  id: 'product-t-shirt',
});
```

##### Get an asset by its code

The provided code snippet demonstrates how to retrieve an asset by its unique code.

```ts
const asset = await client.API.REST.Asset.get('d5caa515-dbdd-4a3b-bc0e-front');
```

##### Update an asset

The provided code snippet demonstrates how to update an asset, In this example, the asset is updated by changing its `asset_title` attribute to **Red T-shirt** for english locale.

```ts
const updatedAsset = await client.API.REST.Asset.update(
  'd5caa515-dbdd-4a3b-bc0e-front',
  {
    attributes: {
      asset_title: {
        en_US: 'Red T-shirt',
      },
    },
  }
);
```

#### 3 - GraphQL API Methods

##### GraphQL Query

The provided code snippet demonstrates how to execute a GraphQL query to retrieve data:

```ts
const query = `
  query {
    documents {
      id
      attributes
    }
  }
`;

const result = await client.API.GraphQL.query(query);
```

##### GraphQL Query with Variables

The provided code snippet demonstrates how to execute a GraphQL query with variables:

```ts
const query = `
  query getDocument($id: String!) {
    document(id: $id) {
      id
      attributes
    }
  }
`;

const result = await client.API.GraphQL.query(query, { id: 'my-document-id' });
```

#### 4 - PDA Methods

#### Query data aggregation :

The provided code snippet performs a data aggregation query, focusing on specified documents identified by their unique IDs in the `documentIds` array. This query collects data related to these specific documents and their associated attributes, assets, and other linked data:

```ts
const payload = {
  documentType: 'product',
  documentAssetLink: ['article_images_media'],
  secondLevelLink: 'link_type_link_product',
  secondLevelAssetLink: ['article_images_media'],
  thirdLevelLink: '__variants__',
  thirdLevelAssetLink: ['sku_images_media'],
  localeCode: 'fr_FR',
  filters: { documentIds: ['CODE_8397340377410'] },
};

const data = await client.PimDataAggregator.Query.getData(payload);
```

#### Query bulk data aggregation:

The provided code snippet performs a bulk data aggregation query to retrieve data related to documents of type **product.** While it doesn't specify particular document IDs in the `documentIds` array, it effectively retrieves data for all documents that meet the specified criteria, including the `documentType`, `asset links`, `locale`, and `filters`:

```ts
const payload = {
  documentType: 'product',
  documentAssetLink: ['article_images_media'],
  secondLevelLink: 'link_type_link_product',
  secondLevelAssetLink: ['article_images_media'],
  thirdLevelLink: '__variants__',
  thirdLevelAssetLink: ['sku_images_media'],
  localeCode: 'fr_FR',
};

const { id } = await client.PimDataAggregator.Operation.create(payload);
const { status } = await client.PimDataAggregator.Operation.get(id);

const outputDir = './operation-files';

if (status == 'Completed')
  await client.PimDataAggregator.Operation.downloadAndUnzip(id, outputDir);
```

### Development

#### Installation

**With npm**:
```bash
npm install
```

**With yarn**:
```bash
yarn install
```

#### Testing

To run tests within the Quable SDK JS:

**With npm**:
```bash
npm test
```

**With yarn**:
```bash
yarn test
```

#### Watch mode

**With npm**:
```bash
npm test -- --watch
```

**With yarn**:
```bash
yarn test --watch
```

## Documentation

Documentation for API endpoints can be found in [here](https://docs.quable.com/v5-EN/docs).

## Author

[support@quable.com](mailto:support@quable.com)

## License

[MIT License](https://opensource.org/license/mit/)