@openlimiter/core 0.1.0 → 0.4.0

package/dist/normalizer.js

@@ -1,4 +1,4 @@
-import { PROVIDER_CODES } from "./types.js";
+import { ACCOUNT_ID_PATTERN, MAX_SNAPSHOT_AMOUNT, PROVIDER_CODES, SNAPSHOT_OBSERVED_VIA, SNAPSHOT_SOURCE_KINDS, UNKNOWN_PROVENANCE } from "./types.js";
 const units = new Set(["PERCENT", "CREDITS", "TOKENS", "REQUESTS"]);
 const sources = new Set([
     "native_payload",
@@ -8,7 +8,10 @@ const sources = new Set([
     "manual_entry"
 ]);
 const precisions = new Set(["exact", "estimated", "manual"]);
+const currencies = new Set(["USD"]);
 const providerCodes = new Set(PROVIDER_CODES);
+const sourceKinds = new Set(SNAPSHOT_SOURCE_KINDS);
+const observedVia = new Set(SNAPSHOT_OBSERVED_VIA);
 const safeMeter = /^[A-Z][A-Z0-9_]{0,31}$/u;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -64,6 +67,77 @@ function normalizeLabels(value) {
         verification: "UNVERIFIED"
     };
 }
+/**
+ * Validate the money amounts, as one unit or not at all.
+ *
+ * They arrive together or they do not arrive, and they leave together or they
+ * do not leave. Any one of them being absent, out of range, the wrong type, or
+ * inconsistent with the other drops all three, which is what keeps a card from
+ * ever printing a spend with no plan size beside it. The percentage on the same
+ * reading is untouched by this: a provider that misreports its money has not
+ * misreported how full the meter is.
+ */
+function normalizeAmounts(raw) {
+    const used = raw.usedAmount;
+    const limit = raw.limitAmount;
+    const currency = raw.currency;
+    if (used === undefined && limit === undefined && currency === undefined)
+        return null;
+    if (typeof used !== "number" || typeof limit !== "number")
+        return null;
+    if (typeof currency !== "string" || !currencies.has(currency)) {
+        return null;
+    }
+    if (!Number.isFinite(used) || !Number.isFinite(limit))
+        return null;
+    if (used < 0 || limit < 0)
+        return null;
+    if (used > limit)
+        return null;
+    if (used > MAX_SNAPSHOT_AMOUNT || limit > MAX_SNAPSHOT_AMOUNT)
+        return null;
+    return { usedAmount: used, limitAmount: limit, currency: currency };
+}
+/**
+ * Read the account this reading belongs to.
+ *
+ * Absent is the ordinary case and means one unnamed account. Present but
+ * malformed is the dangerous case, because an identity we cannot trust would
+ * quietly split or merge a user's meters in the cache, so that row is refused
+ * outright rather than stripped back to the unnamed account.
+ */
+function readAccountId(value) {
+    if (value === undefined)
+        return { ok: true, accountId: null };
+    if (typeof value !== "string" || !ACCOUNT_ID_PATTERN.test(value))
+        return { ok: false };
+    return { ok: true, accountId: value };
+}
+/**
+ * Read how the observation arrived.
+ *
+ * The opposite call to the one above, and deliberately so. Provenance is a
+ * label on a reading, not part of its identity, so a provenance we cannot read
+ * costs the reading nothing: it becomes unknown and the number survives. Either
+ * field failing makes the whole thing unknown, because half a provenance would
+ * invite a surface to describe a source it cannot actually vouch for.
+ */
+function readProvenance(value) {
+    if (value === undefined)
+        return null;
+    if (!isRecord(value))
+        return UNKNOWN_PROVENANCE;
+    const kind = value["sourceKind"];
+    const via = value["observedVia"];
+    if (typeof kind !== "string" || !sourceKinds.has(kind))
+        return UNKNOWN_PROVENANCE;
+    if (typeof via !== "string" || !observedVia.has(via))
+        return UNKNOWN_PROVENANCE;
+    return {
+        sourceKind: kind,
+        observedVia: via
+    };
+}
 export function normalizeMeter(raw) {
     if (typeof raw.provider !== "string" || !providerCodes.has(raw.provider))
         return null;
@@ -94,6 +168,11 @@ export function normalizeMeter(raw) {
         return null;
     if (Date.parse(raw.expiresAt) < Date.parse(raw.observedAt))
         return null;
+    const account = readAccountId(raw.accountId);
+    if (!account.ok)
+        return null;
+    const provenance = readProvenance(raw.provenance);
+    const amounts = normalizeAmounts(raw);
     return {
         provider: raw.provider,
         meter: raw.meter,
@@ -105,7 +184,10 @@ export function normalizeMeter(raw) {
         precision: raw.precision,
         observedAt: raw.observedAt,
         expiresAt: raw.expiresAt,
-        labels
+        labels,
+        ...(amounts === null ? {} : amounts),
+        ...(account.accountId === null ? {} : { accountId: account.accountId }),
+        ...(provenance === null ? {} : { provenance })
     };
 }
 export function normalizeMeters(rawMeters) {
@@ -114,6 +196,23 @@ export function normalizeMeters(rawMeters) {
         return normalized === null ? [] : [normalized];
     });
 }
+export function normalizeMetersReport(rawMeters) {
+    const snapshots = [];
+    const rejected = new Set();
+    let dropped = 0;
+    for (const raw of rawMeters) {
+        const normalized = normalizeMeter(raw);
+        if (normalized !== null) {
+            snapshots.push(normalized);
+            continue;
+        }
+        dropped += 1;
+        if (typeof raw.provider === "string" && providerCodes.has(raw.provider)) {
+            rejected.add(raw.provider);
+        }
+    }
+    return { snapshots, rejected: [...rejected], dropped };
+}
 function sortDeep(value) {
     if (Array.isArray(value))
         return value.map(sortDeep);

package/dist/normalizer.js.map

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

package/dist/schedule.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 declare const REFRESH_BACKOFF_CEILING_SECONDS = 3600;
+/**
+ * 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 declare const REFRESH_RETRY_AFTER_CEILING_SECONDS = 86400;
+/** How far either side of the computed delay the jitter may move it. */
+export declare const REFRESH_JITTER_RATIO = 0.2;
+/** The reader supplied sentinel for a connection that only refreshes by hand. */
+export declare const SCHEDULE_EXEMPT_BASE_SECONDS = 0;
+/** Missing wire cadence fails closed to the most conservative live default. */
+export declare const REFRESH_FALLBACK_BASE_SECONDS = 300;
+/** A stable scheduled instant for a connection exempt from background reads. */
+export declare const SCHEDULE_EXEMPT_INSTANT = "9999-12-31T23:59:59.999Z";
+export interface RefreshInput {
+    /**
+     * Consecutive failures behind this schedule. Zero means the last attempt
+     * succeeded, so the delay is the plain interval with jitter on it.
+     */
+    attempt: number;
+    /** The interval this connection uses when nothing is failing, in seconds. */
+    baseSeconds: number;
+    /** Retry-After in seconds when the provider sent one, otherwise null. */
+    retryAfterSeconds?: number | null;
+    /** Injected uniform random in the range zero to one. */
+    random: () => number;
+}
+/**
+ * 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 declare function refreshDelaySeconds(input: RefreshInput): number;
+/**
+ * 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 declare function nextRefreshAt(now: string, input: RefreshInput): string | 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 declare function isDue(nextAt: string | null, now: string): boolean;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,+BAA+B,OAAQ,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAE1D,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wDAAwD;IACxD,MAAM,EAAE,MAAM,MAAM,CAAC;CACtB;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAY/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAOjE"}

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

@@ -8,6 +8,70 @@ export interface SnapshotWindow {
     kind: "rolling" | "fixed" | "lifetime" | "unknown";
     durationSeconds?: number;
 }
+/**
+ * The one currency an amount may be stated in, for now.
+ *
+ * A literal rather than a string keeps a provider from writing its own text
+ * into a field a human reads. When a second currency is genuinely supported it
+ * is added here and the normalizer's set below grows with it.
+ */
+export type SnapshotCurrency = "USD";
+/** Largest money amount a reading may carry. Above this it is not a plan. */
+export declare const MAX_SNAPSHOT_AMOUNT = 1000000;
+/**
+ * What a credit based plan has spent, and out of how much.
+ *
+ * Optional everywhere and travelling as one unit: a reading either carries all
+ * three of these or none of them, so a surface can never print a used figure
+ * with no limit beside it. A percentage never depends on them, which is why a
+ * pair that fails validation is dropped while the percentage survives.
+ */
+export interface SnapshotAmounts {
+    usedAmount: number;
+    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";
@@ -26,6 +90,20 @@ export interface Snapshot {
     observedAt: string;
     expiresAt: string;
     labels: ConnectorLabels;
+    /** Present only when the provider's own documented payload carried money. */
+    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;
@@ -39,6 +117,11 @@ export interface RawMeter {
     observedAt: unknown;
     expiresAt: unknown;
     labels: unknown;
+    usedAmount?: unknown;
+    limitAmount?: unknown;
+    currency?: unknown;
+    accountId?: unknown;
+    provenance?: unknown;
 }
 export interface ConnectorReadContext {
     payload?: unknown;
@@ -52,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":"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"}
+{"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;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,gGAMxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,4JAUxB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,kBAGhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,QAA+B,CAAC;AAE/D,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;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;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;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;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;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD,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,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,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"}

package/dist/types.js

@@ -6,4 +6,60 @@ export const PROVIDER_CODES = [
     "OPENCODE",
     "MANUAL"
 ];
+/** 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"}
+{"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.1.0",
+  "version": "0.4.0",
   "description": "Shared types, quota models, cache handling, and forecasts for OpenLimiter.",
   "type": "module",
   "main": "./dist/index.js",