adsbooster-js-sdk 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adsbooster.net Engineering Team
+
+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

@@ -1,3 +1,187 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Adsbooster JavaScript SDK
+
+Official JavaScript / TypeScript client for the **Adsbooster.net REST API v1** — built for SaaS teams that want AI ad creatives, multi-network campaign management, social publishing and server-side conversion tracking inside their own product.
+
+- **Zero dependencies** — one small file, works in Node.js (≥18) and modern browsers
+- **Typed** — ships complete TypeScript definitions
+- **Resilient** — automatic retries on `429`/`5xx`, timeout via `AbortController`, rate-limit telemetry on every response
+- **Universal** — UMD (`dist/adsbooster.js`), ESM (`dist/adsbooster.esm.js`)
+
+> SDK repo: https://github.com/FushionHub/adsbooster-js-sdk
+> Platform repo: https://github.com/FushionHub/seopp
+> The SDK will move to the `adsbooster-sdks` organization — after transferring, update `repository` in package.json and the links above.
+
+---
+
+## Install
+
+**npm / yarn / pnpm**
+```bash
+npm install adsbooster-js-sdk
+```
+
+**Browser (CDN or self-hosted from your Adsbooster deployment)**
+```html
+<!-- Self-hosted — served straight from your platform, always in sync -->
+<script src="https://adsbooster.net/api/v1/sdk/adsbooster.js"></script>
+
+<!-- or jsDelivr once published -->
+<script src="https://cdn.jsdelivr.net/npm/adsbooster-js-sdk/dist/adsbooster.js"></script>
+```
+
+## Quick start
+
+```js
+const { Adsbooster } = require('adsbooster-js-sdk');   // Node
+// import { Adsbooster } from 'adsbooster-js-sdk';     // ESM / TS
+// const Adsbooster = window.Adsbooster.Adsbooster;    // Browser <script>
+
+const client = new Adsbooster({
+  apiKey: process.env.ADSBOOSTER_API_KEY, // from Developer Console → api-settings
+  // baseUrl: 'https://adsbooster.net',   // default; change for self-hosted
+});
+
+// 1) Check wallet balance
+const balance = await client.credits.balance();
+console.log(balance.ad_credits, balance.ai_credits);
+
+// 2) Generate an AI UGC creative (Nano Banana 2 image stack)
+const creative = await client.ugc.generateImage({
+  product_name: 'Cloud-Knit Running Shoes',
+  ugc_style: 'selfie_hold',
+  creator_persona: 'gen_z',
+  aspect_ratio: '1:1',
+});
+console.log(creative.creative.image_url);
+
+// 3) Launch a campaign across connected networks
+const campaign = await client.campaigns.create({
+  name: 'Q4 Sneaker Drop',
+  platform: 'meta',
+  objective: 'conversions',
+  budget_amount: 25,
+  budget_type: 'daily',
+});
+
+// 4) Publish a post live to social
+await client.posts.create({
+  platform: 'tiktok',
+  caption: 'New drop 🚀 link in bio #ad',
+  media_url: creative.creative.image_url,
+  media_type: 'image',
+});
+```
+
+## API surface
+
+| Namespace | Methods | Endpoint |
+|---|---|---|
+| `client.campaigns` | `list({page,limit,status})` · `get(id)` · `create(payload)` · `update(id,payload)` · `pause(id)` · `resume(id)` | `/api/v1/campaigns.php` |
+| `client.posts` | `list({page,limit,status})` · `get(id)` · `create(payload)` · `remove(id)` | `/api/v1/posts.php` |
+| `client.ugc` | `generateImage(payload)` · `listRecent({limit})` | `/api/v1/ugc.php` |
+| `client.credits` | `balance()` | `/api/v1/credits.php` |
+| `client.directory` | `list({category,q,limit})` · `createListing(payload)` | `/api/v1/directory.php` |
+| `client.reviews` | `list({limit})` · `submit({rating,review_text,…})` | `/api/v1/reviews.php` |
+| `client.capi` | `scriptUrl()` · `track({pixel_token,event_name,…})` | `/api/v1/capi-bridge.php` |
+| `client.webhooks` | `list()` · `test(url)` — signed ping to YOUR registered https endpoint | `/api/v1/webhooks.php` |
+| `client.publicAnalytics` | `feed(view?)` · `totals()` — public aggregate, no auth (30 req/min/IP) | `/api/v1/public-analytics.php` |
+
+Every response is the raw API payload (`{ success: true, … }`). Non-2xx responses throw an [`AdsboosterError`](#error-handling).
+
+## Error handling
+
+```js
+const { Adsbooster, AdsboosterError } = require('adsbooster-js-sdk');
+
+try {
+  await client.ugc.generateImage({ product_name: '…' });
+} catch (err) {
+  if (err instanceof AdsboosterError) {
+    console.error(err.status);        // 401, 429, 500… (0 = network/timeout)
+    console.error(err.code);          // 'Unauthorized', 'RateLimitExceeded'…
+    console.error(err.rateLimit);     // { limit: 60, remaining: 0, reset: 1768… }
+    if (err.isRateLimit) {
+      await new Promise(r => setTimeout(r, 60_000)); // or rely on auto-retry
+    }
+  } else {
+    throw err;
+  }
+}
+```
+
+### Rate limits
+The platform enforces **60 requests / minute / key** (sliding window). The SDK:
+- reads `X-RateLimit-*` headers on **every** response into `client.lastRateLimit`
+- **auto-retries** `429` honoring `Retry-After` / `X-RateLimit-Reset`, and `5xx` with exponential backoff (default `maxRetries: 2`)
+
+```js
+const client = new Adsbooster({ apiKey, maxRetries: 4, timeout: 60000 });
+```
+
+## Webhooks (server-side)
+
+Outbound webhooks (`campaign.status_changed`, `post.published`, `payment.completed`) are signed with `X-Adsbooster-Signature: sha256=<hmac>` — verify with the raw body:
+
+```js
+const express = require('express');
+const { webhooks } = require('adsbooster-js-sdk');
+
+app.post('/adsbooster/webhook', express.raw({ type: '*/*' }), (req, res) => {
+  const ok = webhooks.verify(
+    req.body,                                       // RAW body (Buffer/string)
+    req.get('X-Adsbooster-Signature') || '',
+    process.env.WEBHOOK_SECRET                      // per-endpoint secret from api-settings
+  );
+  if (!ok) return res.status(401).send('bad signature');
+  const event = JSON.parse(req.body.toString('utf8'));
+  console.log(event.event, event.data);
+  res.sendStatus(200);
+});
+```
+
+## Server-side conversion tracking (Meta CAPI / TikTok Events)
+
+```js
+// Browser: drop-in script (no SDK needed)
+// <script src="https://adsbooster.net/api/v1/capi-bridge.php?js=1"></script>
+// <script>window._adsbooster_token='px_live_…'; AdsboosterTrack('Purchase',{value:49.99,currency:'USD'});</script>
+
+// Server-side from your SaaS:
+await client.capi.track({
+  pixel_token: 'px_live_…',
+  event_name: 'Purchase',
+  event_id: 'order_8841',
+  custom_data: { value: 49.99, currency: 'USD' },
+  user_data: { email_hash: sha256(email) },
+});
+```
+
+## Examples
+
+ runnable scripts live in [`examples/`](examples/):
+
+- `examples/node-smoke-test.js` — end-to-end smoke test against a live deployment
+- `examples/node-create-campaign.js` — campaign lifecycle (create → pause → resume)
+- `examples/browser-ugc.html` — generate an AI creative from a web page
+- `examples/express-webhooks.js` — verify signed webhooks in Express
+
+## TypeScript
+
+Full definitions ship in `types/index.d.ts`:
+
+```ts
+import { Adsbooster, AdsboosterError } from 'adsbooster-js-sdk';
+const client = new Adsbooster({ apiKey: process.env.ADSBOOSTER_API_KEY! });
+const res = await client.campaigns.list({ status: 'active', limit: 50 });
+```
+
+## Getting an API key
+
+1. Sign up / log in on your Adsbooster deployment
+2. Open **Developer Console** (`/api-settings`)
+3. Generate a key (`adsb_live_…`) — optionally restrict it to your server IPs
+4. Fund ad/AI credits from **Billing & Wallet** (top-ups from $2.50)
+
+## License
+
+[MIT](LICENSE) © Adsbooster.net Engineering Team

package/dist/adsbooster.esm.js

@@ -0,0 +1,473 @@
+/**
+ * Adsbooster JavaScript SDK — ESM build. Generated from src/adsbooster.js (UMD).
+ * Do not edit by hand — edit the source and regenerate.
+ */
+'use strict';
+
+
+  var VERSION = '1.1.0';
+  var DEFAULT_TIMEOUT = 30000;   // ms
+  var DEFAULT_RETRIES = 2;       // retries on 429/5xx (initial attempt excluded)
+  var AI_CREDITS_PER_USD = 100;  // documented platform rate
+
+  /* ─────────────────────────── Errors ─────────────────────────── */
+
+  /**
+   * Raised for any non-2xx API response, network failure, or usage error.
+   * `status` is the HTTP status (0 for network errors), `code` the API error
+   * slug (e.g. 'RateLimitExceeded'), `rateLimit` the last seen quota snapshot.
+   */
+  function AdsboosterError(message, opts) {
+    opts = opts || {};
+    this.name = 'AdsboosterError';
+    this.message = message || 'Unknown Adsbooster API error';
+    this.status = typeof opts.status === 'number' ? opts.status : 0;
+    this.code = opts.code || null;
+    this.details = opts.details || null;
+    this.rateLimit = opts.rateLimit || null;
+    this.isRateLimit = this.code === 'RateLimitExceeded' || this.status === 429;
+    var stackFn = Error.captureStackTrace;
+    if (stackFn) {
+      stackFn.call(Error, this, AdsboosterError);
+    } else {
+      this.stack = new Error(this.message).stack;
+    }
+  }
+  AdsboosterError.prototype = Object.create(Error.prototype);
+  AdsboosterError.prototype.constructor = AdsboosterError;
+
+  /* ─────────────────────── Small utilities ────────────────────── */
+
+  function isObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+  function sleep(ms) { return new Promise(function (r) { setTimeout(r, ms); }); }
+
+  function buildQuery(params) {
+    if (!params) return '';
+    var parts = [];
+    Object.keys(params).forEach(function (k) {
+      var v = params[k];
+      if (v === undefined || v === null || v === '') return;
+      parts.push(encodeURIComponent(k) + '=' + encodeURIComponent(v));
+    });
+    return parts.length ? '?' + parts.join('&') : '';
+  }
+
+  function nowSec() { return Math.floor(Date.now() / 1000); }
+
+  function parseRetryAfter(headers) {
+    if (!headers) return null;
+    var ra = headers.get ? headers.get('retry-after') : null;
+    if (ra) {
+      var n = parseInt(ra, 10);
+      if (!isNaN(n)) return n * 1000;
+      var asDate = Date.parse(ra);
+      if (!isNaN(asDate)) return Math.max(1000, asDate - Date.now());
+    }
+    var reset = headers.get ? headers.get('x-ratelimit-reset') : null;
+    if (reset) {
+      var delta = (parseInt(reset, 10) - nowSec()) * 1000;
+      if (!isNaN(delta) && delta > 0) return delta;
+    }
+    return null;
+  }
+
+  /* ────────────────────────── Client ──────────────────────────── */
+
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey            Required. adsb_live_… / adsb_test_… key from the Developer Console.
+   * @param {string} [options.baseUrl]         Platform origin, e.g. https://adsbooster.net (no trailing /api).
+   * @param {number} [options.timeout=30000]   Per-request timeout in ms.
+   * @param {number} [options.maxRetries=2]    Automatic retries on 429 + 5xx.
+   * @param {function} [options.fetch]         Custom fetch implementation (testing, proxies).
+   */
+  function Adsbooster(options) {
+    options = options || {};
+    if (!options.apiKey || typeof options.apiKey !== 'string') {
+      throw new AdsboosterError('An `apiKey` is required — generate one in your Adsbooster Developer Console (api-settings).');
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl || 'https://adsbooster.net').replace(/\/+$/, '');
+    this.apiBase = this.baseUrl + '/api/v1';
+    this.timeout = typeof options.timeout === 'number' ? options.timeout : DEFAULT_TIMEOUT;
+    this.maxRetries = typeof options.maxRetries === 'number' ? options.maxRetries : DEFAULT_RETRIES;
+    this._fetch = options.fetch || (typeof fetch === 'function' ? fetch : null);
+    if (!this._fetch) {
+      throw new AdsboosterError('No fetch implementation found. Adsbooster SDK needs Node >= 18 or a modern browser.');
+    }
+
+    // Resource namespaces
+    this.campaigns  = new CampaignsResource(this);
+    this.posts      = new PostsResource(this);
+    this.ugc        = new UgcResource(this);
+    this.credits    = new CreditsResource(this);
+    this.directory  = new DirectoryResource(this);
+    this.reviews    = new ReviewsResource(this);
+    this.capi       = new CapiResource(this);
+    this.webhooks   = new WebhooksResource(this);
+    this.publicAnalytics = new PublicAnalyticsResource(this);
+
+    // Last observed quota: { limit, remaining, reset }
+    this.lastRateLimit = null;
+  }
+
+  Adsbooster.prototype.VERSION = VERSION;
+
+  /** Low-level request with timeout, retries and error normalisation. */
+  Adsbooster.prototype.request = function (method, path, body, options) {
+    options = options || {};
+    var self = this;
+    var url = this.apiBase + path;
+    var attempt = 0;
+
+    function once() {
+      var controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+      var timer = controller ? setTimeout(function () { controller.abort(); }, self.timeout) : null;
+
+      var headers = {
+        'X-API-Key': self.apiKey,
+        'Accept': 'application/json'
+      };
+      var payload;
+      if (body !== undefined && body !== null && method !== 'GET') {
+        if (typeof FormData !== 'undefined' && body instanceof FormData) {
+          payload = body; // browser sets the multipart boundary itself
+        } else {
+          headers['Content-Type'] = 'application/json';
+          payload = JSON.stringify(body);
+        }
+      }
+
+      return self._fetch(url, {
+        method: method,
+        headers: headers,
+        body: payload,
+        signal: controller ? controller.signal : undefined,
+        credentials: 'omit'
+      }).then(function (res) {
+        if (timer) clearTimeout(timer);
+        return res.text().then(function (text) {
+          var data = null;
+          try { data = text ? JSON.parse(text) : null; } catch (e) { /* non-JSON */ }
+
+          // Capture quota telemetry on every response.
+          if (res.headers && res.headers.get) {
+            var limit = parseInt(res.headers.get('x-ratelimit-limit'), 10);
+            var remaining = parseInt(res.headers.get('x-ratelimit-remaining'), 10);
+            var reset = parseInt(res.headers.get('x-ratelimit-reset'), 10);
+            if (!isNaN(limit)) {
+              self.lastRateLimit = {
+                limit: limit,
+                remaining: isNaN(remaining) ? null : remaining,
+                reset: isNaN(reset) ? null : reset
+              };
+            }
+          }
+
+          if (res.ok && data && data.success === false) {
+            // 2xx with success:false — treat as an API error (rare).
+            throw new AdsboosterError(data.message || data.error || 'Request failed', {
+              status: res.status, code: data.error || null, details: data,
+              rateLimit: self.lastRateLimit
+            });
+          }
+          if (!res.ok) {
+            throw new AdsboosterError(
+              (data && (data.message || data.error)) || ('HTTP ' + res.status),
+              { status: res.status, code: data && data.error || null, details: data, rateLimit: self.lastRateLimit }
+            );
+          }
+          return data;
+        });
+      }).catch(function (err) {
+        if (timer) clearTimeout(timer);
+        if (err instanceof AdsboosterError) throw err;
+        var aborted = controller && controller.signal && controller.signal.aborted;
+        throw new AdsboosterError(
+          aborted ? 'Request timed out after ' + self.timeout + 'ms' : ('Network error: ' + (err && err.message)),
+          { status: 0, code: aborted ? 'Timeout' : 'NetworkError' }
+        );
+      });
+    }
+
+    function run() {
+      return once().catch(function (err) {
+        var retryable = err.isRateLimit || (err.status >= 500 && err.status < 600) || err.status === 0;
+        if (retryable && attempt < self.maxRetries) {
+          attempt += 1;
+          var wait = err.isRateLimit
+            ? (parseRetryAfter(err.details && err.details.__headers) || 5000 * attempt)
+            : Math.min(8000, 400 * Math.pow(2, attempt - 1));
+          return sleep(wait).then(run);
+        }
+        throw err;
+      });
+    }
+    return run();
+  };
+
+  /* ───────────────────── Resource: Campaigns ──────────────────── */
+
+  function CampaignsResource(client) { this._c = client; }
+
+  /** GET /campaigns.php — list your campaigns. opts: { page, limit, status } */
+  CampaignsResource.prototype.list = function (opts) {
+    return this._c.request('GET', '/campaigns.php' + buildQuery(opts || {}));
+  };
+
+  /** GET /campaigns.php?id=N — fetch a single campaign. */
+  CampaignsResource.prototype.get = function (id) {
+    return this._c.request('GET', '/campaigns.php?id=' + encodeURIComponent(id));
+  };
+
+  /** POST /campaigns.php — create a campaign. */
+  CampaignsResource.prototype.create = function (payload) {
+    if (!isObject(payload)) {
+      return Promise.reject(new AdsboosterError('campaigns.create() expects a payload object.'));
+    }
+    return this._c.request('POST', '/campaigns.php', payload);
+  };
+
+  /** PUT /campaigns.php?id=N — update (status, budget, targeting…). */
+  CampaignsResource.prototype.update = function (id, payload) {
+    if (!isObject(payload)) {
+      return Promise.reject(new AdsboosterError('campaigns.update() expects a payload object.'));
+    }
+    return this._c.request('PUT', '/campaigns.php?id=' + encodeURIComponent(id), payload);
+  };
+
+  /** Convenience: pause a campaign. */
+  CampaignsResource.prototype.pause = function (id) {
+    return this.update(id, { status: 'paused' });
+  };
+
+  /** Convenience: resume a paused campaign. */
+  CampaignsResource.prototype.resume = function (id) {
+    return this.update(id, { status: 'active' });
+  };
+
+  /* ─────────────────────── Resource: Posts ────────────────────── */
+
+  function PostsResource(client) { this._c = client; }
+
+  /** GET /posts.php — list social posts. opts: { page, limit, status } */
+  PostsResource.prototype.list = function (opts) {
+    return this._c.request('GET', '/posts.php' + buildQuery(opts || {}));
+  };
+
+  /** GET /posts.php?id=N — fetch a single post. */
+  PostsResource.prototype.get = function (id) {
+    return this._c.request('GET', '/posts.php?id=' + encodeURIComponent(id));
+  };
+
+  /** POST /posts.php — create / publish / schedule a post. */
+  PostsResource.prototype.create = function (payload) {
+    if (!isObject(payload)) {
+      return Promise.reject(new AdsboosterError('posts.create() expects a payload object.'));
+    }
+    return this._c.request('POST', '/posts.php', payload);
+  };
+
+  /** DELETE /posts.php?id=N — remove a scheduled post. */
+  PostsResource.prototype.remove = function (id) {
+    return this._c.request('DELETE', '/posts.php?id=' + encodeURIComponent(id));
+  };
+
+  /* ──────────────────────── Resource: UGC ─────────────────────── */
+
+  function UgcResource(client) { this._c = client; }
+
+  /** GET /ugc.php — recent AI creatives. opts: { limit ≤ 50 } */
+  UgcResource.prototype.listRecent = function (opts) {
+    return this._c.request('GET', '/ugc.php' + buildQuery(opts || {}));
+  };
+
+  /**
+   * POST /ugc.php — generate a photoreal UGC image (Nano Banana 2 stack).
+   * payload: { product_name, ugc_style, creator_persona, aspect_ratio, target_audience, headline, badge_text }
+   */
+  UgcResource.prototype.generateImage = function (payload) {
+    if (!payload || !payload.product_name) {
+      return Promise.reject(new AdsboosterError("ugc.generateImage() requires { product_name: '…' }."));
+    }
+    return this._c.request('POST', '/ugc.php', payload);
+  };
+
+  /* ────────────────────── Resource: Credits ───────────────────── */
+
+  function CreditsResource(client) { this._c = client; }
+
+  /** GET /credits.php — ad + AI credit balance for the API key's account. */
+  CreditsResource.prototype.balance = function () {
+    return this._c.request('GET', '/credits.php');
+  };
+
+  /* ───────────────────── Resource: Directory ──────────────────── */
+
+  function DirectoryResource(client) { this._c = client; }
+
+  /** GET /directory.php — browse the verified business directory. opts: { category, q, limit } */
+  DirectoryResource.prototype.list = function (opts) {
+    return this._c.request('GET', '/directory.php' + buildQuery(opts || {}));
+  };
+
+  /** POST /directory.php — submit a marketplace listing. */
+  DirectoryResource.prototype.createListing = function (payload) {
+    if (!isObject(payload)) {
+      return Promise.reject(new AdsboosterError('directory.createListing() expects a payload object.'));
+    }
+    return this._c.request('POST', '/directory.php', payload);
+  };
+
+  /* ────────────────────── Resource: Reviews ───────────────────── */
+
+  function ReviewsResource(client) { this._c = client; }
+
+  /** GET /reviews.php — approved community reviews. opts: { limit } */
+  ReviewsResource.prototype.list = function (opts) {
+    return this._c.request('GET', '/reviews.php' + buildQuery(opts || {}));
+  };
+
+  /** POST /reviews.php — submit or update your platform review. */
+  ReviewsResource.prototype.submit = function (payload) {
+    if (!payload || !payload.rating || !payload.review_text) {
+      return Promise.reject(new AdsboosterError('reviews.submit() requires { rating: 1-5, review_text: "…" }.'));
+    }
+    return this._c.request('POST', '/reviews.php', payload);
+  };
+
+  /* ──────────────── Resource: Server-side tracking ────────────── */
+
+  function CapiResource(client) { this._c = client; }
+
+  /** URL of the drop-in browser tracking script (Meta CAPI / TikTok Events bridge). */
+  CapiResource.prototype.scriptUrl = function () {
+    return this._c.apiBase + '/capi-bridge.php?js=1';
+  };
+
+  /**
+   * POST /capi-bridge.php — forward a conversion event server-side.
+   * payload: { pixel_token, event_name, user_data, custom_data, source_url }
+   */
+  CapiResource.prototype.track = function (payload) {
+    if (!payload || !payload.pixel_token) {
+      return Promise.reject(new AdsboosterError('capi.track() requires { pixel_token: "…" } from your Server Tracking console.'));
+    }
+    return this._c.request('POST', '/capi-bridge.php', payload);
+  };
+
+  /* ───────────────────── Resource: Webhooks ───────────────────── */
+
+  function WebhooksResource(client) { this._c = client; }
+
+  /**
+   * GET /webhooks.php — list your registered webhook endpoints.
+   * Result: { success, endpoints: [{ id, event_type, target_url, is_active, created_at }] }
+   */
+  WebhooksResource.prototype.list = function () {
+    return this._c.request('GET', '/webhooks.php');
+  };
+
+  /**
+   * GET /webhooks.php?ping=<url> — fire a signed test ping to one of YOUR
+   * registered https:// endpoints. Authenticated with the API key, so no
+   * console session is needed. Returns { success, http_code, latency_ms,
+   * signature, response, error }.
+   */
+  WebhooksResource.prototype.test = function (targetUrl) {
+    if (!targetUrl || typeof targetUrl !== 'string' || targetUrl.indexOf('https://') !== 0) {
+      return Promise.reject(new AdsboosterError('webhooks.test() requires an exact https:// target_url registered to your account.'));
+    }
+    return this._c.request('GET', '/webhooks.php?ping=' + encodeURIComponent(targetUrl));
+  };
+
+  /**
+   * @deprecated SDK-side URL builder for the old console flow — the console
+   * tests endpoints server-side via the session (api-settings form POST),
+   * which an API key cannot sign for. Prefer webhooks.test(url).
+   */
+  WebhooksResource.prototype.testPingUrl = function (targetUrl) {
+    return Promise.resolve(this._c.apiBase + '/webhooks.php?ping=' + encodeURIComponent(targetUrl));
+  };
+
+  /* ───────────────── Public aggregate analytics (no auth) ─────── */
+
+  /**
+   * Feed of the SAME live aggregate analytics the homepage achievements
+   * modal renders — totals, performance ratios, 14-day trend, campaign
+   * status mix and platform mix. Zero user-level data; no API key is
+   * actually required server-side (the client key is simply ignored).
+   * Rate limit: 30 requests/minute/IP → 429 with Retry-After.
+   */
+  function PublicAnalyticsResource(client) { this._c = client; }
+
+  /**
+   * Fetch the aggregate analytics feed.
+   * @param {string} [view]  one of 'all' | 'campaigns' | 'users' | 'platforms' | 'success' —
+   *                         selects which sections the homepage modal focuses on.
+   * @returns {Promise<object>} { success, generated, homepage, analytics, _meta }
+   */
+  PublicAnalyticsResource.prototype.feed = function (view) {
+    var suffix = view ? '?view=' + encodeURIComponent(String(view)) : '';
+    return this._c.request('GET', '/public-analytics.php' + suffix, undefined, { publicEndpoint: true });
+  };
+
+  /** Convenience: the analytics section only (totals, performance, trend, mixes). */
+  PublicAnalyticsResource.prototype.totals = function () {
+    return this.feed('all').then(function (j) {
+      return j && j.analytics ? j.analytics : j;
+    });
+  };
+
+  /* ───────────────────── Webhook verification ─────────────────── */
+
+  var webhooks = {
+    /**
+     * Verify an inbound webhook signature (X-Adsbooster-Signature header).
+     * Node-only: use `crypto.timingSafeEqual`. Provide the RAW request body.
+     * Signature format: "sha256=<hex hmac of raw body using the webhook secret>".
+     */
+    verify: function (rawBody, signature, secret) {
+      if (typeof signature !== 'string' || signature.indexOf('sha256=') !== 0) {
+        return false;
+      }
+      var expected = signature.slice(7);
+      var cryptoApi = null;
+      try { cryptoApi = require('crypto'); } catch (e) { /* browser */ }
+      if (!cryptoApi || !cryptoApi.createHmac) {
+        throw new AdsboosterError('Webhook signatures must be verified server-side in Node.js (crypto is unavailable here).');
+      }
+      var hmac = cryptoApi.createHmac('sha256', secret).update(String(rawBody), 'utf8').digest('hex');
+      var a = Buffer.from(hmac);
+      var b = Buffer.from(String(expected));
+      if (a.length !== b.length) return false;
+      return cryptoApi.timingSafeEqual(a, b);
+    },
+
+    /** Build the expected signature yourself (useful for tests). */
+    sign: function (rawBody, secret) {
+      var cryptoApi = null;
+      try { cryptoApi = require('crypto'); } catch (e) { /* browser */ }
+      if (!cryptoApi || !cryptoApi.createHmac) {
+        throw new AdsboosterError('webhooks.sign() is Node-only.');
+      }
+      return 'sha256=' + cryptoApi.createHmac('sha256', secret).update(String(rawBody), 'utf8').digest('hex');
+    }
+  };
+
+  /* ────────────────────────── Exports ─────────────────────────── */
+
+  var API = {
+    VERSION: VERSION,
+    Adsbooster: Adsbooster,
+    AdsboosterError: AdsboosterError,
+    AI_CREDITS_PER_USD: AI_CREDITS_PER_USD,
+    webhooks: webhooks,
+    /** Back-compat alias */
+    default: Adsbooster
+  };
+
+
+export { VERSION, Adsbooster, AdsboosterError, AI_CREDITS_PER_USD, webhooks };
+export default Adsbooster;