@consent.software/interfaces

# @consent.software/interfaces
the interfaces for consent.software

## Install

To install the @consent.software/interfaces package, you can use npm. Make sure you have Node.js installed on your machine, as npm comes bundled with Node.js installations. Use the following command to install the package:

```bash
npm install @consent.software/interfaces

This command will download and install the module into your node_modules directory along with any necessary dependencies.

Usage

The @consent.software/interfaces package provides an organized structure for handling consent-related operations, specifically tailored for consent.software. It leverages the typedrequest-interfaces for seamless request handling. Below are some scenarios demonstrating the usage of this module utilizing TypeScript and adhering to ESM syntax.

Import Interfaces and Modules

To get started, import the necessary interfaces and modules. This package adopts a modular pattern, making it straightforward to import only what you need:

import { IRequest_Client_ConsentSoftwareServer_GetDomainSettings } from '@consent.software/interfaces';
import { IConsentTuple, TCookieLevel } from '@consent.software/interfaces';

Define Consent Tuples

A ConsentTuple represents a consent configuration that can be executed based on specified levels of user consent. This is particularly useful for defining scripts or snippets that should execute conditionally:

const consentTuples: IConsentTuple[] = [
  {
    name: 'Google Analytics',
    description: 'Tracks page views for analytics purposes',
    level: 'analytics',
    script: async (dataArg, consentLevels) => {
      if (consentLevels.includes('analytics')) {
        // Google Analytics script execution logic
        console.log(`Running Google Analytics script with dataArg:`, dataArg);
      }
    },
    scriptExecutionDataArg: { userId: '12345' }
  },
  {
    name: 'Ad Tracking',
    description: 'Tracks ad views for marketing purposes',
    level: 'marketing',
    script: `
      // Marketing script here
      console.log('Running marketing script');
    `
  }
];

Handling Domain Settings Request

The IRequest_Client_ConsentSoftwareServer_GetDomainSettings interface can be used to define the structure for requesting domain settings, including consent tuples, from a server.

Here's an example:

const domainSettingsRequest: IRequest_Client_ConsentSoftwareServer_GetDomainSettings = {
  method: 'getDomainSettings',
  request: {
    domain: 'example.com'
  },
  response: {
    domain: 'example.com',
    consentTuples: consentTuples
  }
};

// Simulating a server response
console.log(`Domain: ${domainSettingsRequest.response.domain}`);
domainSettingsRequest.response.consentTuples.forEach(tuple => {
  console.log(`Consent Tuple Name: ${tuple.name}`);
  console.log(`Description: ${tuple.description}`);
  if (typeof tuple.script === 'string') {
    console.log(`Script: ${tuple.script}`);
  } else {
    console.log('Script is a function.');
  }
});

Managing Domain and Web Client Settings

You may also define DomainSettings and WebclientSettings to manage consent data both server-side and client-side.

DomainSettings Example

const domainSettings: IDomainSettings = {
  id: 'domain-123',
  domainName: 'example.com',
  googleAnalyticsUniversalId: 'UA-XXXXX-Y',
  googleAnalytics4Id: 'G-XXXXX-Z',
  fullStoryId: 'FS-XXXXX-A',
  customTuples: consentTuples
};

console.log(`Domain Settings for ${domainSettings.domainName}:`);
console.log(`GA Universal ID: ${domainSettings.googleAnalyticsUniversalId}`);
console.log(`GA4 ID: ${domainSettings.googleAnalytics4Id}`);
console.log(`FullStory ID: ${domainSettings.fullStoryId}`);

WebclientSettings Example

The WebclientSettings allow storage of client-side consent levels and acceptance timestamps.

const webClientSettings: IWebclientSettings = {
  acceptanceTimestamp: Date.now(),
  acceptedCookieLevels: ['functional', 'analytics']
};

console.log(`Client Settings Accepted at: ${new Date(webClientSettings.acceptanceTimestamp).toISOString()}`);
console.log(`Accepted Levels: ${webClientSettings.acceptedCookieLevels.join(', ')}`);

Integrating with Backend Systems

To integrate these interfaces with a backend system, you might define service functions that handle requests adhering to these interfaces, ensuring type-safe operations and clear contract definitions.

For instance, a function to fetch domain settings:

async function fetchDomainSettings(domainName: string): Promise<IDomainSettings> {
  // Simulate fetching from API or database
  return {
    id: 'domain-123',
    domainName: domainName,
    googleAnalyticsUniversalId: '',
    googleAnalytics4Id: '',
    fullStoryId: '',
    customTuples: consentTuples
  };
}

(async () => {
  const domainName = 'example.com';
  const settings = await fetchDomainSettings(domainName);
  console.log(`Fetched settings for domain: ${settings.domainName}`);
})();

Extending Interface Usage

The usage scenarios above demonstrate the base capabilities of the @consent.software/interfaces module. However, extending its functionality to encompass more advanced use cases, such as real-time data stream integrations, microfrontend consent management, or detailed user profiling based on consent choices expands its versatility.

Consider the potential for additional interfaces to handle:

• Real-time consent changes and their immediate application across services.
• Synchronization of consent preferences among several client applications.
• Advanced analytics on consent behaviors to fine-tune user experience strategies.

In summary, the @consent.software/interfaces module exposes a rich suite of tools for managing consent-related integrations in a structured, type-safe manner and is robust to accommodate complex use cases beyond the basic examples provided herein.

undefined