@hnnp/sdk 0.1.0

package/README.md

@@ -0,0 +1,226 @@
+# 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:
+
+```ts
+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
+
+```ts
+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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@hnnp/sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "HNNP Node.js SDK",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hawkeye17-warex/hnnp"
+  },
+  "keywords": [
+    "nearid",
+    "hnnp",
+    "presence",
+    "ble",
+    "security",
+    "sdk"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "dependencies": {
+    "hnnp-monorepo": "file:../.."
+  }
+}