Node.js client

npm install https://console.dpconsent.com/consent/sdk/v1/packages/piedap-consent-1.0.7.tgz

import { ConsentClient } from '@piedap/consent/server';
// or
const { ConsentClient } = require('@piedap/consent/server');

import { ConsentClient } from '@piedap/consent/server';

export const client = new ConsentClient({
  apiUrl: 'https://console.dpconsent.com/consent',
  secretKey: process.env.PIEDAP_SECRET_KEY,
});

const { form } = await client.resolveForm({
  formKey: 'kalpa-account',
  country: 'IN',
});
const keys = form.purposes.filter((p) => !p.alwaysOn).map((p) => p.key);

const record = await client.recordConsent({
  formKey: 'kalpa-account',
  subjectId: 'usr_8f2K1xQz',
  subjectType: 'USER_ID',
  countryCode: 'IN',
  interaction: 'SAVE_PREFERENCES',
  decisions: [
    { purposeKey: 'course-updates-by-email', granted: true },
    { purposeKey: 'class-reminders-by-sms', granted: false },
  ],
  identifiers: [
    { subjectType: 'EMAIL', subjectId: 'kavya.menon@example.in' },
  ],
  idempotencyKey: 'signup-usr_8f2K1xQz',
});

const record = await client.getConsent('cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8');
const mayEmail = record?.decisions.some(
  (d) => d.purposeKey === 'course-updates-by-email' && d.granted,
);

await client.updateConsent(
  'cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8',
  [{ purposeKey: 'class-reminders-by-sms', granted: true }],
  { interaction: 'PREFERENCE_CENTRE' },
);

await client.withdrawConsent(
  'cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8',
  'Asked by phone',
);

const signed = await client.receipt('cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8');
console.log(signed.receipt.proof.verification.valid);

const keys = await client.publicKeys();

const pending = await client.startEmailConsent({
  email: 'rohan.das@example.in',
  formKey: 'newsletter',
  decisions: [{ purposeKey: 'newsletter', granted: true }],
  returnUrl: 'https://www.example.in/subscribed',
});

await client.recordActivity('usr_8f2K1xQz', 'USER_ID');

const { url } = await client.consentPortalLink('usr_8f2K1xQz', 'USER_ID');

const { url, headers } = await client.unsubscribeLink(record.consentId);

const { records } = await client.findSubject('+919846011223', 'PHONE');

const pack = await client.exportSubject('usr_8f2K1xQz', 'USER_ID');

await client.withdrawSubject('usr_8f2K1xQz', 'USER_ID', {
  reason: 'Account closed',
  idempotencyKey: 'close-usr_8f2K1xQz',
});

await client.eraseSubject('usr_8f2K1xQz', 'USER_ID', {
  reason: 'Erasure requested by the learner',
  idempotencyKey: 'erase-usr_8f2K1xQz',
});

await client.linkIdentifiers('usr_8f2K1xQz', 'USER_ID', [
  { subjectType: 'PHONE', subjectId: '+919846099887' },
]);

await client.linkRequest('DSR-2026-4F2A91', 'usr_8f2K1xQz', 'USER_ID');

const check = await client.checkConsent({
  subjectId: 'CIF00412873',
  subjectType: 'USER_ID',
  alsoKnownAs: [{ subjectType: 'PHONE', subjectId: '+919846011223' }],
  purposeKey: 'offers-by-sms',
});
if (check.allowed) await sendOffer(check.basedOn[0].consentId);

type SubjectType =
  | 'COOKIE_ID' | 'SESSION_ID' | 'EMAIL'
  | 'USER_ID' | 'PHONE' | 'DEVICE_ID';

interface DecisionInput {
  purposeKey: string;
  granted: boolean;
  partners?: Record<string, boolean>; // a partner left out follows granted
}

interface LinkedIdentifier {
  subjectType: SubjectType;
  subjectId: string;
  proof?: string; // only for writes from a browser
}

interface Guardian {
  relationship: 'PARENT' | 'LAWFUL_GUARDIAN';
  verification:
    | 'EXISTING_ACCOUNT' | 'VIRTUAL_TOKEN'
    | 'IDENTITY_DOCUMENT' | 'GUARDIANSHIP_ORDER';
  reference: string;
}

interface ConsentRecord {
  consentId: string;
  status:
    | 'GRANTED' | 'PARTIAL' | 'DENIED'
    | 'WITHDRAWN' | 'EXPIRED' | 'PENDING';
  formId: string;
  formVersion: number;
  formContentHash: string;
  decisions: {
    purposeKey: string;
    purposeName: string;
    category: string;
    granted: boolean;
    partners?: Record<string, boolean>;
  }[];
  test: boolean; // written with a test key
  countryCode: string | null;
  subdivisionCode: string | null;
  lawCode: string | null;
  collectedOn: string;
  expiresOn: string | null;
  withdrawnOn: string | null;
  proofHash: string;
}

interface SubjectRecords {
  subjectType: SubjectType;
  fingerprint: string;
  records: (ConsentRecord & {
    erasedOn: string | null;
    matchedBy: SubjectType[];
  })[];
}

interface AccessPackage {
  subjectType: SubjectType;
  generatedOn: string;
  summary: Record<string, any>;
  contact: Record<string, any>;
  receipts: SignedReceipt[];
}

interface SignedReceipt {
  receipt: Record<string, any>;
  signature: string;
  algorithm: 'Ed25519' | 'HMAC-SHA256';
  keyId?: string;
  publicKeysUrl?: string;
}

interface Jwk { kid: string; kty: string; crv: string; x: string }

type CaptureChannel =
  | 'BRANCH' | 'CALL_CENTRE' | 'IVR'
  | 'KIOSK' | 'FIELD_AGENT' | 'PAPER';
type CaptureMethod =
  | 'OTP' | 'SIGNED_DECLARATION' | 'RECORDED_CALL'
  | 'PAPER_FORM' | 'LINK_CONFIRMED' | 'AGENT_ATTESTED';

interface CaptureInput {
  channel: CaptureChannel;
  method: CaptureMethod;
  agentRef?: string; // stored only as a keyed hash
  locationRef?: string; // stored only as a keyed hash
  methodReference?: string; // never personal data
  documentSha256?: string;
}

interface CaptureContext {
  channel: CaptureChannel;
  method: CaptureMethod;
  agentRefHash?: string;
  locationRefHash?: string;
  methodReference?: string;
  documentSha256?: string;
  attestedByStaffOnly: boolean;
}

// ConsentRecord also has, when set:
//   basis?: 'PRE_COMMENCEMENT';
//   noticeReference?: string;
//   noticeSha256?: string;
//   captureContext?: CaptureContext; // secret-key responses only

type ConsentCheckReason =
  | 'granted' | 'refused' | 'withdrawn' | 'expired'
  | 'pending_confirmation' | 'erased' | 'no_record'
  | 'not_consent_based';

interface ConsentCheckBasis {
  consentId: string | null;
  proofHash: string | null;
  state:
    | 'granted' | 'refused' | 'withdrawn'
    | 'expired' | 'erased' | 'pending_confirmation';
  decidedAt: string | null;
  matchedBy: SubjectType[];
  attestedByStaffOnly: boolean;
}

interface ConsentCheck {
  unavailable: false;
  allowed: boolean;
  reason: ConsentCheckReason;
  recorded: Exclude<ConsentCheckReason, 'not_consent_based'>;
  purpose: {
    key: string;
    category: string;
    declaredBasis: string;
    legitimateUse: string | null;
    consentRequired: boolean;
  };
  partnerKey: string | null;
  validUntil: string | null;
  basedOn: ConsentCheckBasis[];
  notes: (
    | 'PARTNER_NOT_OFFERED' | 'PHONE_NOT_E164'
    | 'ATTESTED_BY_STAFF_ONLY' | 'WITHDRAWAL_IN_PROGRESS'
  )[];
  checkedAt: string;
  test: boolean;
}

interface ConsentCheckUnavailable {
  unavailable: true;
  allowed: false;
  reason: 'unavailable';
  cause: 'timeout' | 'network' | 'rate_limited' | 'server_error';
  status: number | null;
  retryAfter: number | null;
}

type ConsentCheckResult = ConsentCheck | ConsentCheckUnavailable;

import { ConsentApiError } from '@piedap/consent/server';

try {
  await client.eraseSubject(user.id, 'USER_ID');
} catch (error) {
  if (!(error instanceof ConsentApiError)) throw error;
  if (error.status === 429) {
    await retryLater(error.retryAfter ?? 60);
  } else if (error.code === 'SCOPE_REQUIRED') {
    // grant subjects:erase to the key in the console
  } else {
    throw error;
  }
}