@shelbyb/daywalker-sdk 0.1.4 → 0.3.0

package/README.md

@@ -62,7 +62,8 @@ The private key is never printed unless you pass `--print-key`.
 | `DAYWALKER_SIGNING_KEY_PREVIOUS` | during rotation | Previous private key, maintained during deployment transitions |
 | `DAYWALKER_DOMAIN` | optional | Optional caller identifier or host domain name |
 | `DAYWALKER_PUBLIC_KEY` | optional | Daywalker Auth public key for zero-egress offline JWT lease verification |
-| `DAYWALKER_AUTH_URL` | optional | Defaults to `https://auth.daywalker.dev` |
+| `DAYWALKER_AUTH_URL` | optional | Defaults to `https://auth.daywalker.dev`; must be `https://` (except localhost) |
+| `DAYWALKER_LEASE_ISSUER` | optional | Expected `iss` of offline-verified JWT leases |
 
 ---
 
@@ -81,7 +82,8 @@ const client = new Daywalker({
 });
 
 // Option 2: Default lazy singleton (reads process.env automatically)
-const result = await daywalker.validateToken();
+const result = await daywalker.validateToken(incomingToken);
+// Service health check of this service's own DAYWALKER_API_KEY: daywalker.validateServiceKey()
 
 if (result.ok) {
   console.log("Validated tenant:", result.data.tenantId);
@@ -135,6 +137,8 @@ export const config = {
 };
 ```
 
+Each request must carry `Authorization: Bearer <token>` or `x-api-token`; without one, API routes get `401` and pages redirect to `errorPath`. Only `/_next/static/`, `/_next/image`, the favicon and static file extensions outside `/api/` skip auth. To gate the app on this service's own API key instead (the self-healing error page), use `createDaywalkerServiceHealthMiddleware` with the same options.
+
 ### Route Handler Wrapper
 
 ```ts
@@ -181,6 +185,8 @@ const client = new Daywalker({
 const result = await client.validateToken(incomingJwt);
 ```
 
+Leases must have a numeric `exp` and an `aud` (or `serviceSlug`) equal to your service slug, so `serviceSlug` must be configured. Set `leaseIssuer` (or `DAYWALKER_LEASE_ISSUER`) to also check `iss`.
+
 ---
 
 ## CLI Reference
@@ -220,6 +226,29 @@ The exact signature base and test cases are verified against [`test-vectors/sign
 
 ---
 
+## DevPulse SDKs (one package)
+
+The same package ships the [DevPulse](https://github.com/shelbyb/devpulse) client SDKs as subpath exports. Each subpath is tree-shakeable and has zero dependencies; `react` and the OpenFeature SDKs are optional peer dependencies used only by their subpaths.
+
+| Import | What it is | Docs |
+|---|---|---|
+| `@shelbyb/daywalker-sdk/flags` | Feature flags for browsers and JS clients, real-time over SSE | [docs/flags.md](./docs/flags.md) |
+| `@shelbyb/daywalker-sdk/flags/node` | Server-side flags with local evaluation and streaming updates | [docs/flags-node.md](./docs/flags-node.md) |
+| `@shelbyb/daywalker-sdk/flags/react` | React provider and hooks (SSR bootstrap, no flicker) | [docs/flags-react.md](./docs/flags-react.md) |
+| `@shelbyb/daywalker-sdk/flags/engine` | The deterministic evaluation engine (advanced / testing) | — |
+| `@shelbyb/daywalker-sdk/openfeature/server`, `/openfeature/web` | OpenFeature providers | [docs/openfeature.md](./docs/openfeature.md) |
+| `@shelbyb/daywalker-sdk/analytics` | Product analytics: events, page views, identify, sessions (browser and Node) | [docs/analytics.md](./docs/analytics.md) |
+
+```ts
+import { createClient } from "@shelbyb/daywalker-sdk/flags";
+import { createAnalytics } from "@shelbyb/daywalker-sdk/analytics";
+
+const flags = createClient(clientSideId, { kind: "user", key: user.id }, { baseUrl: "https://devpulse.example.com" });
+const analytics = createAnalytics({ writeKey: "dpa_…", host: "https://devpulse.example.com", flags }); // events carry $feature/<key>
+```
+
+---
+
 ## License
 
 MIT

package/dist/analytics/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * DevPulse product analytics. Works in browsers (automatic page views,
+ * sessions, persistence, sendBeacon on page hide) and in Node (pass a
+ * distinctId per call). Events are batched and retried with backoff.
+ */
+export type Properties = Record<string, unknown>;
+/** Anything with `allFlags()`, e.g. a DevPulse feature-flag client. */
+export type FlagSource = {
+    allFlags(): Record<string, unknown>;
+};
+export type AnalyticsOptions = {
+    /** The project's public write key (dpa_…). */
+    writeKey: string;
+    /** Your DevPulse URL, e.g. https://devpulse.example.com (https required except on localhost). */
+    host: string;
+    /** Capture $pageview on load and on client-side navigation (browsers). Default true. */
+    autocapturePageviews?: boolean;
+    /** Send when this many events are queued. Default 20 (1 in Node is not needed: use flush()). */
+    flushAt?: number;
+    /** Send queued events this often, in ms. Default 2000 in browsers, 10000 in Node. */
+    flushInterval?: number;
+    /** Events kept while offline; the oldest are dropped past this. Default 1000. */
+    maxQueueSize?: number;
+    /** Where the anonymous id, super properties and session live. Default localStorage in browsers. */
+    persistence?: "localStorage" | "memory";
+    /** A new session starts after this much inactivity. Default 30. */
+    sessionTimeoutMinutes?: number;
+    /** Adds `$feature/<key>` properties with each flag's current value to every event. */
+    flags?: FlagSource;
+    /** Don't send anything when the browser's Do Not Track is on. Default false. */
+    respectDoNotTrack?: boolean;
+    /** Start opted out (e.g. until the user accepts a consent banner). */
+    optedOut?: boolean;
+    /**
+     * Send $current_url / $referrer with their full query string and fragment. Default false:
+     * the fragment is dropped and only campaign parameters (utm_*, gclid, fbclid, ref) are kept,
+     * so OAuth codes, reset tokens and the like never leave the page.
+     */
+    captureFullUrls?: boolean;
+    fetch?: typeof fetch;
+    onError?: (err: Error) => void;
+};
+export type CaptureOptions = {
+    /** Server-side: who did it. Defaults to the current browser user. */
+    distinctId?: string;
+    timestamp?: Date;
+    $set?: Properties;
+    $set_once?: Properties;
+};
+export declare const VERSION = "0.1.0";
+/** Drop the fragment and every query parameter outside the campaign allowlist. */
+export declare function sanitizeUrl(raw: string): string;
+/** Time-ordered UUID (v7). */
+export declare function uuidv7(ms?: number): string;
+export declare class Analytics {
+    private opts;
+    private store;
+    private state;
+    private queue;
+    private timer;
+    private sending;
+    private backoff;
+    private lastUrl;
+    private cleanup;
+    private endpoint;
+    constructor(options: AnalyticsOptions);
+    /** Record an event. */
+    capture(event: string, properties?: Properties, opts?: CaptureOptions): void;
+    /** Record a page view (automatic unless autocapturePageviews is false). */
+    pageview(properties?: Properties): void;
+    /**
+     * Link this browser to a known user. Events from before (the anonymous id)
+     * are merged into the user's profile. Optionally set person properties.
+     */
+    identify(distinctId: string, set?: Properties, setOnce?: Properties): void;
+    /** Update the current person's properties. */
+    setPersonProperties(set?: Properties, setOnce?: Properties, opts?: {
+        distinctId?: string;
+    }): void;
+    /** Properties sent with every event from now on (persisted in browsers). */
+    register(properties: Properties): void;
+    unregister(key: string): void;
+    /** On logout: a new anonymous id, no super properties, a new session. */
+    reset(): void;
+    optOut(): void;
+    optIn(): void;
+    hasOptedOut(): boolean;
+    getDistinctId(): string;
+    getSessionId(): string | null;
+    /** Send everything queued now. */
+    flush(): Promise<void>;
+    /** Flush and detach listeners (call before a Node process exits). */
+    shutdown(): Promise<void>;
+    private disabled;
+    private context;
+    private url;
+    private flagProps;
+    /** Rolling session: renewed after inactivity or at most every 24 hours. */
+    private session;
+    private enqueue;
+    private schedule;
+    /** Send one batch; on failure requeue it and back off. Resolves true when sent (or dropped as invalid). */
+    private send;
+    /** On page hide, hand the queue to sendBeacon so it survives navigation. */
+    private beacon;
+    private attachBrowser;
+}
+export declare function createAnalytics(options: AnalyticsOptions): Analytics;

package/dist/analytics/index.js

@@ -0,0 +1,371 @@
+import { assertSecureUrl } from "../config.js";
+export const VERSION = "0.1.0";
+const KEPT_QUERY_PARAMS = new Set(["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "gclid", "fbclid", "ref"]);
+/** Drop the fragment and every query parameter outside the campaign allowlist. */
+export function sanitizeUrl(raw) {
+    if (!raw)
+        return raw;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return raw.split(/[?#]/)[0];
+    }
+    url.hash = "";
+    for (const key of [...url.searchParams.keys()]) {
+        if (!KEPT_QUERY_PARAMS.has(key))
+            url.searchParams.delete(key);
+    }
+    return url.toString();
+}
+const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+const MAX_SESSION_MS = 24 * 3_600_000;
+/** Time-ordered UUID (v7). */
+export function uuidv7(ms = Date.now()) {
+    const b = new Uint8Array(16);
+    const c = globalThis.crypto;
+    if (c?.getRandomValues)
+        c.getRandomValues(b);
+    else
+        for (let i = 0; i < 16; i++)
+            b[i] = Math.floor(Math.random() * 256);
+    for (let i = 0; i < 6; i++)
+        b[i] = Math.floor(ms / 2 ** (8 * (5 - i))) % 256;
+    b[6] = (b[6] & 0x0f) | 0x70;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+class Store {
+    key;
+    local;
+    mem = null;
+    constructor(key, local) {
+        this.key = key;
+        this.local = local;
+    }
+    load() {
+        if (this.mem)
+            return this.mem;
+        if (this.local) {
+            try {
+                const raw = localStorage.getItem(this.key);
+                if (raw)
+                    this.mem = JSON.parse(raw);
+            }
+            catch {
+                /* storage blocked: memory only */
+            }
+        }
+        return this.mem;
+    }
+    save(s) {
+        this.mem = s;
+        if (!this.local)
+            return;
+        try {
+            localStorage.setItem(this.key, JSON.stringify(s));
+        }
+        catch {
+            /* storage full or blocked */
+        }
+    }
+}
+export class Analytics {
+    opts;
+    store;
+    state;
+    queue = [];
+    timer;
+    sending = null;
+    backoff = 0;
+    lastUrl = "";
+    cleanup = [];
+    endpoint;
+    constructor(options) {
+        if (!options.writeKey)
+            throw new Error("writeKey is required");
+        if (!options.host)
+            throw new Error("host is required");
+        assertSecureUrl("host", options.host);
+        this.opts = { flushAt: 20, flushInterval: isBrowser ? 2000 : 10000, maxQueueSize: 1000, sessionTimeoutMinutes: 30, ...options };
+        this.endpoint = `${options.host.replace(/\/+$/, "")}/a/batch`;
+        this.store = new Store(`dp_analytics_${options.writeKey}`, (options.persistence ?? (isBrowser ? "localStorage" : "memory")) === "localStorage" && isBrowser);
+        this.state = this.store.load() ?? { distinctId: uuidv7(), identified: false, props: {} };
+        if (options.optedOut !== undefined)
+            this.state.optedOut = options.optedOut;
+        this.store.save(this.state);
+        if (isBrowser)
+            this.attachBrowser();
+    }
+    // ---------- Public API ----------
+    /** Record an event. */
+    capture(event, properties = {}, opts = {}) {
+        if (!event || this.disabled())
+            return;
+        const now = opts.timestamp ?? new Date();
+        const props = { ...this.context(), ...this.state.props, ...this.flagProps(), ...properties };
+        if (!opts.distinctId)
+            props.$session_id = this.session(now.getTime());
+        const e = { uuid: uuidv7(now.getTime()), event, distinct_id: opts.distinctId ?? this.state.distinctId, timestamp: now.toISOString(), properties: props };
+        if (opts.$set)
+            e.$set = opts.$set;
+        if (opts.$set_once)
+            e.$set_once = opts.$set_once;
+        this.enqueue(e);
+    }
+    /** Record a page view (automatic unless autocapturePageviews is false). */
+    pageview(properties = {}) {
+        if (!isBrowser)
+            return this.capture("$pageview", properties);
+        this.lastUrl = location.href;
+        const url = this.url(location.href);
+        const utm = Object.fromEntries([...new URLSearchParams(location.search)].filter(([k]) => /^utm_(source|medium|campaign|term|content)$/.test(k)));
+        let setOnce;
+        if (!this.state.initialSent) {
+            setOnce = {
+                $initial_referrer: document.referrer ? this.url(document.referrer) : "$direct",
+                $initial_referring_domain: referringDomain(document.referrer) ?? "$direct",
+                $initial_current_url: url,
+                $initial_pathname: location.pathname,
+                ...Object.fromEntries(Object.entries(utm).map(([k, v]) => [`$initial_${k}`, v])),
+            };
+            this.state.initialSent = true;
+            this.store.save(this.state);
+        }
+        this.capture("$pageview", { $title: document.title, ...utm, ...properties }, { $set_once: setOnce });
+    }
+    /**
+     * Link this browser to a known user. Events from before (the anonymous id)
+     * are merged into the user's profile. Optionally set person properties.
+     */
+    identify(distinctId, set, setOnce) {
+        if (!distinctId || this.disabled())
+            return;
+        const previous = this.state.distinctId;
+        if (previous === distinctId) {
+            if (set || setOnce)
+                this.setPersonProperties(set, setOnce);
+            return;
+        }
+        this.state = { ...this.state, distinctId, identified: true };
+        this.store.save(this.state);
+        this.capture("$identify", { $anon_distinct_id: previous }, { $set: set, $set_once: setOnce });
+    }
+    /** Update the current person's properties. */
+    setPersonProperties(set, setOnce, opts = {}) {
+        this.capture("$set", {}, { distinctId: opts.distinctId, $set: set, $set_once: setOnce });
+    }
+    /** Properties sent with every event from now on (persisted in browsers). */
+    register(properties) {
+        this.state = { ...this.state, props: { ...this.state.props, ...properties } };
+        this.store.save(this.state);
+    }
+    unregister(key) {
+        const props = { ...this.state.props };
+        delete props[key];
+        this.state = { ...this.state, props };
+        this.store.save(this.state);
+    }
+    /** On logout: a new anonymous id, no super properties, a new session. */
+    reset() {
+        this.state = { distinctId: uuidv7(), identified: false, props: {}, optedOut: this.state.optedOut, initialSent: this.state.initialSent };
+        this.store.save(this.state);
+    }
+    optOut() {
+        this.state = { ...this.state, optedOut: true };
+        this.store.save(this.state);
+        this.queue = [];
+    }
+    optIn() {
+        this.state = { ...this.state, optedOut: false };
+        this.store.save(this.state);
+    }
+    hasOptedOut() {
+        return !!this.state.optedOut;
+    }
+    getDistinctId() {
+        return this.state.distinctId;
+    }
+    getSessionId() {
+        return this.state.session?.id ?? null;
+    }
+    /** Send everything queued now. */
+    async flush() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        while (this.queue.length) {
+            if (this.sending)
+                await this.sending;
+            else {
+                this.sending = this.send().finally(() => (this.sending = null));
+                const ok = await this.sending;
+                if (!ok)
+                    return;
+            }
+        }
+    }
+    /** Flush and detach listeners (call before a Node process exits). */
+    async shutdown() {
+        for (const fn of this.cleanup.splice(0))
+            fn();
+        await this.flush();
+    }
+    // ---------- Internals ----------
+    disabled() {
+        if (this.state.optedOut)
+            return true;
+        if (this.opts.respectDoNotTrack && isBrowser) {
+            const nav = navigator;
+            return nav.doNotTrack === "1" || nav.msDoNotTrack === "1" || window.doNotTrack === "1";
+        }
+        return false;
+    }
+    context() {
+        const base = { $lib: "devpulse-analytics", $lib_version: VERSION };
+        if (!isBrowser)
+            return base;
+        return {
+            ...base,
+            $current_url: this.url(location.href),
+            $host: location.host,
+            $pathname: location.pathname,
+            $referrer: document.referrer ? this.url(document.referrer) : "$direct",
+            $referring_domain: referringDomain(document.referrer) ?? "$direct",
+            $screen_width: screen.width,
+            $screen_height: screen.height,
+            $viewport_width: window.innerWidth,
+            $viewport_height: window.innerHeight,
+            $browser_language: navigator.language,
+            $device_id: this.state.identified ? undefined : this.state.distinctId,
+        };
+    }
+    url(raw) {
+        return this.opts.captureFullUrls ? raw : sanitizeUrl(raw);
+    }
+    flagProps() {
+        if (!this.opts.flags)
+            return {};
+        try {
+            const all = this.opts.flags.allFlags();
+            return Object.fromEntries(Object.entries(all).map(([k, v]) => [`$feature/${k}`, v]));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Rolling session: renewed after inactivity or at most every 24 hours. */
+    session(now) {
+        const s = this.state.session;
+        const timeout = this.opts.sessionTimeoutMinutes * 60_000;
+        if (!s || now - s.last > timeout || now - s.start > MAX_SESSION_MS)
+            this.state.session = { id: uuidv7(now), last: now, start: now };
+        else
+            s.last = now;
+        this.store.save(this.state);
+        return this.state.session.id;
+    }
+    enqueue(e) {
+        this.queue.push(e);
+        if (this.queue.length > this.opts.maxQueueSize)
+            this.queue.splice(0, this.queue.length - this.opts.maxQueueSize);
+        if (this.queue.length >= this.opts.flushAt && !this.backoff)
+            void this.flush();
+        else
+            this.schedule();
+    }
+    schedule() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.flush();
+        }, this.backoff || this.opts.flushInterval);
+        this.timer.unref?.();
+    }
+    /** Send one batch; on failure requeue it and back off. Resolves true when sent (or dropped as invalid). */
+    async send() {
+        const batch = this.queue.splice(0, 100);
+        if (!batch.length)
+            return true;
+        const f = this.opts.fetch ?? globalThis.fetch;
+        try {
+            const res = await f(this.endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: new Date().toISOString() }),
+                keepalive: isBrowser,
+            });
+            if (res.ok || (res.status >= 400 && res.status < 500 && res.status !== 429)) {
+                if (!res.ok)
+                    this.opts.onError?.(new Error(`DevPulse analytics rejected ${batch.length} events: HTTP ${res.status}`));
+                this.backoff = 0;
+                return true;
+            }
+            throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            this.queue.unshift(...batch);
+            this.backoff = Math.min(60_000, (this.backoff || 1000) * 2);
+            this.opts.onError?.(err);
+            this.schedule();
+            return false;
+        }
+    }
+    /** On page hide, hand the queue to sendBeacon so it survives navigation. */
+    beacon() {
+        if (!this.queue.length || typeof navigator.sendBeacon !== "function")
+            return;
+        const batch = this.queue.splice(0, 100);
+        const body = JSON.stringify({ api_key: this.opts.writeKey, batch, sent_at: new Date().toISOString() });
+        // text/plain avoids a CORS preflight, which beacons can't do.
+        if (!navigator.sendBeacon(this.endpoint, new Blob([body], { type: "text/plain" })))
+            this.queue.unshift(...batch);
+    }
+    attachBrowser() {
+        const onHide = () => document.visibilityState === "hidden" && this.beacon();
+        const onPageHide = () => this.beacon();
+        document.addEventListener("visibilitychange", onHide);
+        window.addEventListener("pagehide", onPageHide);
+        this.cleanup.push(() => {
+            document.removeEventListener("visibilitychange", onHide);
+            window.removeEventListener("pagehide", onPageHide);
+        });
+        if (this.opts.autocapturePageviews === false)
+            return;
+        const onNav = () => {
+            // Route changes fire before the new title is set; give the app a tick.
+            setTimeout(() => location.href !== this.lastUrl && this.pageview(), 0);
+        };
+        const { pushState, replaceState } = history;
+        history.pushState = function (...args) {
+            pushState.apply(this, args);
+            onNav();
+        };
+        history.replaceState = function (...args) {
+            replaceState.apply(this, args);
+            onNav();
+        };
+        window.addEventListener("popstate", onNav);
+        this.cleanup.push(() => {
+            history.pushState = pushState;
+            history.replaceState = replaceState;
+            window.removeEventListener("popstate", onNav);
+        });
+        this.pageview();
+    }
+}
+function referringDomain(ref) {
+    if (!ref)
+        return undefined;
+    try {
+        return new URL(ref).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createAnalytics(options) {
+    return new Analytics(options);
+}

package/dist/cli.js

@@ -76,6 +76,8 @@ function writeEnvFile(file, values) {
         out.push("# Daywalker Auth (managed by `daywalker init`)", ...added.map(([k, v]) => `${k}="${v}"`));
     }
     fs.writeFileSync(file, out.join("\n") + "\n", { mode: 0o600 });
+    // `mode` only applies when the file is created; tighten an existing file too.
+    fs.chmodSync(file, 0o600);
 }
 function ensureGitignored(dir, entry) {
     const file = path.join(dir, ".gitignore");
@@ -233,6 +235,9 @@ async function check() {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const parsedArgs = args(rest);
+    if (typeof parsedArgs["api-key"] === "string") {
+        console.warn("! --api-key exposes the key in shell history and process listings; prefer DAYWALKER_API_KEY in the environment or .env.local.");
+    }
     if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
         console.log(HELP);
         return;

package/dist/client.d.ts

@@ -1,5 +1,7 @@
 import { type ResolvedConfig } from "./config.js";
 import { type DaywalkerConfig, type PublicJwk, type RetryOptions, type SelfCheckResult, type TokenPayload, type ValidateResult } from "./types.js";
+/** Validation results kept in memory; the least recently used are evicted past this. */
+export declare const MAX_VALIDATION_CACHE_ENTRIES = 1000;
 export type DaywalkerFetchInit = Omit<RequestInit, "body"> & {
     body?: BodyInit | object | null;
     retry?: RetryOptions;
@@ -18,9 +20,13 @@ export declare class Daywalker {
      * Signs and executes requests with automatic retry and exponential backoff on 429 responses.
      */
     fetch(path: string, init?: DaywalkerFetchInit): Promise<Response>;
+    private _cacheGet;
+    private _cacheSet;
     /**
-     * Validates incoming bearer tokens with memory caching and discriminated union return.
+     * Validates an incoming bearer token with memory caching and discriminated union return.
      * Supports zero-egress offline verification for JWT token leases when Daywalker's public key is configured.
+     * A missing token is always rejected (401); it never falls back to this service's own API key —
+     * use `validateServiceKey()` for that.
      */
     validateToken(tokenOrOptions?: string | {
         token?: string;
@@ -33,6 +39,14 @@ export declare class Daywalker {
         offlineOnly?: boolean;
     }): Promise<ValidateResult>;
     private _validateOnline;
+    /**
+     * Service health check: validates this service's own configured API key (DAYWALKER_API_KEY).
+     * Never use this to authenticate an incoming request.
+     */
+    validateServiceKey(options?: {
+        serviceSlug?: string;
+        forceRefresh?: boolean;
+    }): Promise<ValidateResult>;
     /**
      * Throws DaywalkerAuthError or DaywalkerRateLimitError if token is invalid or rate limited.
      */