Privatrail SDK

Privatrail SDK – a lightweight TypeScript client for communicating with the Privatrail API.
This package is currently in development / internal testing phase.

🧩 Overview

The SDK provides a simple way to send consent logs and perform health checks against the Privatrail API.
It is designed to work in server-only environments (Next.js Server Actions, API routes, or Node.js services).

📦 Structure

src/
 ├── client.ts         # Core HTTP client
 ├── logActions.ts     # Convenience functions for consent logging
 ├── types.ts          # Shared types for requests and responses
 └── index.ts          # Export entry

⚙️ Setup

You can include this SDK locally (until it’s published):

pnpm add ../packages/privatrail-sdk

Then import and initialize it in your Next.js or Node project.

🚀 Usage

1. Initialize SDK Settings

Before making any API calls, set the base URL and token.

import { setClientSettings } from "@privatrail/privatrail-sdk";

setClientSettings(
  process.env.PRIVATRAIL_ENDPOINT!, // e.g. https://api.privatrail.local
  process.env.PRIVATRAIL_TOKEN!     // JWT or API token
);

2. Perform a Health Check

import { getHealthz } from "@privatrail/privatrail-sdk";

const health = await getHealthz();
console.log("API status:", health);

Expected response:

{
  "status": "ok",
  "db": "ok",
  "detail": ""
}

3. Log a Consent Change

import { recordLog } from "@privatrail/privatrail-sdk";

await recordLog({
  visitor_id: "abc123",
  policy_version: "1.0",
  client_name: "demo-site",
  channel: "web",
  client_version: "0.1.0",
  client_config: "default",
  changes: [
    {
      purpose: "analytics",
      lawful_basis: "consent",
      granted: true,
      position: 0
    }
  ]
});

This will POST to /api/v1/consent/log using your configured endpoint.

🧠 Internals

ApiClient

A minimal HTTP wrapper with JSON parsing, header handling, and date revival.
Supports GET / POST / PUT etc., and automatically attaches the Authorization header.

logActions

A convenience layer on top of ApiClient, exposing:

• getHealthz() → quick API status check
• recordLog(request) → send consent log
• setClientSettings(baseUrl, token) → configure before calling

🧰 Requirements

• Node.js ≥ 18
• fetch API available globally (default in Next.js 14+)

🧪 Development Notes

Build the package locally:

pnpm build

Clean old builds:

pnpm run clean

This will generate compiled output in dist/ ready for internal linking or publishing later.

📄 License

Currently unlicensed (internal use only) —
a proper open-source license (e.g. MIT) will be added before public release.

📅 Status

🧱 MVP-level SDK for internal integration testing.
Next steps:

• Add input validation
• Add error handling and retry logic
• Prepare documentation for public release