@lodger/sdk

TypeScript SDK for writing Lodger audit evidence from server-side JavaScript, TypeScript, Bun, Node, and edge runtimes.

Install

bun add @lodger/sdk

For local development in this repository:

import { Lodger } from "./sdk/typescript/src/index"

Record an event

import { Lodger } from "@lodger/sdk"

const lodger = new Lodger({
  apiKey: process.env.LODGER_API_KEY!,
  workspaceId: process.env.LODGER_WORKSPACE_ID!,
  projectId: "core",
  environment: process.env.NODE_ENV,
  server: process.env.HOSTNAME,
})

const receipt = await lodger.event("organization.member.removed", {
  actor: {
    id: user.id,
    type: "user",
    email: user.email,
  },
  target: {
    id: member.id,
    type: "organization_member",
  },
  metadata: {
    organizationId: organization.id,
    reason: "Inactive contractor",
  },
}, {
  request: {
    requestId: request.headers.get("x-request-id"),
    sessionId: session.id,
  },
})

console.log(receipt.receipt)

Typed event names

import { Lodger, defineLodgerEvents } from "@lodger/sdk"

const events = defineLodgerEvents({
  "billing.invoice.paid": {
    targetType: "invoice",
    userVisible: true,
  },
  "organization.member.removed": {
    targetType: "organization_member",
  },
})

const lodger = new Lodger({
  apiKey: process.env.LODGER_API_KEY!,
  workspaceId: process.env.LODGER_WORKSPACE_ID!,
  projectId: "core",
})

const audit = lodger.withCatalog(events)

await audit.event("billing.invoice.paid", {
  actor: { id: "billing-worker", type: "service" },
  target: "invoice_123",
  metadata: { amount: 2900, currency: "usd" },
})

Query records

const page = await lodger.query({
  query: "invoice_123",
  lane: "operations",
  limit: 25,
})

for (const event of page.events) {
  console.log(event.sequence, event.action, event.receipt)
}

Customer activity

const activity = await lodger.activityToken(user.id)
const visibleHistory = await lodger.activity(activity.token)

Activity links keep the token in the URL fragment. Direct activity reads send it as a bearer token.

Build

bun install
bun run build