Skip to main content

SDK: Ledger

The Ledger client provides methods for emitting audit events, managing retention policies, and classifying data fields.

Access it via client.ledger.

Events​

List audit events​

const events = await client.ledger.events.list();
// events: LedgerEvent[]

Returns an array of LedgerEvent objects:

interface LedgerEvent {
  id: string;
  action: string;
  service: string;
  resource: string;
  actor: string;
  details: Record<string, unknown>;
  timestamp: string;
}

Emit an audit event​

const event = await client.ledger.events.emit({
  action: "user.data.export",
  service: "shiftcal",
  resource: "user-profile",
  actor: "admin@example.com",
  details: {
    format: "csv",
    recordCount: 1500,
  },
});

Policies​

List retention policies​

const policies = await client.ledger.policies.list();
// policies: Policy[]

Returns an array of Policy objects:

interface Policy {
  id: string;
  name: string;
  service: string;
  retentionDays: number;
  action: "archive" | "delete" | "anonymize";
  createdAt: string;
}

Create a retention policy​

const policy = await client.ledger.policies.create({
  name: "gdpr-90-day",
  service: "shiftcal",
  retentionDays: 90,
  action: "anonymize",
});

Classifications​

List field classifications​

const classifications = await client.ledger.classifications.list();
// Optionally filter by service:
const filtered = await client.ledger.classifications.list({ service: "shiftcal" });

Returns an array of Classification objects:

interface Classification {
  id: string;
  service: string;
  field: string;
  level: "public" | "internal" | "confidential" | "restricted";
  ppiCategory?: string;
  createdAt: string;
}

Classify a field​

const classification = await client.ledger.classifications.create({
  service: "shiftcal",
  field: "user.email",
  level: "confidential",
  ppiCategory: "contact-info",
});

Full Example​

import { createClient } from "@the-shift/sdk";

const client = createClient({
  gatewayUrl: "https://app.the-shift.dev",
  apiKey: process.env.SHIFT_API_KEY,
});

// Set up a retention policy
const policy = await client.ledger.policies.create({
  name: "audit-log-1yr",
  service: "shiftcal",
  retentionDays: 365,
  action: "archive",
});
console.log(`Policy created: ${policy.id}`);

// Classify sensitive fields
await client.ledger.classifications.create({
  service: "shiftcal",
  field: "user.email",
  level: "confidential",
  ppiCategory: "contact-info",
});

await client.ledger.classifications.create({
  service: "shiftcal",
  field: "booking.title",
  level: "internal",
});

// Emit audit events
await client.ledger.events.emit({
  action: "booking.created",
  service: "shiftcal",
  resource: "booking-abc",
  actor: "user@example.com",
  details: { duration: 60, attendees: 3 },
});

// Verify
const events = await client.ledger.events.list();
const classifications = await client.ledger.classifications.list({ service: "shiftcal" });
console.log(`Audit events: ${events.length}`);
console.log(`Classifications: ${classifications.length}`);