@openlimiter/core 0.2.0 → 0.4.0

package/dist/schedule.js

@@ -0,0 +1,131 @@
+/**
+ * When a connection may next ask its provider a question.
+ *
+ * Background collection is the difference between a quota monitor and a file
+ * viewer, and a collector that retries a failing provider on a fixed interval
+ * is how a monitor gets an account rate limited. The whole policy lives here as
+ * arithmetic over injected values: the caller supplies the clock and the random
+ * source, so a schedule is exactly reproducible in a test and identical on all
+ * three operating systems.
+ */
+/** Longest our own backoff will ever grow to on its own. */
+export const REFRESH_BACKOFF_CEILING_SECONDS = 3_600;
+/**
+ * Longest a provider may push us out with Retry-After.
+ *
+ * The header is honoured because the provider knows its own limits better than
+ * we do, but a header is still input from outside, and a day is already far
+ * past the point where a person would reconnect by hand.
+ */
+export const REFRESH_RETRY_AFTER_CEILING_SECONDS = 86_400;
+/** How far either side of the computed delay the jitter may move it. */
+export const REFRESH_JITTER_RATIO = 0.2;
+/** The reader supplied sentinel for a connection that only refreshes by hand. */
+export const SCHEDULE_EXEMPT_BASE_SECONDS = 0;
+/** Missing wire cadence fails closed to the most conservative live default. */
+export const REFRESH_FALLBACK_BASE_SECONDS = 300;
+/** A stable scheduled instant for a connection exempt from background reads. */
+export const SCHEDULE_EXEMPT_INSTANT = "9999-12-31T23:59:59.999Z";
+function usableRandom(random) {
+    let value;
+    try {
+        value = random();
+    }
+    catch {
+        return 0.5;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 0.5;
+    return Math.min(Math.max(value, 0), 1);
+}
+function usableBase(baseSeconds) {
+    if (!Number.isFinite(baseSeconds) || baseSeconds < 0) {
+        return REFRESH_FALLBACK_BASE_SECONDS;
+    }
+    if (baseSeconds === SCHEDULE_EXEMPT_BASE_SECONDS) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return Math.min(baseSeconds, REFRESH_BACKOFF_CEILING_SECONDS);
+}
+function usableAttempt(attempt) {
+    if (!Number.isFinite(attempt) || attempt <= 0)
+        return 0;
+    /*
+     * The exponent is clamped before it is used rather than after. Two to the
+     * power of a large attempt count overflows to Infinity long before the
+     * ceiling below could catch it, and Infinity times a jitter factor is not a
+     * date.
+     */
+    return Math.min(Math.floor(attempt), 32);
+}
+function usableRetryAfter(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return null;
+    return Math.min(value, REFRESH_RETRY_AFTER_CEILING_SECONDS);
+}
+/**
+ * The delay before the next attempt, in seconds.
+ *
+ * Doubling per consecutive failure, capped at an hour, then jittered by up to
+ * a fifth either way so a hundred installations that all failed at the same
+ * moment do not all come back at the same moment.
+ *
+ * The order matters and is the whole subtlety here. Jitter is applied to OUR
+ * backoff and to nothing else, and the provider's Retry-After is then taken as
+ * a floor underneath the jittered result. Jittering a Retry-After instead would
+ * subtract up to a fifth from an instruction the provider gave us: a header
+ * asking for a day back would come back as nineteen hours and knock on the door
+ * almost five hours early, which is precisely the behaviour that gets an account
+ * limited harder. Jitter exists to spread our own retries, so it may only ever
+ * move our own number. A Retry-After shorter than our backoff changes nothing,
+ * because a provider cannot talk us out of backing off.
+ */
+export function refreshDelaySeconds(input) {
+    const base = usableBase(input.baseSeconds);
+    if (base === Number.POSITIVE_INFINITY)
+        return base;
+    const attempt = usableAttempt(input.attempt);
+    const backoff = Math.min(base * Math.pow(2, attempt), REFRESH_BACKOFF_CEILING_SECONDS);
+    const jitter = 1 + (usableRandom(input.random) * 2 - 1) * REFRESH_JITTER_RATIO;
+    const jittered = backoff * jitter;
+    const retryAfter = usableRetryAfter(input.retryAfterSeconds);
+    return retryAfter === null ? jittered : Math.max(jittered, retryAfter);
+}
+/**
+ * The instant of the next attempt, or null when the supplied clock is not a
+ * readable instant. Nothing is guessed from a clock we cannot read.
+ */
+export function nextRefreshAt(now, input) {
+    const current = Date.parse(now);
+    if (!Number.isFinite(current))
+        return null;
+    if (input.baseSeconds === SCHEDULE_EXEMPT_BASE_SECONDS) {
+        return SCHEDULE_EXEMPT_INSTANT;
+    }
+    const milliseconds = current + Math.round(refreshDelaySeconds(input) * 1_000);
+    if (!Number.isFinite(milliseconds))
+        return null;
+    const next = new Date(milliseconds);
+    return Number.isFinite(next.getTime()) ? next.toISOString() : null;
+}
+/**
+ * Whether a scheduled instant has arrived.
+ *
+ * A schedule we cannot read counts as due. The alternative is a connection that
+ * never refreshes again because one unreadable value got written once, and the
+ * first successful attempt replaces it with a readable one. A clock we cannot
+ * read is the opposite case and counts as not due, because with no present
+ * moment there is nothing to compare against.
+ */
+export function isDue(nextAt, now) {
+    const current = Date.parse(now);
+    if (!Number.isFinite(current))
+        return false;
+    if (nextAt === null)
+        return true;
+    const scheduled = Date.parse(nextAt);
+    if (!Number.isFinite(scheduled))
+        return true;
+    return current >= scheduled;
+}
+//# sourceMappingURL=schedule.js.map

package/dist/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -31,6 +31,47 @@ export interface SnapshotAmounts {
     limitAmount: number;
     currency: SnapshotCurrency;
 }
+/**
+ * How an observation reached us, stated in our own vocabulary.
+ *
+ * A provider tells us what its meter reads. It never tells us how we read it,
+ * so this field is written by OpenLimiter and only ever holds one of the values
+ * below. A human surface can then say "this came from your local Claude Code"
+ * or "this came from an official API" without a provider being able to write
+ * that sentence for us.
+ */
+export declare const SNAPSHOT_SOURCE_KINDS: readonly ["statusline_payload", "explicit_ingest", "manual_document", "remote_api", "unknown"];
+export type SnapshotSourceKind = (typeof SNAPSHOT_SOURCE_KINDS)[number];
+/**
+ * Which reader carried the observation. Closed for the same reason as above.
+ *
+ * The first three name a concrete path this product actually has, because a
+ * source chip saying "your Claude Code statusline" and one saying "you imported
+ * this" are the difference between a live reading and a paste, and a generic
+ * reader kind cannot tell a person which they are looking at. The rest are the
+ * reader kinds the connection architecture defines, kept for paths that exist
+ * on paper before they exist in code.
+ */
+export declare const SNAPSHOT_OBSERVED_VIA: readonly ["claude_code_statusline", "ingest_command", "manual_json", "local_event", "local_file", "local_command", "remote_http", "user_entry", "unknown"];
+export type SnapshotObservedVia = (typeof SNAPSHOT_OBSERVED_VIA)[number];
+export interface SnapshotProvenance {
+    sourceKind: SnapshotSourceKind;
+    observedVia: SnapshotObservedVia;
+}
+/**
+ * What a reading's provenance becomes when the stated provenance cannot be
+ * believed. The reading itself still stands: how a number arrived is a separate
+ * question from whether the number is in range.
+ */
+export declare const UNKNOWN_PROVENANCE: SnapshotProvenance;
+/**
+ * Shape of an account identifier, when a source names one.
+ *
+ * Lowercase, digits and hyphens, never a space, so it can be joined into a cache
+ * identity with a space separator and never collide. It is an opaque local alias
+ * and is not required to be an account name any provider would recognise.
+ */
+export declare const ACCOUNT_ID_PATTERN: RegExp;
 export interface ConnectorLabels {
     credentialOrigin: "official-local-tool" | "user-key" | "browser-session" | "user-entered";
     dataInterfaceStatus: "native-statusline-payload" | "documented-api" | "internal-endpoint" | "authenticated-scrape" | "manual";
@@ -53,6 +94,16 @@ export interface Snapshot {
     usedAmount?: number;
     limitAmount?: number;
     currency?: SnapshotCurrency;
+    /**
+     * Which account this reading belongs to, when a source names one.
+     *
+     * Absent means one unnamed account, which is every reading written before
+     * multiple accounts existed. Absent is not the same as an account called
+     * "default": a row without this field keeps the identity it always had.
+     */
+    accountId?: string;
+    /** How the reading arrived. Absent means it was never recorded. */
+    provenance?: SnapshotProvenance;
 }
 export interface RawMeter {
     provider: unknown;
@@ -69,6 +120,8 @@ export interface RawMeter {
     usedAmount?: unknown;
     limitAmount?: unknown;
     currency?: unknown;
+    accountId?: unknown;
+    provenance?: unknown;
 }
 export interface ConnectorReadContext {
     payload?: unknown;
@@ -82,10 +135,23 @@ export type ConnectorResult = {
     ok: false;
     reason: "unknown" | "unavailable" | "not_configured";
 };
+/**
+ * What a connector's payload IS, before its parser sees it.
+ *
+ * Almost every provider answers JSON. OpenCode answers a logged in HTML page,
+ * because it publishes no usage interface at all. That difference cannot live
+ * only in the reader that happens to know about it: the desktop pipeline, the
+ * ingest command and the web engine all hand payloads to parsers, and any one
+ * of them that assumes JSON silently breaks the text reader. So the connector
+ * declares it, and every payload boundary asks.
+ */
+export type ConnectorEncoding = "json" | "text";
 export interface ConnectorContract {
     readonly id: Lowercase<ProviderCode>;
     readonly displayName: string;
     readonly labels: ConnectorLabels;
+    /** Whether this connector's parser wants parsed JSON or the raw text. */
+    readonly encoding: ConnectorEncoding;
     detect(environment: Readonly<Record<string, string | undefined>>): boolean;
     read(context: ConnectorReadContext): Promise<ConnectorResult>;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,iFAOjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AACzE,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;AACjE,MAAM,MAAM,cAAc,GACtB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,cAAc,CAAC;AAEnB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAErC,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EACZ,qBAAqB,GACrB,UAAU,GACV,iBAAiB,GACjB,cAAc,CAAC;IACnB,mBAAmB,EACf,2BAA2B,GAC3B,gBAAgB,GAChB,mBAAmB,GACnB,sBAAsB,GACtB,QAAQ,CAAC;IACb,cAAc,EAAE,KAAK,GAAG,MAAM,CAAC;IAC/B,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,eAAe,CAAC;IACxB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,OAAO,CAAC;IAC3E,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC/D;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzE,MAAM,MAAM,oBAAoB,GAC5B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,cAAc,GAAG,mBAAmB,CAAC;CAC9C,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,mBAAmB,GAAG,eAAe,GAAG,qBAAqB,CAAC;CACvE,CAAC;AAEN,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,cAAc,EAAE,oBAAoB,CAAC;IACrC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,QAAQ;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -8,4 +8,58 @@ export const PROVIDER_CODES = [
 ];
 /** Largest money amount a reading may carry. Above this it is not a plan. */
 export const MAX_SNAPSHOT_AMOUNT = 1_000_000;
+/**
+ * How an observation reached us, stated in our own vocabulary.
+ *
+ * A provider tells us what its meter reads. It never tells us how we read it,
+ * so this field is written by OpenLimiter and only ever holds one of the values
+ * below. A human surface can then say "this came from your local Claude Code"
+ * or "this came from an official API" without a provider being able to write
+ * that sentence for us.
+ */
+export const SNAPSHOT_SOURCE_KINDS = [
+    "statusline_payload",
+    "explicit_ingest",
+    "manual_document",
+    "remote_api",
+    "unknown"
+];
+/**
+ * Which reader carried the observation. Closed for the same reason as above.
+ *
+ * The first three name a concrete path this product actually has, because a
+ * source chip saying "your Claude Code statusline" and one saying "you imported
+ * this" are the difference between a live reading and a paste, and a generic
+ * reader kind cannot tell a person which they are looking at. The rest are the
+ * reader kinds the connection architecture defines, kept for paths that exist
+ * on paper before they exist in code.
+ */
+export const SNAPSHOT_OBSERVED_VIA = [
+    "claude_code_statusline",
+    "ingest_command",
+    "manual_json",
+    "local_event",
+    "local_file",
+    "local_command",
+    "remote_http",
+    "user_entry",
+    "unknown"
+];
+/**
+ * What a reading's provenance becomes when the stated provenance cannot be
+ * believed. The reading itself still stands: how a number arrived is a separate
+ * question from whether the number is in range.
+ */
+export const UNKNOWN_PROVENANCE = {
+    sourceKind: "unknown",
+    observedVia: "unknown"
+};
+/**
+ * Shape of an account identifier, when a source names one.
+ *
+ * Lowercase, digits and hyphens, never a space, so it can be joined into a cache
+ * identity with a space separator and never collide. It is an opaque local alias
+ * and is not required to be an account name any provider would recognise.
+ */
+export const ACCOUNT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/u;
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,QAAQ;IACR,YAAY;IACZ,OAAO;IACP,aAAa;IACb,UAAU;IACV,QAAQ;CACA,CAAC;AA2BX,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,QAAQ;IACR,YAAY;IACZ,OAAO;IACP,aAAa;IACb,UAAU;IACV,QAAQ;CACA,CAAC;AA2BX,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAgB7C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,oBAAoB;IACpB,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;IACZ,SAAS;CACD,CAAC;AAIX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,wBAAwB;IACxB,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,YAAY;IACZ,eAAe;IACf,aAAa;IACb,YAAY;IACZ,SAAS;CACD,CAAC;AASX;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAuB;IACpD,UAAU,EAAE,SAAS;IACrB,WAAW,EAAE,SAAS;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlimiter/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared types, quota models, cache handling, and forecasts for OpenLimiter.",
   "type": "module",
   "main": "./dist/index.js",