silon-sdk 0.2.0

package/dist/types/whatsapp-templates.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Types for the WhatsAppTemplates resource.
+ *
+ * Field names mirror the wire format exactly (snake_case) and date-times are
+ * ISO-8601 strings — this SDK performs no casing or date transformation.
+ */
+/** One fillable variable of a WhatsApp template. */
+export interface WhatsAppTemplateVariable {
+    /** Use this key in the send `whatsapp_template.variables` map. */
+    key: string;
+    /** Human label shown in the dashboard composer. */
+    label: string;
+}
+/** The WhatsApp Business Account a template belongs to. */
+export interface Waba {
+    id?: number | null;
+    name?: string | null;
+}
+/**
+ * A single approved WhatsApp template.
+ *
+ * `components` (the raw Meta-shaped payload) is only present on the detail
+ * endpoint; the list endpoint omits it.
+ */
+export interface WhatsAppTemplate {
+    id: number;
+    /** Pass as `whatsapp_template.name` when sending a Meta-Cloud template. */
+    name: string;
+    /** BCP-47-ish template language, e.g. `"en"`, `"ar"`. */
+    language: string;
+    /** Meta category, e.g. `"UTILITY"`, `"MARKETING"`. */
+    category: string;
+    /** Meta review status, e.g. `"APPROVED"`. */
+    status: string;
+    /** Meta's template id. */
+    external_id: string;
+    waba: Waba;
+    /** Human-readable body preview with `{{n}}` placeholders. */
+    preview: string;
+    mode: string;
+    variables: WhatsAppTemplateVariable[];
+    /** Raw Meta component payload — detail endpoint only. */
+    components?: Array<Record<string, unknown>> | null;
+}
+/** Body of `GET /api/v1/whatsapp/templates/`. */
+export interface WhatsAppTemplateList {
+    count: number;
+    results: WhatsAppTemplate[];
+}
+/** Query filters for {@link WhatsAppTemplates.list}. */
+export interface WhatsAppTemplateListParams {
+    /** Filter by template name (contains). */
+    name?: string | null;
+    /** Filter by template language, e.g. `"en"`. */
+    language?: string | null;
+    /** Filter by WhatsApp Business Account id. */
+    waba_id?: number | null;
+}
+//# sourceMappingURL=whatsapp-templates.d.ts.map

package/dist/types/whatsapp-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-templates.d.ts","sourceRoot":"","sources":["../../src/types/whatsapp-templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2DAA2D;AAC3D,MAAM,WAAW,IAAI;IACnB,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,IAAI,CAAC;IACX,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACtC,yDAAyD;IACzD,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CACpD;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,wDAAwD;AACxD,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB"}

package/dist/types/whatsapp-templates.js

@@ -0,0 +1,8 @@
+/**
+ * Types for the WhatsAppTemplates resource.
+ *
+ * Field names mirror the wire format exactly (snake_case) and date-times are
+ * ISO-8601 strings — this SDK performs no casing or date transformation.
+ */
+export {};
+//# sourceMappingURL=whatsapp-templates.js.map

package/dist/types/whatsapp-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp-templates.js","sourceRoot":"","sources":["../../src/types/whatsapp-templates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** SDK version, sent in the `User-Agent` header of every request. */
+export declare const VERSION = "0.2.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+/** SDK version, sent in the `User-Agent` header of every request. */
+export const VERSION = "0.2.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/webhooks.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Verify Silon webhook deliveries — no HTTP client needed.
+ *
+ * Every delivery to a webhook endpoint carries a `Silon-Signature` header of
+ * the Stripe-style form `t=<unix_ts>,v1=<hex_hmac>`, where the HMAC-SHA256 is
+ * taken over `<unix_ts>.<raw_request_body>` with the endpoint's `whsec_`
+ * secret. Typical usage in a request handler:
+ *
+ * ```ts
+ * import { webhooks } from "silon-sdk";
+ *
+ * const event = webhooks.constructEvent(
+ *   rawBody,                                    // raw string/bytes, not parsed JSON
+ *   req.headers["silon-signature"],
+ *   process.env.SILON_WEBHOOK_SECRET,
+ * );
+ * if (event.type === "message.failed") { ... }
+ * ```
+ */
+import type { Event } from "./types/events.js";
+/** Name of the HTTP header carrying the webhook signature. */
+export declare const SIGNATURE_HEADER = "Silon-Signature";
+/** Maximum accepted clock skew, in seconds, between the signed timestamp and now. */
+export declare const DEFAULT_TOLERANCE = 300;
+/** Raw webhook payload — the unparsed request body. */
+export type WebhookPayload = string | Uint8Array;
+/**
+ * Produce a valid `Silon-Signature` value — useful in tests and mocks.
+ *
+ * @param secret - The endpoint's `whsec_` secret.
+ * @param payload - The raw request body to sign.
+ * @param timestamp - Unix timestamp in seconds; defaults to now.
+ */
+export declare function sign(secret: string, payload: WebhookPayload, timestamp?: number): string;
+/**
+ * `true` iff `header` is a valid signature for `payload` under `secret` and
+ * within `tolerance` seconds of now (`tolerance <= 0` skips the freshness
+ * check). Malformed headers return `false`. The comparison is constant-time.
+ */
+export declare function verifySignature(payload: WebhookPayload, header: string, secret: string, tolerance?: number): boolean;
+/**
+ * Verify the signature and parse `payload` into a typed {@link Event}.
+ *
+ * @throws {WebhookSignatureVerificationError} when the signature is missing,
+ *   stale, or does not match.
+ */
+export declare function constructEvent(payload: WebhookPayload, header: string, secret: string, tolerance?: number): Event;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,CAAC;AAcjD;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxF;AAmBD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAA0B,GACpC,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAA0B,GACpC,KAAK,CASP"}

package/dist/webhooks.js

@@ -0,0 +1,97 @@
+/**
+ * Verify Silon webhook deliveries — no HTTP client needed.
+ *
+ * Every delivery to a webhook endpoint carries a `Silon-Signature` header of
+ * the Stripe-style form `t=<unix_ts>,v1=<hex_hmac>`, where the HMAC-SHA256 is
+ * taken over `<unix_ts>.<raw_request_body>` with the endpoint's `whsec_`
+ * secret. Typical usage in a request handler:
+ *
+ * ```ts
+ * import { webhooks } from "silon-sdk";
+ *
+ * const event = webhooks.constructEvent(
+ *   rawBody,                                    // raw string/bytes, not parsed JSON
+ *   req.headers["silon-signature"],
+ *   process.env.SILON_WEBHOOK_SECRET,
+ * );
+ * if (event.type === "message.failed") { ... }
+ * ```
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { WebhookSignatureVerificationError } from "./errors.js";
+/** Name of the HTTP header carrying the webhook signature. */
+export const SIGNATURE_HEADER = "Silon-Signature";
+/** Maximum accepted clock skew, in seconds, between the signed timestamp and now. */
+export const DEFAULT_TOLERANCE = 300;
+function toBuffer(payload) {
+    if (typeof payload === "string")
+        return Buffer.from(payload, "utf8");
+    return Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
+}
+function digest(secret, timestamp, payload) {
+    const mac = createHmac("sha256", secret);
+    mac.update(`${timestamp}.`);
+    mac.update(toBuffer(payload));
+    return mac.digest("hex");
+}
+/**
+ * Produce a valid `Silon-Signature` value — useful in tests and mocks.
+ *
+ * @param secret - The endpoint's `whsec_` secret.
+ * @param payload - The raw request body to sign.
+ * @param timestamp - Unix timestamp in seconds; defaults to now.
+ */
+export function sign(secret, payload, timestamp) {
+    const ts = Math.trunc(timestamp ?? Date.now() / 1000);
+    return `t=${ts},v1=${digest(secret, ts, payload)}`;
+}
+function parseHeader(header) {
+    let ts = null;
+    let sig = null;
+    for (const rawPart of (header ?? "").split(",")) {
+        const part = rawPart.trim();
+        const eq = part.indexOf("=");
+        const key = eq === -1 ? part : part.slice(0, eq);
+        const value = eq === -1 ? "" : part.slice(eq + 1);
+        if (key === "t" && /^\d+$/.test(value)) {
+            ts = Number.parseInt(value, 10);
+        }
+        else if (key === "v1") {
+            sig = value;
+        }
+    }
+    return { ts, sig };
+}
+/**
+ * `true` iff `header` is a valid signature for `payload` under `secret` and
+ * within `tolerance` seconds of now (`tolerance <= 0` skips the freshness
+ * check). Malformed headers return `false`. The comparison is constant-time.
+ */
+export function verifySignature(payload, header, secret, tolerance = DEFAULT_TOLERANCE) {
+    const { ts, sig } = parseHeader(header);
+    if (ts === null || !sig)
+        return false;
+    if (tolerance > 0 && Math.abs(Math.floor(Date.now() / 1000) - ts) > tolerance) {
+        return false;
+    }
+    const expected = Buffer.from(digest(secret, ts, payload), "utf8");
+    const provided = Buffer.from(sig, "utf8");
+    if (expected.length !== provided.length)
+        return false;
+    return timingSafeEqual(expected, provided);
+}
+/**
+ * Verify the signature and parse `payload` into a typed {@link Event}.
+ *
+ * @throws {WebhookSignatureVerificationError} when the signature is missing,
+ *   stale, or does not match.
+ */
+export function constructEvent(payload, header, secret, tolerance = DEFAULT_TOLERANCE) {
+    if (!verifySignature(payload, header, secret, tolerance)) {
+        throw new WebhookSignatureVerificationError("Webhook signature verification failed. Check that you are using the " +
+            "endpoint's whsec_ secret and the raw (unparsed) request body.");
+    }
+    const text = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
+    return JSON.parse(text);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "silon-sdk",
+  "version": "0.2.0",
+  "description": "Official Silon SDK for Node.js — messaging, broadcasts, OTP, CRM, bulk, reports and webhooks.",
+  "keywords": [
+    "silon",
+    "sdk",
+    "api",
+    "messaging",
+    "whatsapp",
+    "sms",
+    "email",
+    "push",
+    "webhooks"
+  ],
+  "license": "MIT",
+  "author": "Silon",
+  "homepage": "https://silon.tech",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KUWAITNET/silon-node-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KUWAITNET/silon-node-sdk/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}