Core API

@luno-oss/core holds all the business logic and depends only on @luno-oss/protocol. It is designed so that a backend developer never has to read the protocol specification.

Composition

Every dependency is injected; nothing is ambient.

import { createLuno } from '@luno-oss/core'
import { postgresStore } from '@luno-oss/store-postgres'
 
const luno = createLuno({
  store: postgresStore(pool),
  secret: process.env.LUNO_SECRET!, // at least 16 characters
  pairing: {
    expiresInMs: 10 * 60 * 1000,
    maxEnrollments: 1,
    requireApproval: false,
    allowReplacement: false
  }
})
 
luno.on('sms.received', async ({ from, body }) => {
  /* your business logic */
})
luno.on('device.online', async ({ deviceId }) => {})

Subscriptions are registered with luno.on(event, handler), which returns an unsubscribe function. A handler that throws is logged and swallowed — a failing webhook is your application’s problem, not a reason to drop a node’s connection.

Pairing options

These are SDK defaults, not protocol requirements. The node works with any of them because it enforces no pairing policy of its own.

Operator API

The surface a dashboard or your own services call.

Pairing

const { session, code, qrUri, qrJson } = await luno.pairing.createSession({
  label: 'Acme',
  createdBy: user.id,
  backendUrl: 'https://gw.example.com' // needed to build a scannable payload
})
 
session.id // 'ses_9f3' — non-secret handle, safe to log
code       // 'ABCD-1234' — plaintext, returned exactly once
qrUri      // 'luno://pair?v=1&…', or null without backendUrl
qrJson     // the same payload as JSON, or null

Approval gates are driven from the same service:

await luno.pairing.approveEnrollment(enrollmentId)
await luno.pairing.denyEnrollment(enrollmentId)
await luno.pairing.revokeSession(session.id)

Devices

await luno.devices.list()
await luno.devices.get(deviceId)
 
await luno.devices.revoke(deviceId)   // kill the credential, then tell the node
await luno.devices.wipe(deviceId)     // same reset, different command to the node
await luno.devices.requestStatus(deviceId) // throws if the device is offline
 
await luno.devices.updateConfig(deviceId, {
  heartbeatSec: 60,
  rateLimitPerMinute: 30,
  allowlist: ['+977*'],
})

Messaging

const msg = await luno.sms.send({
  deviceId,
  to: '+9779800000000',
  body: 'hi',
  ref: 'order-42',        // your correlation id, echoed on every event
  subscriptionId: 1,      // optional: pick a SIM
  deliveryReport: true    // default true
})
 
msg.id     // track through sms_accepted → sms_sent → delivery_report
msg.status // 'pending' | 'dispatched' | 'accepted' | 'sent' |
           // 'delivered' | 'undelivered' | 'failed' | 'cancelled'
 
await luno.sms.get(msg.id)
await luno.sms.cancel(msg.id) // only while still cancellable

Events

luno.on(name, handler) subscribes and returns an unsubscribe function. Handlers may be async; one that throws is logged and swallowed rather than taking down the frame loop that emitted it.

const off = luno.on('device.offline', ({ deviceId }) => alert(deviceId))
off() // unsubscribe

Audit trail

Every frame in and out, plus lifecycle events, is persisted:

await luno.events({ deviceId, limit: 100 })

Protocol-facing API

What adapters call, and the only thing they call.

await luno.http.handle(request)                // all REST: /enroll, /enroll/status
await luno.connections.authorize(credential)   // WSS upgrade check
const session = await luno.connections.open(device, sink)
await session.receive(rawFrame)                // drives the state machine
await session.close()

FrameSink

interface FrameSink {
  send(frame: ProtocolFrame): Promise<void>
  close(code?: number, reason?: string): Promise<void>
}

That one interface is the entire transport abstraction. A ws socket, a Cloudflare Durable Object, an SSE stream and a long-poll buffer all satisfy it identically, and the connection and reliability logic is written once against it.

Ports

Narrow and purpose-built, never one god-interface.

Storage — PairingSessionStore, DeviceStore, MessageStore, EventLogStore, EnrollmentStore, composed into one LunoStore. Each is a handful of methods. See Stores.

Runtime — Clock, IdGenerator, CryptoPort, Logger. Each has a default (systemClock, tokenIdGenerator, webCrypto, silentLogger), so you only inject the ones you want to control.

Distribution — SessionRegistry, defaulting to localSessionRegistry(). Its DeliveryOutcome distinguishes offline from not_local: a single-process registry never returns the latter, while a broker-backed one returns it when it cannot route. That distinction is what keeps multi-instance and socketless deployments expressible without changing the core.

Authentication — two axes

The two are deliberately split, and conflating them would be a security regression.

Operator and API-consumer auth — a human or service calling luno.sms.send. Entirely yours. Firebase Auth, Supabase Auth, JWT, OAuth, cookies, API keys: you authenticate the caller and decide whether they may act on that device before you call into the engine. The operator API is not exposed over HTTP by any adapter, so nothing reaches it that you did not route there yourself.

Node credential auth — a Luno node presenting its credential on the handshake. Belongs to the core. It is protocol-defined, security-critical, and involves constant-time comparison, credential hashing, rotation and revocation. Pushing it into every adapter means writing it many times and getting it subtly wrong in at least one.

// Your job: authenticate the caller and authorize the action.
const user = await myAuth(req)
if (!(await userOwnsDevice(user, deviceId))) throw new Forbidden()
await luno.sms.send({ deviceId, to, body })
 
// The core's job: the node credential on the WSS upgrade.
const device = await luno.connections.authorize(bearerToken)

Extension

New protocol-level capability — a new command, a new transport like MMS — lands in @luno-oss/protocol and @luno-oss/core once, and every adapter inherits it with no code change.

That is also the test for whether a change is in the right place: if adding a feature requires touching more than one adapter, it belongs in the core.