@molecule/api-compliance

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Compliance core interface for molecule.dev.

Provides the ComplianceProvider interface for GDPR and data compliance operations including user data export, deletion, consent management, and data processing logs. Bond a concrete provider (e.g. @molecule/api-compliance-gdpr) at startup via setProvider().

Quick Start

import {
  setProvider,
  exportUserData,
  deleteUserData,
  getConsent,
  setConsent,
} from '@molecule/api-compliance'
import { provider } from '@molecule/api-compliance-gdpr'

// Wire the provider at startup
setProvider(provider)

// Export user data for a data portability request
const exportData = await exportUserData('user-123', 'json')

// Handle a deletion request (right to erasure)
const result = await deleteUserData('user-123', { retainLegalObligations: true })

// Manage user consent
await setConsent('user-123', { purpose: 'marketing', granted: false })
const consent = await getConsent('user-123')

Type

core

Installation

npm install @molecule/api-compliance @molecule/api-bond @molecule/api-i18n

API

Interfaces

ComplianceConfig

Configuration options for a compliance provider.

interface ComplianceConfig {
  /** Data retention period in days. */
  retentionDays?: number

  /** Whether to automatically purge expired data. */
  autoPurge?: boolean

  /** Data categories managed by this provider. */
  categories?: DataCategory[]
}

ComplianceProvider

Compliance provider interface.

All compliance providers must implement this interface to provide data export, deletion, consent management, and processing log capabilities required by data protection regulations.

interface ComplianceProvider {
  /**
   * Exports all data associated with a user in a portable format.
   *
   * @param userId - The identifier of the user whose data to export.
   * @param format - The export format (defaults to 'json').
   * @returns The exported user data package.
   */
  exportUserData(userId: string, format?: ExportFormat): Promise<UserDataExport>

  /**
   * Deletes user data according to the specified options. May retain
   * certain categories if required by legal obligations.
   *
   * @param userId - The identifier of the user whose data to delete.
   * @param options - Optional deletion parameters.
   * @returns The result of the deletion request.
   */
  deleteUserData(userId: string, options?: DeletionOptions): Promise<DeletionResult>

  /**
   * Retrieves the current consent record for a user.
   *
   * @param userId - The identifier of the user.
   * @returns The user's consent record.
   */
  getConsent(userId: string): Promise<ConsentRecord>

  /**
   * Updates consent for a specific data processing purpose.
   *
   * @param userId - The identifier of the user.
   * @param consent - The consent update to apply.
   */
  setConsent(userId: string, consent: ConsentUpdate): Promise<void>

  /**
   * Retrieves the data processing log for a user, showing all
   * recorded processing activities on their data.
   *
   * @param userId - The identifier of the user.
   * @returns Array of processing log entries.
   */
  getDataProcessingLog(userId: string): Promise<ProcessingLogEntry[]>
}

ConsentEntry

A single consent entry for a specific data processing purpose.

interface ConsentEntry {
  /** The purpose or category of data processing. */
  purpose: string

  /** Whether consent has been granted. */
  granted: boolean

  /** When consent was last updated. */
  updatedAt: Date

  /** Legal basis for processing. */
  legalBasis?: LegalBasis
}

ConsentRecord

Full consent record for a user.

interface ConsentRecord {
  /** The user this consent record belongs to. */
  userId: string

  /** Individual consent entries by purpose. */
  consents: ConsentEntry[]

  /** When the consent record was last modified. */
  updatedAt: Date
}

ConsentUpdate

Update payload for modifying user consent.

interface ConsentUpdate {
  /** The purpose or category of data processing. */
  purpose: string

  /** Whether consent is being granted or revoked. */
  granted: boolean

  /** Legal basis for processing. */
  legalBasis?: LegalBasis
}

DeletionOptions

Options for user data deletion requests.

interface DeletionOptions {
  /** Specific data categories to delete (defaults to all). */
  categories?: DataCategory[]

  /** Whether to retain data required by legal obligations. */
  retainLegalObligations?: boolean

  /** Reason for the deletion request. */
  reason?: string
}

DeletionResult

Result of a data deletion request.

interface DeletionResult {
  /** The user whose data was deleted. */
  userId: string

  /** Current status of the deletion. */
  status: DeletionStatus

  /** Categories that were deleted. */
  deletedCategories: DataCategory[]

  /** Categories that were retained (e.g., for legal reasons). */
  retainedCategories: DataCategory[]

  /** Timestamp when the deletion was requested. */
  requestedAt: Date

  /** Timestamp when the deletion was completed (if applicable). */
  completedAt?: Date
}

ProcessingLogEntry

A log entry recording a data processing activity.

interface ProcessingLogEntry {
  /** Unique identifier for the log entry. */
  id: string

  /** The user whose data was processed. */
  userId: string

  /** Description of the processing activity. */
  activity: string

  /** Data category that was processed. */
  category: DataCategory

  /** Legal basis for the processing. */
  legalBasis: LegalBasis

  /** Who or what performed the processing. */
  processor: string

  /** When the processing occurred. */
  timestamp: Date

  /** Additional details about the processing. */
  details?: Record<string, unknown>
}

UserDataExport

Exported user data package.

interface UserDataExport {
  /** The user whose data was exported. */
  userId: string

  /** Timestamp when the export was generated. */
  exportedAt: Date

  /** Format of the exported data. */
  format: ExportFormat

  /** Exported data organized by category. */
  data: Record<string, unknown>

  /** Categories included in the export. */
  categories: DataCategory[]
}

Types

DataCategory

Categories of user data that can be managed for compliance purposes.

type DataCategory =
  | 'profile'
  | 'activity'
  | 'preferences'
  | 'communications'
  | 'billing'
  | 'analytics'
  | 'content'
  | 'authentication'

DeletionStatus

Status of a data deletion request.

type DeletionStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'partial'

ExportFormat

Supported data export formats.

type ExportFormat = 'json' | 'csv'

LegalBasis

Legal bases for data processing under regulations like GDPR.

type LegalBasis =
  | 'consent'
  | 'contract'
  | 'legal_obligation'
  | 'vital_interests'
  | 'public_task'
  | 'legitimate_interests'

Functions

deleteUserData(userId, options)

Deletes user data using the bonded provider.

function deleteUserData(userId: string, options?: DeletionOptions): Promise<DeletionResult>

• userId — The identifier of the user whose data to delete.
• options — Optional deletion parameters.

Returns: The result of the deletion request.

exportUserData(userId, format)

Exports all data associated with a user using the bonded provider.

function exportUserData(userId: string, format?: ExportFormat): Promise<UserDataExport>

• userId — The identifier of the user whose data to export.
• format — The export format (defaults to 'json').

Returns: The exported user data package.

getConsent(userId)

Retrieves the current consent record for a user using the bonded provider.

function getConsent(userId: string): Promise<ConsentRecord>

• userId — The identifier of the user.

Returns: The user's consent record.

getDataProcessingLog(userId)

Retrieves the data processing log for a user using the bonded provider.

function getDataProcessingLog(userId: string): Promise<ProcessingLogEntry[]>

• userId — The identifier of the user.

Returns: Array of processing log entries.

getProvider()

Retrieves the bonded compliance provider, throwing if none is configured.

function getProvider(): ComplianceProvider

Returns: The bonded compliance provider.

hasProvider()

Checks whether a compliance provider is currently bonded.

function hasProvider(): boolean

Returns: true if a compliance provider is bonded.

setConsent(userId, consent)

Updates consent for a specific data processing purpose using the bonded provider.

function setConsent(userId: string, consent: ConsentUpdate): Promise<void>

• userId — The identifier of the user.
• consent — The consent update to apply.

Returns: Resolves when the bonded provider applies the update.

setProvider(provider)

Registers a compliance provider as the active singleton. Called by bond packages during application startup.

function setProvider(provider: ComplianceProvider): void

• provider — The compliance provider implementation to bond.

Available Providers

| Provider | Package | | ---------- | ------------------------------- | | Compliance | @molecule/api-compliance-gdpr |

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1
• @molecule/api-i18n ^1.0.1

Runtime Dependencies

• @molecule/api-bond
• @molecule/api-i18n

Compliance endpoints are attack surface — the rules a generator gets wrong:

• Act on the AUTHENTICATED user's id, never a client-supplied one. An endpoint that exports or deletes data for whatever userId the request names lets any user exfiltrate or erase another user's data. Derive the id from the session; an admin-facing variant needs an explicit admin authorizer.
• Deletion is destructive — gate it. Require an explicit confirmation step in the UI (there is no undo), check DeletionResult.status ('partial' and 'failed' are real outcomes), and surface retained categories (retainLegalObligations) instead of claiming everything was deleted.
• Enforce consent SERVER-SIDE. Before running consent-scoped processing (marketing sends, analytics), check getConsent() in the handler/job that does the processing — a client-side flag is not consent enforcement.
• Wire the provider once at startup (setProvider(provider) in the app's bond setup); every convenience function throws until then.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

• [ ] A logged-in user can export their own data from the UI and the export contains their data — and only theirs.
• [ ] Requesting an export or deletion for a DIFFERENT user's id (e.g. by editing the request) is rejected server-side — not merely hidden in the UI.
• [ ] The deletion flow requires an explicit confirmation, completes, and the user's content is gone after a full reload; any retained categories are stated in the UI.
• [ ] Toggling a consent purpose off persists (survives reload) and the consent-scoped behavior actually stops.