oc2token 0.1.0

package/dist/src/domain/errors.d.ts

@@ -0,0 +1,25 @@
+/** Codes used when a domain value cannot be trusted or a collection cannot finish. */
+export type CollectionErrorCode = "cancelled" | "authentication" | "rate-limited" | "transport" | "protocol" | "invalid-data" | "cache-busy" | "cache-unavailable" | "cache-corrupt" | "unknown";
+export type DomainErrorCode = CollectionErrorCode | "invalid-date" | "invalid-timezone" | "invalid-window" | "missing-token-components" | "invalid-token-components" | "invalid-usage-record" | "invalid-snapshot";
+export interface DomainErrorOptions {
+    readonly retryable?: boolean;
+    readonly sessionID?: string;
+    readonly cause?: unknown;
+}
+/** A typed error that adapters and callers can classify without parsing text. */
+export declare class DomainError extends Error {
+    readonly code: DomainErrorCode;
+    readonly retryable: boolean;
+    readonly sessionID: string | undefined;
+    constructor(code: DomainErrorCode, message: string, options?: DomainErrorOptions);
+}
+export interface CollectionError {
+    readonly code: CollectionErrorCode;
+    readonly message: string;
+    readonly sessionID?: string;
+    readonly retryable: boolean;
+}
+export declare function cancellationError(message?: string): DomainError;
+export declare function isCancellationError(error: unknown): boolean;
+/** Convert an adapter failure into the bounded error shape carried by Coverage. */
+export declare function toCollectionError(error: unknown, fallbackCode?: CollectionErrorCode, sessionID?: string): CollectionError;

package/dist/src/domain/errors.js

@@ -0,0 +1,65 @@
+/** A typed error that adapters and callers can classify without parsing text. */
+export class DomainError extends Error {
+    code;
+    retryable;
+    sessionID;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "DomainError";
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.sessionID = options.sessionID;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function cancellationError(message = "The operation was cancelled") {
+    return new DomainError("cancelled", message, { retryable: false });
+}
+export function isCancellationError(error) {
+    if (error instanceof DomainError) {
+        return error.code === "cancelled";
+    }
+    if (error instanceof Error) {
+        return error.name === "AbortError" || error.name === "CanceledError";
+    }
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const code = error.code;
+        return code === "ABORT_ERR" || code === "ERR_CANCELED";
+    }
+    return false;
+}
+const COLLECTION_ERROR_CODES = new Set([
+    "cancelled",
+    "authentication",
+    "rate-limited",
+    "transport",
+    "protocol",
+    "invalid-data",
+    "cache-busy",
+    "cache-unavailable",
+    "cache-corrupt",
+    "unknown",
+]);
+function isCollectionErrorCode(code) {
+    return COLLECTION_ERROR_CODES.has(code);
+}
+/** Convert an adapter failure into the bounded error shape carried by Coverage. */
+export function toCollectionError(error, fallbackCode = "unknown", sessionID) {
+    if (error instanceof DomainError && isCollectionErrorCode(error.code)) {
+        return {
+            code: error.code,
+            message: error.message,
+            ...(error.sessionID === undefined && sessionID === undefined
+                ? {}
+                : { sessionID: error.sessionID ?? sessionID }),
+            retryable: error.retryable,
+        };
+    }
+    return {
+        code: fallbackCode,
+        message: error instanceof Error ? error.message : String(error),
+        ...(sessionID === undefined ? {} : { sessionID }),
+        retryable: false,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/domain/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/domain/errors.ts"],"names":[],"mappings":"AA6BA,iFAAiF;AACjF,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAkB;IACtB,SAAS,CAAU;IACnB,SAAS,CAAqB;IAEvC,YAAY,IAAqB,EAAE,OAAe,EAAE,UAA8B,EAAE;QAClF,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AASD,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAG,6BAA6B;IACvE,OAAO,IAAI,WAAW,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC;IACpC,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;IACvE,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QACnE,MAAM,IAAI,GAAI,KAAqC,CAAC,IAAI,CAAC;QACzD,OAAO,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,cAAc,CAAC;IACzD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,sBAAsB,GAAqC,IAAI,GAAG,CAAC;IACvE,WAAW;IACX,gBAAgB;IAChB,cAAc;IACd,WAAW;IACX,UAAU;IACV,cAAc;IACd,YAAY;IACZ,mBAAmB;IACnB,eAAe;IACf,SAAS;CACV,CAAC,CAAC;AAEH,SAAS,qBAAqB,CAAC,IAAqB;IAClD,OAAO,sBAAsB,CAAC,GAAG,CAAC,IAA2B,CAAC,CAAC;AACjE,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,eAAoC,SAAS,EAC7C,SAAkB;IAElB,IAAI,KAAK,YAAY,WAAW,IAAI,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS;gBAC1D,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC;YAChD,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC/D,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;QACjD,SAAS,EAAE,KAAK;KACjB,CAAC;AACJ,CAAC"}

package/dist/src/domain/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./contracts.js";
+export * from "./errors.js";
+export * from "./records.js";
+export * from "./tokens.js";
+export * from "./windows.js";

package/dist/src/domain/index.js

@@ -0,0 +1,6 @@
+export * from "./contracts.js";
+export * from "./errors.js";
+export * from "./records.js";
+export * from "./tokens.js";
+export * from "./windows.js";
+//# sourceMappingURL=index.js.map

package/dist/src/domain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/domain/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/src/domain/records.d.ts

@@ -0,0 +1,59 @@
+import { type UsageWindow } from "./windows.js";
+import { type TokenComponents, type UsageTotals } from "./tokens.js";
+import type { ProviderKind } from "./contracts.js";
+export type UsageRecordCompleteness = "final" | "provisional";
+export declare const PROVIDER_KINDS: readonly ["opencode", "codex", "antigravity"];
+export declare function isProviderKind(value: unknown): value is ProviderKind;
+export interface UsageRecordInput {
+    readonly sessionID: string;
+    readonly messageID: string;
+    readonly createdAt: Date;
+    readonly model: string;
+    readonly tokens: TokenComponents;
+    readonly observedAt: Date;
+    readonly completeness: UsageRecordCompleteness;
+    /** Provider that produced this record. Defaults to "opencode" for back-compat when omitted. */
+    readonly provider?: ProviderKind;
+    /** Adapters may supply a provider revision; otherwise a deterministic value is derived. */
+    readonly tokenRevision?: string;
+    /** Project that produced this record (directory or projectID). Optional for back-compat. */
+    readonly project?: string;
+}
+/** Canonical normalized usage-bearing assistant message. */
+export interface UsageRecord extends TokenComponents {
+    /** Idempotency key: one OpenCode session plus one assistant message. */
+    readonly key: string;
+    readonly sessionID: string;
+    readonly messageID: string;
+    readonly createdAt: Date;
+    readonly model: string;
+    readonly recorded_total: number;
+    readonly tokenRevision: string;
+    readonly observedAt: Date;
+    readonly completeness: UsageRecordCompleteness;
+    readonly provider: ProviderKind;
+    /** Project that produced this record (directory or projectID). Undefined for non-opencode or legacy records. */
+    readonly project?: string;
+}
+/**
+ * The default revision is deliberately deterministic and content-addressed.
+ * A later observation of the same message with different tokens therefore
+ * replaces the old record instead of being added as a delta.
+ */
+export declare function tokenRevisionFor(tokens: TokenComponents, completeness: UsageRecordCompleteness): string;
+/**
+ * Return the stable idempotency key used by cache reducers and retries.
+ * The key is `sessionID/messageID` only; `provider` is metadata and not part
+ * of the key. Cross-provider collisions are impossible in practice because
+ * each provider prefixes distinct session/message IDs (e.g. Codex rollout
+ * path vs Antigravity cascadeId).
+ */
+export declare function usageRecordKey(sessionID: string, messageID: string): string;
+export declare const stableRecordKey: typeof usageRecordKey;
+export declare function createUsageRecord(input: UsageRecordInput): UsageRecord;
+export interface SumUsageRecordsOptions {
+    /** Provisional messages are excluded by default until a caller opts in. */
+    readonly includeProvisional?: boolean;
+}
+/** Sum canonical records in a half-open window without mutating the records. */
+export declare function sumUsageRecords(records: ReadonlyArray<UsageRecord>, window: UsageWindow, options?: SumUsageRecordsOptions): UsageTotals;

package/dist/src/domain/records.js

@@ -0,0 +1,141 @@
+import { DomainError } from "./errors.js";
+import { containsInstant } from "./windows.js";
+import { parseTokenComponents, recorded_total, toUsageTotals, } from "./tokens.js";
+export const PROVIDER_KINDS = ["opencode", "codex", "antigravity"];
+export function isProviderKind(value) {
+    return (typeof value === "string" &&
+        PROVIDER_KINDS.includes(value));
+}
+function assertProviderKind(value, field) {
+    if (!isProviderKind(value)) {
+        throw new DomainError("invalid-usage-record", `${field} must be one of ${PROVIDER_KINDS.join(", ")}`);
+    }
+}
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new DomainError("invalid-usage-record", `${field} must not be empty`);
+    }
+}
+function assertRecordID(value, field) {
+    assertNonEmpty(value, field);
+    if (value.includes("/")) {
+        throw new DomainError("invalid-usage-record", `${field} must not contain '/' because it is part of the stable record key`);
+    }
+}
+function assertDate(value, field) {
+    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+        throw new DomainError("invalid-usage-record", `${field} must be a valid Date`);
+    }
+}
+function assertProject(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new DomainError("invalid-usage-record", "project must be a string when present");
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed.length > 1024) {
+        throw new DomainError("invalid-usage-record", "project must be 1..1024 characters");
+    }
+    if (/[\u0000-\u001f]/.test(trimmed)) {
+        throw new DomainError("invalid-usage-record", "project must not contain control characters");
+    }
+    return trimmed;
+}
+/**
+ * The default revision is deliberately deterministic and content-addressed.
+ * A later observation of the same message with different tokens therefore
+ * replaces the old record instead of being added as a delta.
+ */
+export function tokenRevisionFor(tokens, completeness) {
+    const normalized = parseTokenComponents(tokens);
+    return [
+        "v1",
+        normalized.input,
+        normalized.output,
+        normalized.reasoning,
+        normalized.cacheRead,
+        normalized.cacheWrite,
+        completeness,
+    ].join(":");
+}
+/**
+ * Return the stable idempotency key used by cache reducers and retries.
+ * The key is `sessionID/messageID` only; `provider` is metadata and not part
+ * of the key. Cross-provider collisions are impossible in practice because
+ * each provider prefixes distinct session/message IDs (e.g. Codex rollout
+ * path vs Antigravity cascadeId).
+ */
+export function usageRecordKey(sessionID, messageID) {
+    assertRecordID(sessionID, "sessionID");
+    assertRecordID(messageID, "messageID");
+    return `${sessionID}/${messageID}`;
+}
+export const stableRecordKey = usageRecordKey;
+export function createUsageRecord(input) {
+    assertRecordID(input.sessionID, "sessionID");
+    assertRecordID(input.messageID, "messageID");
+    assertNonEmpty(input.model, "model");
+    if (input.completeness !== "final" && input.completeness !== "provisional") {
+        throw new DomainError("invalid-usage-record", "completeness must be 'final' or 'provisional'");
+    }
+    assertDate(input.createdAt, "createdAt");
+    assertDate(input.observedAt, "observedAt");
+    let provider;
+    if (input.provider === undefined) {
+        provider = "opencode";
+    }
+    else {
+        assertNonEmpty(input.provider, "provider");
+        assertProviderKind(input.provider, "provider");
+        provider = input.provider;
+    }
+    const tokens = parseTokenComponents(input.tokens);
+    const recordedTotal = recorded_total(tokens);
+    const tokenRevision = input.tokenRevision ?? tokenRevisionFor(tokens, input.completeness);
+    assertNonEmpty(tokenRevision, "tokenRevision");
+    const project = assertProject(input.project);
+    return {
+        key: usageRecordKey(input.sessionID, input.messageID),
+        sessionID: input.sessionID,
+        messageID: input.messageID,
+        createdAt: new Date(input.createdAt.getTime()),
+        model: input.model,
+        ...tokens,
+        recorded_total: recordedTotal,
+        tokenRevision,
+        observedAt: new Date(input.observedAt.getTime()),
+        completeness: input.completeness,
+        provider,
+        ...(project === undefined ? {} : { project }),
+    };
+}
+/** Sum canonical records in a half-open window without mutating the records. */
+export function sumUsageRecords(records, window, options = {}) {
+    const totals = {
+        input: 0,
+        output: 0,
+        reasoning: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+    };
+    for (const record of records) {
+        if (record.completeness === "provisional" && !options.includeProvisional) {
+            continue;
+        }
+        if (!containsInstant(window, record.createdAt)) {
+            continue;
+        }
+        for (const name of ["input", "output", "reasoning", "cacheRead", "cacheWrite"]) {
+            const next = totals[name] + record[name];
+            if (!Number.isSafeInteger(next)) {
+                throw new DomainError("invalid-token-components", `Summing ${name} exceeds the safe integer range`);
+            }
+            totals[name] = next;
+        }
+    }
+    return toUsageTotals(totals);
+}
+//# sourceMappingURL=records.js.map

package/dist/src/domain/records.js.map

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

package/dist/src/domain/tokens.d.ts

@@ -0,0 +1,51 @@
+import { DomainError } from "./errors.js";
+export declare const TOKEN_COMPONENT_NAMES: readonly ["input", "output", "reasoning", "cacheRead", "cacheWrite"];
+export type TokenComponentName = (typeof TOKEN_COMPONENT_NAMES)[number];
+/** Normalized non-negative token counts. Raw API objects must be parsed first. */
+export interface TokenComponents {
+    readonly input: number;
+    readonly output: number;
+    readonly reasoning: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+}
+export interface UsageTotals extends TokenComponents {
+    readonly recorded_total: number;
+}
+/**
+ * The transport adapter may receive either OpenCode's nested cache shape or an
+ * already flattened shape. Once normalized, all five fields are present.
+ *
+ * A present token object may omit fields; omitted component fields mean zero.
+ * An absent token object is represented by `undefined` and is not accepted by
+ * `parseTokenComponents`, because absence is not evidence of a zero-token
+ * completed message.
+ */
+export interface TokenComponentsInput {
+    readonly input?: number;
+    readonly output?: number;
+    readonly reasoning?: number;
+    readonly cache?: {
+        readonly read?: number;
+        readonly write?: number;
+    };
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+}
+export type TokenValidationResult = {
+    readonly ok: true;
+    readonly value: TokenComponents;
+} | {
+    readonly ok: false;
+    readonly error: DomainError;
+};
+/** Parse and validate an OpenCode-shaped token object. */
+export declare function parseTokenComponents(value: unknown): TokenComponents;
+/** Return a non-throwing validation result for transport and boundary code. */
+export declare function validateTokenComponents(value: unknown): TokenValidationResult;
+export declare function isTokenComponents(value: unknown): value is TokenComponents;
+/** Calculate the explicitly named accounting sum; this is not a billing total. */
+export declare function recorded_total(components: TokenComponents): number;
+export declare const recordedTotal: typeof recorded_total;
+export declare function toUsageTotals(components: TokenComponents): UsageTotals;
+export declare const sumTokenComponents: typeof toUsageTotals;

package/dist/src/domain/tokens.js

@@ -0,0 +1,93 @@
+import { DomainError } from "./errors.js";
+export const TOKEN_COMPONENT_NAMES = [
+    "input",
+    "output",
+    "reasoning",
+    "cacheRead",
+    "cacheWrite",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readNonNegativeInteger(value, path) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new DomainError("invalid-token-components", `${path} must be a finite non-negative safe integer`);
+    }
+    return value;
+}
+function readOptionalComponent(record, name) {
+    return name in record ? readNonNegativeInteger(record[name], name) : 0;
+}
+function readCacheComponent(cache, name) {
+    return name in cache
+        ? readNonNegativeInteger(cache[name], `cache.${name}`)
+        : 0;
+}
+/** Parse and validate an OpenCode-shaped token object. */
+export function parseTokenComponents(value) {
+    if (value === undefined || value === null) {
+        throw new DomainError("missing-token-components", "A usage-bearing message must contain a token components object");
+    }
+    if (!isRecord(value)) {
+        throw new DomainError("invalid-token-components", "Token components must be an object");
+    }
+    const input = readOptionalComponent(value, "input");
+    const output = readOptionalComponent(value, "output");
+    const reasoning = readOptionalComponent(value, "reasoning");
+    let cacheRead = readOptionalComponent(value, "cacheRead");
+    let cacheWrite = readOptionalComponent(value, "cacheWrite");
+    if ("cache" in value) {
+        if (!isRecord(value.cache)) {
+            throw new DomainError("invalid-token-components", "cache must be an object when present");
+        }
+        const nestedRead = readCacheComponent(value.cache, "read");
+        const nestedWrite = readCacheComponent(value.cache, "write");
+        if ("cacheRead" in value && nestedRead !== cacheRead) {
+            throw new DomainError("invalid-token-components", "cache.read and cacheRead disagree");
+        }
+        if ("cacheWrite" in value && nestedWrite !== cacheWrite) {
+            throw new DomainError("invalid-token-components", "cache.write and cacheWrite disagree");
+        }
+        cacheRead = nestedRead;
+        cacheWrite = nestedWrite;
+    }
+    return { input, output, reasoning, cacheRead, cacheWrite };
+}
+/** Return a non-throwing validation result for transport and boundary code. */
+export function validateTokenComponents(value) {
+    try {
+        return { ok: true, value: parseTokenComponents(value) };
+    }
+    catch (error) {
+        if (error instanceof DomainError) {
+            return { ok: false, error };
+        }
+        return {
+            ok: false,
+            error: new DomainError("invalid-token-components", "Token components could not be validated", { cause: error }),
+        };
+    }
+}
+export function isTokenComponents(value) {
+    const result = validateTokenComponents(value);
+    if (!result.ok) {
+        return false;
+    }
+    return TOKEN_COMPONENT_NAMES.every((name) => name in value);
+}
+/** Calculate the explicitly named accounting sum; this is not a billing total. */
+export function recorded_total(components) {
+    const normalized = parseTokenComponents(components);
+    const total = TOKEN_COMPONENT_NAMES.reduce((sum, name) => sum + normalized[name], 0);
+    if (!Number.isSafeInteger(total)) {
+        throw new DomainError("invalid-token-components", "recorded_total exceeds the safe integer range");
+    }
+    return total;
+}
+export const recordedTotal = recorded_total;
+export function toUsageTotals(components) {
+    const normalized = parseTokenComponents(components);
+    return { ...normalized, recorded_total: recorded_total(normalized) };
+}
+export const sumTokenComponents = toUsageTotals;
+//# sourceMappingURL=tokens.js.map

package/dist/src/domain/tokens.js.map

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

package/dist/src/domain/windows.d.ts

@@ -0,0 +1,59 @@
+export declare const USAGE_WINDOW_KINDS: readonly ["hour", "day", "week"];
+export type UsageWindowKind = (typeof USAGE_WINDOW_KINDS)[number];
+export interface UsageWindowBase {
+    /** Short stable key used by the CLI and JSON output. */
+    readonly kind: UsageWindowKind;
+    /** Human-readable semantics; the kind alone must not be interpreted as all-time. */
+    readonly semantics: "rolling-hour" | "local-day" | "iso-week";
+    /** The IANA time zone used for calendar labels and boundaries. */
+    readonly timezone: string;
+    /** Inclusive start and exclusive end instants. */
+    readonly from: Date;
+    readonly to: Date;
+    readonly label: string;
+}
+export interface RollingHourWindow extends UsageWindowBase {
+    readonly kind: "hour";
+    readonly semantics: "rolling-hour";
+}
+export interface LocalDayWindow extends UsageWindowBase {
+    readonly kind: "day";
+    readonly semantics: "local-day";
+    /** Local Gregorian date represented as YYYY-MM-DD. */
+    readonly localDate: string;
+}
+export interface ISOWeekWindow extends UsageWindowBase {
+    readonly kind: "week";
+    readonly semantics: "iso-week";
+    readonly isoWeekYear: number;
+    readonly isoWeek: number;
+    /** ISO week label represented as YYYY-Www. */
+    readonly isoWeekLabel: string;
+}
+export type UsageWindow = RollingHourWindow | LocalDayWindow | ISOWeekWindow;
+export interface UsageWindowSet {
+    readonly hour: RollingHourWindow;
+    readonly day: LocalDayWindow;
+    readonly week: ISOWeekWindow;
+}
+/** One half-open, timezone-aware interval used to plot a usage trend. */
+export interface UsageBucket {
+    readonly label: string;
+    readonly from: Date;
+    readonly to: Date;
+}
+/** Build one explicitly bounded usage window from one captured wall-clock instant. */
+export declare function createUsageWindow(kind: "hour", now: Date, timezone: string): RollingHourWindow;
+export declare function createUsageWindow(kind: "day", now: Date, timezone: string): LocalDayWindow;
+export declare function createUsageWindow(kind: "week", now: Date, timezone: string): ISOWeekWindow;
+/** Build all v1 windows from the same captured instant, avoiding boundary drift. */
+export declare function createUsageWindows(now: Date, timezone: string): UsageWindowSet;
+/**
+ * Build the stable trend intervals for a requested window. Calendar-day
+ * buckets advance in elapsed time from the local-day bounds, which preserves
+ * both missing and repeated hours on DST transition days. Week buckets use
+ * local midnights, so a DST day changes the bucket duration without changing
+ * the seven-day shape of the ISO week.
+ */
+export declare function createUsageTrendBuckets(window: UsageWindow): readonly UsageBucket[];
+export declare function containsInstant(window: UsageWindow, instant: Date): boolean;