@ykurilov/agent-chat-limits 0.0.0-stage → 0.55.0

package/dist/types/spending-windows.d.ts

@@ -0,0 +1,68 @@
+import type { SpendingPeriod, SpendingScope } from "@ykurilov/agent-chat-core";
+import type { CalendarUnit } from "./spending-period.js";
+/** Чей лимит считается: человек и чат хода. `chatId` нет — окна чата не читаются. */
+export interface SpendingSubject {
+    userId: string;
+    chatId?: string;
+}
+/**
+ * Лимит окна в долларах или сообщениях: число или функция от человека и чата (у тарифов разные лимиты). Функция
+ * зовётся на каждую проверку, так что смена тарифа действует сразу; `undefined` или `null` — у этого человека окна нет.
+ */
+export type WindowLimit = number | ((subject: SpendingSubject) => number | null | undefined | Promise<number | null | undefined>);
+interface WindowBase {
+    /** Имя окна: по нему личные лимиты, ручной сброс, события порогов и экран. Уникальное. */
+    id: string;
+    /** Чей расход: человека (все его чаты), одного чата или всего сервиса (все люди вместе). */
+    scope: SpendingScope;
+    /** Лимит в долларах. У окна ровно один лимит: `limitUsd` или `limitMessages`. */
+    limitUsd?: WindowLimit;
+    /**
+     * Лимит в сообщениях человека (целое число): считаются отправка и правка, переделка, повтор, служебные и ответы на
+     * подтверждения — нет. Счёт ведётся в состоянии лимитов, удаление чата его не сбрасывает; нужны методы состояния
+     * хранилища. Ход такого окна не останавливает: место берётся одно на сообщение до его записи.
+     */
+    limitMessages?: WindowLimit;
+    /** Перерасход окна (ход доделан сверх лимита) переносится в начало следующего окна. По умолчанию нет. Только у денег. */
+    carryOverrun?: boolean;
+}
+/** Календарное окно: сутки, неделя или месяц по часовому поясу. */
+export interface CalendarWindowConfig extends WindowBase {
+    kind: "calendar";
+    unit: CalendarUnit;
+    /** Пояс IANA; нет — пояс лимитов (`timeZone`), без него — UTC. */
+    timeZone?: string;
+    /** С какого дня начинается неделя: 1 — понедельник (по умолчанию) … 7 — воскресенье. */
+    weekStartsOn?: number;
+}
+/** Скользящее окно: `hours` часов от первого запроса после конца прошлого окна. Нужны методы состояния хранилища. */
+export interface RollingWindowConfig extends WindowBase {
+    kind: "rolling";
+    hours: number;
+}
+/** Окно на всё время: расход не обнуляется (сбросить можно вручную). */
+export interface TotalWindowConfig extends WindowBase {
+    kind: "total";
+}
+export type SpendingWindowConfig = CalendarWindowConfig | RollingWindowConfig | TotalWindowConfig;
+/** Окно после проверки настроек: пояс и день недели подставлены, лимит — всегда функция. */
+export interface SpendingWindow {
+    id: string;
+    scope: SpendingScope;
+    kind: "calendar" | "rolling" | "total";
+    unit?: CalendarUnit;
+    timeZone: string;
+    weekStartsOn: number;
+    hours?: number;
+    carryOverrun: boolean;
+    period: SpendingPeriod;
+    /** Чем меряется окно: доллары или сообщения человека. */
+    measure: WindowMeasure;
+    limit: (subject: SpendingSubject) => Promise<number | undefined>;
+}
+export type WindowMeasure = "usd" | "messages";
+/** Проверяет настройки окон и приводит их к одному виду. Ошибка — при создании лимитов, а не на первом ходе. */
+export declare function normalizeWindows(configs: readonly SpendingWindowConfig[], defaultTimeZone: string | undefined): SpendingWindow[];
+/** Лимит окна: доллары — неотрицательное число, сообщения — целое неотрицательное. */
+export declare function validLimit(amount: unknown, measure: WindowMeasure, where: string): number;
+export {};

package/dist/types/window-reading.d.ts

@@ -0,0 +1,63 @@
+import type { SpendingState, UsageFilter } from "@ykurilov/agent-chat-core";
+import type { LimitStateStore } from "./limit-state.js";
+import type { SpendingSubject, SpendingWindow } from "./spending-windows.js";
+/**
+ * Состояние окна в хранилище. `start` — начало окна, к которому относится запись (календарное — его начало,
+ * скользящее — первый запрос, на всё время — `null`). Перешли в новое окно — перенос, сброс и пороги прошлого не действуют.
+ */
+export interface WindowState {
+    start: string | null;
+    /** Перерасход прошлого окна, перенесённый в это. */
+    carriedUsd: number;
+    /** Ручной сброс: расход до этого момента в окне не считается. */
+    resetAt?: string;
+    /** Пороги, о которых в этом окне уже сообщено. */
+    notified: number[];
+}
+export interface WindowReading {
+    window: SpendingWindow;
+    /** Ключ состояния окна этого человека, чата или сервиса. */
+    stateKey: string;
+    /** Лимит в долларах; `null` — лимита нет (читается только для отчёта). */
+    limitUsd: number | null;
+    /** Начало окна; `null` — окно на всё время или скользящее ещё не началось. */
+    start: string | null;
+    resetsAt: string | null;
+    /** Скользящее окно ещё не началось: ждёт первого запроса. */
+    waiting: boolean;
+    /** Расход в окне вместе с переносом и заказанным, но не записанным. */
+    spentUsd: number;
+    carriedUsd: number;
+    state: SpendingState;
+    share: number | null;
+    /** Состояние, которое стоит записать: окно сменилось или скользящее открыто этим запросом. */
+    nextState: WindowState | null;
+    /** Начало окна в прочитанной записи: новая запись ложится, только если её никто не сменил. */
+    savedStart: string | null | undefined;
+}
+export interface ReadWindowInput {
+    window: SpendingWindow;
+    subject: SpendingSubject;
+    limitUsd: number | undefined;
+    now: Date;
+    store: LimitStateStore | null;
+    sumSince: (filter: UsageFilter, since: string | null) => Promise<number>;
+    warnAt: number;
+    /** Скользящее окно, которое не идёт, открывается этим запросом (проверка перед ходом). */
+    open: boolean;
+    pendingUsd?: number;
+}
+/** Ключ состояния окна; у окна чата без чата — `null` (окно не читается). */
+export declare function windowStateKey(window: SpendingWindow, subject: SpendingSubject): string | null;
+export declare function usageFilterOf(window: SpendingWindow, subject: SpendingSubject): UsageFilter;
+/** Где сейчас окно: начало, конец и идёт ли оно. */
+export declare function currentSpan(window: SpendingWindow, saved: WindowState | null, now: Date, open: boolean): {
+    start: null;
+    end: null;
+    active: boolean;
+} | {
+    start: string;
+    end: string;
+    active: boolean;
+};
+export declare function readWindow(input: ReadWindowInput): Promise<WindowReading | null>;

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@ykurilov/agent-chat-limits",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.55.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "@ykurilov/agent-chat-source": "./src/index.ts",
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ykurilov/agent-chat-sdk.git",
+    "directory": "packages/limits"
+  },
+  "dependencies": {
+    "@ykurilov/agent-chat-core": "0.55.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "4.0.19",
+    "ai": "7.0.122",
+    "@ykurilov/agent-chat-server": "0.55.0",
+    "@ykurilov/agent-chat-storage-sqlite": "0.55.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }