HNNP Node.js SDK

This directory contains the official Node.js SDK for interacting with the HNNP Cloud backend. It implements REST API wrappers and webhook verification logic exactly as defined in the protocol specification.

All SDK behavior MUST follow: protocol/spec.md

Features

• Typed API client (TypeScript)
• REST methods for orgs, sessions lifecycle, receivers, presence, billing, incidents
• Webhook signature verification
• Pagination helpers
• Error handling & retry wrappers

Installation

npm install @hnnp/sdk

Usage Example

import { HnnpClient } from "@hnnp/sdk";

const client = new HnnpClient({ apiKey: "YOUR_API_KEY", baseUrl: "https://api.hnnp.example" });

const events = await client.listPresenceEvents({ orgId: "org_123" });

await client.createLink({ orgId: "org_123", userRef: "emp_45" });

await client.linkPresenceSession({ presenceSessionId: "psess_001", userRef: "emp_45", orgId: "org_123" });

Webhook Verification

import { verifyHnnpWebhook } from "@hnnp/sdk";

const isValid = verifyHnnpWebhook({ rawBody, signature: headers["x-hnnp-signature"], timestamp: headers["x-hnnp-timestamp"], webhookSecret: process.env.WEBHOOK_SECRET });

Webhook Consumer Example (Express)

You can use the SDK helper inside a minimal Express server. An example is provided in:

• examples/webhook-consumer.ts

Outline:

import express from "express";
import { verifyHnnpWebhook } from "@hnnp/sdk";

const app = express();
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = Buffer.from(buf); } }));

app.post("/hnnp/webhook", (req, res) => {
  const isValid = verifyHnnpWebhook({
    rawBody: req.rawBody,
    signature: req.header("X-HNNP-Signature"),
    timestamp: req.header("X-HNNP-Timestamp"),
    webhookSecret: process.env.WEBHOOK_SECRET
  });

  if (!isValid) return res.status(400).json({ error: "invalid_webhook_signature" });

  console.log("Received HNNP webhook", req.body);
  return res.status(200).json({ status: "ok" });
});

Available Methods

Receivers

• listReceivers({ orgId })
• createReceiver({ orgId, receiverId, authMode, ... })
• updateReceiver({ orgId, receiverId, ... })

Presence (public)

• listPresenceEvents({ orgId, ... })
• listPresenceSessions({ orgId, ... })

Links (public)

• createLink({ orgId, userRef, deviceId? })
• activateLink(id)
• revokeLink(id)
• listLinks({ orgId, userRef? })
• linkPresenceSession({ orgId, presenceSessionId, userRef })
• unlink(id)

Org console

• listOrgs()
• getOrg({ orgId })
• getOrgSettings({ orgId })
• updateOrgSettings({ orgId, settings })
• getOrgConfig({ orgId })
• updateOrgConfig({ orgId, config })
• getOrgMetricsRealtime({ orgId, ... })
• listOrgUsers({ orgId })

Receivers health (org console)

• listReceiversAdmin()
• getReceiver({ receiverId })
• updateReceiverAdmin({ receiverId, payload })
• getReceiverStatus({ receiverId })
• getReceiverHealth({ receiverId })

Sessions lifecycle (org console)

• listOrgSessions()
• getOrgSessionsSummary()
• createOrgSession(payload)
• updateOrgSession({ sessionId, payload })
• deleteOrgSession({ sessionId })
• finalizeOrgSession({ sessionId })

Attendance + presence (org console)

• getPresenceLive()
• getPresenceLogs()
• getPresenceEvents()
• listLocations()
• listGroups()
• createGroup(payload)
• updateGroup({ groupId, payload })
• deleteGroup({ groupId })
• getAttendance()
• exportAttendanceCsv()

Billing

• getBillingSummary()
• listInvoices()
• getInvoicePdf({ invoiceId })

Incidents + safety

• listIncidents()
• getIncident({ incidentId })
• getIncidentRollcall({ incidentId })
• getSafetyStatus()
• getSafetySummary()

File Structure

src/ index.ts client.ts http.ts webhook.ts types.ts

Environment Variables

WEBHOOK_SECRET=your_org_webhook_secret

Notes

• Webhook signing follows the HMAC rules in Section 10.3 of the v2 spec.
• All network calls use HTTPS.
• SDK MUST NOT alter any packet formats or cryptographic logic.
• Some endpoints require an org admin JWT (org console auth) instead of an API key.

Typed models are exported from @hnnp/sdk (see types.ts).

Pagination helpers

for await (const evt of client.iteratePresenceEvents({ orgId: "org_123" })) {
  console.log(evt.id);
}

for await (const sess of client.iteratePresenceSessions({ orgId: "org_123" })) {
  console.log(sess.session_id);
}

for await (const rcv of client.iterateReceivers({ orgId: "org_123" })) {
  console.log(rcv.receiver_id);
}

Rate limiting

The client retries on 5xx and 429 responses with exponential backoff.
If Retry-After is provided, it is respected (up to 30s).

Testing

npm test

Reference

Full protocol spec: ../../protocol/spec.md