@guidelytech/node 0.0.0-stage → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guidely
+
+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,128 @@
-# Temporary Holding Version
+# @guidelytech/node
 
-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.
+Send product data to [Guidely](https://guidelytech.com) from your Node.js backend: who a user is
+(`identify`), what they did (`track`) and which account they belong to (`group`). Server events land
+next to browser and app events, so they work in Events, Funnels, Retention, audiences and guide
+targeting.
+
+* Node.js 18+, no runtime dependencies (uses the global `fetch`). ESM and CommonJS.
+* Calls never throw and never wait for the network: they validate, queue and return.
+* Batched (100 messages, every 5 s), one request at a time, retried with exponential backoff and
+  `Retry-After`. Every message has a `messageId`, so retries never double-count.
+
+```bash
+npm install @guidelytech/node
+```
+
+Feature flags for servers live in [`@guidelytech/flags`](../flags).
+
+## Keys
+
+Create a **secret key** (`gly_sk_…`) with the **`events:write`** scope in **Settings → API keys**.
+Keep it in your secret manager; never ship it to a browser or app. Each client writes to one
+environment: `development`, `staging` or `production`.
+
+## Usage
+
+```ts
+import { Guidely } from "@guidelytech/node";
+
+const guidely = new Guidely({
+  secretKey: process.env.GUIDELY_SECRET_KEY!, // gly_sk_…
+  environment: "production",
+});
+
+// Who the user is (merged into the user's traits; creates the user if needed).
+guidely.identify({ userId: "u_42", traits: { email: "ada@example.com", plan: "pro" }, accountId: "acme" });
+
+// What they did.
+guidely.track({ userId: "u_42", event: "Report Exported", properties: { format: "csv", rows: 1200 } });
+
+// A visitor who has not signed in: pass the browser SDK's Guidely.anonymousId.
+guidely.track({ anonymousId: req.body.anonymousId, event: "Pricing Viewed" });
+
+// Account traits (`name` also becomes the account name); userId adds the user to the account.
+guidely.group({ accountId: "acme", traits: { name: "Acme Inc", mrr: 4200, seats: 25 }, userId: "u_42" });
+```
+
+Use the same `userId` your frontend passes to `Guidely.identify()`. Every call accepts an optional
+`timestamp` (a `Date`, epoch milliseconds or an ISO 8601 string) for events that happened earlier.
+
+Create **one client per process** and share it. Before the process exits, call `shutdown()`: it
+stops the timer and sends what is queued (waiting at most `shutdownTimeoutMs`).
+
+```ts
+process.on("SIGTERM", async () => {
+  await guidely.shutdown();
+  process.exit(0);
+});
+```
+
+The client also flushes on Node's `beforeExit` event (when the event loop empties, e.g. at the end
+of a script). `process.exit()` and signals skip `beforeExit`, so servers should call `shutdown()`.
+
+### Serverless (AWS Lambda, Vercel, Cloud Functions)
+
+The function may be frozen as soon as it returns, so send before returning:
+
+```ts
+export const handler = async (event) => {
+  guidely.track({ userId: event.userId, event: "Invoice Paid" });
+  await guidely.flush();
+  return { statusCode: 200 };
+};
+```
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `secretKey` | — | **Required.** A `gly_sk_…` key with `events:write`. |
+| `environment` | — | **Required.** `development`, `staging` or `production`. |
+| `apiUrl` | `https://guidelytech.com` | For self-hosted or local servers. |
+| `flushAt` | `100` | Send when this many messages are queued (a batch holds at most 100 messages and 500 KB). |
+| `flushIntervalMs` | `5000` | Send what is queued at least this often. The timer never keeps the process alive. |
+| `maxQueueSize` | `10000` | Messages held in memory; beyond it the oldest are dropped and reported. |
+| `maxRetries` | `5` | Retries after network errors, timeouts, `429` and `5xx` (1 s, 2 s, 4 s… capped at 30 s, ±20 % jitter; `Retry-After` wins, capped at 60 s). Other `4xx` answers drop the batch. |
+| `timeoutMs` | `10000` | Timeout of one request. |
+| `shutdownTimeoutMs` | `10000` | How long `shutdown()` and the exit hook wait. |
+| `onError` | `console.warn` | Receives a `GuidelyError` for every problem (see below). |
+| `handleExit` | `true` | Flush on `beforeExit`. |
+| `fetch` | global `fetch` | Any `fetch`-compatible function (proxies, tests). |
+
+## Validation and errors
+
+Invalid calls are dropped and reported, never thrown: `identify` needs a `userId`; `track` needs an
+`event` (1–120 characters) and a `userId` or `anonymousId`; `group` needs an `accountId`. Ids are
+strings of 1–256 characters (integers are converted); `traits` and `properties` must be plain
+objects. Messages over 32 KB are dropped.
+
+`onError` receives a `GuidelyError` with a `code`:
+
+| `code` | |
+|---|---|
+| `invalid_message` | A call was invalid and dropped. |
+| `message_too_large` | A message serialized to more than 32 KB. |
+| `queue_full` | The queue was full; `count` oldest messages were dropped. |
+| `delivery_failed` | A batch of `count` messages was rejected (`status`: `400`, `401`/`403` = bad key or missing scope, …), failed after every retry (`status` `0` = unreachable) or was cut short by the shutdown timeout. |
+| `closed` | A call was made after `shutdown()`. |
+
+```ts
+const guidely = new Guidely({
+  secretKey: process.env.GUIDELY_SECRET_KEY!,
+  environment: "production",
+  onError: (err) => logger.warn({ code: err.code, count: err.count, status: err.status }, err.message),
+});
+```
+
+## HTTP API
+
+The client posts to `POST /api/v1/sdk/server/batch?environment=<env>` with
+`Authorization: Bearer gly_sk_…`; see [docs/server-sdks.md](../../docs/server-sdks.md) to call it
+from other languages. Its behaviour is pinned by the cross-language vectors in
+[`sdks/conformance/track-vectors.json`](../../sdks/conformance/track-vectors.json), which the Java
+and PHP SDKs run too (regenerate them with `node packages/node/scripts/generate-track-vectors.mjs`).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,444 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_API_URL: () => DEFAULT_API_URL,
+  Guidely: () => Guidely,
+  GuidelyError: () => GuidelyError,
+  SDK_NAME: () => SDK_NAME,
+  SDK_VERSION: () => SDK_VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/message.ts
+var import_node_crypto = require("crypto");
+var LIMITS = {
+  /** Most messages in one request (the API accepts 1–100). */
+  maxBatchMessages: 100,
+  /** Most serialized message bytes in one request (the API accepts bodies up to 512 KB). */
+  maxBatchBytes: 5e5,
+  /** A message larger than this when serialized is dropped and reported. */
+  maxMessageBytes: 32768,
+  maxEventLength: 120,
+  maxIdLength: 256
+};
+var InvalidMessageError = class extends Error {
+};
+var ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function newMessageId() {
+  let id2 = "";
+  while (id2.length < 24) {
+    for (const b of (0, import_node_crypto.randomBytes)(32)) {
+      if (b < 248) id2 += ALPHABET[b % 62];
+      if (id2.length === 24) break;
+    }
+  }
+  return id2;
+}
+function formatTimestamp(value) {
+  let date;
+  if (value instanceof Date) date = value;
+  else if (typeof value === "number") date = new Date(value);
+  else if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i.test(value.trim())) date = new Date(value.trim());
+  else throw new InvalidMessageError("timestamp must be a Date, epoch milliseconds or an ISO 8601 string with an offset");
+  if (Number.isNaN(date.getTime())) throw new InvalidMessageError("timestamp is not a valid date");
+  return date.toISOString();
+}
+var length = (s) => s.length;
+function id(name, value, required) {
+  if (value === void 0 || value === null || !required && value === "") {
+    if (required) throw new InvalidMessageError(`${name} is required`);
+    return void 0;
+  }
+  let s;
+  if (typeof value === "string") s = value;
+  else if (typeof value === "number" && Number.isSafeInteger(value)) s = String(value);
+  else throw new InvalidMessageError(`${name} must be a string`);
+  if (s.trim() === "") throw new InvalidMessageError(`${name} must not be empty`);
+  if (length(s) > LIMITS.maxIdLength) throw new InvalidMessageError(`${name} is longer than ${LIMITS.maxIdLength} characters`);
+  return s;
+}
+function isPlainObject(v) {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function object(name, value) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isPlainObject(value)) throw new InvalidMessageError(`${name} must be an object`);
+  return value;
+}
+function buildMessage(type, args, now = () => /* @__PURE__ */ new Date()) {
+  if (!isPlainObject(args)) throw new InvalidMessageError(`${type}() needs an object argument`);
+  const timestamp = args.timestamp === void 0 || args.timestamp === null ? now().toISOString() : formatTimestamp(args.timestamp);
+  const base = { type, messageId: newMessageId(), timestamp };
+  switch (type) {
+    case "identify": {
+      const userId = id("userId", args.userId, true);
+      const traits = object("traits", args.traits);
+      const accountId = id("accountId", args.accountId, false);
+      return { ...base, userId, ...traits ? { traits } : {}, ...accountId ? { accountId } : {} };
+    }
+    case "track": {
+      const userId = id("userId", args.userId, false);
+      const anonymousId = id("anonymousId", args.anonymousId, false);
+      if (!userId && !anonymousId) throw new InvalidMessageError("track() needs a userId or an anonymousId");
+      const event = args.event;
+      if (typeof event !== "string" || event.trim() === "") throw new InvalidMessageError("track() needs an event name");
+      if (length(event) > LIMITS.maxEventLength) throw new InvalidMessageError(`event is longer than ${LIMITS.maxEventLength} characters`);
+      const properties = object("properties", args.properties);
+      const accountId = id("accountId", args.accountId, false);
+      return {
+        ...base,
+        ...userId ? { userId } : {},
+        ...anonymousId ? { anonymousId } : {},
+        event,
+        ...properties ? { properties } : {},
+        ...accountId ? { accountId } : {}
+      };
+    }
+    case "group": {
+      const accountId = id("accountId", args.accountId, true);
+      const traits = object("traits", args.traits);
+      const userId = id("userId", args.userId, false);
+      return { ...base, accountId, ...traits ? { traits } : {}, ...userId ? { userId } : {} };
+    }
+  }
+}
+
+// src/retry.ts
+var DEFAULT_BACKOFF = { baseMs: 1e3, maxMs: 3e4, retryAfterMaxMs: 6e4 };
+function responseAction(status) {
+  if (status >= 200 && status < 300) return "ok";
+  if (status === 0 || status === 429 || status >= 500 && status < 600) return "retry";
+  return "drop";
+}
+function parseRetryAfter(value) {
+  if (value == null) return null;
+  const v = value.trim();
+  return /^\d+$/.test(v) ? Number(v) * 1e3 : null;
+}
+function backoffDelay(attempt, retryAfter, o = DEFAULT_BACKOFF) {
+  const ra = parseRetryAfter(retryAfter);
+  if (ra !== null) return Math.min(ra, o.retryAfterMaxMs);
+  return Math.min(o.baseMs * 2 ** Math.max(0, attempt - 1), o.maxMs);
+}
+function jitter(delayMs, random) {
+  return Math.round(delayMs * (0.8 + 0.4 * random));
+}
+
+// src/client.ts
+var SDK_NAME = "guidely-node";
+var SDK_VERSION = "0.12.0";
+var DEFAULT_API_URL = "https://guidelytech.com";
+var BATCH_PATH = "/api/v1/sdk/server/batch";
+var ENVIRONMENTS = ["development", "staging", "production"];
+var GuidelyError = class extends Error {
+  constructor(code, message, count = 1, status, options) {
+    super(message, options);
+    this.code = code;
+    this.count = count;
+    this.status = status;
+  }
+  code;
+  count;
+  status;
+  name = "GuidelyError";
+};
+var int = (value, fallback, min) => typeof value === "number" && Number.isFinite(value) ? Math.max(min, Math.floor(value)) : fallback;
+var Guidely = class {
+  url;
+  headers;
+  flushAt;
+  flushIntervalMs;
+  maxQueueSize;
+  maxRetries;
+  shutdownTimeoutMs;
+  timeoutMs;
+  onError;
+  fetch;
+  sdkJson = JSON.stringify({ name: SDK_NAME, version: SDK_VERSION });
+  queue = [];
+  droppedSinceReport = 0;
+  timer;
+  pumping = null;
+  drainAll = false;
+  /** Bumped to abandon the running pump (shutdown timeout): its request is aborted and its sleeps end. */
+  epoch = 0;
+  inflight = null;
+  sleeps = /* @__PURE__ */ new Set();
+  closed = false;
+  shutdownPromise = null;
+  exitDrain = null;
+  exitListener = null;
+  constructor(options) {
+    const o = options ?? {};
+    const key = typeof o.secretKey === "string" ? o.secretKey.trim() : "";
+    if (!key.startsWith("gly_sk_")) {
+      throw new TypeError("Guidely: secretKey must be a secret API key (gly_sk_\u2026) with the events:write scope");
+    }
+    if (!ENVIRONMENTS.includes(o.environment)) {
+      throw new TypeError('Guidely: environment must be "development", "staging" or "production"');
+    }
+    const fetchImpl = o.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
+    if (!fetchImpl) throw new TypeError("Guidely: no global fetch (Node 18+ is required), pass the fetch option");
+    this.fetch = fetchImpl;
+    const apiUrl = (o.apiUrl ?? DEFAULT_API_URL).trim().replace(/\/+$/, "");
+    this.url = `${apiUrl}${BATCH_PATH}?environment=${encodeURIComponent(o.environment)}`;
+    this.headers = {
+      Authorization: `Bearer ${key}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": `${SDK_NAME}/${SDK_VERSION} (Node ${typeof process !== "undefined" ? process.version : "unknown"})`
+    };
+    this.flushAt = int(o.flushAt, 100, 1);
+    this.flushIntervalMs = int(o.flushIntervalMs, 5e3, 1);
+    this.maxQueueSize = int(o.maxQueueSize, 1e4, 1);
+    this.maxRetries = int(o.maxRetries, 5, 0);
+    this.shutdownTimeoutMs = int(o.shutdownTimeoutMs, 1e4, 0);
+    this.timeoutMs = int(o.timeoutMs, 1e4, 1);
+    this.onError = o.onError ?? ((e) => console.warn(`[${SDK_NAME}] ${e.message}`));
+    if (o.handleExit !== false && typeof process !== "undefined" && typeof process.on === "function") {
+      this.exitListener = () => this.onBeforeExit();
+      process.on("beforeExit", this.exitListener);
+    }
+  }
+  /** Who a user is: merges `traits` into the user (creating it if needed), optionally linking an account. */
+  identify(message) {
+    this.enqueue("identify", message);
+  }
+  /** What a user (or anonymous visitor) did. */
+  track(message) {
+    this.enqueue("track", message);
+  }
+  /** Account traits, and optionally adds `userId` to the account. */
+  group(message) {
+    this.enqueue("group", message);
+  }
+  /** Sends everything queued; resolves once it has been delivered or dropped. Never rejects. */
+  flush() {
+    return this.startPump(true);
+  }
+  /**
+   * Stops the timer and the exit hook, then flushes, waiting at most `shutdownTimeoutMs`. Later calls
+   * are dropped (and reported). Call it before your process exits. Never rejects.
+   */
+  shutdown() {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    this.closed = true;
+    this.clearTimer();
+    if (this.exitListener) process.removeListener("beforeExit", this.exitListener);
+    this.shutdownPromise = this.drain(this.shutdownTimeoutMs);
+    return this.shutdownPromise;
+  }
+  // --- queueing ------------------------------------------------------------------------------
+  enqueue(type, args) {
+    try {
+      if (this.closed) {
+        this.report(new GuidelyError("closed", `${type}() was called after shutdown(); the message was dropped`));
+        return;
+      }
+      const message = buildMessage(type, args);
+      let json;
+      try {
+        json = JSON.stringify(message);
+      } catch (e) {
+        throw new InvalidMessageError(`could not be serialized to JSON (${e instanceof Error ? e.message : String(e)})`);
+      }
+      const bytes = Buffer.byteLength(json, "utf8");
+      if (bytes > LIMITS.maxMessageBytes) {
+        this.report(new GuidelyError("message_too_large", `${type}() message is ${bytes} bytes, more than the ${LIMITS.maxMessageBytes}-byte limit; it was dropped`));
+        return;
+      }
+      if (this.queue.length >= this.maxQueueSize) {
+        this.queue.shift();
+        this.droppedSinceReport++;
+      }
+      this.queue.push({ json, bytes });
+      if (this.queue.length >= this.flushAt) void this.startPump(false);
+      else this.scheduleTimer();
+    } catch (e) {
+      if (e instanceof InvalidMessageError) this.report(new GuidelyError("invalid_message", `Invalid ${type}() call dropped: ${e.message}`));
+      else this.report(new GuidelyError("invalid_message", `${type}() failed: ${e instanceof Error ? e.message : String(e)}`, 1, void 0, { cause: e }));
+    }
+  }
+  scheduleTimer() {
+    if (this.timer !== void 0 || this.closed) return;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      void this.startPump(true);
+    }, this.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  clearTimer() {
+    if (this.timer !== void 0) clearTimeout(this.timer);
+    this.timer = void 0;
+  }
+  // --- sending -------------------------------------------------------------------------------
+  /** Starts (or joins) the single sender. `all`: send everything, not only full batches. */
+  startPump(all) {
+    if (all) this.drainAll = true;
+    if (!this.pumping) this.pumping = this.pump();
+    return this.pumping;
+  }
+  async pump() {
+    await Promise.resolve();
+    const epoch = this.epoch;
+    try {
+      const cap = Math.min(this.flushAt, LIMITS.maxBatchMessages);
+      for (; ; ) {
+        this.reportDrops();
+        if (epoch !== this.epoch || this.queue.length === 0 || !this.drainAll && this.queue.length < cap) break;
+        await this.deliver(this.takeBatch(cap), epoch);
+      }
+    } catch (e) {
+      this.report(new GuidelyError("delivery_failed", `Unexpected error while sending: ${e instanceof Error ? e.message : String(e)}`, 0, void 0, { cause: e }));
+    } finally {
+      this.pumping = null;
+      this.drainAll = false;
+      if (this.queue.length > 0) this.scheduleTimer();
+    }
+  }
+  /** Up to `cap` messages from the head of the queue, at most `maxBatchBytes` of them (at least one). */
+  takeBatch(cap) {
+    let n = 0;
+    let size = 0;
+    while (n < this.queue.length && n < cap) {
+      const next = this.queue[n];
+      if (n > 0 && size + next.bytes > LIMITS.maxBatchBytes) break;
+      size += next.bytes;
+      n++;
+    }
+    return this.queue.splice(0, n);
+  }
+  async deliver(batch, epoch) {
+    const messages = batch.map((m) => m.json).join(",");
+    for (let attempt = 1; ; attempt++) {
+      if (epoch !== this.epoch) {
+        this.report(new GuidelyError("delivery_failed", `${batch.length} messages were not sent before the shutdown timeout`, batch.length, 0));
+        return;
+      }
+      const body = `{"batch":[${messages}],"sentAt":${JSON.stringify((/* @__PURE__ */ new Date()).toISOString())},"sdk":${this.sdkJson}}`;
+      let status = 0;
+      let retryAfter = null;
+      let failure;
+      try {
+        const res = await this.send(body);
+        status = res.status;
+        retryAfter = res.headers.get("retry-after");
+      } catch (e) {
+        failure = e;
+      }
+      const action = responseAction(status);
+      if (action === "ok") return;
+      if (epoch !== this.epoch) continue;
+      if (action === "drop" || attempt > this.maxRetries) {
+        this.report(new GuidelyError("delivery_failed", failureMessage(status, failure, batch.length, attempt), batch.length, status, { cause: failure }));
+        return;
+      }
+      const delay = parseRetryAfter(retryAfter) !== null ? backoffDelay(attempt, retryAfter) : jitter(backoffDelay(attempt, null, DEFAULT_BACKOFF), Math.random());
+      await this.sleep(delay);
+    }
+  }
+  async send(body) {
+    const controller = new AbortController();
+    this.inflight = controller;
+    const timeout = setTimeout(() => controller.abort(new Error(`request timed out after ${this.timeoutMs} ms`)), this.timeoutMs);
+    try {
+      const res = await this.fetch(this.url, { method: "POST", headers: this.headers, body, signal: controller.signal });
+      try {
+        await res.text?.();
+      } catch {
+      }
+      return res;
+    } finally {
+      clearTimeout(timeout);
+      if (this.inflight === controller) this.inflight = null;
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      const s = { timer: void 0, resolve };
+      s.timer = setTimeout(() => {
+        this.sleeps.delete(s);
+        resolve();
+      }, ms);
+      this.sleeps.add(s);
+    });
+  }
+  /** Flushes, giving up after `timeoutMs`: the request in flight is aborted and what is left is dropped. */
+  async drain(timeoutMs) {
+    let timer;
+    const timedOut = await Promise.race([
+      this.startPump(true).then(() => false),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(true), timeoutMs);
+      })
+    ]);
+    clearTimeout(timer);
+    if (!timedOut) return;
+    this.epoch++;
+    this.inflight?.abort(new Error("shutdown timeout"));
+    for (const s of this.sleeps) {
+      clearTimeout(s.timer);
+      s.resolve();
+    }
+    this.sleeps.clear();
+    const left = this.queue.length;
+    this.queue = [];
+    if (left > 0) this.report(new GuidelyError("delivery_failed", `${left} queued messages were not sent within ${timeoutMs} ms`, left, 0));
+  }
+  onBeforeExit() {
+    if (this.closed || this.exitDrain || this.queue.length === 0 && !this.pumping) return;
+    this.exitDrain = this.drain(this.shutdownTimeoutMs).finally(() => {
+      this.exitDrain = null;
+    });
+  }
+  // --- errors --------------------------------------------------------------------------------
+  reportDrops() {
+    if (this.droppedSinceReport === 0) return;
+    const n = this.droppedSinceReport;
+    this.droppedSinceReport = 0;
+    this.report(new GuidelyError("queue_full", `The queue was full (maxQueueSize ${this.maxQueueSize}): dropped the ${n} oldest messages`, n));
+  }
+  report(error) {
+    try {
+      this.onError(error);
+    } catch {
+    }
+  }
+};
+function failureMessage(status, failure, count, attempts) {
+  const what = `${count} messages were dropped`;
+  if (status === 0) return `${what}: Guidely could not be reached in ${attempts} attempt${attempts === 1 ? "" : "s"} (${failure instanceof Error ? failure.message : String(failure)})`;
+  if (status === 401 || status === 403) return `${what}: the key was rejected (HTTP ${status}). Check it is a gly_sk_ key with the events:write scope for this environment`;
+  if (attempts > 1) return `${what}: HTTP ${status} after ${attempts} attempts`;
+  return `${what}: HTTP ${status}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_API_URL,
+  Guidely,
+  GuidelyError,
+  SDK_NAME,
+  SDK_VERSION
+});
+//# sourceMappingURL=index.cjs.map