@dregs/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,576 @@
+export { DEFAULT_TOLERANCE_SECONDS, EVENT_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, VerifyWebhookOptions, WebhookEvent, WebhookPayload, computeWebhookSignature, verifyWebhook, verifyWebhookSignature } from './webhooks.js';
+
+/**
+ * The package version, used in the `User-Agent` header.
+ *
+ * Kept here rather than read from `package.json` at runtime, because the published package is
+ * both ESM and CommonJS and neither can reach its own manifest portably. A test asserts this
+ * stays in step with `package.json`, so the two cannot drift.
+ */
+declare const VERSION = "0.1.0";
+
+/**
+ * Typed views over the Dregs API's responses.
+ *
+ * Every model keeps the response it was built from in `raw`, so a field Dregs adds after this
+ * release is still reachable without waiting for an SDK upgrade. Parsing is deliberately lenient:
+ * a missing field becomes `null` rather than an error, because an SDK that refuses to parse a
+ * response it half-understands is worse than one that hands back what it got.
+ *
+ * @module
+ */
+/**
+ * The four categories Dregs scores an identity in.
+ *
+ * A plain string union rather than an enum, so `scores.get('HUMANITY')` type-checks and a
+ * category from a future Dregs release still survives parsing (as a `null` category on a
+ * {@link Score} whose `raw` still names it).
+ */
+type Category = 'HUMANITY' | 'AUTHENTICITY' | 'UNIQUENESS' | 'BEHAVIOR';
+/** The four categories, in the order the dashboard shows them. */
+declare const CATEGORIES: readonly Category[];
+/** An unparsed JSON object, as received. */
+type RawPayload = Readonly<Record<string, unknown>>;
+/** The outcome of a {@link Dregs.track} call. */
+interface TrackResult {
+    /** The status Dregs reported, normally `"success"`. */
+    readonly status: string | null;
+    /**
+     * The event's identifier, either the one you supplied or one the SDK generated. It is `null`
+     * when the event was not recorded.
+     */
+    readonly id: string | null;
+    /**
+     * The device fingerprint Dregs resolved, for events that carried a device signature.
+     * Server-side events do not, so this is normally `null`.
+     */
+    readonly fingerprint: string | null;
+    /**
+     * Whether Dregs recorded the event.
+     *
+     * This is `false` in the uncommon case where Dregs accepts the request without recording an
+     * event. A server-side integration holding a valid secret key should not normally see it, so it
+     * is worth a log line if you do. Ingestion failures that are yours to act on (a bad request, an
+     * unknown key, an exhausted quota, a rate limit) throw instead of landing here.
+     */
+    readonly accepted: boolean;
+    /** The response body as received. */
+    readonly raw: RawPayload;
+}
+/** A label Dregs applied to an identity, from an analyzer or a badge rule. */
+interface Badge {
+    /** The badge's slug, such as `"behavior.account-takeover-signal"`. */
+    readonly slug: string | null;
+    /** The human-readable name, such as `"Account Takeover Suspected"`. */
+    readonly name: string | null;
+    /** Where the badge came from: an analyzer observation or a badge rule. */
+    readonly type: string | null;
+    /** A sentence describing why the badge was applied. */
+    readonly explanation: string | null;
+    /** The counts and details behind the badge. */
+    readonly metadata: RawPayload;
+    /** The response fragment this badge was built from. */
+    readonly raw: RawPayload;
+}
+/** One analyzer's finding, and the reasoning behind a slice of a score. */
+interface Observation {
+    /** The category the observation contributes to, or `null` for one this release predates. */
+    readonly category: Category | null;
+    /** The analyzer's identifier, such as `"humanity.user-agent"`. */
+    readonly id: string | null;
+    /** A human-readable name for the analyzer. */
+    readonly label: string | null;
+    /** A sentence describing what the analyzer found. This is the text to show or log. */
+    readonly explanation: string | null;
+    /** 0.0 for entirely suspicious, 1.0 for entirely legitimate. */
+    readonly value: number | null;
+    /** How sure the analyzer is, from 0.0 to 1.0. */
+    readonly confidence: number | null;
+    /** How heavily this observation counts toward the category score. */
+    readonly weight: number | null;
+    /** The counts and details behind the finding. */
+    readonly metadata: RawPayload;
+    /** The response fragment this observation was built from. */
+    readonly raw: RawPayload;
+}
+/** One category's score. */
+interface Score {
+    /** The category scored, or `null` for one this release predates. */
+    readonly category: Category | null;
+    /** An integer from 0 (worst) to 100 (best). */
+    readonly value: number | null;
+    /**
+     * The observations behind the score. Empty on the result of `identities.scores()`, which
+     * reports the scores alone; the observations come from `identities.analysis()`.
+     */
+    readonly observations: readonly Observation[];
+    /** The response fragment this score was built from. */
+    readonly raw: RawPayload;
+}
+/**
+ * An identity's category scores.
+ *
+ * An array of {@link Score}, so it indexes, iterates, spreads, and maps like any other, and it
+ * also offers the four categories by name:
+ *
+ * ```ts
+ * const scores = await client.identities.scores('user_12345');
+ *
+ * if (scores.authenticity !== null && scores.authenticity < 40) {
+ *   await holdForReview('user_12345');
+ * }
+ * ```
+ *
+ * A category Dregs has not scored yet is absent from the array, and its named accessor reads
+ * `null`. A brand-new identity comes back empty.
+ */
+declare class Scores extends Array<Score> {
+    /**
+     * `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](): ArrayConstructor;
+    constructor(items?: readonly Score[]);
+    /** Returns the score for `category`, or `null` when it has not been scored. */
+    get(category: Category): Score | null;
+    private value;
+    /** How likely it is that a person, rather than a script, is behind the account. */
+    get humanity(): number | null;
+    /** How genuine the details on the account look. */
+    get authenticity(): number | null;
+    /** How distinct the account is from others in the same tenant. */
+    get uniqueness(): number | null;
+    /** How ordinary the account's activity looks. */
+    get behavior(): number | null;
+}
+/**
+ * A user Dregs is tracking, and their current scores.
+ *
+ * `id` is your own identifier for the user, the one you pass to {@link Dregs.track} and to
+ * `dregs.identify()` in the browser tracker, not an internal Dregs id.
+ */
+interface Identity {
+    /** Your own id for the user. */
+    readonly id: string | null;
+    /** The name Dregs resolved from the identity attributes you have sent. */
+    readonly displayName: string | null;
+    /** The email address Dregs resolved from the identity attributes you have sent. */
+    readonly displayEmail: string | null;
+    /** The username Dregs resolved from the identity attributes you have sent. */
+    readonly displayUsername: string | null;
+    /** The current humanity score, 0 to 100, or `null` when the category is unscored. */
+    readonly humanityScore: number | null;
+    /** The current authenticity score, 0 to 100, or `null` when the category is unscored. */
+    readonly authenticityScore: number | null;
+    /** The current uniqueness score, 0 to 100, or `null` when the category is unscored. */
+    readonly uniquenessScore: number | null;
+    /** The current behavior score, 0 to 100, or `null` when the category is unscored. */
+    readonly behaviorScore: number | null;
+    /** When Dregs first saw this identity. */
+    readonly createdAt: Date | null;
+    /** When the identity record last changed. */
+    readonly updatedAt: Date | null;
+    /** When the most recent event for this identity arrived. */
+    readonly lastTrackedAt: Date | null;
+    /** When the most recent analysis cycle finished. */
+    readonly lastScoredAt: Date | null;
+    /**
+     * Whether the identity is excluded from fraud analysis, which is how an operator marks their
+     * own admin or load-test accounts.
+     */
+    readonly disregarded: boolean;
+    /** The badges currently applied to the identity. */
+    readonly badges: readonly Badge[];
+    /** Every identity attribute you have sent, merged. */
+    readonly data: RawPayload;
+    /**
+     * The four category scores, as a {@link Scores} for parity with `identities.scores()`.
+     *
+     * Built from the score fields on this response, so it costs no extra request.
+     */
+    readonly scores: Scores;
+    /** The response body this identity was built from. */
+    readonly raw: RawPayload;
+}
+/** One analysis cycle: the scores an identity was given, and why. */
+interface Analysis {
+    /** The cycle's identifier. */
+    readonly id: number | null;
+    /** The identity that was analyzed. */
+    readonly identityId: string | null;
+    /** The category scores, each carrying its observations. */
+    readonly scores: Scores;
+    /** Every observation from the cycle, flattened across all categories. */
+    readonly observations: readonly Observation[];
+    /** How many events the cycle considered. */
+    readonly eventCount: number | null;
+    /** How many devices the cycle considered. */
+    readonly deviceCount: number | null;
+    /** How long the cycle took, in milliseconds. */
+    readonly durationMillis: number | null;
+    /** When the cycle started. */
+    readonly startedAt: Date | null;
+    /** When the cycle finished. */
+    readonly finishedAt: Date | null;
+    /** The response body this analysis was built from. */
+    readonly raw: RawPayload;
+}
+
+/**
+ * The `client.identities` namespace.
+ *
+ * These are thin: they name the endpoint, then hand the response to a parser. The transport,
+ * retries, and error mapping all live on the client.
+ *
+ * @module
+ */
+
+/** How a resource reaches the client's transport. @internal */
+type RequestFn = (method: string, path: string, body?: unknown) => Promise<unknown>;
+/**
+ * Read identities and their scores.
+ *
+ * Reached as `client.identities`; there is no reason to construct one yourself.
+ */
+declare class Identities {
+    #private;
+    /** @internal */
+    constructor(request: RequestFn);
+    /**
+     * 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.
+     */
+    get(identityId: string): Promise<Identity>;
+    /**
+     * 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.
+     */
+    scores(identityId: string): Promise<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.
+     */
+    analysis(identityId: string): Promise<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.
+     */
+    analyze(identityId: string): Promise<void>;
+}
+
+/**
+ * The Dregs client.
+ *
+ * There is one client and every method returns a promise; JavaScript has no meaningful
+ * sync/async split, so there is no async twin to pick between.
+ *
+ * @module
+ */
+
+/** The API root used when neither an option nor `DREGS_BASE_URL` names one. */
+declare const DEFAULT_BASE_URL = "https://dregs.com/api";
+/** How long a request may take before it is abandoned, in milliseconds. */
+declare const DEFAULT_TIMEOUT_MS = 10000;
+/** How many times a failed request is retried before the error is thrown. */
+declare const DEFAULT_MAX_RETRIES = 2;
+/** The environment variable the secret key is read from. */
+declare const SECRET_KEY_ENV = "DREGS_SECRET_KEY";
+/** The environment variable the base URL is read from. */
+declare const BASE_URL_ENV = "DREGS_BASE_URL";
+/** The `source` sent on events when the caller does not name one. */
+declare const DEFAULT_SOURCE = "node-sdk";
+/** The `fetch` this client calls. Any implementation with the standard signature will do. */
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Everything you can configure on a {@link Dregs} client. */
+interface DregsOptions {
+    /**
+     * Your credential's secret key, the one starting `sk_`. Found under **Settings → Credentials**
+     * in the dashboard. Defaults to `$DREGS_SECRET_KEY`.
+     */
+    secretKey?: string;
+    /**
+     * The API root every request is built against. Defaults to `$DREGS_BASE_URL`, then
+     * `https://dregs.com/api`. A trailing slash is harmless.
+     */
+    baseUrl?: string;
+    /**
+     * Milliseconds before a request is abandoned and retried. Defaults to 10 000.
+     *
+     * This covers the whole request, not just the connect, so raise it if you are behind a slow
+     * egress proxy rather than lowering `maxRetries` to compensate.
+     */
+    timeout?: number;
+    /**
+     * How many times to retry a failed request. Defaults to 2; pass 0 to handle it yourself.
+     *
+     * Retries cover connection failures, timeouts, 408, 429, and 5xx, with exponential backoff and
+     * full jitter. `Retry-After` wins when the server sends one. A retried event keeps its id, so
+     * a retry can never double-count.
+     */
+    maxRetries?: number;
+    /**
+     * A `fetch` to call instead of the runtime's own, for callers who need a proxy agent, custom
+     * TLS, or their own instrumentation. Anything with the standard signature works, including a
+     * stub in a test.
+     */
+    fetch?: FetchLike;
+}
+/** The arguments to {@link Dregs.track} beyond the event type. */
+interface TrackOptions {
+    /**
+     * Your own id for the user. This is the same id you pass to `dregs.identify()` in the browser
+     * tracker, and the one you look scores up by.
+     *
+     * It is required: a server-side event carries no device signature, so the identity is the only
+     * thing tying the event to a user.
+     */
+    identity: string;
+    /** Attributes of the event itself, such as the plan bought or the referrer that sent them. */
+    data?: Readonly<Record<string, unknown>>;
+    /**
+     * Attributes of the *user*, such as email, name, or username. Dregs merges these into the
+     * identity, and the analyzers lean on them heavily, so send them whenever you have them.
+     *
+     * Flat keys work best. Name them as your application already does and map them to Dregs's
+     * canonical fields under **Settings → Mappings**.
+     */
+    identityData?: Readonly<Record<string, unknown>>;
+    /**
+     * Your own id for the event, which makes ingestion idempotent: reposting the same id returns
+     * the original event instead of recording a second one.
+     *
+     * Pass the id your application already has — the row id of the record that triggered the
+     * event, say. When you omit it the SDK generates one, which is what makes its own retries
+     * safe. At most 64 characters, and it cannot start with `dregs-`.
+     */
+    eventId?: string;
+    /**
+     * When the event happened, if not now. A `Date`, or an ISO-8601 string. Sent as UTC.
+     */
+    timestamp?: Date | string;
+    /** A label for where the event came from. Defaults to `"node-sdk"`. */
+    source?: string;
+}
+/**
+ * A Dregs client.
+ *
+ * The secret key comes from the `DREGS_SECRET_KEY` environment variable unless you pass one.
+ * Find it under **Settings → Credentials** in the dashboard; it is the key starting `sk_`, not
+ * the `pk_` public key the browser tracker uses.
+ *
+ * ```ts
+ * import { Dregs } from '@dregs/sdk';
+ *
+ * const client = new Dregs();
+ *
+ * await client.track('user.signup', { identity: 'user_12345', data: { plan: 'pro' } });
+ *
+ * const scores = await client.identities.scores('user_12345');
+ * ```
+ *
+ * Build one at startup and keep it. There is nothing to close: the client holds no state beyond
+ * its configuration, and connection pooling belongs to the runtime's `fetch`.
+ */
+declare class Dregs {
+    #private;
+    /** Read identities, their scores, and their analysis. */
+    readonly identities: Identities;
+    /**
+     * @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?: DregsOptions);
+    /** The API root every request is built against, with any trailing slash removed. */
+    get baseUrl(): string;
+    /** How many times a failed request is retried before the error is thrown. */
+    get maxRetries(): number;
+    /** Milliseconds before a request is abandoned. */
+    get timeout(): number;
+    /**
+     * 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.
+     */
+    track(type: string, options: TrackOptions): Promise<TrackResult>;
+    /**
+     * 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.
+     */
+    private trackBody;
+    /**
+     * 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.
+     */
+    private request;
+    private requestInit;
+    private shouldRetry;
+    /**
+     * 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.
+     */
+    protected backoff(attempt: number, retryAfterSeconds: number | null): number;
+}
+
+/**
+ * Errors thrown by the Dregs SDK.
+ *
+ * Everything this library throws derives from {@link DregsError}, so a caller that only wants a
+ * coarse "the Dregs call failed" branch can catch that one class. Errors that came back from the
+ * API carry the HTTP status and the parsed body; errors that never reached the API (DNS failure,
+ * connection refused, timeout) derive from {@link DregsConnectionError} instead.
+ *
+ * @module
+ */
+/**
+ * Base class for everything this library throws.
+ *
+ * `instanceof DregsError` is the one check that catches every failure mode, including webhook
+ * verification and transport failures that never produced an HTTP status.
+ */
+declare class DregsError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The request never reached Dregs: DNS, TCP, TLS, or a dropped connection. */
+declare class DregsConnectionError extends DregsError {
+}
+/** The request was still outstanding when the configured timeout elapsed. */
+declare class DregsTimeoutError extends DregsConnectionError {
+}
+/** An incoming webhook did not verify against the channel's signing secret. */
+declare class WebhookVerificationError extends DregsError {
+}
+/** The fields carried by every error that reached the API and came back an error. */
+interface DregsAPIErrorOptions {
+    /** The HTTP status code. */
+    statusCode: number;
+    /** The parsed JSON body, or `null` when the response was not JSON. */
+    body?: unknown;
+    /** Value of the `X-Request-Id` response header, when the response carried one. */
+    requestId?: string | null;
+    /** The underlying cause, when there is one worth keeping. */
+    cause?: unknown;
+}
+/**
+ * Dregs answered, and the answer was an error.
+ *
+ * `message` is the human-readable message the API sent, so `err.message` reads the way a JS
+ * caller expects. `toString()` prefixes it with the status and the request id, which is the form
+ * worth putting in a log line when you open a support ticket.
+ */
+declare class DregsAPIError extends DregsError {
+    /** The HTTP status code. */
+    readonly statusCode: number;
+    /** The parsed JSON body, or `null` when the response was not JSON. */
+    readonly body: unknown;
+    /**
+     * Value of the `X-Request-Id` response header, when present.
+     *
+     * Quote it when you report a problem: it is what lets Dregs find your exact request.
+     */
+    readonly requestId: string | null;
+    constructor(message: string, options: DregsAPIErrorOptions);
+    toString(): string;
+}
+/**
+ * 400. The request was malformed or missing something Dregs requires.
+ *
+ * For event ingestion this most often means the event carried neither an identity nor a device,
+ * or the body failed validation.
+ */
+declare class BadRequestError extends DregsAPIError {
+}
+/** 401. The secret key was missing, unrecognized, revoked, or expired. */
+declare class AuthenticationError extends DregsAPIError {
+}
+/**
+ * 402. The account is over its monthly event limit and ingestion is refused.
+ *
+ * Events are not queued while an account is over its limit, so the caller decides whether to drop
+ * the event or hold it. The limit resets with the billing period; upgrading the plan clears it
+ * immediately.
+ */
+declare class QuotaExceededError extends DregsAPIError {
+}
+/** 403. The credential authenticated but is not allowed to do this. */
+declare class PermissionDeniedError extends DregsAPIError {
+}
+/** 404. No such identity, or no analysis has been run for it yet. */
+declare class NotFoundError extends DregsAPIError {
+}
+/** The fields carried by a 429, on top of the usual API error fields. */
+interface RateLimitErrorOptions extends Omit<DregsAPIErrorOptions, 'statusCode'> {
+    statusCode?: number;
+    /** Seconds to wait before retrying, from the `Retry-After` header. */
+    retryAfter?: number | null;
+}
+/**
+ * 429. The credential exceeded its request rate limit.
+ *
+ * The client retries these on its own; you only see one when the retries were exhausted or turned
+ * off. Wait {@link RateLimitError.retryAfter} seconds before trying again when it is set.
+ */
+declare class RateLimitError extends DregsAPIError {
+    /**
+     * Seconds to wait before retrying, from the `Retry-After` header when the response carried a
+     * numeric one, and `null` otherwise.
+     */
+    readonly retryAfter: number | null;
+    constructor(message: string, options?: RateLimitErrorOptions);
+}
+/** 5xx. Something went wrong inside Dregs. These are retried automatically. */
+declare class ServerError extends DregsAPIError {
+}
+/**
+ * Returns the error class that represents `statusCode`.
+ *
+ * 429 is deliberately absent from the table: it needs the `Retry-After` header, so the client
+ * builds a {@link RateLimitError} directly rather than going through here.
+ */
+declare function errorForStatus(statusCode: number): new (message: string, options: DregsAPIErrorOptions) => DregsAPIError;
+
+export { type Analysis, AuthenticationError, BASE_URL_ENV, BadRequestError, type Badge, CATEGORIES, type Category, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_SOURCE, DEFAULT_TIMEOUT_MS, Dregs, DregsAPIError, type DregsAPIErrorOptions, DregsConnectionError, DregsError, type DregsOptions, DregsTimeoutError, type FetchLike, Identities, type Identity, NotFoundError, type Observation, PermissionDeniedError, QuotaExceededError, RateLimitError, type RateLimitErrorOptions, type RawPayload, SECRET_KEY_ENV, type Score, Scores, ServerError, type TrackOptions, type TrackResult, VERSION, WebhookVerificationError, errorForStatus };