PrivacyOps
Ops Docs

npm install @privacyops/sdk

import { PrivacyOps } from '@privacyops/sdk';

const privacy = new PrivacyOps({
  apiKey: process.env.PRIVACYOPS_API_KEY,
  region: 'me-riyadh-1',   // 'eu-west-1' | 'us-east-1' | 'ap-southeast-1'
  environment: 'production',
});

const status = await privacy.health.check();
console.log(status); // { ok: true, region: 'me-riyadh-1', latencyMs: 42 }

// All requests require a Bearer token
curl -X GET https://api.privacy-ops.io/v1/consent/user_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-PrivacyOps-Region: me-riyadh-1"

// Rotate your API key
curl -X POST https://api.privacy-ops.io/v1/auth/rotate-key \
  -H "Authorization: Bearer YOUR_API_KEY"

// Capture consent at the point of collection
await privacy.consent.capture({
  userId: 'user_abc123',
  purposes: ['analytics', 'marketing', 'personalization'],
  source: 'cookie-banner-v2',
  ipAddress: req.ip,
  userAgent: req.headers['user-agent'],
  legalBasis: 'consent',          // 'consent' | 'legitimate_interest' | 'contract'
  jurisdiction: 'SA',             // ISO 3166-1 alpha-2
  consentVersion: '2.1',
});

// Check before processing
const allowed = await privacy.consent.check({
  userId: 'user_abc123',
  purpose: 'analytics',
});
if (!allowed) return;

// Withdraw
await privacy.consent.withdraw({
  userId: 'user_abc123',
  purposes: ['marketing'],
  reason: 'user_request',
});

<!-- Drop-in consent banner (auto-detects jurisdiction) -->
<script src="https://cdn.privacy-ops.io/banner/v2/bundle.js"
  data-api-key="YOUR_API_KEY"
  data-theme="light"
  data-position="bottom"
  data-auto-block="true">
</script>

// Scan a domain for cookies and trackers
const scan = await privacy.cookies.scan({
  domain: 'www.company.com',
  depth: 'full',               // 'homepage' | 'full'
  includeSubdomains: true,
});

// scan.found: [
//   { name: '_ga',        category: 'analytics',   duration: '2 years',  thirdParty: true,  vendor: 'Google Analytics' },
//   { name: 'session_id', category: 'necessary',   duration: 'session',  thirdParty: false, vendor: 'internal' },
//   { name: 'fbp',        category: 'marketing',   duration: '3 months', thirdParty: true,  vendor: 'Meta Pixel' },
// ]

// Sync scan results to consent banner categories
await privacy.cookies.syncToBanner({
  scanId: scan.id,
  autoBlock: ['marketing', 'analytics'],   // block until consent given
});

// Submit a Data Subject Request
const request = await privacy.dsr.submit({
  type: 'access',          // 'access' | 'erasure' | 'rectification' | 'portability' | 'restriction' | 'objection'
  subjectEmail: '[email protected]',
  subjectName: 'Jane Smith',
  jurisdiction: 'SA',
  verificationMethod: 'email_otp',
  metadata: { requestChannel: 'web-portal' },
});

// Returns: { id: 'dsr_01HXY...', status: 'pending', deadline: '2026-07-13T...' }

// Fulfil a request (called from your internal workflow)
await privacy.dsr.fulfil({
  requestId: request.id,
  action: 'export',
  dataPackage: exportedUserData,   // Buffer | ReadableStream
  format: 'json',
});

// Webhook payload for new DSR
{
  "event": "dsr.received",
  "data": {
    "id": "dsr_01HXY9ABCDEF",
    "type": "erasure",
    "subjectEmail": "[email protected]",
    "jurisdiction": "SA",
    "deadline": "2026-07-13T00:00:00Z",
    "status": "pending"
  }
}

// Connect a data source and run a PII scan
const scan = await privacy.discovery.scan({
  source: {
    type: 'postgresql',
    connectionString: process.env.DB_URL,
  },
  options: {
    depth: 'full',
    classifiers: ['email', 'phone', 'national_id', 'credit_card', 'ip_address', 'dob'],
    schedule: 'weekly',
    sampleSize: 1000,
  },
});

const result = await privacy.discovery.getResult(scan.id);
// result.findings:
// [
//   { table: 'users',  column: 'email',         type: 'EMAIL',       count: 48203, risk: 'high' },
//   { table: 'orders', column: 'billing_phone',  type: 'PHONE',       count: 12891, risk: 'medium' },
//   { table: 'logs',   column: 'ip',             type: 'IP_ADDRESS',  count: 2100000, risk: 'low' },
// ]

// Create a Record of Processing Activity
const activity = await privacy.ropa.create({
  name: 'Customer Order Processing',
  purpose: 'Fulfil purchase orders and manage customer accounts',
  legalBasis: 'contract',
  dataCategories: ['contact', 'financial', 'transactional'],
  dataSubjects: ['customers'],
  retentionPeriod: { value: 7, unit: 'years' },
  processors: [
    { name: 'Stripe', role: 'payment_processor', country: 'US', safeguard: 'scc' },
    { name: 'AWS',    role: 'cloud_hosting',      country: 'SA', safeguard: 'adequacy' },
  ],
  crossBorderTransfers: true,
  transferMechanism: 'standard_contractual_clauses',
});

// Export full RoPA as PDF or Excel
const export_ = await privacy.ropa.export({ format: 'pdf', includeEvidence: true });

// Register a data flow between systems
await privacy.dataMap.addFlow({
  source: { system: 'CRM', field: 'email', category: 'contact' },
  destination: { system: 'Email Marketing Platform', field: 'email_address' },
  purpose: 'marketing',
  legalBasis: 'consent',
  transferType: 'internal',    // 'internal' | 'third_party' | 'cross_border'
  encrypted: true,
});

// Get a visual data map for a specific system
const map = await privacy.dataMap.getSystemMap('CRM');
// Returns nodes, edges, risk scores, and processing purposes

// Export as JSON or PDF for regulator submission
const export_ = await privacy.dataMap.export({ format: 'pdf', includeRiskScores: true });

// Define a retention policy for a data category
await privacy.retention.createPolicy({
  name: 'Customer Records — Financial',
  dataCategory: 'financial',
  retentionPeriod: { value: 7, unit: 'years' },
  legalBasis: 'legal_obligation',
  jurisdiction: 'SA',
  regulation: 'Saudi Companies Law Art. 68',
  deletionMethod: 'cryptographic_erasure',  // 'hard_delete' | 'anonymisation' | 'cryptographic_erasure'
  reviewCycle: 'annual',
});

// Trigger a deletion run for expired records
const run = await privacy.retention.runDeletion({
  dryRun: true,   // set false to execute
  categories: ['marketing_leads'],
  olderThan: '2024-01-01',
});
// run.scheduled: 4821 records
// run.exemptions: 12 records (active legal hold)

// Initiate a DPIA (Data Protection Impact Assessment)
const dpia = await privacy.dpia.create({
  projectName: 'AI-Powered Customer Scoring',
  description: 'Automated profiling of customers for credit risk',
  processingTypes: ['automated_decision_making', 'profiling', 'large_scale'],
  dataCategories: ['financial', 'behavioural'],
  riskLevel: 'high',
  assignedTo: '[email protected]',
});

// Add risk entries
await privacy.dpia.addRisk(dpia.id, {
  risk: 'Discriminatory profiling outcomes',
  likelihood: 'possible',
  severity: 'high',
  mitigation: 'Bias audits every quarter; human review for adverse decisions',
  residualRisk: 'low',
});

// Submit for DPO sign-off
await privacy.dpia.submit(dpia.id);

// Register webhook for breach events
await privacy.incidents.registerWebhook({
  url: 'https://your-app.com/webhooks/privacyops',
  events: ['breach.detected', 'breach.confirmed', 'breach.resolved'],
  secret: process.env.WEBHOOK_SECRET,
});

// Handle incoming event
app.post('/webhooks/privacyops', (req, res) => {
  const event = privacy.webhooks.verify(req.body, req.headers['x-privacyops-signature']);

  if (event.type === 'breach.confirmed') {
    const { severity, affectedRecords, dataTypes, notificationDeadline } = event.data;
    // notificationDeadline = 72h from detection (GDPR Art. 33)
    // Trigger your internal incident response runbook
  }
  res.status(200).json({ received: true });
});

// Manually log an incident
const incident = await privacy.incidents.create({
  type: 'unauthorised_access',
  severity: 'high',
  affectedRecords: 1200,
  dataTypes: ['email', 'hashed_password'],
  discoveredAt: new Date().toISOString(),
  containmentActions: ['Revoked compromised tokens', 'Forced password reset'],
});

// Register a third-party vendor
const vendor = await privacy.vendors.create({
  name: 'Salesforce',
  category: 'crm',
  dataShared: ['contact', 'transactional'],
  country: 'US',
  dpaExecuted: true,
  dpaUrl: 'https://internal.company.com/dpa/salesforce.pdf',
  reviewCycle: 'annual',
  contactEmail: '[email protected]',
});

// Run a vendor risk assessment
const assessment = await privacy.vendors.assess(vendor.id, {
  questionnaire: 'standard_v3',
  dueDate: '2026-09-01',
});

// List vendors due for review
const due = await privacy.vendors.listDueForReview({ withinDays: 30 });

// Flag a user as a minor and apply enhanced protections
await privacy.subjects.setAgeGroup({
  userId: 'user_xyz',
  ageGroup: 'minor',           // 'minor' | 'adult'
  verificationMethod: 'parental_consent_form',
  parentEmail: '[email protected]',
});

// Consent capture for minors requires parental approval
await privacy.consent.captureParental({
  childUserId: 'user_xyz',
  parentUserId: 'parent_abc',
  purposes: ['service_delivery'],
  verifiedAt: new Date().toISOString(),
});

// Automatically restrict data processing for minors
const profile = await privacy.subjects.getProfile('user_xyz');
// profile.restrictions: ['no_profiling', 'no_marketing', 'no_cross_context_sharing']

// Register a cross-border transfer
const transfer = await privacy.transfers.create({
  fromJurisdiction: 'SA',
  toJurisdiction: 'US',
  recipient: 'AWS Inc.',
  dataCategories: ['contact', 'transactional'],
  transferMechanism: 'standard_contractual_clauses',
  sccVersion: '2021/914/EU',
  tiaCompleted: true,           // Transfer Impact Assessment
  approvedBy: '[email protected]',
  approvedAt: new Date().toISOString(),
});

// Check if a transfer is permitted under current rules
const check = await privacy.transfers.check({
  fromJurisdiction: 'SA',
  toJurisdiction: 'CN',
  dataCategories: ['health'],
});
// check.permitted: false
// check.reason: 'No adequacy decision; SCCs insufficient for health data under PDPL Art. 29'

// Attach a Privacy by Design checklist to a project
const project = await privacy.pbd.createProject({
  name: 'New Mobile App — v3.0',
  owner: '[email protected]',
  launchDate: '2026-10-01',
});

await privacy.pbd.checkItem(project.id, {
  principle: 'data_minimisation',
  status: 'compliant',
  evidence: 'Only email and phone collected; no DOB required',
  reviewedBy: '[email protected]',
});

// Generate a Privacy by Design sign-off report
const report = await privacy.pbd.generateReport(project.id, { format: 'pdf' });

// Create a DPO task
const task = await privacy.dpo.createTask({
  title: 'Review DPIA for AI Scoring Project',
  type: 'dpia_review',
  priority: 'high',
  dueDate: '2026-07-01',
  assignedTo: '[email protected]',
  linkedRecordType: 'dpia',
  linkedRecordId: 'dpia_01HXY...',
});

// Get DPO workload summary
const workload = await privacy.dpo.getWorkload('[email protected]');
// workload.openTasks: 14
// workload.overdueItems: 2
// workload.upcomingDeadlines: [{ type: 'dsr', deadline: '2026-06-20', count: 3 }]

// Log a DPO consultation
await privacy.dpo.logConsultation({
  topic: 'New HR analytics system',
  outcome: 'DPIA required before go-live',
  participants: ['[email protected]', '[email protected]'],
  date: new Date().toISOString(),
});

// Query the immutable audit log
const logs = await privacy.audit.query({
  from: '2026-01-01T00:00:00Z',
  to:   '2026-06-30T23:59:59Z',
  eventTypes: ['consent.captured', 'dsr.fulfilled', 'data.accessed'],
  userId: 'user_abc123',       // optional — filter by subject
  actorId: 'admin_xyz',        // optional — filter by operator
  limit: 100,
  cursor: undefined,           // pagination
});

// Export audit log for regulator submission
const export_ = await privacy.audit.export({
  format: 'csv',
  period: { from: '2026-01-01', to: '2026-06-30' },
  signed: true,   // cryptographically signed export
});

// Set up a real-time compliance health check
const monitor = await privacy.compliance.createMonitor({
  name: 'PDPL Baseline Monitor',
  framework: 'pdpl',
  checks: [
    'consent_coverage',
    'dsr_response_time',
    'ropa_completeness',
    'vendor_dpa_coverage',
    'breach_notification_readiness',
  ],
  alertThreshold: 'medium',    // 'low' | 'medium' | 'high' | 'critical'
  notifyEmail: '[email protected]',
  schedule: 'daily',
});

// Get current compliance score
const score = await privacy.compliance.getScore({ framework: 'pdpl' });
// score.overall: 87
// score.breakdown: { consent: 94, dsr: 82, ropa: 91, vendors: 78, breach: 90 }

// Subscribe to regulatory updates for your jurisdictions
await privacy.regulatory.subscribe({
  jurisdictions: ['SA', 'EU', 'US-CA', 'BH', 'QA'],
  categories: ['new_regulation', 'amendment', 'enforcement_action', 'guidance'],
  notifyEmail: '[email protected]',
  webhookUrl: 'https://your-app.com/webhooks/regulatory',
});

// Get latest updates
const updates = await privacy.regulatory.getUpdates({
  jurisdiction: 'SA',
  since: '2026-01-01',
  limit: 20,
});
// updates[0]: {
//   title: 'SDAIA issues updated PDPL implementing regulations',
//   jurisdiction: 'SA',
//   effectiveDate: '2026-03-01',
//   impact: 'high',
//   affectedModules: ['consent', 'cross_border_transfers'],
// }

// Assign a training module to a user
await privacy.training.assign({
  userId: 'emp_456',
  moduleId: 'pdpl-fundamentals-v2',
  dueDate: '2026-07-31',
  mandatory: true,
});

// Bulk assign to a department
await privacy.training.bulkAssign({
  department: 'engineering',
  moduleIds: ['privacy-by-design-101', 'data-handling-secure'],
  dueDate: '2026-08-31',
});

// Get training completion report
const report = await privacy.training.getComplianceReport({
  department: 'all',
  period: { from: '2026-01-01', to: '2026-06-30' },
});
// report.completionRate: 84%
// report.overdueCount: 23

import crypto from 'crypto';

function verifyWebhook(payload: Buffer, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

app.post('/webhooks/privacyops', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-privacyops-signature'] as string;
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const event = JSON.parse(req.body.toString());
  // handle event...
  res.json({ received: true });
});

// Generate a compliance report
const report = await privacy.compliance.generateReport({
  framework: 'pdpl',           // 'gdpr' | 'pdpl' | 'ccpa' | 'hipaa' | 'nca'
  period: { from: '2026-01-01', to: '2026-06-30' },
  format: 'pdf',
  includeEvidence: true,
  sections: ['consent', 'dsr', 'ropa', 'incidents', 'vendors'],
});

const url = await privacy.compliance.getDownloadUrl(report.id);
// Signed URL valid for 24 hours