dpdpguard-server-node-sdk

DPDP Guard Server SDK (Node/TypeScript) — typed API client, consent gate, token broker helper, and webhook signature verifier over DPDP Guard's public /api/v1 (spec §4.2).

Package: @dpdpguard/server

Part of the DPDP Guard SDK family. See the design spec: https://github.com/dpdp-guard-ai/dpdpbot/blob/main/docs/specs/mobile-server-sdk.md

Install

npm install @dpdpguard/server

Usage

import { DpdpGuardClient, hasConsent, verifyWebhookSignature } from "@dpdpguard/server";

const client = new DpdpGuardClient({
  baseUrl: "https://<your-deployment>.convex.site",
  apiKey: process.env.DPDP_SERVICE_API_KEY, // convex/apiKeys.ts, for broker-token only
});

// Mint a brokered principal access token (ADR-004 D1/D2) for a known user.
await client.brokerToken(externalId);

// Now authenticated calls use that token automatically.
const { requests } = await client.listDsrRequests();
await client.createDsrRequest({ organizationId, type: "erasure" });

// Public reads need no auth at all.
const org = await client.getOrganization("acme");
const { notices } = await client.getNotices(org.orgId);

// Verify an inbound webhook (convex/webhooks.ts's X-DPDP-Signature header).
const ok = verifyWebhookSignature(webhookSecret, rawBody, req.headers["x-dpdp-signature"]);

Every non-2xx response throws a DpdpGuardApiError with a code from the ADR-002 error catalog (err.code, e.g. "NOT_FOUND") and the HTTP status.

Contract

This package depends on @dpdpguard/contract as the single source of truth for the wire shape (ADR-001/002):

• src/generated/api-types.ts is regenerated from the installed contract's openapi/v1.yaml via openapi-typescript (npm run codegen, also run automatically on npm install via postinstall and before npm run build). It's gitignored — never hand-edited, always regenerated.
• src/errorCatalog.ts loads @dpdpguard/contract/conformance/error-catalog.json at runtime (ADR-002 D2) rather than hand-copying the error codes.
• src/auditHash.test.ts runs @dpdpguard/contract/conformance/audit-hash-vectors.json as a required CI gate (ADR-002 D5) — a failure means this SDK's auditHash.ts has drifted from convex/lib/auditHash.ts.

Bumping the @dpdpguard/contract dependency and re-running npm run codegen is how this SDK picks up a new contract version; there is no separate manual sync step.

Scripts

| Script | Purpose | | --- | --- | | npm run codegen | Regenerate src/generated/api-types.ts from the installed contract | | npm test | Run the unit tests, including the golden-vector conformance gate | | npm run build | Codegen + tsc to dist/ |