verifence 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verifence
+
+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

@@ -0,0 +1,53 @@
+# Verifence JavaScript SDK
+
+Official Node.js / TypeScript client for [Verifence](../../README.md) — the pre-send
+firewall for SMS verification. Zero dependencies (uses built-in `fetch`, Node ≥ 18).
+
+```bash
+npm install verifence
+```
+
+> **Your API key is a secret.** Every call is server-to-server. Read it from an
+> environment variable; never ship it in browser or mobile code.
+
+## Usage
+
+```js
+import { Verifence, QuotaExceededError } from 'verifence';
+
+const vf = new Verifence(process.env.VERIFENCE_KEY);
+
+// Before you hand a message to Twilio/Vonage/etc:
+const verdict = await vf.check('+14155552671', req.ip, { userId: 'u_123' });
+//                                              ^ the END USER's IP, from your inbound request
+
+if (!verdict.allow) {
+  return res.status(429).json({ error: 'too_many_verification_requests' });
+}
+
+// ... send the SMS with your provider ...
+
+// After the user enters the correct code:
+await vf.confirm(req.ip);
+```
+
+Handle a spent quota:
+
+```js
+try {
+  await vf.check('+14155552671', req.ip);
+} catch (err) {
+  if (err instanceof QuotaExceededError) {
+    console.log('quota resets at', err.resetsAt);
+  }
+}
+```
+
+## API
+
+- `check(phone, clientIp, { userId?, requireMobile? })` → `Decision` (`{ allow, reason, detail, degraded, ... }`)
+- `confirm(clientIp)` → `{ recorded }`
+- `stats()` → account totals
+
+A block is a resolved promise with `allow: false` — not a throw. Only bad input,
+auth, and quota (429) reject. Self-hosting? `new Verifence(key, { baseUrl: 'https://verifence.internal' })`.

package/index.d.ts

@@ -0,0 +1,60 @@
+export interface CheckOptions {
+  /** Your id for the end user — the counter that survives account rotation. */
+  userId?: string;
+  /** Reject numbers classified as landline. */
+  requireMobile?: boolean;
+}
+
+export interface Decision {
+  allow: boolean;
+  reason: string | null;
+  detail: string;
+  degraded: boolean;
+  e164?: string;
+  country?: string;
+  lineType?: string;
+  network?: string;
+  counts?: Record<string, number>;
+  confirmationRate?: number;
+  allowlisted?: boolean;
+}
+
+export interface ConfirmResult {
+  recorded: boolean;
+  detail?: string;
+}
+
+export interface Stats {
+  allowed: number;
+  blocked: number;
+  total: number;
+  block_rate: number;
+  estimated_saving_usd: { low: number; high: number; note: string };
+}
+
+export interface VerifenceOptions {
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+export class VerifenceError extends Error {
+  status: number;
+  code: string | null;
+  body: unknown;
+}
+
+export class QuotaExceededError extends VerifenceError {
+  /** ISO-8601 timestamp of when the quota resets. */
+  resetsAt: string | null;
+}
+
+export class Verifence {
+  constructor(apiKey: string, options?: VerifenceOptions);
+  /** @param clientIp The END USER's IP, forwarded from your inbound request. */
+  check(phone: string, clientIp: string, opts?: CheckOptions): Promise<Decision>;
+  confirm(clientIp: string): Promise<ConfirmResult>;
+  stats(): Promise<Stats>;
+}
+
+export default Verifence;

package/index.js

@@ -0,0 +1,109 @@
+/**
+ * Verifence JavaScript SDK.
+ *
+ * Call check() immediately before you hand a message to your SMS provider. A deny
+ * is a message you never pay for. Report a real code entry with confirm() so the
+ * network-reputation layer can learn.
+ *
+ * The API key is a SECRET — server-to-server only. Never ship it in browser or
+ * mobile code. Read it from an environment variable.
+ *
+ *   import { Verifence } from '@verifence/verifence';
+ *   const vf = new Verifence(process.env.VERIFENCE_KEY);
+ *   const verdict = await vf.check('+14155552671', req.ip, { userId: 'u_123' });
+ *   if (!verdict.allow) return; // do not send
+ */
+
+export class VerifenceError extends Error {
+  constructor(message, { status = 0, code = null, body = null } = {}) {
+    super(message);
+    this.name = 'VerifenceError';
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+}
+
+export class QuotaExceededError extends VerifenceError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = 'QuotaExceededError';
+    this.resetsAt = opts?.body?.resets_at ?? null;
+  }
+}
+
+export class Verifence {
+  /**
+   * @param {string} apiKey  Your secret `vf_live_…` key.
+   * @param {{ baseUrl?: string, timeoutMs?: number, fetch?: typeof fetch }} [options]
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) throw new VerifenceError('A Verifence API key is required.');
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl ?? 'https://api.verifence.dev';
+    this.timeoutMs = options.timeoutMs ?? 4000;
+    this._fetch = options.fetch ?? globalThis.fetch;
+  }
+
+  /**
+   * Pre-send decision.
+   * @param {string} phone     E.164, e.g. "+14155552671".
+   * @param {string} clientIp  The END USER's IP, forwarded from your inbound request — not your server's.
+   * @param {{ userId?: string, requireMobile?: boolean }} [opts]
+   */
+  async check(phone, clientIp, opts = {}) {
+    const body = { phone, client_ip: clientIp };
+    if (opts.userId != null) body.user_id = opts.userId;
+    if (opts.requireMobile) body.require_mobile = true;
+    return this.#request('POST', '/v1/check', body);
+  }
+
+  /**
+   * Report that a code sent to this end user was entered correctly.
+   * @param {string} clientIp  The same end-user IP you sent to check().
+   */
+  async confirm(clientIp) {
+    return this.#request('POST', '/v1/confirm', { client_ip: clientIp });
+  }
+
+  /** Account totals: allowed, blocked, block rate, estimated saving. */
+  async stats() {
+    return this.#request('GET', '/v1/stats', null);
+  }
+
+  async #request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let res;
+    try {
+      res = await this._fetch(this.baseUrl + path, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: 'application/json',
+          ...(body ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+    } catch (err) {
+      throw new VerifenceError(`Verifence request failed: ${err.message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const data = await res.json().catch(() => null);
+    if (!data) throw new VerifenceError(`Unexpected response (HTTP ${res.status})`, { status: res.status });
+
+    if (res.status >= 400) {
+      const message = data.detail ?? data.error ?? `HTTP ${res.status}`;
+      const opts = { status: res.status, code: data.error ?? null, body: data };
+      throw res.status === 429 ? new QuotaExceededError(message, opts) : new VerifenceError(message, opts);
+    }
+
+    return data;
+  }
+}
+
+export default Verifence;

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "verifence",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for Verifence — the pre-send firewall for SMS verification.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["verifence", "sms", "verification", "fraud", "otp", "sms-pumping"],
+  "license": "MIT"
+}