dpdpstack-js-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,539 @@
+/**
+ * Request/response shapes for the DPDPStack HTTP API.
+ *
+ * The SDK mirrors the wire format (snake_case) exactly, so these types double as
+ * documentation and line up 1:1 with the curl examples in the docs. Free-form
+ * maps (`metadata`, `payload`, `translations`) are intentionally `Record<…>`.
+ */
+/** ISO-8601 timestamp string, or null when not yet set. */
+type Timestamp = string;
+type Nullable<T> = T | null;
+interface LocalizedNotice {
+    name?: string;
+    description?: string;
+}
+interface Purpose {
+    code: string;
+    name: string;
+    description: string;
+    /** Per-locale notice overrides, e.g. `{ hi: { name, description } }`. */
+    translations: Record<string, LocalizedNotice>;
+    active: boolean;
+}
+interface PurposeInput {
+    code: string;
+    name: string;
+    description?: string;
+    translations?: Record<string, LocalizedNotice>;
+    active?: boolean;
+}
+interface ConsentGrantInput {
+    /** Your opaque user id (an internal id or hash) — never PII. */
+    principal_ref: string;
+    /** Purpose `code` to record consent for. */
+    purpose: string;
+    locale?: string;
+    /** Arbitrary metadata stored on the audit receipt (kept verbatim). */
+    metadata?: Record<string, unknown>;
+}
+interface ConsentReceipt {
+    /** Hash of the immutable audit entry — the consent receipt id. */
+    receipt_id: string;
+    audit_sequence: number;
+    principal_ref: string;
+    purpose: string;
+    status: string;
+    granted_at: Nullable<Timestamp>;
+    /** The exact notice text shown to the principal, in the chosen locale. */
+    notice_shown: Required<LocalizedNotice>;
+}
+interface ConsentWithdrawInput {
+    principal_ref: string;
+    purpose: string;
+}
+/** Outcome of an erasure resolution (fires now, or defers under a legal hold). */
+interface ErasureOutcome {
+    status: string;
+    action?: string;
+    legal_basis?: string;
+    erase_after?: Nullable<Timestamp>;
+    [key: string]: unknown;
+}
+interface ConsentWithdrawResult {
+    principal_ref: string;
+    purpose: string;
+    status: string;
+    withdrawn_at: Nullable<Timestamp>;
+    erasure: ErasureOutcome;
+}
+interface ConsentStatusEntry {
+    purpose: string;
+    status: string;
+    granted_at: Nullable<Timestamp>;
+    withdrawn_at: Nullable<Timestamp>;
+}
+interface ConsentStatus {
+    principal_ref: string;
+    consents: ConsentStatusEntry[];
+}
+interface ConsentRecordSummary {
+    principal_ref: string;
+    purpose: string;
+    status: string;
+    granted_at: Nullable<Timestamp>;
+    withdrawn_at: Nullable<Timestamp>;
+}
+interface ErasureInput {
+    principal_ref: string;
+}
+interface ErasureResult {
+    principal_ref: string;
+    status: string;
+    results: Array<{
+        purpose: string;
+    } & ErasureOutcome>;
+}
+interface ErasureConfirmResult {
+    status: string;
+    target: string;
+}
+interface AuditEntry {
+    sequence: number;
+    event_type: string;
+    principal_ref: string;
+    payload: Record<string, unknown>;
+    prev_hash: string;
+    entry_hash: string;
+    created_at: Timestamp;
+}
+interface AuditLog {
+    /** Whether the hash chain still verifies end-to-end. */
+    chain_verified: boolean;
+    count: number;
+    entries: AuditEntry[];
+}
+type RetentionTrigger = "consent_withdrawn" | "inactivity" | "fixed_period" | string;
+type ErasureAction = "delete" | "anonymize";
+interface RetentionPolicy {
+    purpose: string;
+    retention_days: number;
+    trigger: RetentionTrigger;
+    notice_hours_before: number;
+    erasure_action: ErasureAction;
+    legal_hold_days: number;
+    legal_basis: string;
+    active: boolean;
+}
+interface RetentionPolicyInput {
+    purpose: string;
+    retention_days: number;
+    trigger?: RetentionTrigger;
+    notice_hours_before?: number;
+    erasure_action?: ErasureAction;
+    legal_hold_days?: number;
+    legal_basis?: string;
+    active?: boolean;
+}
+interface RetentionRunResult {
+    dry_run: boolean;
+    [key: string]: unknown;
+}
+interface ActivityInput {
+    principal_ref: string;
+    purpose?: string;
+}
+interface ActivityResult {
+    updated: number;
+    last_activity_at: Timestamp;
+}
+/** The certificate payload (subject, status, action, legal_basis, chain_verified, …). */
+type CertificatePayload = Record<string, unknown>;
+interface IssueCertificateInput {
+    principal_ref: string;
+    purpose?: string;
+}
+interface IssuedCertificate {
+    certificate_jwt: string;
+    fingerprint: string;
+    issued_at: Timestamp;
+    payload: CertificatePayload;
+    public_key_url: string;
+    verify_url: string;
+}
+interface CertificateVerifyResult {
+    valid: boolean;
+    error?: string;
+    issuer?: string;
+    fingerprint?: string;
+    in_registry?: boolean;
+    revoked?: boolean;
+    payload?: CertificatePayload;
+}
+interface CertificatePublicKey {
+    issuer: string;
+    algorithm: string;
+    public_key_pem: string;
+}
+interface CertificateRegistryResult {
+    found: boolean;
+    fingerprint?: string;
+    status?: string;
+    issued_at?: Timestamp;
+    revoked?: boolean;
+}
+interface IssueEvidenceCertificateInput {
+    subject: string;
+    purpose?: string;
+    source?: string;
+}
+interface EvidenceIngestInput {
+    /** SDK-pushed hash-chain entries (each needs at least `sequence` + `entry_hash`). */
+    entries: Array<Record<string, unknown>>;
+    source?: string;
+}
+interface EvidenceIngestResult {
+    source: string;
+    stored: number;
+    total: number;
+    chain_verified: boolean;
+}
+interface EvidenceEntry {
+    sequence: number;
+    event_type: string;
+    subject: string;
+    payload: Record<string, unknown>;
+    entry_hash: string;
+    source_timestamp: Nullable<Timestamp>;
+    received_at: Timestamp;
+}
+interface EvidenceListResult {
+    source: string;
+    chain_verified: boolean;
+    total: number;
+    entries: EvidenceEntry[];
+}
+interface EvidenceListQuery {
+    source?: string;
+    subject?: string;
+}
+type DSRRequestType = "access" | "correction" | "erasure" | "nomination" | "grievance";
+type DSRStatus = "received" | "in_progress" | "completed" | "rejected" | "extended";
+type DSRAction = "acknowledge" | "start" | "complete" | "reject" | "extend";
+interface DSR {
+    id: number;
+    principal_ref: string;
+    request_type: DSRRequestType;
+    status: DSRStatus;
+    detail: string;
+    response: string;
+    sla_days: number;
+    received_at: Timestamp;
+    deadline_at: Nullable<Timestamp>;
+    acknowledged_at: Nullable<Timestamp>;
+    completed_at: Nullable<Timestamp>;
+    is_overdue: boolean;
+    days_remaining: Nullable<number>;
+}
+interface DSRCreateInput {
+    principal_ref: string;
+    request_type: DSRRequestType;
+    detail?: string;
+    sla_days?: number;
+}
+interface DSRActionInput {
+    action: DSRAction;
+    /** Used by `complete`/`reject`. */
+    response?: string;
+    /** Used by `extend` (default 30). */
+    extra_days?: number;
+}
+interface DSRListQuery {
+    status?: DSRStatus;
+    request_type?: DSRRequestType;
+    principal_ref?: string;
+    overdue?: boolean;
+}
+type BreachSeverity = "low" | "medium" | "high" | "critical";
+type BreachStatus = "reported" | "investigating" | "contained" | "notified" | "closed";
+type BreachAction = "investigate" | "contain" | "notify_board" | "notify_principals" | "close";
+interface Breach {
+    id: number;
+    title: string;
+    description: string;
+    severity: BreachSeverity;
+    status: BreachStatus;
+    nature: string;
+    affected_count: number;
+    measures: string;
+    discovered_at: Timestamp;
+    occurred_at: Nullable<Timestamp>;
+    notified_board_at: Nullable<Timestamp>;
+    notified_principals_at: Nullable<Timestamp>;
+}
+interface BreachReportInput {
+    title: string;
+    description?: string;
+    severity?: BreachSeverity;
+    nature?: string;
+    affected_count?: number;
+    measures?: string;
+    occurred_at?: Nullable<Timestamp>;
+}
+interface BreachActionInput {
+    action: BreachAction;
+    measures?: string;
+}
+interface BreachListQuery {
+    status?: BreachStatus;
+    severity?: BreachSeverity;
+}
+/** Draft Board + data-principal breach notices generated from the incident. */
+type BreachNotifications = Record<string, unknown>;
+interface Target {
+    id: number;
+    name: string;
+    url: string;
+    active: boolean;
+    created_at: Timestamp;
+}
+interface TargetCreateInput {
+    name: string;
+    url: string;
+    active?: boolean;
+}
+/** Target create response — includes the signing `secret`, returned only once. */
+interface TargetWithSecret extends Target {
+    secret: string;
+}
+interface TargetUpdateInput {
+    name?: string;
+    url?: string;
+    active?: boolean;
+}
+interface ErasureTask {
+    id: number;
+    target: string;
+    principal_ref: string;
+    purpose: string;
+    action: string;
+    reason: string;
+    status: string;
+    status_code: Nullable<number>;
+    error: string;
+    created_at: Timestamp;
+    delivered_at: Nullable<Timestamp>;
+    confirmed_at: Nullable<Timestamp>;
+}
+interface ErasureTaskListQuery {
+    principal_ref?: string;
+    status?: string;
+    target?: string;
+}
+
+declare const DEFAULT_API_BASE = "https://getdpdp.net/api/v1";
+interface DPDPStackOptions {
+    /**
+     * API key. A **secret** key (`dpdp_sk_…`) for server-side use, or a
+     * **publishable** key (`dpdp_pk_…`) — the only kind safe to ship to a browser,
+     * limited to reading purposes and recording consent. Omit for public-only
+     * calls (certificate verify/registry/public-key).
+     */
+    apiKey?: string;
+    /** API base URL. Default `https://getdpdp.net/api/v1`. Use a relative path (e.g. `/api/v1`) to call a same-origin proxy. */
+    apiBase?: string;
+    /** Custom fetch implementation (for Node < 18, testing, or proxies). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+    /** `fetch` credentials mode (e.g. `"include"` to send cookies). Default: unset. */
+    credentials?: RequestCredentials;
+}
+/** Thrown for any non-2xx API response. */
+declare class DPDPError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    readonly body: unknown;
+    constructor(status: number, detail: string, body: unknown);
+}
+/**
+ * Thin, typed client for the DPDPStack API.
+ *
+ * ```ts
+ * const dpdp = new DPDPStack({ apiKey: "dpdp_sk_…" });
+ * await dpdp.grantConsent({ principal_ref: "user_42", purpose: "marketing" });
+ * ```
+ */
+declare class DPDPStack {
+    private readonly apiBase;
+    private readonly apiKey?;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly credentials?;
+    constructor(options?: DPDPStackOptions);
+    /** Low-level request. Most callers use the typed methods below. */
+    request<T>(method: string, path: string, opts?: {
+        query?: object;
+        body?: unknown;
+    }): Promise<T>;
+    /** List consent purposes (with multilingual notices). Publishable-key safe. */
+    listPurposes(): Promise<Purpose[]>;
+    /** Create a consent purpose. Requires a secret key. */
+    createPurpose(input: PurposeInput): Promise<Purpose>;
+    /** Record purpose-level consent and get an immutable receipt. Publishable-key safe. */
+    grantConsent(input: ConsentGrantInput): Promise<ConsentReceipt>;
+    /** Withdraw consent for a purpose (triggers erasure/deferral). Requires a secret key. */
+    withdrawConsent(input: ConsentWithdrawInput): Promise<ConsentWithdrawResult>;
+    /** Current consent state for a principal. Requires a secret key. */
+    consentStatus(principalRef: string): Promise<ConsentStatus>;
+    /** List the organization's consent records (latest first). Requires a secret key. */
+    listConsentRecords(): Promise<ConsentRecordSummary[]>;
+    /** Record principal activity, resetting inactivity-based retention. Requires a secret key. */
+    recordActivity(input: ActivityInput): Promise<ActivityResult>;
+    /** Right to erasure: resolve erasure across the principal's purposes. Requires a secret key. */
+    requestErasure(input: ErasureInput): Promise<ErasureResult>;
+    /** Confirm a downstream erasure with the token delivered to that system. No API key needed. */
+    confirmErasure(token: string): Promise<ErasureConfirmResult>;
+    /** Hash-chained audit trail (optionally filtered by principal), plus chain status. Requires a secret key. */
+    getAuditLog(query?: {
+        principal_ref?: string;
+    }): Promise<AuditLog>;
+    readonly retention: {
+        /** List retention policies. Requires a secret key. */
+        list: () => Promise<RetentionPolicy[]>;
+        /** Create or update a retention policy. Requires a secret key. */
+        upsert: (input: RetentionPolicyInput) => Promise<RetentionPolicy>;
+        /** Run the retention sweep now (`{ dry_run: true }` to preview). Requires a secret key. */
+        run: (input?: {
+            dry_run?: boolean;
+        }) => Promise<RetentionRunResult>;
+    };
+    readonly certificates: {
+        /** Issue a counter-signed Certificate of Erasure for a principal. Requires a secret key. */
+        issue: (input: IssueCertificateInput) => Promise<IssuedCertificate>;
+        /** Verify a Certificate of Erasure (JWT) against the public key. Public — no key needed. */
+        verify: (certificateJwt: string) => Promise<CertificateVerifyResult>;
+        /** Fetch the issuer public key. Public — no key needed. */
+        publicKey: () => Promise<CertificatePublicKey>;
+        /** Look up a certificate in the public registry by fingerprint. Public — no key needed. */
+        registry: (fingerprint: string) => Promise<CertificateRegistryResult>;
+        /** Issue a certificate from SDK-pushed evidence. Requires a secret key. */
+        issueFromEvidence: (input: IssueEvidenceCertificateInput) => Promise<IssuedCertificate>;
+    };
+    readonly evidence: {
+        /** Push tamper-evident audit evidence (hash chain) for server-timestamping. Requires a secret key. */
+        ingest: (input: EvidenceIngestInput) => Promise<EvidenceIngestResult>;
+        /** List stored evidence for a source/subject, with chain status. Requires a secret key. */
+        list: (query?: EvidenceListQuery) => Promise<EvidenceListResult>;
+    };
+    readonly dsr: {
+        /** List rights requests (filter by status/type/principal/overdue). Requires a secret key. */
+        list: (query?: DSRListQuery) => Promise<DSR[]>;
+        /** Create a rights request. Requires a secret key. */
+        create: (input: DSRCreateInput) => Promise<DSR>;
+        /** Get a single rights request. Requires a secret key. */
+        get: (id: number) => Promise<DSR>;
+        /** Advance a rights request (acknowledge/start/complete/reject/extend). Requires a secret key. */
+        act: (id: number, input: DSRActionInput) => Promise<DSR>;
+    };
+    readonly breaches: {
+        /** List breach incidents. Requires a secret key. */
+        list: (query?: BreachListQuery) => Promise<Breach[]>;
+        /** Report a breach incident (metadata only — never PII). Requires a secret key. */
+        report: (input: BreachReportInput) => Promise<Breach>;
+        /** Get a single breach. Requires a secret key. */
+        get: (id: number) => Promise<Breach>;
+        /** Advance a breach (investigate/contain/notify_board/notify_principals/close). Requires a secret key. */
+        act: (id: number, input: BreachActionInput) => Promise<Breach>;
+        /** Generate draft Board + principal breach notices. Requires a secret key. */
+        notifications: (id: number) => Promise<BreachNotifications>;
+    };
+    readonly targets: {
+        /** List downstream erasure targets. Requires a secret key. */
+        list: () => Promise<Target[]>;
+        /** Register a target. The signing `secret` is returned only once. Requires a secret key. */
+        create: (input: TargetCreateInput) => Promise<TargetWithSecret>;
+        /** Get a single target. Requires a secret key. */
+        get: (id: number) => Promise<Target>;
+        /** Update a target. Requires a secret key. */
+        update: (id: number, input: TargetUpdateInput) => Promise<Target>;
+        /** Delete a target. Requires a secret key. */
+        remove: (id: number) => Promise<void>;
+    };
+    readonly erasureTasks: {
+        /** List per-system erasure fan-out tasks (the propagation evidence). Requires a secret key. */
+        list: (query?: ErasureTaskListQuery) => Promise<ErasureTask[]>;
+        /** Re-deliver an erasure instruction to a target. Requires a secret key. */
+        retry: (id: number) => Promise<ErasureTask>;
+    };
+}
+
+interface ConsentWidgetTexts {
+    heading: string;
+    subheading: string;
+    save: string;
+    saving: string;
+    saved: string;
+    loading: string;
+    error: string;
+}
+interface ConsentWidgetOptions {
+    /** Your opaque user id (internal id or hash) — never PII. */
+    principalRef: string;
+    /** Pre-built client. If omitted, one is built from `apiBase`/`apiKey`. */
+    client?: DPDPStack;
+    /** Used to build a client when `client` is not supplied. */
+    apiBase?: string;
+    /** Publishable key (`dpdp_pk_…`). Used to build a client when `client` is not supplied. */
+    apiKey?: string;
+    /** Purposes to render. If omitted, they're fetched via `client.listPurposes()`. */
+    purposes?: Purpose[];
+    /** Initial locale for notice text. Default `"en"`. */
+    locale?: string;
+    /** Purpose codes checked on first render. */
+    defaultChecked?: string[];
+    /** Override any UI strings. */
+    texts?: Partial<ConsentWidgetTexts>;
+    /** Called with the receipts after a successful save. */
+    onSave?: (receipts: ConsentReceipt[]) => void;
+    /** Called if loading purposes or saving fails. */
+    onError?: (error: unknown) => void;
+}
+interface ConsentWidgetController {
+    /** Switch the notice language and re-render. */
+    setLocale(locale: string): void;
+    /** Re-fetch purposes (when not passed in) and re-render. */
+    refresh(): Promise<void>;
+    /** Remove the widget from the DOM. */
+    destroy(): void;
+}
+/**
+ * Mount a drop-in consent capture widget. Returns a controller for switching
+ * locale, refreshing, or removing it.
+ *
+ * ```ts
+ * mountConsentWidget("#consent", {
+ *   apiBase: "/api/v1",
+ *   apiKey: "dpdp_pk_…",       // publishable key
+ *   principalRef: "user_123",
+ * });
+ * ```
+ */
+declare function mountConsentWidget(target: string | HTMLElement, options: ConsentWidgetOptions): ConsentWidgetController;
+
+/**
+ * Backward-compatible shim for the original `DPDPConsent.init({ el, … })`
+ * script-tag widget. Prefer {@link mountConsentWidget} in new code.
+ */
+declare const DPDPConsent: {
+    init(config: {
+        el: string | HTMLElement;
+        apiBase?: string;
+        apiKey?: string;
+        principalRef: string;
+        locale?: string;
+        purposes?: Purpose[];
+        onSave?: (receipts: ConsentReceipt[]) => void;
+    }): ConsentWidgetController;
+};
+
+export { type ActivityInput, type ActivityResult, type AuditEntry, type AuditLog, type Breach, type BreachAction, type BreachActionInput, type BreachListQuery, type BreachNotifications, type BreachReportInput, type BreachSeverity, type BreachStatus, type CertificatePayload, type CertificatePublicKey, type CertificateRegistryResult, type CertificateVerifyResult, type ConsentGrantInput, type ConsentReceipt, type ConsentRecordSummary, type ConsentStatus, type ConsentStatusEntry, type ConsentWidgetController, type ConsentWidgetOptions, type ConsentWidgetTexts, type ConsentWithdrawInput, type ConsentWithdrawResult, DEFAULT_API_BASE, DPDPConsent, DPDPError, DPDPStack, type DPDPStackOptions, type DSR, type DSRAction, type DSRActionInput, type DSRCreateInput, type DSRListQuery, type DSRRequestType, type DSRStatus, type ErasureAction, type ErasureConfirmResult, type ErasureInput, type ErasureOutcome, type ErasureResult, type ErasureTask, type ErasureTaskListQuery, type EvidenceEntry, type EvidenceIngestInput, type EvidenceIngestResult, type EvidenceListQuery, type EvidenceListResult, type IssueCertificateInput, type IssueEvidenceCertificateInput, type IssuedCertificate, type LocalizedNotice, type Nullable, type Purpose, type PurposeInput, type RetentionPolicy, type RetentionPolicyInput, type RetentionRunResult, type RetentionTrigger, type Target, type TargetCreateInput, type TargetUpdateInput, type TargetWithSecret, type Timestamp, mountConsentWidget };