Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/rickypid/iubenda-consent-solution-api

API client to implement Iubenda Consent Solution in backend service
https://github.com/rickypid/iubenda-consent-solution-api
api api-client iubenda iubenda-api iubenda-consent-solution npm npm-package typescript
Last synced: 16 days ago
JSON representation
API client to implement Iubenda Consent Solution in backend service
Host: GitHub
URL: https://github.com/rickypid/iubenda-consent-solution-api
Owner: rickypid
License: mit
Created: 2022-01-02T11:12:10.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2023-12-19T15:49:50.000Z (11 months ago)
Last Synced: 2024-10-12T14:32:53.240Z (27 days ago)
Topics: api, api-client, iubenda, iubenda-api, iubenda-consent-solution, npm, npm-package, typescript
Language: TypeScript
Homepage:
Size: 372 KB
Stars: 6
Watchers: 2
Forks: 2
Open Issues: 1
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

        # iubenda-consent-solution-api

[![npm](https://badgen.net/npm/v/iubenda-consent-solution-api)](https://www.npmjs.com/package/iubenda-consent-solution-api)

[![Downloads](https://badgen.net/npm/dt/iubenda-consent-solution-api)](https://www.npmjs.com/package/iubenda-consent-solution-api)

[![Types](https://badgen.net/npm/types/iubenda-consent-solution-api)](https://www.npmjs.com/package/iubenda-consent-solution-api)

[![Test CI](https://github.com/rickypid/iubenda-consent-solution-api/actions/workflows/test.yml/badge.svg)](https://github.com/rickypid/iubenda-consent-solution-api/actions/workflows/test.yml)

[![codecov](https://codecov.io/gh/rickypid/iubenda-consent-solution-api/branch/main/graph/badge.svg?token=3100WHBX8W)](https://codecov.io/gh/rickypid/iubenda-consent-solution-api)

[![GitHub issues](https://img.shields.io/github/issues/rickypid/iubenda-consent-solution-api)](https://github.com/rickypid/iubenda-consent-solution-api/issues)

[![GitHub forks](https://img.shields.io/github/forks/rickypid/iubenda-consent-solution-api)](https://github.com/rickypid/iubenda-consent-solution-api/network)

[![GitHub stars](https://img.shields.io/github/stars/rickypid/iubenda-consent-solution-api)](https://github.com/rickypid/iubenda-consent-solution-api/star)

[![GitHub license](https://img.shields.io/github/license/rickypid/iubenda-consent-solution-api)](https://github.com/rickypid/iubenda-consent-solution-api/blob/main/LICENSE)

API client to implement Iubenda Consent Solution in backend service.

## Install

```bash

npm install iubenda-consent-solution-api

```

This library implements all methods described in Official

Iubenda [Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation).

## Usage

### Client initialization

To be initialized, the IubendaConsentSolution class requires a private API Key, which can be obtained from the dashboard

of your application on [Iubenda](https://www.iubenda.com/).

it is possible to specify whether to use the API in `BETA` mode by setting the optional

parameter `beta: true` [Official Guide](https://www.iubenda.com/en/help/18199-consent-solution-delivery-channels).

Also the "unescape_json" option is supported, you can enable it by setting the optional `unescape_json: true` parameter.

### Client options

| parameter       | required | default |

|-----------------|----------|---------|

| `apiKey`        | `true`   | `---`   |

| `beta`          | `false`  | `false` |

| `unescape_json` | `true`   | `false` |

#### Client options example

```ts

import {IubendaConsentSolution} from 'iubenda-consent-solution-api';

const options = {

  apiKey: 'YOUR-VALID-IUBENDA-API-KEY',

  beta: false,

  unescape_json: false,

};

const client = new IubendaConsentSolution(options);

```

#### Example basic

```ts

import {IubendaConsentSolution} from 'iubenda-consent-solution-api';

const validApiKey = 'YOUR-VALID-IUBENDA-API-KEY';

const client = new IubendaConsentSolution({apiKey: validApiKey});

```

### Request response error

if the request returns an error you will get an object like the following:

```ts

interface ResponseError {

  error: boolean;

  status: number;

  message: string;

}

```

This error is returned if the API server responds with an `HTTP status` >= 300

| field     | description                                  |

|-----------|----------------------------------------------|

| `error`   | always true                                  |

| `status`  | HTTP status (300, 401, ...)                  |

| `message` | Text message received from API HTTP response |

### Rate Limits

By default, you can perform a maximum of `50` requests per second and `108000` requests per hour. Server-side, the API

will respond with `429 Too Many Requests` if these limits are exceeded

### Max Request Size

There is a maximum of `1 MB` per call. Server-side, the API will respond with `413 Request Entity Too Large` if these

limits are exceeded.

### Consents

---

#### Get Consents

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#list-consents))

```ts

const result = await client.getConsents();

```

  Example response HTTP Status 200

```json

[

  {

    "id": "b04c4b2b-80b7-439f-8997-ade3d35cbb95",

    "timestamp": "2018-06-04T08:11:34.000+00:00",

    "owner": "521686",

    "source": "private",

    "subject": {

      "id": "0e371678-634a-4016-83ce-9b7c36f828e6",

      "email": "[email protected]",

      "first_name": "Kianna",

      "last_name": "Fahey",

      "full_name": "Kianna Fahey",

      "verified": false

    },

    "preferences": {

      "newsletter": false

    }

  },

  {

    "id": "ee6644ea-08e9-4aaa-a7a9-18602731a123",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "681109",

    "source": "public",

    "subject": {

      "id": "8c6d1b71-0908-4604-948f-2f706500b5b1",

      "email": "[email protected]",

      "first_name": "Eleanora",

      "last_name": "Adams",

      "full_name": "Eleanora Adams",

      "verified": false

    },

    "preferences": {

      "newsletter": true

    }

  },

  {

    "id": "e7a9f5db-481e-4c80-ac7d-a35e35d37f98",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "178473",

    "source": "private",

    "subject": {

      "id": "d084ab70-0460-4523-94b2-44841055b49c",

      "email": "[email protected]",

      "first_name": "Abbie",

      "last_name": "Heidenreich",

      "full_name": "Abbie Heidenreich",

      "verified": false

    },

    "preferences": {

      "third_party": true

    }

  },

  {

    "id": "e3481085-296c-4b11-a999-73d5d1309128",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "393753",

    "source": "private",

    "subject": {

      "id": "be8ca546-150d-4a6e-b2ac-ef76fb8a279e",

      "email": "[email protected]",

      "first_name": "Grace",

      "last_name": "Dooley",

      "full_name": "Grace Dooley",

      "verified": false

    },

    "preferences": {

      "another_preference_key": false,

      "newsletter": false

    }

  },

  {

    "id": "e1be0320-a854-4b01-a468-49b1752ee4f3",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "629879",

    "source": "public",

    "subject": {

      "id": "f8878254-c7ae-4169-b474-19e90d7b2f4f",

      "email": "[email protected]",

      "first_name": "Providenci",

      "last_name": "Kulas",

      "full_name": "Providenci Kulas",

      "verified": false

    },

    "preferences": {

      "newsletter": false,

      "random_preference_key": true,

      "third_party": true,

      "another_preference_key": false

    }

  },

  {

    "id": "cbe2bba8-d31d-4a27-9e2d-b38de4f22a68",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "989797",

    "source": "public",

    "subject": {

      "id": "6387dc5d-d474-4da8-8c40-8b197dee8d7c",

      "email": "[email protected]",

      "first_name": "Alan",

      "last_name": "Rutherford",

      "full_name": "Alan Rutherford",

      "verified": false

    },

    "preferences": {

      "newsletter": true,

      "random_preference_key": true

    }

  },

  {

    "id": "ca429c28-e1cd-4b95-87ae-48adb8fe56bb",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "885846",

    "source": "public",

    "subject": {

      "id": "b2ad578d-0aa9-4bd5-becd-e2e7a2019e7a",

      "email": "[email protected]",

      "first_name": "Ruby",

      "last_name": "Lemke",

      "full_name": "Ruby Lemke",

      "verified": false

    },

    "preferences": {

      "third_party": true,

      "random_preference_key": false

    }

  },

  {

    "id": "bf12770e-840a-40cd-ab79-5d88576b6b73",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "369168",

    "source": "public",

    "subject": {

      "id": "d4f24d92-56c2-4372-8696-fec829da5ccc",

      "email": "[email protected]",

      "first_name": "Hank",

      "last_name": "Klein",

      "full_name": "Hank Klein",

      "verified": false

    },

    "preferences": {

      "newsletter": false

    }

  },

  {

    "id": "b489e2d4-2fc6-44e1-ba54-e5f81000d30a",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "781022",

    "source": "public",

    "subject": {

      "id": "38bc623f-b386-4b66-8ee6-5e7d91c19800",

      "email": "[email protected]",

      "first_name": "Kamren",

      "last_name": "Pacocha",

      "full_name": "Kamren Pacocha",

      "verified": false

    },

    "preferences": {

      "newsletter": true

    }

  },

  {

    "id": "b2ec7aa8-35e7-470c-8b51-bd39fa686a3a",

    "timestamp": "2018-06-04T08:11:33.000+00:00",

    "owner": "527898",

    "source": "public",

    "subject": {

      "id": "0cc94c66-d9eb-4ace-af3d-1d48fba265f9",

      "email": "[email protected]",

      "first_name": "Maryjane",

      "last_name": "Wiegand",

      "full_name": "Maryjane Wiegand",

      "verified": false

    },

    "preferences": {

      "newsletter": true

    }

  }

]

```

---

#### Get Consent (With specific `ID`)

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#get-consent))

```ts

const id = 'consent-id'

const result = await client.getConsent(id);

```

  Example response HTTP Status 200

```json

{

  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",

  "timestamp": "2018-05-04T14:52:26Z",

  "checksum": "336dd0c5ee2253794b8cca6ee2b2fec835ab25a7097c4405014d02e4ffe4d5e5",

  "owner": "1",

  "subject": {

    "id": "custom_subject_id",

    "owner_id": "1",

    "email": "[email protected]",

    "first_name": "John",

    "last_name": "Doe",

    "verified": false

  },

  "preferences": {

    "privacy_policy": true,

    "newsletter": false

  },

  "legal_notices": [

    {

      "identifier": "privacy_policy",

      "version": 123

    },

    {

      "identifier": "term",

      "version": 123

    }

  ],

  "proofs": [

    {

      "content": "proof_1",

      "form": "proof_1 form"

    },

    {

      "content": "proof_2",

      "form": "proof_2 form"

    }

  ],

  "ip_address": null

}

```

---

#### Create Consent

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#create-consent))

```ts

const consent: ConsentExtended = {};//Set your fields

const result = await client.createConsent(consent);

```

  Example response HTTP Status 200

```json

{

  "id": "de801ca9-abec-45e2-8f7c-729822cfffad",

  "timestamp": "2018-05-04T14:52:26Z",

  "subject_id": "testsubject"

}

```

---

### Subjects

---

#### Get Subjects

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#list-subjects))

```ts

const result = await client.getSubjects();

```

  Example response HTTP Status 200

```json

[

  {

    "id": "d2a55da5-0777-4625-94bd-b69948703e71",

    "owner_id": "131132",

    "email": "[email protected]",

    "first_name": "Jorge",

    "last_name": "Rath",

    "full_name": "Jorge Rath",

    "preferences": null,

    "verified": true,

    "timestamp": "2018-09-12T16:22:21+00:00"

  },

  {

    "id": "b75c6d0c-550f-4f84-9e92-2f351d481220",

    "owner_id": "131132",

    "email": "[email protected]",

    "first_name": "Alfonso",

    "last_name": "Aufderhar",

    "full_name": "Alfonso Aufderhar",

    "preferences": null,

    "verified": true,

    "timestamp": "2018-09-12T16:22:21+00:00"

  },

  {

    "id": "a9c8c720-cb07-4a52-81c3-7cb7fb4f877e",

    "owner_id": "131132",

    "email": "[email protected]",

    "first_name": "Furman",

    "last_name": "Vandervort",

    "full_name": "Furman Vandervort",

    "preferences": null,

    "verified": true,

    "timestamp": "2018-09-12T16:22:21+00:00"

  },

  {

    "id": "6ccc2802-3bcb-49af-a4c5-14dc89ba94bc",

    "owner_id": "131132",

    "email": "[email protected]",

    "first_name": "Alvis",

    "last_name": "Rohan",

    "full_name": "Alvis Rohan",

    "preferences": null,

    "verified": true,

    "timestamp": "2018-09-12T16:22:21+00:00"

  },

  {

    "id": "5900f856-619e-42b0-92a5-b2ebd016ac01",

    "owner_id": "131132",

    "email": "[email protected]",

    "first_name": "Marlee",

    "last_name": "Brown",

    "full_name": "Marlee Brown",

    "preferences": null,

    "verified": true,

    "timestamp": "2018-09-12T16:22:21+00:00"

  }

]

```

---

#### Get Subject (With specific `ID`)

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#get-subjects))

```ts

const id = 'subject-id'

const result = await client.getSubject(id);

```

  Example response HTTP Status 200

```json

{

  "id": "testsubject",

  "owner_id": "1",

  "email": "[email protected]",

  "first_name": "John",

  "last_name": "Doe",

  "verified": false,

  "preferences": {

    "privacy_policy": {

      "value": true,

      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"

    },

    "newsletter": {

      "value": true,

      "consent_id": "de801ca9-abec-45e2-8f7c-729822cfffad"

    }

  }

}

```

---

#### Create Subject

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#create-subjects))

```ts

const subject: Subject = {};//Set your fields

const result = await client.createSubject(subject);

```

  Example response HTTP Status 200

```ts

//Empty response

```

  Example response BETA HTTP Status 200

```json

{

  "id": "testsubject",

  "email": "[email protected]",

  "first_name": "John",

  "last_name": "Doe",

  "full_name": "John Doe",

  "verified": false

}

```

---

#### Update Subject

Look

Iubenda ([Official Guide](https://www.iubenda.com/en/help/6484-consent-solution-http-api-documentation#update-subjects))

```ts

const id = 'subject-id'

const subject: Subject = {};//Set your fields

const result = await client.updateSubject(subject, id);

```

  Example response HTTP Status 200

```ts

//Empty response

```

  Example response BETA HTTP Status 200

```json

{

  "first_name": "Mary",

  "verified": true

}

```

---