nixflex 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nixflex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -75,6 +75,43 @@ try {
 - **Timeouts + AbortSignal support** per client or per request
 - **Zero runtime dependencies** — native fetch, Node 18+
 
+## Verifying webhooks
+
+Nixflex signs every webhook delivery with an `X-Nixflex-Signature` header. Verify it before trusting a payload — pass the **raw** request body, not a re-serialized object:
+
+```js
+import express from 'express';
+import { verifyWebhookSignature } from 'nixflex';
+
+const app = express();
+
+app.post('/nixflex/calls', express.raw({ type: 'application/json' }), (req, res) => {
+  const ok = verifyWebhookSignature(
+    req.body,                                  // raw Buffer
+    req.get('x-nixflex-signature'),
+    process.env.NIXFLEX_KEY_SECRET             // the nxfs_... half of your key
+  );
+  if (!ok) return res.sendStatus(400);
+
+  const event = JSON.parse(req.body.toString('utf8'));
+  // handle event.event === 'call.completed'
+  res.sendStatus(200);
+});
+```
+
+Returns `false` for a tampered body, wrong secret, malformed header, or a signature older than the tolerance window (300 seconds; override with `{ toleranceSeconds }`). It never throws.
+
+## Deleting call data
+
+```js
+await client.calls.delete(callId);   // one call: record, transcript, recording
+await client.calls.deleteAll();      // everything on the key
+```
+
+Both are immediate and irreversible — fetch anything you need to keep first.
+
 ## Docs
 
 Full API reference: **https://docs.nixflex.com**
+
+Release history: [CHANGELOG.md](CHANGELOG.md). Licensed under [MIT](LICENSE).

package/dist/index.cjs

@@ -29,7 +29,8 @@ __export(index_exports, {
   NixflexRateLimitError: () => NixflexRateLimitError,
   NixflexServerError: () => NixflexServerError,
   default: () => index_default,
-  errorFromResponse: () => errorFromResponse
+  errorFromResponse: () => errorFromResponse,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -285,6 +286,16 @@ var Calls = class {
   get(callId, opts) {
     return this.http.request("GET", `/calls/${encodeURIComponent(callId)}`, void 0, void 0, opts);
   }
+  /** GDPR: PERMANENTLY erase one call - the record AND its recording file.
+   * Irreversible. Throws NixflexNotFoundError if the ID is not yours. */
+  delete(callId, opts) {
+    return this.http.request("DELETE", `/calls/${encodeURIComponent(callId)}`, void 0, void 0, opts);
+  }
+  /** GDPR: PERMANENTLY erase ALL calls, recordings, and SMS messages on this
+   * key. Irreversible - intended for data-erasure requests and offboarding. */
+  deleteAll(opts) {
+    return this.http.request("DELETE", "/calls", void 0, void 0, opts);
+  }
 };
 var Campaigns = class {
   constructor(http) {
@@ -306,6 +317,33 @@ var Campaigns = class {
   }
 };
 
+// src/webhook-verify.ts
+var import_node_crypto = require("crypto");
+function verifyWebhookSignature(rawBody, signatureHeader, keySecret, options = {}) {
+  try {
+    if (!signatureHeader || !keySecret) return false;
+    const parts = {};
+    for (const seg of signatureHeader.split(",")) {
+      const i = seg.indexOf("=");
+      if (i > 0) parts[seg.slice(0, i).trim()] = seg.slice(i + 1).trim();
+    }
+    const t = parseInt(parts["t"] || "", 10);
+    const v1 = parts["v1"] || "";
+    if (!isFinite(t) || !/^[0-9a-f]{64}$/.test(v1)) return false;
+    const tolerance = options.toleranceSeconds ?? 300;
+    const now = options.now ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - t) > tolerance) return false;
+    const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    const expected = (0, import_node_crypto.createHmac)("sha256", keySecret).update(t + "." + body).digest("hex");
+    const a = Buffer.from(expected, "hex");
+    const b = Buffer.from(v1, "hex");
+    if (a.length !== b.length) return false;
+    return (0, import_node_crypto.timingSafeEqual)(a, b);
+  } catch {
+    return false;
+  }
+}
+
 // src/resources/stage3.ts
 function enc(phoneNumber) {
   return encodeURIComponent(phoneNumber);
@@ -432,6 +470,12 @@ var Webhooks = class {
     this.http = http;
   }
   http;
+  /** Verify a webhook delivery's X-Nixflex-Signature header. Pass the RAW
+   * request body (string or Buffer) and your key_secret. Returns true only
+   * for an authentic, fresh signature. See webhook-verify.ts. */
+  verify(rawBody, signatureHeader, keySecret, options) {
+    return verifyWebhookSignature(rawBody, signatureHeader, keySecret, options);
+  }
   /** Point a number's post-call events at your HTTPS endpoint.
    * slot 2 = the second destination (webhook2). */
   set(phoneNumber, url, slot = 1, opts) {
@@ -512,5 +556,6 @@ var index_default = Nixflex;
   NixflexPaymentRequiredError,
   NixflexRateLimitError,
   NixflexServerError,
-  errorFromResponse
+  errorFromResponse,
+  verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -281,6 +281,18 @@ interface BatchLaunchResponse {
     recipients_count: number;
     queued_count: number;
 }
+interface CallDeleteResponse {
+    call_id: string;
+    deleted: boolean;
+    /** Whether a recording file was found and removed from storage. */
+    recording_deleted: boolean;
+}
+interface CallDeleteAllResponse {
+    deleted: boolean;
+    calls_deleted: number;
+    recordings_deleted: number;
+    sms_deleted: number;
+}
 
 declare class Calls {
     private readonly http;
@@ -302,6 +314,12 @@ declare class Calls {
      * excluded, so it will not equal end_timestamp - start_timestamp on
      * outbound calls. */
     get(callId: string, opts?: RequestOptions): Promise<Call>;
+    /** GDPR: PERMANENTLY erase one call - the record AND its recording file.
+     * Irreversible. Throws NixflexNotFoundError if the ID is not yours. */
+    delete(callId: string, opts?: RequestOptions): Promise<CallDeleteResponse>;
+    /** GDPR: PERMANENTLY erase ALL calls, recordings, and SMS messages on this
+     * key. Irreversible - intended for data-erasure requests and offboarding. */
+    deleteAll(opts?: RequestOptions): Promise<CallDeleteAllResponse>;
 }
 
 declare class Campaigns {
@@ -318,6 +336,15 @@ declare class Campaigns {
     launch(campaignId: string, opts?: RequestOptions): Promise<BatchLaunchResponse>;
 }
 
+interface VerifyOptions {
+    /** Max allowed age of the signature in seconds (replay protection). Default 300. */
+    toleranceSeconds?: number;
+    /** Override "now" (unix seconds) - for testing. */
+    now?: number;
+}
+/** Returns true only if the signature is authentic AND fresh. Never throws. */
+declare function verifyWebhookSignature(rawBody: string | Buffer, signatureHeader: string | null | undefined, keySecret: string, options?: VerifyOptions): boolean;
+
 /** Import params - the carrier is INFERRED from which credentials you send.
  * Twilio: twilio_sid + twilio_token. Telnyx: telnyx_api_key + telnyx_connection_id
  * (the ID of a TeXML Application you created in your Telnyx portal, voice webhook
@@ -609,6 +636,10 @@ declare class UsageResource {
 declare class Webhooks {
     private readonly http;
     constructor(http: HttpClient);
+    /** Verify a webhook delivery's X-Nixflex-Signature header. Pass the RAW
+     * request body (string or Buffer) and your key_secret. Returns true only
+     * for an authentic, fresh signature. See webhook-verify.ts. */
+    verify(rawBody: string | Buffer, signatureHeader: string | null | undefined, keySecret: string, options?: VerifyOptions): boolean;
     /** Point a number's post-call events at your HTTPS endpoint.
      * slot 2 = the second destination (webhook2). */
     set(phoneNumber: string, url: string, slot?: 1 | 2, opts?: RequestOptions): Promise<WebhookConfigResponse>;
@@ -701,4 +732,4 @@ declare class Nixflex {
     }, baseUrl?: string): Promise<KeyCreateResponse>;
 }
 
-export { type Agent, type AgentCreateParams, type AgentDeleteResponse, type AgentUpdateParams, type BatchCampaignParams, type BatchCreateResponse, type BatchInvalidEntry, type BatchLaunchResponse, type BatchRecipient, type Call, type CallDirection, type CallerSentiment, type KeyCreateResponse, type KeyRotateResponse, type ListParams, type MonitorToggleResponse, Nixflex, type NixflexAPIErrorBody, NixflexAuthenticationError, type NixflexClientOptions, NixflexConnectionError, NixflexError, NixflexInvalidRequestError, NixflexNotFoundError, NixflexPaymentRequiredError, NixflexRateLimitError, NixflexServerError, type OutboundCallParams, type OutboundCallResponse, type PhoneNumber, type PhoneNumberDeleteResponse, type PhoneNumberImportParams, type PhoneNumberListResponse, type PhoneNumberUpdateParams, type RequestOptions, type ResponseLength, type SmsCampaign, type SmsCampaignCreateParams, type SmsCampaignDeleteResponse, type SmsCampaignLaunchResponse, type SmsCampaignListResponse, type SmsCampaignRecipient, type SmsCampaignStatus, type SmsSendParams, type SmsSendResponse, type TransferType, type Usage, type WebCallsToggleResponse, type WebhookConfigResponse, type Weekday, Nixflex as default, errorFromResponse };
+export { type Agent, type AgentCreateParams, type AgentDeleteResponse, type AgentUpdateParams, type BatchCampaignParams, type BatchCreateResponse, type BatchInvalidEntry, type BatchLaunchResponse, type BatchRecipient, type Call, type CallDeleteAllResponse, type CallDeleteResponse, type CallDirection, type CallerSentiment, type KeyCreateResponse, type KeyRotateResponse, type ListParams, type MonitorToggleResponse, Nixflex, type NixflexAPIErrorBody, NixflexAuthenticationError, type NixflexClientOptions, NixflexConnectionError, NixflexError, NixflexInvalidRequestError, NixflexNotFoundError, NixflexPaymentRequiredError, NixflexRateLimitError, NixflexServerError, type OutboundCallParams, type OutboundCallResponse, type PhoneNumber, type PhoneNumberDeleteResponse, type PhoneNumberImportParams, type PhoneNumberListResponse, type PhoneNumberUpdateParams, type RequestOptions, type ResponseLength, type SmsCampaign, type SmsCampaignCreateParams, type SmsCampaignDeleteResponse, type SmsCampaignLaunchResponse, type SmsCampaignListResponse, type SmsCampaignRecipient, type SmsCampaignStatus, type SmsSendParams, type SmsSendResponse, type TransferType, type Usage, type VerifyOptions, type WebCallsToggleResponse, type WebhookConfigResponse, type Weekday, Nixflex as default, errorFromResponse, verifyWebhookSignature };

package/dist/index.d.ts

@@ -281,6 +281,18 @@ interface BatchLaunchResponse {
     recipients_count: number;
     queued_count: number;
 }
+interface CallDeleteResponse {
+    call_id: string;
+    deleted: boolean;
+    /** Whether a recording file was found and removed from storage. */
+    recording_deleted: boolean;
+}
+interface CallDeleteAllResponse {
+    deleted: boolean;
+    calls_deleted: number;
+    recordings_deleted: number;
+    sms_deleted: number;
+}
 
 declare class Calls {
     private readonly http;
@@ -302,6 +314,12 @@ declare class Calls {
      * excluded, so it will not equal end_timestamp - start_timestamp on
      * outbound calls. */
     get(callId: string, opts?: RequestOptions): Promise<Call>;
+    /** GDPR: PERMANENTLY erase one call - the record AND its recording file.
+     * Irreversible. Throws NixflexNotFoundError if the ID is not yours. */
+    delete(callId: string, opts?: RequestOptions): Promise<CallDeleteResponse>;
+    /** GDPR: PERMANENTLY erase ALL calls, recordings, and SMS messages on this
+     * key. Irreversible - intended for data-erasure requests and offboarding. */
+    deleteAll(opts?: RequestOptions): Promise<CallDeleteAllResponse>;
 }
 
 declare class Campaigns {
@@ -318,6 +336,15 @@ declare class Campaigns {
     launch(campaignId: string, opts?: RequestOptions): Promise<BatchLaunchResponse>;
 }
 
+interface VerifyOptions {
+    /** Max allowed age of the signature in seconds (replay protection). Default 300. */
+    toleranceSeconds?: number;
+    /** Override "now" (unix seconds) - for testing. */
+    now?: number;
+}
+/** Returns true only if the signature is authentic AND fresh. Never throws. */
+declare function verifyWebhookSignature(rawBody: string | Buffer, signatureHeader: string | null | undefined, keySecret: string, options?: VerifyOptions): boolean;
+
 /** Import params - the carrier is INFERRED from which credentials you send.
  * Twilio: twilio_sid + twilio_token. Telnyx: telnyx_api_key + telnyx_connection_id
  * (the ID of a TeXML Application you created in your Telnyx portal, voice webhook
@@ -609,6 +636,10 @@ declare class UsageResource {
 declare class Webhooks {
     private readonly http;
     constructor(http: HttpClient);
+    /** Verify a webhook delivery's X-Nixflex-Signature header. Pass the RAW
+     * request body (string or Buffer) and your key_secret. Returns true only
+     * for an authentic, fresh signature. See webhook-verify.ts. */
+    verify(rawBody: string | Buffer, signatureHeader: string | null | undefined, keySecret: string, options?: VerifyOptions): boolean;
     /** Point a number's post-call events at your HTTPS endpoint.
      * slot 2 = the second destination (webhook2). */
     set(phoneNumber: string, url: string, slot?: 1 | 2, opts?: RequestOptions): Promise<WebhookConfigResponse>;
@@ -701,4 +732,4 @@ declare class Nixflex {
     }, baseUrl?: string): Promise<KeyCreateResponse>;
 }
 
-export { type Agent, type AgentCreateParams, type AgentDeleteResponse, type AgentUpdateParams, type BatchCampaignParams, type BatchCreateResponse, type BatchInvalidEntry, type BatchLaunchResponse, type BatchRecipient, type Call, type CallDirection, type CallerSentiment, type KeyCreateResponse, type KeyRotateResponse, type ListParams, type MonitorToggleResponse, Nixflex, type NixflexAPIErrorBody, NixflexAuthenticationError, type NixflexClientOptions, NixflexConnectionError, NixflexError, NixflexInvalidRequestError, NixflexNotFoundError, NixflexPaymentRequiredError, NixflexRateLimitError, NixflexServerError, type OutboundCallParams, type OutboundCallResponse, type PhoneNumber, type PhoneNumberDeleteResponse, type PhoneNumberImportParams, type PhoneNumberListResponse, type PhoneNumberUpdateParams, type RequestOptions, type ResponseLength, type SmsCampaign, type SmsCampaignCreateParams, type SmsCampaignDeleteResponse, type SmsCampaignLaunchResponse, type SmsCampaignListResponse, type SmsCampaignRecipient, type SmsCampaignStatus, type SmsSendParams, type SmsSendResponse, type TransferType, type Usage, type WebCallsToggleResponse, type WebhookConfigResponse, type Weekday, Nixflex as default, errorFromResponse };
+export { type Agent, type AgentCreateParams, type AgentDeleteResponse, type AgentUpdateParams, type BatchCampaignParams, type BatchCreateResponse, type BatchInvalidEntry, type BatchLaunchResponse, type BatchRecipient, type Call, type CallDeleteAllResponse, type CallDeleteResponse, type CallDirection, type CallerSentiment, type KeyCreateResponse, type KeyRotateResponse, type ListParams, type MonitorToggleResponse, Nixflex, type NixflexAPIErrorBody, NixflexAuthenticationError, type NixflexClientOptions, NixflexConnectionError, NixflexError, NixflexInvalidRequestError, NixflexNotFoundError, NixflexPaymentRequiredError, NixflexRateLimitError, NixflexServerError, type OutboundCallParams, type OutboundCallResponse, type PhoneNumber, type PhoneNumberDeleteResponse, type PhoneNumberImportParams, type PhoneNumberListResponse, type PhoneNumberUpdateParams, type RequestOptions, type ResponseLength, type SmsCampaign, type SmsCampaignCreateParams, type SmsCampaignDeleteResponse, type SmsCampaignLaunchResponse, type SmsCampaignListResponse, type SmsCampaignRecipient, type SmsCampaignStatus, type SmsSendParams, type SmsSendResponse, type TransferType, type Usage, type VerifyOptions, type WebCallsToggleResponse, type WebhookConfigResponse, type Weekday, Nixflex as default, errorFromResponse, verifyWebhookSignature };

package/dist/index.js

@@ -250,6 +250,16 @@ var Calls = class {
   get(callId, opts) {
     return this.http.request("GET", `/calls/${encodeURIComponent(callId)}`, void 0, void 0, opts);
   }
+  /** GDPR: PERMANENTLY erase one call - the record AND its recording file.
+   * Irreversible. Throws NixflexNotFoundError if the ID is not yours. */
+  delete(callId, opts) {
+    return this.http.request("DELETE", `/calls/${encodeURIComponent(callId)}`, void 0, void 0, opts);
+  }
+  /** GDPR: PERMANENTLY erase ALL calls, recordings, and SMS messages on this
+   * key. Irreversible - intended for data-erasure requests and offboarding. */
+  deleteAll(opts) {
+    return this.http.request("DELETE", "/calls", void 0, void 0, opts);
+  }
 };
 var Campaigns = class {
   constructor(http) {
@@ -271,6 +281,33 @@ var Campaigns = class {
   }
 };
 
+// src/webhook-verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(rawBody, signatureHeader, keySecret, options = {}) {
+  try {
+    if (!signatureHeader || !keySecret) return false;
+    const parts = {};
+    for (const seg of signatureHeader.split(",")) {
+      const i = seg.indexOf("=");
+      if (i > 0) parts[seg.slice(0, i).trim()] = seg.slice(i + 1).trim();
+    }
+    const t = parseInt(parts["t"] || "", 10);
+    const v1 = parts["v1"] || "";
+    if (!isFinite(t) || !/^[0-9a-f]{64}$/.test(v1)) return false;
+    const tolerance = options.toleranceSeconds ?? 300;
+    const now = options.now ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - t) > tolerance) return false;
+    const body = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+    const expected = createHmac("sha256", keySecret).update(t + "." + body).digest("hex");
+    const a = Buffer.from(expected, "hex");
+    const b = Buffer.from(v1, "hex");
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
 // src/resources/stage3.ts
 function enc(phoneNumber) {
   return encodeURIComponent(phoneNumber);
@@ -397,6 +434,12 @@ var Webhooks = class {
     this.http = http;
   }
   http;
+  /** Verify a webhook delivery's X-Nixflex-Signature header. Pass the RAW
+   * request body (string or Buffer) and your key_secret. Returns true only
+   * for an authentic, fresh signature. See webhook-verify.ts. */
+  verify(rawBody, signatureHeader, keySecret, options) {
+    return verifyWebhookSignature(rawBody, signatureHeader, keySecret, options);
+  }
   /** Point a number's post-call events at your HTTPS endpoint.
    * slot 2 = the second destination (webhook2). */
   set(phoneNumber, url, slot = 1, opts) {
@@ -477,5 +520,6 @@ export {
   NixflexRateLimitError,
   NixflexServerError,
   index_default as default,
-  errorFromResponse
+  errorFromResponse,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,11 +1,29 @@
 {
   "name": "nixflex",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Official Node.js SDK for the Nixflex voice AI platform - AI phone agents, outbound campaigns, and SMS.",
-  "keywords": ["nixflex", "voice ai", "ai phone agent", "telephony", "sms", "voice agent", "ai calls"],
-  "homepage": "https://docs.nixflex.com",
-  "bugs": { "url": "https://github.com/nixflex/nixflex-node/issues" },
-  "repository": { "type": "git", "url": "git+https://github.com/nixflex/nixflex-node.git" },
+  "keywords": [
+    "nixflex",
+    "voice-ai",
+    "voice-agent",
+    "phone",
+    "telephony",
+    "ai-receptionist",
+    "twilio",
+    "telnyx",
+    "sms",
+    "speech",
+    "api-client",
+    "sdk"
+  ],
+  "homepage": "https://github.com/nixflex/nixflex-node#readme",
+  "bugs": {
+    "url": "https://github.com/nixflex/nixflex-node/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nixflex/nixflex-node.git"
+  },
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,15 +36,23 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "check": "node --test tests/*.test.cjs",
     "prepublishOnly": "npm run build && npm run check"
   },
   "devDependencies": {
+    "@types/node": "^26.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0"
-  }
+  },
+  "author": "Nixflex"
 }