Skip to main content
The TypeScript SDK is a small wrapper around the Lodger HTTP API. It sends idempotency keys, normalizes simple actor and target inputs, attaches provenance headers, and returns typed receipts.

​
Install

bun add @lodger/sdk

​
Client

import { Lodger } from "@lodger/sdk"

export 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,
})
apiKey, workspaceId, and projectId are required. workspaceId is the Ave organization ID for the workspace. Set apiBase only for private deployments. 
const privateDeployment = new Lodger({
  apiKey: process.env.LODGER_API_KEY!,
  workspaceId: "org_01JZ2M9E7G6D8R5K3D",
  projectId: "core",
  apiBase: process.env.LODGER_API_BASE!,
})

​
Record events

await lodger.event("billing.invoice.paid", {
  actor: { id: "billing-worker", type: "service" },
  target: { id: invoice.id, type: "invoice" },
  metadata: {
    amount: invoice.amount_paid,
    currency: invoice.currency,
    relatedReceiptIds: previousReceipts,
  },
  userVisible: true,
})
You can pass a custom idempotency key and request context as the third argument. 
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 },
  },
  {
    idempotencyKey: `member_removed_${member.id}_${requestId}`,
    request: {
      requestId,
      sessionId,
      traceId,
    },
  }
)

await lodger.consent({
  subject: { id: user.id, type: "user", email: user.email },
  mode: "explicit",
  policyVersion: 4,
  surface: "settings/privacy",
  metadata: { checkboxId: "terms-v4" },
})

​
Read records

const page = await lodger.query({
  query: "invoice_123",
  lane: "operations",
  from: "2026-05-01T00:00:00.000Z",
  limit: 50,
})

​
Verify receipts

const result = await lodger.receipt("rcpt_093a339cc2c2ffed")

if (!result.verified) {
  throw new Error("Receipt verification failed")
}
Public project receipts can be verified by receipt ID. Private project receipts require the SDK API key, a dashboard session, or a scoped receipt token. 
const link = await lodger.receiptToken("rcpt_093a339cc2c2ffed", {
  expiresInSeconds: 3600,
})

const sharedResult = await lodger.receipt("rcpt_093a339cc2c2ffed", {
  token: link.token,
})
Generated browser links keep the receipt token in the URL fragment. Private policy pages can be shared with scoped policy tokens. 
const policy = await lodger.policyToken({ expiresInSeconds: 3600 })

return policy.policyUrl
Evidence package links use evidence tokens. The generated verifier URL can download that one package and live-check private receipts included in the package. 
const evidence = await lodger.evidenceToken("pack_20260516_001")

return evidence.evidenceUrl

​
Customer activity

Mint activity links from trusted server-side code after enabling activity links on the project. The token is scoped to the configured workspace, project, and subject, and project settings cap the maximum token lifetime. 
const link = await lodger.activityToken(user.id)

return link.activityUrl
Use the token to read that subject’s visible activity. Raw subject lookup is not public. 
const page = await lodger.activity(link.token, { limit: 25 })
The SDK sends activity tokens as bearer tokens. Generated browser links keep the token in the URL fragment.