@hnnp/sdk 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import type { AttendanceResponse, BillingSummary, Invoice, Incident, IncidentListResponse, IncidentRollcallResponse, LinkListResponse, LinkResponse, Org, OrgSettings, OrgConfig, OrgUser, PresenceEvent, PresenceEventListResponse, PresenceSession, PresenceSessionListResponse, Receiver, ReceiverHealth, ReceiverListResponse, ReceiverStatus, RealtimeMetrics, SafetyStatus, SafetySummary, SessionConfig, SessionListResponse, SessionSummaryResponse } from "./types";
+type FetchLike = typeof fetch;
+export declare class HnnpApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export interface HnnpClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    fetch?: FetchLike;
+    retries?: number;
+}
+export type { AttendanceSummary, AttendanceResponse, BillingDecision, BillingSummary, Incident, IncidentListResponse, IncidentRollcallResponse, Invoice, InvoiceLine, Link, LinkListResponse, LinkResponse, Org, OrgConfig, OrgListResponse, OrgSettings, OrgUser, PresenceEvent, PresenceEventListResponse, PresenceSession, PresenceSessionListResponse, Receiver, ReceiverHealth, ReceiverListResponse, ReceiverStatus, RealtimeMetrics, SafetyStatus, SafetySummary, SessionConfig, SessionListResponse, SessionSummary, SessionSummaryResponse, } from "./types";
+export declare class HnnpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly retries;
+    constructor(opts: HnnpClientOptions);
+    listReceivers(params: {
+        orgId: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<ReceiverListResponse>;
+    createReceiver(params: {
+        orgId: string;
+        receiverId: string;
+        displayName?: string;
+        locationLabel?: string;
+        authMode: string;
+        sharedSecret?: string;
+        publicKeyPem?: string;
+        firmwareVersion?: string;
+        status?: string;
+    }): Promise<Receiver>;
+    updateReceiver(params: {
+        orgId: string;
+        receiverId: string;
+        displayName?: string;
+        locationLabel?: string;
+        authMode?: string;
+        sharedSecret?: string;
+        publicKeyPem?: string;
+        firmwareVersion?: string;
+        status?: string;
+    }): Promise<Receiver>;
+    listPresenceEvents(params: {
+        orgId: string;
+        userRef?: string;
+        receiverId?: string;
+        from?: string;
+        to?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PresenceEventListResponse>;
+    listPresenceSessions(params: {
+        orgId: string;
+        userRef?: string;
+        receiverId?: string;
+        deviceIdHash?: string;
+        from?: string;
+        to?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PresenceSessionListResponse>;
+    createLink(params: {
+        orgId: string;
+        userRef: string;
+        deviceId?: string;
+    }): Promise<LinkResponse>;
+    activateLink(id: string): Promise<LinkResponse>;
+    revokeLink(id: string): Promise<LinkResponse>;
+    listLinks(params: {
+        orgId: string;
+        userRef?: string;
+    }): Promise<LinkListResponse>;
+    linkPresenceSession(params: {
+        orgId: string;
+        presenceSessionId: string;
+        userRef: string;
+    }): Promise<LinkResponse>;
+    unlink(id: string): Promise<LinkResponse>;
+    listOrgs(params?: Record<string, unknown>): Promise<Org[]>;
+    getOrg(params: {
+        orgId: string;
+    }): Promise<Org>;
+    getOrgSettings(params: {
+        orgId: string;
+    }): Promise<OrgSettings>;
+    updateOrgSettings(params: {
+        orgId: string;
+        settings: Record<string, unknown>;
+    }): Promise<OrgSettings>;
+    getOrgConfig(params: {
+        orgId: string;
+    }): Promise<OrgConfig>;
+    updateOrgConfig(params: {
+        orgId: string;
+        config: Record<string, unknown>;
+    }): Promise<OrgConfig>;
+    getOrgMetricsRealtime(params: {
+        orgId: string;
+    } & Record<string, unknown>): Promise<RealtimeMetrics>;
+    listOrgUsers(params: {
+        orgId: string;
+    }): Promise<OrgUser[]>;
+    listReceiversAdmin(params?: Record<string, unknown>): Promise<ReceiverListResponse>;
+    getReceiver(params: {
+        receiverId: string;
+    }): Promise<Receiver>;
+    updateReceiverAdmin(params: {
+        receiverId: string;
+        payload: Record<string, unknown>;
+    }): Promise<Receiver>;
+    getReceiverStatus(params: {
+        receiverId: string;
+    }): Promise<ReceiverStatus>;
+    getReceiverHealth(params: {
+        receiverId: string;
+    }): Promise<ReceiverHealth>;
+    listOrgSessions(params?: Record<string, unknown>): Promise<SessionListResponse>;
+    getOrgSessionsSummary(params?: Record<string, unknown>): Promise<SessionSummaryResponse>;
+    createOrgSession(payload: Record<string, unknown>): Promise<SessionConfig>;
+    updateOrgSession(params: {
+        sessionId: string;
+        payload: Record<string, unknown>;
+    }): Promise<SessionConfig>;
+    deleteOrgSession(params: {
+        sessionId: string;
+    }): Promise<{
+        status?: string;
+    }>;
+    finalizeOrgSession(params: {
+        sessionId: string;
+    }): Promise<SessionConfig>;
+    getPresenceLive(params?: Record<string, unknown>): Promise<{
+        status?: string;
+        events?: PresenceEvent[];
+    }>;
+    getPresenceLogs(params?: Record<string, unknown>): Promise<{
+        status?: string;
+        events?: PresenceEvent[];
+    }>;
+    getPresenceEvents(params?: Record<string, unknown>): Promise<PresenceEventListResponse>;
+    listLocations(): Promise<any[]>;
+    listGroups(): Promise<any[]>;
+    createGroup(payload: Record<string, unknown>): Promise<any>;
+    updateGroup(params: {
+        groupId: string;
+        payload: Record<string, unknown>;
+    }): Promise<any>;
+    deleteGroup(params: {
+        groupId: string;
+    }): Promise<{
+        status?: string;
+    }>;
+    getAttendance(params?: Record<string, unknown>): Promise<AttendanceResponse>;
+    exportAttendanceCsv(params?: Record<string, unknown>): Promise<string>;
+    getBillingSummary(): Promise<BillingSummary>;
+    listInvoices(): Promise<Invoice[]>;
+    getInvoicePdf(params: {
+        invoiceId: string;
+    }): Promise<Uint8Array<ArrayBufferLike>>;
+    listIncidents(params?: Record<string, unknown>): Promise<IncidentListResponse>;
+    getIncident(params: {
+        incidentId: string;
+    }): Promise<Incident>;
+    getIncidentRollcall(params: {
+        incidentId: string;
+    }): Promise<IncidentRollcallResponse>;
+    getSafetyStatus(): Promise<SafetyStatus>;
+    getSafetySummary(): Promise<SafetySummary>;
+    iteratePresenceEvents(params: {
+        orgId: string;
+    } & Record<string, unknown>): AsyncGenerator<PresenceEvent, void, unknown>;
+    iteratePresenceSessions(params: {
+        orgId: string;
+    } & Record<string, unknown>): AsyncGenerator<PresenceSession, void, unknown>;
+    iterateReceivers(params: {
+        orgId: string;
+        limit?: number;
+    }): AsyncGenerator<Receiver, void, unknown>;
+    private getJson;
+    private postJson;
+    private patchJson;
+    private deleteJson;
+    private getText;
+    private getBytes;
+    private authHeaders;
+    private buildUrl;
+    private requestWithRetry;
+    private requestRaw;
+}
+/**
+ * Example:
+ * const client = new HnnpClient({ baseUrl: process.env.HNNP_URL!, apiKey: process.env.HNNP_KEY! });
+ * const events = await client.listPresenceEvents({ orgId: "test_org" });
+ */
+export declare function verifyWebhookSignature(params: {
+    secret: string;
+    timestamp: string | number;
+    rawBody: string | Buffer;
+    signature: string;
+}): boolean;
+export declare function verifyHnnpWebhook(params: {
+    rawBody: string | Buffer;
+    signature: string;
+    timestamp: string | number;
+    webhookSecret: string;
+}): boolean;

package/dist/index.js

@@ -0,0 +1,412 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HnnpClient = exports.HnnpApiError = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.verifyHnnpWebhook = verifyHnnpWebhook;
+const crypto_1 = __importDefault(require("crypto"));
+class HnnpApiError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.HnnpApiError = HnnpApiError;
+class HnnpClient {
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("Fetch API is not available. Provide a fetch implementation.");
+        }
+        this.retries = typeof opts.retries === "number" ? opts.retries : 2;
+    }
+    // ---- Receivers ----
+    async listReceivers(params) {
+        const { orgId } = params;
+        const query = {};
+        if (params.cursor)
+            query.cursor = params.cursor;
+        if (params.limit)
+            query.limit = params.limit;
+        return this.getJson(`/v2/orgs/${encodeURIComponent(orgId)}/receivers`, query);
+    }
+    async createReceiver(params) {
+        const { orgId, ...body } = params;
+        return this.postJson(`/v2/orgs/${encodeURIComponent(orgId)}/receivers`, {
+            receiver_id: body.receiverId,
+            display_name: body.displayName,
+            location_label: body.locationLabel,
+            auth_mode: body.authMode,
+            shared_secret: body.sharedSecret,
+            public_key_pem: body.publicKeyPem,
+            firmware_version: body.firmwareVersion,
+            status: body.status,
+        });
+    }
+    async updateReceiver(params) {
+        const { orgId, receiverId, ...body } = params;
+        return this.patchJson(`/v2/orgs/${encodeURIComponent(orgId)}/receivers/${encodeURIComponent(receiverId)}`, {
+            display_name: body.displayName,
+            location_label: body.locationLabel,
+            auth_mode: body.authMode,
+            shared_secret: body.sharedSecret,
+            public_key_pem: body.publicKeyPem,
+            firmware_version: body.firmwareVersion,
+            status: body.status,
+        });
+    }
+    // ---- Presence read ----
+    async listPresenceEvents(params) {
+        return this.getJson("/v1/presence/events", params);
+    }
+    async listPresenceSessions(params) {
+        return this.getJson("/v1/presence/sessions", params);
+    }
+    // ---- Links ----
+    async createLink(params) {
+        return this.postJson("/v1/links", params);
+    }
+    async activateLink(id) {
+        return this.postJson(`/v1/links/${encodeURIComponent(id)}/activate`);
+    }
+    async revokeLink(id) {
+        return this.postJson(`/v1/links/${encodeURIComponent(id)}/revoke`);
+    }
+    async listLinks(params) {
+        return this.getJson("/v1/links", params);
+    }
+    async linkPresenceSession(params) {
+        return this.postJson("/v1/links", {
+            orgId: params.orgId,
+            presenceSessionId: params.presenceSessionId,
+            userRef: params.userRef,
+        });
+    }
+    async unlink(id) {
+        return this.revokeLink(id);
+    }
+    // ---- Org console APIs ----
+    async listOrgs(params) {
+        return this.getJson("/v2/orgs", params);
+    }
+    async getOrg(params) {
+        return this.getJson(`/v2/orgs/${encodeURIComponent(params.orgId)}`);
+    }
+    async getOrgSettings(params) {
+        return this.getJson(`/v2/orgs/${encodeURIComponent(params.orgId)}/settings`);
+    }
+    async updateOrgSettings(params) {
+        return this.patchJson(`/v2/orgs/${encodeURIComponent(params.orgId)}/settings`, params.settings);
+    }
+    async getOrgConfig(params) {
+        return this.getJson(`/v2/orgs/${encodeURIComponent(params.orgId)}/config`);
+    }
+    async updateOrgConfig(params) {
+        return this.patchJson(`/v2/orgs/${encodeURIComponent(params.orgId)}/config`, params.config);
+    }
+    async getOrgMetricsRealtime(params) {
+        const { orgId, ...query } = params;
+        return this.getJson(`/v2/orgs/${encodeURIComponent(orgId)}/metrics/realtime`, query);
+    }
+    async listOrgUsers(params) {
+        return this.getJson(`/v2/orgs/${encodeURIComponent(params.orgId)}/users`);
+    }
+    // ---- Receiver health (org console) ----
+    async listReceiversAdmin(params) {
+        return this.getJson("/api/receivers", params);
+    }
+    async getReceiver(params) {
+        return this.getJson(`/api/receivers/${encodeURIComponent(params.receiverId)}`);
+    }
+    async updateReceiverAdmin(params) {
+        return this.patchJson(`/api/receivers/${encodeURIComponent(params.receiverId)}`, params.payload);
+    }
+    async getReceiverStatus(params) {
+        return this.getJson(`/api/receivers/${encodeURIComponent(params.receiverId)}/status`);
+    }
+    async getReceiverHealth(params) {
+        return this.getJson(`/api/receivers/${encodeURIComponent(params.receiverId)}/health`);
+    }
+    // ---- Sessions lifecycle ----
+    async listOrgSessions(params) {
+        return this.getJson("/api/sessions", params);
+    }
+    async getOrgSessionsSummary(params) {
+        return this.getJson("/api/sessions/summary", params);
+    }
+    async createOrgSession(payload) {
+        return this.postJson("/api/sessions", payload);
+    }
+    async updateOrgSession(params) {
+        return this.patchJson(`/api/sessions/${encodeURIComponent(params.sessionId)}`, params.payload);
+    }
+    async deleteOrgSession(params) {
+        return this.deleteJson(`/api/sessions/${encodeURIComponent(params.sessionId)}`);
+    }
+    async finalizeOrgSession(params) {
+        return this.postJson(`/api/sessions/${encodeURIComponent(params.sessionId)}/finalize`);
+    }
+    // ---- Presence + attendance ----
+    async getPresenceLive(params) {
+        return this.getJson("/api/presence/live", params);
+    }
+    async getPresenceLogs(params) {
+        return this.getJson("/api/presence/logs", params);
+    }
+    async getPresenceEvents(params) {
+        return this.getJson("/api/presence/events", params);
+    }
+    async listLocations() {
+        return this.getJson("/api/locations");
+    }
+    async listGroups() {
+        return this.getJson("/api/groups");
+    }
+    async createGroup(payload) {
+        return this.postJson("/api/groups", payload);
+    }
+    async updateGroup(params) {
+        return this.patchJson(`/api/groups/${encodeURIComponent(params.groupId)}`, params.payload);
+    }
+    async deleteGroup(params) {
+        return this.deleteJson(`/api/groups/${encodeURIComponent(params.groupId)}`);
+    }
+    async getAttendance(params) {
+        return this.getJson("/api/attendance", params);
+    }
+    async exportAttendanceCsv(params) {
+        return this.getText("/api/attendance/export", params);
+    }
+    // ---- Billing ----
+    async getBillingSummary() {
+        return this.getJson("/api/org/billing");
+    }
+    async listInvoices() {
+        return this.getJson("/api/org/invoices");
+    }
+    async getInvoicePdf(params) {
+        return this.getBytes(`/api/org/invoices/${encodeURIComponent(params.invoiceId)}/pdf`);
+    }
+    // ---- Incidents + safety ----
+    async listIncidents(params) {
+        return this.getJson("/api/incidents", params);
+    }
+    async getIncident(params) {
+        return this.getJson(`/api/incidents/${encodeURIComponent(params.incidentId)}`);
+    }
+    async getIncidentRollcall(params) {
+        return this.getJson(`/api/incidents/${encodeURIComponent(params.incidentId)}/rollcall`);
+    }
+    async getSafetyStatus() {
+        return this.getJson("/api/safety/status");
+    }
+    async getSafetySummary() {
+        return this.getJson("/api/safety/summary");
+    }
+    // ---- Pagination helpers ----
+    async *iteratePresenceEvents(params) {
+        let page = typeof params.page === "number" ? params.page : 1;
+        const limit = typeof params.limit === "number" ? params.limit : undefined;
+        while (true) {
+            const response = await this.listPresenceEvents({ ...params, page, limit });
+            const events = response?.events ?? [];
+            for (const event of events) {
+                yield event;
+            }
+            if (!response?.nextPage)
+                break;
+            page = response.nextPage;
+        }
+    }
+    async *iteratePresenceSessions(params) {
+        let page = typeof params.page === "number" ? params.page : 1;
+        const limit = typeof params.limit === "number" ? params.limit : undefined;
+        while (true) {
+            const response = await this.listPresenceSessions({ ...params, page, limit });
+            const sessions = response?.sessions ?? [];
+            for (const session of sessions) {
+                yield session;
+            }
+            if (!response?.nextPage)
+                break;
+            page = response.nextPage;
+        }
+    }
+    async *iterateReceivers(params) {
+        let cursor;
+        while (true) {
+            const response = await this.listReceivers({ orgId: params.orgId, cursor, limit: params.limit });
+            const items = response?.items ?? [];
+            for (const item of items) {
+                yield item;
+            }
+            if (!response?.nextCursor)
+                break;
+            cursor = response.nextCursor;
+        }
+    }
+    // ---- HTTP helpers ----
+    async getJson(path, query) {
+        const url = this.buildUrl(path, query);
+        return this.requestWithRetry(url, { method: "GET", headers: this.authHeaders() });
+    }
+    async postJson(path, body) {
+        const url = this.buildUrl(path);
+        return this.requestWithRetry(url, {
+            method: "POST",
+            headers: { ...this.authHeaders(), "Content-Type": "application/json" },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async patchJson(path, body) {
+        const url = this.buildUrl(path);
+        return this.requestWithRetry(url, {
+            method: "PATCH",
+            headers: { ...this.authHeaders(), "Content-Type": "application/json" },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async deleteJson(path, body) {
+        const url = this.buildUrl(path);
+        return this.requestWithRetry(url, {
+            method: "DELETE",
+            headers: { ...this.authHeaders(), "Content-Type": "application/json" },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async getText(path, query) {
+        const url = this.buildUrl(path, query);
+        const res = await this.requestRaw(url, { method: "GET", headers: this.authHeaders() });
+        return new TextDecoder().decode(res);
+    }
+    async getBytes(path, query) {
+        const url = this.buildUrl(path, query);
+        return this.requestRaw(url, { method: "GET", headers: this.authHeaders() });
+    }
+    authHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    buildUrl(path, query) {
+        const url = new URL(path, `${this.baseUrl}/`);
+        if (query) {
+            Object.entries(query).forEach(([k, v]) => {
+                if (v === undefined || v === null)
+                    return;
+                url.searchParams.set(k, String(v));
+            });
+        }
+        return url.toString();
+    }
+    async requestWithRetry(url, init, attempt = 0) {
+        try {
+            const res = await this.fetchImpl(url, init);
+            const text = await res.text();
+            const body = text ? safeJsonParse(text) : null;
+            if (!res.ok) {
+                if (res.status === 429 && attempt < this.retries) {
+                    await sleep(getRetryDelayMs(res, attempt));
+                    return this.requestWithRetry(url, init, attempt + 1);
+                }
+                throw new HnnpApiError(`HTTP ${res.status}`, res.status, body);
+            }
+            return body;
+        }
+        catch (err) {
+            if (attempt < this.retries && isRetryable(err)) {
+                await sleep(200 * (attempt + 1));
+                return this.requestWithRetry(url, init, attempt + 1);
+            }
+            throw err;
+        }
+    }
+    async requestRaw(url, init, attempt = 0) {
+        try {
+            const res = await this.fetchImpl(url, init);
+            if (!res.ok) {
+                const text = await res.text();
+                const body = text ? safeJsonParse(text) : null;
+                if (res.status === 429 && attempt < this.retries) {
+                    await sleep(getRetryDelayMs(res, attempt));
+                    return this.requestRaw(url, init, attempt + 1);
+                }
+                throw new HnnpApiError(`HTTP ${res.status}`, res.status, body);
+            }
+            const buf = new Uint8Array(await res.arrayBuffer());
+            return buf;
+        }
+        catch (err) {
+            if (attempt < this.retries && isRetryable(err)) {
+                await sleep(200 * (attempt + 1));
+                return this.requestRaw(url, init, attempt + 1);
+            }
+            throw err;
+        }
+    }
+}
+exports.HnnpClient = HnnpClient;
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isRetryable(err) {
+    if (err instanceof HnnpApiError) {
+        return (err.status >= 500 && err.status < 600) || err.status === 429;
+    }
+    return true;
+}
+function getRetryDelayMs(res, attempt) {
+    const retryAfter = res.headers.get("retry-after");
+    if (retryAfter) {
+        const parsed = Number.parseInt(retryAfter, 10);
+        if (Number.isFinite(parsed)) {
+            return Math.min(parsed * 1000, 30000);
+        }
+    }
+    return Math.min(500 * Math.pow(2, attempt), 30000);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Example:
+ * const client = new HnnpClient({ baseUrl: process.env.HNNP_URL!, apiKey: process.env.HNNP_KEY! });
+ * const events = await client.listPresenceEvents({ orgId: "test_org" });
+ */
+function verifyWebhookSignature(params) {
+    const { secret, timestamp, rawBody, signature } = params;
+    const key = Buffer.isBuffer(secret) ? secret : Buffer.from(secret, "utf8");
+    const ts = String(timestamp);
+    const bodyBuf = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, "utf8");
+    const msg = Buffer.concat([Buffer.from(ts, "utf8"), bodyBuf]);
+    const expected = crypto_1.default.createHmac("sha256", key).update(msg).digest("hex");
+    return safeTimingCompare(expected, signature);
+}
+function verifyHnnpWebhook(params) {
+    return verifyWebhookSignature({
+        secret: params.webhookSecret,
+        timestamp: params.timestamp,
+        rawBody: params.rawBody,
+        signature: params.signature,
+    });
+}
+function safeTimingCompare(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return crypto_1.default.timingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tests/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/client.test.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_1 = require("../index");
+const buildFetchMock = () => {
+    const calls = [];
+    const fetchMock = async (url, init) => {
+        calls.push({ url, init });
+        if (url.includes("/v1/presence/events")) {
+            const page = new URL(url).searchParams.get("page") ?? "1";
+            const events = page === "1" ? [{ id: "evt1" }] : [{ id: "evt2" }];
+            const nextPage = page === "1" ? 2 : null;
+            const body = JSON.stringify({ events, nextPage, page: Number(page) });
+            return {
+                ok: true,
+                status: 200,
+                text: async () => body,
+                arrayBuffer: async () => new TextEncoder().encode(body).buffer,
+            };
+        }
+        if (url.includes("/v2/orgs/org_1/receivers")) {
+            const cursor = new URL(url).searchParams.get("cursor");
+            const items = cursor ? [{ receiver_id: "rcv2" }] : [{ receiver_id: "rcv1" }];
+            const nextCursor = cursor ? null : "cursor2";
+            const body = JSON.stringify({ items, nextCursor });
+            return {
+                ok: true,
+                status: 200,
+                text: async () => body,
+                arrayBuffer: async () => new TextEncoder().encode(body).buffer,
+            };
+        }
+        const isPdf = url.includes("/pdf");
+        const body = isPdf ? "" : JSON.stringify({ ok: true });
+        return {
+            ok: true,
+            status: 200,
+            text: async () => body,
+            arrayBuffer: async () => new TextEncoder().encode("pdf").buffer,
+        };
+    };
+    return { fetchMock, calls };
+};
+(0, vitest_1.describe)("HnnpClient endpoints", () => {
+    (0, vitest_1.it)("builds correct urls and methods", async () => {
+        const { fetchMock, calls } = buildFetchMock();
+        const client = new index_1.HnnpClient({
+            baseUrl: "https://api.example",
+            apiKey: "test_key",
+            fetch: fetchMock,
+        });
+        await client.listReceivers({ orgId: "org_1" });
+        await client.createReceiver({ orgId: "org_1", receiverId: "rcv1", authMode: "token" });
+        await client.updateReceiver({ orgId: "org_1", receiverId: "rcv1", status: "active" });
+        await client.listPresenceEvents({ orgId: "org_1", userRef: "user_1" });
+        await client.listPresenceSessions({ orgId: "org_1", receiverId: "rcv1" });
+        await client.createLink({ orgId: "org_1", userRef: "user_1" });
+        await client.activateLink("link_1");
+        await client.revokeLink("link_2");
+        await client.listLinks({ orgId: "org_1" });
+        await client.linkPresenceSession({ orgId: "org_1", presenceSessionId: "psess_1", userRef: "user_1" });
+        await client.unlink("link_3");
+        await client.listOrgs();
+        await client.getOrg({ orgId: "org_1" });
+        await client.getOrgSettings({ orgId: "org_1" });
+        await client.updateOrgSettings({ orgId: "org_1", settings: { timezone: "UTC" } });
+        await client.getOrgConfig({ orgId: "org_1" });
+        await client.updateOrgConfig({ orgId: "org_1", config: { modules: ["attendance"] } });
+        await client.getOrgMetricsRealtime({ orgId: "org_1" });
+        await client.listOrgUsers({ orgId: "org_1" });
+        await client.listReceiversAdmin();
+        await client.getReceiver({ receiverId: "rcv1" });
+        await client.updateReceiverAdmin({ receiverId: "rcv1", payload: { status: "active" } });
+        await client.getReceiverStatus({ receiverId: "rcv1" });
+        await client.getReceiverHealth({ receiverId: "rcv1" });
+        await client.listOrgSessions();
+        await client.getOrgSessionsSummary();
+        await client.createOrgSession({ name: "Session 1" });
+        await client.updateOrgSession({ sessionId: "s1", payload: { name: "Updated" } });
+        await client.deleteOrgSession({ sessionId: "s1" });
+        await client.finalizeOrgSession({ sessionId: "s1" });
+        await client.getPresenceLive();
+        await client.getPresenceLogs();
+        await client.getPresenceEvents();
+        await client.listLocations();
+        await client.listGroups();
+        await client.createGroup({ name: "Group 1" });
+        await client.updateGroup({ groupId: "g1", payload: { name: "Group 1b" } });
+        await client.deleteGroup({ groupId: "g1" });
+        await client.getAttendance();
+        await client.exportAttendanceCsv();
+        await client.getBillingSummary();
+        await client.listInvoices();
+        await client.getInvoicePdf({ invoiceId: "inv_1" });
+        await client.listIncidents();
+        await client.getIncident({ incidentId: "inc_1" });
+        await client.getIncidentRollcall({ incidentId: "inc_1" });
+        await client.getSafetyStatus();
+        await client.getSafetySummary();
+        const methods = calls.map((c) => c.init?.method ?? "GET");
+        (0, vitest_1.expect)(methods).toContain("POST");
+        (0, vitest_1.expect)(methods).toContain("PATCH");
+        (0, vitest_1.expect)(methods).toContain("DELETE");
+        const urls = calls.map((c) => c.url);
+        (0, vitest_1.expect)(urls).toContain("https://api.example/v2/orgs/org_1/receivers");
+        (0, vitest_1.expect)(urls).toContain("https://api.example/v1/presence/events?orgId=org_1&userRef=user_1");
+        (0, vitest_1.expect)(urls).toContain("https://api.example/api/sessions/s1/finalize");
+        (0, vitest_1.expect)(urls).toContain("https://api.example/api/org/invoices/inv_1/pdf");
+    });
+    (0, vitest_1.it)("iterates paginated endpoints", async () => {
+        const { fetchMock } = buildFetchMock();
+        const client = new index_1.HnnpClient({
+            baseUrl: "https://api.example",
+            apiKey: "test_key",
+            fetch: fetchMock,
+        });
+        const events = [];
+        for await (const evt of client.iteratePresenceEvents({ orgId: "org_1" })) {
+            events.push(evt.id);
+        }
+        (0, vitest_1.expect)(events).toEqual(["evt1", "evt2"]);
+        const receivers = [];
+        for await (const rcv of client.iterateReceivers({ orgId: "org_1" })) {
+            receivers.push(rcv.receiver_id);
+        }
+        (0, vitest_1.expect)(receivers).toEqual(["rcv1", "rcv2"]);
+    });
+});

package/dist/tests/webhook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/webhook.test.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_1 = require("../index");
+(0, vitest_1.describe)("verifyWebhookSignature", () => {
+    const secret = "webhook_secret_test";
+    const timestamp = "1700000000";
+    const rawBody = '{"hello":"world"}';
+    (0, vitest_1.it)("accepts valid signature", () => {
+        const crypto = require("crypto");
+        const msg = Buffer.concat([Buffer.from(timestamp, "utf8"), Buffer.from(rawBody, "utf8")]);
+        const expected = crypto.createHmac("sha256", Buffer.from(secret, "utf8")).update(msg).digest("hex");
+        const result = (0, index_1.verifyWebhookSignature)({
+            secret,
+            timestamp,
+            rawBody,
+            signature: expected,
+        });
+        (0, vitest_1.expect)(result).toBe(true);
+    });
+    (0, vitest_1.it)("rejects invalid signature", () => {
+        const result = (0, index_1.verifyWebhookSignature)({
+            secret,
+            timestamp,
+            rawBody,
+            signature: "deadbeef",
+        });
+        (0, vitest_1.expect)(result).toBe(false);
+    });
+    (0, vitest_1.it)("rejects when length differs", () => {
+        const result = (0, index_1.verifyWebhookSignature)({
+            secret,
+            timestamp,
+            rawBody,
+            signature: "00",
+        });
+        (0, vitest_1.expect)(result).toBe(false);
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,268 @@
+export interface Receiver {
+    receiver_id?: string;
+    org_id?: string;
+    display_name?: string | null;
+    location_label?: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    auth_mode?: string | null;
+    firmware_version?: string | null;
+    status?: string | null;
+    last_seen_at?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface ReceiverListResponse {
+    items?: Receiver[];
+    nextCursor?: string | null;
+}
+export interface ReceiverStatus {
+    id?: string;
+    receiver_id?: string;
+    status?: string;
+    last_seen_at?: string | null;
+    incidents?: unknown[];
+}
+export interface ReceiverHealth {
+    receiver_id?: string;
+    status?: string;
+    last_seen_at?: string | null;
+    metrics?: Record<string, unknown>;
+}
+export interface PresenceEvent {
+    id?: string;
+    org_id?: string;
+    receiver_id?: string | null;
+    user_ref?: string | null;
+    member_id?: string | null;
+    location_id?: string | null;
+    timestamp?: string | null;
+    verification_status?: string | null;
+    loa_level?: string | null;
+    reason_codes?: string[] | null;
+    session_id?: string | null;
+    device_id_hash?: string | null;
+    client_timestamp_ms?: number | null;
+    server_timestamp?: string | null;
+    time_slot?: string | null;
+    version?: string | null;
+    flags?: Record<string, unknown> | null;
+    token_prefix?: string | null;
+    auth_result?: string | null;
+    is_anonymous?: boolean | null;
+    reason?: string | null;
+    meta?: Record<string, unknown> | null;
+}
+export interface PresenceEventListResponse {
+    status?: string;
+    page?: number;
+    nextPage?: number | null;
+    events?: PresenceEvent[];
+}
+export interface PresenceSession {
+    id?: string;
+    org_id?: string;
+    receiver_id?: string | null;
+    user_ref?: string | null;
+    device_id_hash?: string | null;
+    started_at?: string | null;
+    ended_at?: string | null;
+    session_id?: string | null;
+    session_type?: string | null;
+}
+export interface PresenceSessionListResponse {
+    status?: string;
+    page?: number;
+    nextPage?: number | null;
+    sessions?: PresenceSession[];
+}
+export interface Link {
+    id?: string;
+    org_id?: string;
+    user_ref?: string;
+    device_id?: string | null;
+    status?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+export interface LinkListResponse {
+    status?: string;
+    links?: Link[];
+    items?: Link[];
+}
+export interface LinkResponse {
+    status?: string;
+    link?: Link;
+}
+export interface Org {
+    id?: string;
+    name?: string | null;
+    slug?: string | null;
+    status?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    plan?: string | null;
+    enabled_modules?: string[] | null;
+}
+export interface OrgListResponse {
+    items?: Org[];
+    nextCursor?: string | null;
+}
+export interface OrgSettings {
+    timezone?: string | null;
+    region?: string | null;
+    country?: string | null;
+    [key: string]: unknown;
+}
+export interface OrgConfig {
+    [key: string]: unknown;
+}
+export interface RealtimeMetrics {
+    active_receivers?: number;
+    receivers_window_minutes?: number;
+    active_sessions?: number;
+    present_users?: number;
+    incidents_open?: number;
+    [key: string]: unknown;
+}
+export interface OrgUser {
+    id?: string;
+    email?: string | null;
+    name?: string | null;
+    role?: string | null;
+    status?: string | null;
+}
+export interface SessionConfig {
+    id?: string;
+    session_id?: string;
+    name?: string;
+    startTime?: string | null;
+    endTime?: string | null;
+    locationId?: string | null;
+    groupId?: string | null;
+    sessionType?: string | null;
+    finalizedAt?: string | null;
+    reportUrl?: string | null;
+}
+export interface SessionSummary {
+    session_id?: string;
+    session_name?: string;
+    present_count?: number;
+    late_count?: number;
+    absent_count?: number;
+    total_count?: number;
+}
+export interface SessionSummaryResponse {
+    sessions?: SessionSummary[];
+}
+export interface SessionListResponse {
+    items?: SessionConfig[];
+    page?: number;
+    pageSize?: number;
+    totalPages?: number;
+    totalCount?: number;
+}
+export interface AttendanceSummary {
+    session_id?: string;
+    name?: string;
+    date?: string;
+    startTime?: string;
+    endTime?: string;
+    locationId?: string | null;
+    groupId?: string | null;
+    presentCount?: number;
+    lateCount?: number;
+    absentCount?: number;
+    totalCount?: number;
+}
+export interface AttendanceResponse {
+    sessions?: AttendanceSummary[];
+    rules?: Record<string, unknown>;
+    page?: number;
+    nextPage?: number | null;
+}
+export interface BillingDecision {
+    id?: string;
+    session_id?: string | null;
+    session_type?: string | null;
+    verified_count?: number | null;
+    base_price_cents?: number | null;
+    overage_count?: number | null;
+    overage_price_cents?: number | null;
+    quiz_count?: number | null;
+    quiz_fee_cents?: number | null;
+    final_price_cents?: number | null;
+    finalized_at?: string | null;
+    invoice_id?: string | null;
+}
+export interface InvoiceLine {
+    id?: string;
+    kind?: string;
+    reference_id?: string | null;
+    description?: string | null;
+    quantity?: number | null;
+    unit_price_cents?: number | null;
+    total_cents?: number | null;
+}
+export interface Invoice {
+    id?: string;
+    status?: string;
+    period_start?: string;
+    period_end?: string;
+    total_cents?: number;
+    currency?: string | null;
+    created_at?: string;
+    lines?: InvoiceLine[];
+}
+export interface BillingSummary {
+    plan?: string | null;
+    seat_count?: number;
+    seat_price_cents?: number;
+    seat_total_cents?: number;
+    decision_count?: number;
+    decision_total_cents?: number;
+    unbilled_decision_count?: number;
+    total_cents?: number;
+    period_start?: string;
+    period_end?: string;
+    decisions?: BillingDecision[];
+    invoices?: Invoice[];
+    last_invoice?: Invoice | null;
+}
+export interface Incident {
+    id?: string;
+    type?: string;
+    severity?: string;
+    status?: string;
+    started_at?: string | null;
+    resolved_at?: string | null;
+    location_id?: string | null;
+    workzone_id?: string | null;
+    created_by?: string | null;
+    notes?: string | null;
+    timestamp?: string;
+    title?: string;
+    description?: string;
+    use_case?: string;
+}
+export interface IncidentListResponse {
+    items?: Incident[];
+    page?: number;
+    pageSize?: number;
+    totalPages?: number;
+    totalCount?: number;
+    incidents?: Incident[];
+}
+export interface IncidentRollcallResponse {
+    incident?: Incident;
+    rollcall?: unknown[];
+    summary?: Record<string, unknown>;
+}
+export interface SafetyStatus {
+    active_incidents?: Incident[];
+    [key: string]: unknown;
+}
+export interface SafetySummary {
+    totals?: Record<string, unknown>;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hnnp/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "HNNP Node.js SDK",
   "license": "UNLICENSED",
@@ -24,7 +24,8 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "typescript": "^5.5.0",