@lupla/sdk

Phase 11 v0.1 of the Lupla SDK. Eight nouns hide all of Cloudflare. v0.1 ships only tl.db (CRUD + migrate) — tl.vectors, tl.files, tl.speech, tl.agent land in v0.2+.

Install

npm install @lupla/sdk
# or: pnpm add @lupla/sdk · yarn add @lupla/sdk · bun add @lupla/sdk

Usage

import { tl } from '@lupla/sdk'

await tl.db.migrate(`
  CREATE TABLE IF NOT EXISTS notes (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    body TEXT,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
  )
`)

const notes = await tl.db.query('SELECT * FROM notes ORDER BY created_at DESC')
const created = await tl.db.insert('notes', { title: 'Hello', body: 'World' })
await tl.db.update('notes', { id: created.id }, { title: 'Updated' })
await tl.db.delete('notes', { id: created.id })

Configuration

The SDK reads from environment variables. Same code, different backend depending on mode:

Var	Default	Used in
`LUPLA_MODE`	`local`	both
`LUPLA_APP_ID`	`local-app`	both
`LUPLA_API_KEY`	(none)	remote (required)
`LUPLA_ENDPOINT`	`https://api.lupla.ai`	remote
`LUPLA_LOCAL_DB`	`./lupla.db`	local
`LUPLA_METERING_PATH`	`./metering.jsonl`	local

Override programmatically with new TL({ mode: 'remote', apiKey: '...', appId: '...' }).

Metering

Every call records a metering event with op kind, latency, row count, and payload bytes:

Local mode: appended to ./metering.jsonl (one JSON event per line).
Remote mode: batched and POSTed to the Worker every 5s or 100 events.

The exported projectCost() helper translates a batch of events into projected Cloudflare cost.

What's deferred

tl.vectors, tl.files, tl.speech, tl.agent, tl.auth, tl.email, tl.schedule, tl.webhooks, tl.realtime — see 12-cloudflare-deployment-plan-v4.md for the planned API surface.
Connection pooling, prepared statement caching, query result streaming.
Stripe metering integration (events flow into D1 in v0.1; D1 → Stripe Meters comes in Phase 13).