@dregs/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,645 @@
+'use strict';
+
+var chunkK63AUEQR_cjs = require('./chunk-K63AUEQR.cjs');
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/models.ts
+var CATEGORIES = [
+  "HUMANITY",
+  "AUTHENTICITY",
+  "UNIQUENESS",
+  "BEHAVIOR"
+];
+var Scores = class extends Array {
+  /**
+   * `map`, `filter`, and `slice` return plain arrays rather than trying to rebuild a `Scores`
+   * through a constructor whose shape they know nothing about.
+   */
+  static get [Symbol.species]() {
+    return Array;
+  }
+  constructor(items = []) {
+    super();
+    for (const item of items) {
+      this.push(item);
+    }
+  }
+  /** Returns the score for `category`, or `null` when it has not been scored. */
+  get(category) {
+    return this.find((score) => score.category === category) ?? null;
+  }
+  value(category) {
+    return this.get(category)?.value ?? null;
+  }
+  /** How likely it is that a person, rather than a script, is behind the account. */
+  get humanity() {
+    return this.value("HUMANITY");
+  }
+  /** How genuine the details on the account look. */
+  get authenticity() {
+    return this.value("AUTHENTICITY");
+  }
+  /** How distinct the account is from others in the same tenant. */
+  get uniqueness() {
+    return this.value("UNIQUENESS");
+  }
+  /** How ordinary the account's activity looks. */
+  get behavior() {
+    return this.value("BEHAVIOR");
+  }
+};
+function asPayload(value) {
+  return isPayload(value) ? value : {};
+}
+function isPayload(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+  return typeof value === "string" ? value : null;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function asDate(value) {
+  if (typeof value !== "string" || !value) {
+    return null;
+  }
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function asCategory(value) {
+  return typeof value === "string" && CATEGORIES.includes(value) ? value : null;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value.filter(isPayload) : [];
+}
+function parseTrackResult(payload) {
+  const body = asPayload(payload);
+  const id = asString(body.id);
+  return {
+    status: asString(body.status),
+    id,
+    fingerprint: asString(body.fingerprint),
+    accepted: id !== null,
+    raw: body
+  };
+}
+function parseBadge(payload) {
+  const body = asPayload(payload);
+  return {
+    slug: asString(body.slug),
+    name: asString(body.name),
+    type: asString(body.type),
+    explanation: asString(body.explanation),
+    metadata: asPayload(body.metadata),
+    raw: body
+  };
+}
+function parseObservation(payload) {
+  const body = asPayload(payload);
+  return {
+    category: asCategory(body.category),
+    id: asString(body.id),
+    label: asString(body.label),
+    explanation: asString(body.explanation),
+    value: asNumber(body.value),
+    confidence: asNumber(body.confidence),
+    weight: asNumber(body.weight),
+    metadata: asPayload(body.metadata),
+    raw: body
+  };
+}
+function parseScore(payload) {
+  const body = asPayload(payload);
+  return {
+    category: asCategory(body.category),
+    value: asNumber(body.value),
+    observations: asArray(body.observations).map(parseObservation),
+    raw: body
+  };
+}
+function parseScores(payload) {
+  return new Scores(asArray(payload).map(parseScore));
+}
+function parseIdentity(payload) {
+  const body = asPayload(payload);
+  const humanityScore = asNumber(body.humanityScore);
+  const authenticityScore = asNumber(body.authenticityScore);
+  const uniquenessScore = asNumber(body.uniquenessScore);
+  const behaviorScore = asNumber(body.behaviorScore);
+  const pairs = [
+    ["HUMANITY", humanityScore],
+    ["AUTHENTICITY", authenticityScore],
+    ["UNIQUENESS", uniquenessScore],
+    ["BEHAVIOR", behaviorScore]
+  ];
+  const scores = new Scores(
+    pairs.filter(([, value]) => value !== null).map(([category, value]) => ({ category, value, observations: [], raw: {} }))
+  );
+  return {
+    id: asString(body.id),
+    displayName: asString(body.displayName),
+    displayEmail: asString(body.displayEmail),
+    displayUsername: asString(body.displayUsername),
+    humanityScore,
+    authenticityScore,
+    uniquenessScore,
+    behaviorScore,
+    createdAt: asDate(body.createdAt),
+    updatedAt: asDate(body.updatedAt),
+    lastTrackedAt: asDate(body.lastTrackedAt),
+    lastScoredAt: asDate(body.lastScoredAt),
+    disregarded: body.disregarded === true,
+    badges: asArray(body.badges).map(parseBadge),
+    data: asPayload(body.data),
+    scores,
+    raw: body
+  };
+}
+function parseAnalysis(payload) {
+  const body = asPayload(payload);
+  const scores = parseScores(body.scores);
+  return {
+    id: asNumber(body.id),
+    identityId: asString(body.identityId),
+    scores,
+    observations: scores.flatMap((score) => [...score.observations]),
+    eventCount: asNumber(body.eventCount),
+    deviceCount: asNumber(body.deviceCount),
+    durationMillis: asNumber(body.durationMillis),
+    startedAt: asDate(body.startedAt),
+    finishedAt: asDate(body.finishedAt),
+    raw: body
+  };
+}
+
+// src/resources.ts
+function path(identityId, suffix = "") {
+  if (!identityId) {
+    throw new TypeError("An identity id is required.");
+  }
+  return `/identities/${encodeURIComponent(identityId)}${suffix}`;
+}
+var Identities = class {
+  #request;
+  /** @internal */
+  constructor(request) {
+    this.#request = request;
+  }
+  /**
+   * Returns the identity, with its current scores, badges, and attributes.
+   *
+   * @param identityId Your own id for the user, the one you pass to `track()`.
+   * @throws {NotFoundError} Dregs has never seen this identity.
+   */
+  async get(identityId) {
+    return parseIdentity(await this.#request("GET", path(identityId)));
+  }
+  /**
+   * Returns the current category scores.
+   *
+   * This is the cheap read and the one most integrations want. It reports the scores Dregs has
+   * already computed without triggering any work. For the observations behind them, use
+   * {@link Identities.analysis}.
+   *
+   * A category that has not been scored yet is absent, so a brand-new identity comes back empty.
+   *
+   * @throws {NotFoundError} Dregs has never seen this identity.
+   */
+  async scores(identityId) {
+    return parseScores(await this.#request("GET", path(identityId, "/scores")));
+  }
+  /**
+   * Returns the most recent analysis cycle, with the observations behind each score.
+   *
+   * Use this when you need to show or log *why* an identity scored the way it did.
+   *
+   * @throws {NotFoundError} The identity is unknown, or it has not been analyzed yet.
+   */
+  async analysis(identityId) {
+    return parseAnalysis(await this.#request("GET", path(identityId, "/analysis")));
+  }
+  /**
+   * Queues a re-analysis of the identity.
+   *
+   * Scoring is asynchronous: this resolves as soon as the job is queued, not when it has run.
+   * Poll {@link Identities.scores} or watch for a webhook rather than expecting fresh scores on
+   * the next line.
+   *
+   * @throws {NotFoundError} Dregs has never seen this identity.
+   */
+  async analyze(identityId) {
+    await this.#request("POST", path(identityId, "/actions/analyze"));
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://dregs.com/api";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RETRIES = 2;
+var SECRET_KEY_ENV = "DREGS_SECRET_KEY";
+var BASE_URL_ENV = "DREGS_BASE_URL";
+var DEFAULT_SOURCE = "node-sdk";
+var RETRY_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var STATUS_RATE_LIMITED = "rate_limited";
+var STATUS_QUOTA_EXCEEDED = "quota_exceeded";
+var MAX_BACKOFF_MS = 8e3;
+var MAX_RETRY_AFTER_MS = 6e4;
+var Dregs = class {
+  /** Read identities, their scores, and their analysis. */
+  identities;
+  #secretKey;
+  #baseUrl;
+  #timeout;
+  #maxRetries;
+  #fetch;
+  /**
+   * @param options Configuration. Every field has a default, so `new Dregs()` reads the
+   *   environment and is usually enough.
+   * @throws {TypeError} No secret key was found, the key given is a `pk_` public key, or
+   *   `maxRetries` is negative.
+   */
+  constructor(options = {}) {
+    const secretKey = options.secretKey ?? readEnv(SECRET_KEY_ENV);
+    if (!secretKey) {
+      throw new TypeError(
+        `No Dregs secret key. Pass { secretKey: '...' } or set the ${SECRET_KEY_ENV} environment variable. You will find your credential's secret key under Settings -> Credentials in the Dregs dashboard.`
+      );
+    }
+    if (secretKey.startsWith("pk_")) {
+      throw new TypeError(
+        "That is a public key. The public key is for the browser tracker and cannot read identities or scores; this SDK needs the secret key from the same credential, which starts with 'sk_'."
+      );
+    }
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    if (maxRetries < 0 || !Number.isInteger(maxRetries)) {
+      throw new TypeError("maxRetries must be a non-negative integer.");
+    }
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    if (timeout <= 0) {
+      throw new TypeError("timeout must be greater than zero.");
+    }
+    const resolvedFetch = options.fetch ?? globalThis.fetch;
+    if (!resolvedFetch) {
+      throw new TypeError(
+        "No global fetch. This SDK needs Node 20 or newer, or a fetch implementation passed as the fetch option."
+      );
+    }
+    this.#secretKey = secretKey;
+    this.#baseUrl = (options.baseUrl ?? readEnv(BASE_URL_ENV) ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    this.#timeout = timeout;
+    this.#maxRetries = maxRetries;
+    this.#fetch = resolvedFetch;
+    const request = (method, path2, body) => this.request(method, path2, body);
+    this.identities = new Identities(request);
+  }
+  /** The API root every request is built against, with any trailing slash removed. */
+  get baseUrl() {
+    return this.#baseUrl;
+  }
+  /** How many times a failed request is retried before the error is thrown. */
+  get maxRetries() {
+    return this.#maxRetries;
+  }
+  /** Milliseconds before a request is abandoned. */
+  get timeout() {
+    return this.#timeout;
+  }
+  /**
+   * Records a backend event against an identity.
+   *
+   * ```ts
+   * await client.track('user.signup', {
+   *   identity: 'user_12345',
+   *   data: { plan: 'pro', referrer: 'partner-x' },
+   *   identityData: { email: 'ada@example.com', name: 'Ada Lovelace' },
+   * });
+   * ```
+   *
+   * @param type Your name for the event, such as `"user.signup"`. Map it to one of Dregs's
+   *   canonical types under **Settings → Mappings** so the analyzers know what it means.
+   * @param options The identity the event belongs to, and anything else worth sending.
+   * @returns The outcome. Check `.accepted` to confirm Dregs recorded the event.
+   * @throws {QuotaExceededError} The account is over its monthly event limit.
+   * @throws {RateLimitError} The credential is ingesting too fast.
+   * @throws {AuthenticationError} The secret key was not recognized.
+   * @throws {BadRequestError} The event was malformed.
+   * @throws {TypeError} The event type, identity, or event id was unusable. These are thrown
+   *   before anything is sent.
+   */
+  async track(type, options) {
+    return parseTrackResult(await this.request("POST", "/events", this.trackBody(type, options)));
+  }
+  /**
+   * Builds the `POST /api/events` body.
+   *
+   * An event id is always sent. When the caller has an id of their own it is used verbatim, so
+   * reposting the same event is a no-op on the Dregs side; otherwise one is generated, which is
+   * what makes this client's own retries safe to perform.
+   */
+  trackBody(type, options) {
+    if (!type) {
+      throw new TypeError("An event type is required.");
+    }
+    if (!options?.identity) {
+      throw new TypeError(
+        "An identity is required. A server-side event has no device signature, so the identity is the only thing tying the event to a user."
+      );
+    }
+    const eventId = options.eventId ?? randomEventId();
+    if (eventId.startsWith("dregs-")) {
+      throw new TypeError("Event ids starting with 'dregs-' are reserved for Dregs itself.");
+    }
+    if (eventId.length > 64) {
+      throw new TypeError("Event ids cannot be longer than 64 characters.");
+    }
+    const body = {
+      id: eventId,
+      type,
+      data: { ...options.data ?? {} },
+      identity: { id: options.identity, data: { ...options.identityData ?? {} } },
+      source: options.source ?? DEFAULT_SOURCE
+    };
+    if (options.timestamp !== void 0) {
+      body.timestamp = toIsoUtc(options.timestamp);
+    }
+    return body;
+  }
+  /**
+   * Sends one request, retrying what is worth retrying, and returns the parsed JSON body.
+   *
+   * The retry loop reuses the request body verbatim, which is what keeps a retried event
+   * idempotent: the generated id is built once, before the first attempt.
+   */
+  async request(method, path2, body) {
+    const url = `${this.#baseUrl}/${path2.replace(/^\/+/, "")}`;
+    const init = this.requestInit(method, body);
+    for (let attempt = 0; ; attempt += 1) {
+      let response;
+      let text;
+      try {
+        response = await this.#fetch(url, { ...init, signal: AbortSignal.timeout(this.#timeout) });
+        text = await response.text();
+      } catch (cause) {
+        if (!this.shouldRetry(attempt, null)) {
+          throw isTimeout(cause) ? new chunkK63AUEQR_cjs.DregsTimeoutError(
+            `The request to ${url} did not answer within ${this.#timeout}ms.`,
+            { cause }
+          ) : new chunkK63AUEQR_cjs.DregsConnectionError(`Could not reach Dregs at ${url}: ${describe(cause)}`, {
+            cause
+          });
+        }
+        await sleep(this.backoff(attempt, null));
+        continue;
+      }
+      try {
+        return processResponse(response, text);
+      } catch (error) {
+        if (error instanceof chunkK63AUEQR_cjs.DregsAPIError && this.shouldRetry(attempt, error.statusCode)) {
+          await sleep(
+            this.backoff(attempt, error instanceof chunkK63AUEQR_cjs.RateLimitError ? error.retryAfter : null)
+          );
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+  requestInit(method, body) {
+    const headers = {
+      Authorization: `Bearer ${this.#secretKey}`,
+      Accept: "application/json",
+      "User-Agent": userAgent()
+    };
+    if (body === void 0) {
+      return { method, headers };
+    }
+    headers["Content-Type"] = "application/json";
+    return { method, headers, body: JSON.stringify(body) };
+  }
+  shouldRetry(attempt, statusCode) {
+    if (attempt >= this.#maxRetries) {
+      return false;
+    }
+    return statusCode === null || RETRY_STATUSES.has(statusCode);
+  }
+  /**
+   * Milliseconds to wait before attempt `attempt + 1`.
+   *
+   * `Retry-After` wins when the server sent one. Otherwise this is exponential with full jitter,
+   * which keeps a fleet of workers that all hit the limit at once from retrying in lockstep.
+   *
+   * Protected rather than private so a test can stub the waiting out.
+   */
+  backoff(attempt, retryAfterSeconds) {
+    if (retryAfterSeconds !== null && retryAfterSeconds >= 0) {
+      return Math.min(retryAfterSeconds * 1e3, MAX_RETRY_AFTER_MS);
+    }
+    return Math.random() * Math.min(500 * 2 ** attempt, MAX_BACKOFF_MS);
+  }
+};
+function processResponse(response, text) {
+  const payload = parseJson(text);
+  if (response.status >= 400) {
+    throw apiError(response, payload);
+  }
+  if (isRecord(payload)) {
+    if (payload.status === STATUS_RATE_LIMITED) {
+      throw new chunkK63AUEQR_cjs.RateLimitError("Ingestion rate limit exceeded for this credential.", {
+        body: payload,
+        requestId: requestId(response),
+        retryAfter: retryAfter(response)
+      });
+    }
+    if (payload.status === STATUS_QUOTA_EXCEEDED) {
+      throw new chunkK63AUEQR_cjs.QuotaExceededError("The account is over its monthly event limit.", {
+        statusCode: 402,
+        body: payload,
+        requestId: requestId(response)
+      });
+    }
+  }
+  return payload;
+}
+function apiError(response, payload) {
+  const message = messageFrom(payload) ?? response.statusText ?? "Request failed";
+  const id = requestId(response);
+  if (response.status === 429) {
+    return new chunkK63AUEQR_cjs.RateLimitError(message, {
+      body: payload,
+      requestId: id,
+      retryAfter: retryAfter(response)
+    });
+  }
+  const ErrorClass = chunkK63AUEQR_cjs.errorForStatus(response.status);
+  return new ErrorClass(message, { statusCode: response.status, body: payload, requestId: id });
+}
+function messageFrom(payload) {
+  if (!isRecord(payload)) {
+    return null;
+  }
+  for (const key of ["message", "error", "status"]) {
+    const value = payload[key];
+    if (typeof value === "string" && value) {
+      return value;
+    }
+  }
+  return null;
+}
+function requestId(response) {
+  return response.headers.get("X-Request-Id");
+}
+function retryAfter(response) {
+  const raw = response.headers.get("Retry-After");
+  if (raw === null) {
+    return null;
+  }
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) ? seconds : null;
+}
+function parseJson(text) {
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTimeout(cause) {
+  const names = [nameOf(cause), nameOf(cause?.cause)];
+  return names.includes("TimeoutError") || names.includes("AbortError");
+}
+function nameOf(value) {
+  if (typeof value !== "object" || value === null || !("name" in value)) {
+    return null;
+  }
+  const { name } = value;
+  return typeof name === "string" ? name : null;
+}
+function describe(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+function sleep(ms) {
+  return ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+}
+function readEnv(name) {
+  return typeof process === "undefined" ? void 0 : process.env[name];
+}
+function randomEventId() {
+  return globalThis.crypto.randomUUID().replace(/-/g, "");
+}
+function toIsoUtc(value) {
+  const moment = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(moment.getTime())) {
+    throw new TypeError(`The timestamp ${JSON.stringify(value)} is not a valid date.`);
+  }
+  return moment.toISOString().replace(/\.000Z$/, "Z");
+}
+function userAgent() {
+  const runtime = typeof process !== "undefined" && process.versions?.node ? `node ${process.versions.node}` : "unknown";
+  return `dregs-node/${VERSION} (${runtime})`;
+}
+
+Object.defineProperty(exports, "AuthenticationError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.AuthenticationError; }
+});
+Object.defineProperty(exports, "BadRequestError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.BadRequestError; }
+});
+Object.defineProperty(exports, "DEFAULT_TOLERANCE_SECONDS", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.DEFAULT_TOLERANCE_SECONDS; }
+});
+Object.defineProperty(exports, "DregsAPIError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.DregsAPIError; }
+});
+Object.defineProperty(exports, "DregsConnectionError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.DregsConnectionError; }
+});
+Object.defineProperty(exports, "DregsError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.DregsError; }
+});
+Object.defineProperty(exports, "DregsTimeoutError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.DregsTimeoutError; }
+});
+Object.defineProperty(exports, "EVENT_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.EVENT_HEADER; }
+});
+Object.defineProperty(exports, "NotFoundError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.NotFoundError; }
+});
+Object.defineProperty(exports, "PermissionDeniedError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.PermissionDeniedError; }
+});
+Object.defineProperty(exports, "QuotaExceededError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.QuotaExceededError; }
+});
+Object.defineProperty(exports, "RateLimitError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.RateLimitError; }
+});
+Object.defineProperty(exports, "SIGNATURE_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.SIGNATURE_HEADER; }
+});
+Object.defineProperty(exports, "ServerError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.ServerError; }
+});
+Object.defineProperty(exports, "TIMESTAMP_HEADER", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.TIMESTAMP_HEADER; }
+});
+Object.defineProperty(exports, "WebhookVerificationError", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.WebhookVerificationError; }
+});
+Object.defineProperty(exports, "computeWebhookSignature", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.computeWebhookSignature; }
+});
+Object.defineProperty(exports, "errorForStatus", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.errorForStatus; }
+});
+Object.defineProperty(exports, "verifyWebhook", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.verifyWebhook; }
+});
+Object.defineProperty(exports, "verifyWebhookSignature", {
+  enumerable: true,
+  get: function () { return chunkK63AUEQR_cjs.verifyWebhookSignature; }
+});
+exports.BASE_URL_ENV = BASE_URL_ENV;
+exports.CATEGORIES = CATEGORIES;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_MAX_RETRIES = DEFAULT_MAX_RETRIES;
+exports.DEFAULT_SOURCE = DEFAULT_SOURCE;
+exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+exports.Dregs = Dregs;
+exports.Identities = Identities;
+exports.SECRET_KEY_ENV = SECRET_KEY_ENV;
+exports.Scores = Scores;
+exports.VERSION = VERSION;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map