charness 0.0.0-stage → 3.0.0

package/dist/utils/reminderWizard.d.ts

@@ -0,0 +1,710 @@
+/**
+ * @description Pure core of the `/reminders` wizard — the bot-LOCAL reminder
+ * feature: an inline-button flow that produces a {@link ScheduleSpec} with ZERO
+ * agent involvement (the `/schedule` path, by contrast, hands free text to the
+ * agent and lets it call the `schedule_*` MCP tools).
+ *
+ * Everything here is pure: no I/O, no `Date.now()` (every entry point takes the
+ * caller's `nowMs`), no telegraf, no `t()`. It returns STRUCTURED data —
+ * keyboard PLANS carrying i18n KEY names plus `callback_data`, and structured
+ * schedule descriptors — which `bot.ts` maps onto `Markup.inlineKeyboard` and
+ * `t(...)`. The split is mandatory rather than stylistic: user-facing text lives
+ * behind the ASYNC `t()` in 12 locales, so a pure layer that emitted prose could
+ * neither be localized nor unit-tested, and `bot.ts` itself cannot be imported
+ * by a test (its module-scope `parseEnv()` exits the process).
+ *
+ * Time math is HOST-LOCAL on purpose: the instance-wide `/timezone` setting is
+ * applied to `process.env.TZ` at boot, so plain `Date` arithmetic already IS the
+ * operator's clock and threading a zone through here would create a second
+ * source of truth.
+ */
+import type { ScheduleSpec } from '../scheduler/types';
+/**
+ * @name ReminderRepeatKind
+ * @description How often a reminder fires. `once` is an absolute instant; the
+ * other four map onto the exactly four cron shapes `describeCron`
+ * (`scheduler/recurrence.ts`) renders as words — deliberate, so a
+ * wizard-created job never shows up as a raw cron expression anywhere.
+ */
+export declare const reminderRepeatKinds: readonly ["once", "daily", "weekdays", "weekly", "monthly"];
+export type ReminderRepeatKind = (typeof reminderRepeatKinds)[number];
+export declare function checkIsReminderRepeatKind(value: string): value is ReminderRepeatKind;
+/**
+ * @name ReminderWizardStep
+ * @description Which screen the wizard is on. `dateGrid`, `dayOfMonthGrid`,
+ * `hour` and `minute` are the "other …" expansions of their quick-pick steps —
+ * separate steps rather than modes so `back` has one unambiguous meaning
+ * everywhere.
+ */
+export declare const reminderWizardSteps: readonly ["repeat", "date", "dateGrid", "weekday", "dayOfMonth", "dayOfMonthGrid", "time", "hour", "minute", "text"];
+export type ReminderWizardStep = (typeof reminderWizardSteps)[number];
+/** One wall-clock time of day, the wizard's time pick. */
+export interface ReminderTimeOfDay {
+    hour: number;
+    minute: number;
+}
+/** Quick-pick times offered on the time step, in render order. */
+export declare const reminderQuickTimes: readonly ReminderTimeOfDay[];
+/**
+ * Granularity of the custom-minute grid. Five minutes keeps the grid at 12
+ * buttons (4 rows of 3) — a full 0–59 grid would need 60, which is past
+ * Telegram's comfortable keyboard size and unreadable on a phone.
+ */
+export declare const reminderMinuteStep = 5;
+/** Cron `dow` values in Monday-first DISPLAY order (Sunday is `0` in cron). */
+export declare const reminderWeekdayDisplayOrder: readonly number[];
+/**
+ * @description i18n keys the keyboard plans reference. Collected in one object
+ * so the strings exist exactly once (and so the i18n scope has a single list to
+ * mirror into every locale); the pure layer never resolves them.
+ */
+export declare const reminderLabelKeys: {
+    readonly hubAdd: "reminders.addButton";
+    readonly hubList: "reminders.listButton";
+    readonly repeatOnce: "reminders.repeatOnceButton";
+    readonly repeatDaily: "reminders.repeatDailyButton";
+    readonly repeatWeekdays: "reminders.repeatWeekdaysButton";
+    readonly repeatWeekly: "reminders.repeatWeeklyButton";
+    readonly repeatMonthly: "reminders.repeatMonthlyButton";
+    readonly dateToday: "reminders.dateTodayButton";
+    readonly dateTomorrow: "reminders.dateTomorrowButton";
+    readonly dateOther: "reminders.dateOtherButton";
+    readonly dayOfMonthOther: "reminders.dayOfMonthOtherButton";
+    readonly timeOther: "reminders.timeOtherButton";
+    readonly back: "reminders.backButton";
+    readonly cancel: "reminders.cancelButton";
+    readonly listPrev: "reminders.listPrevButton";
+    readonly listNext: "reminders.listNextButton";
+    readonly listBackToHub: "reminders.listBackToHubButton";
+    readonly cardDelete: "reminders.cardDeleteButton";
+    readonly cardBackToList: "reminders.cardBackToListButton";
+};
+/**
+ * Weekday button label keys, indexed by CRON `dow` value (Sunday = 0) so the
+ * display order and the stored value never drift apart.
+ */
+export declare const reminderWeekdayLabelKeys: readonly string[];
+/**
+ * Repeat-kind → its button label key. Exported because the wizard's running
+ * summary ("Repeat: Every day") must name the pick with the SAME word its button
+ * carried — a second wording would read as a different option.
+ */
+export declare const reminderRepeatLabelKeys: Readonly<Record<ReminderRepeatKind, string>>;
+/**
+ * @name ReminderButtonLabel
+ * @description A button's caption: either an i18n `key` (worded labels, which
+ * must be translated) or a locale-neutral `literal` (clock times, dates,
+ * numbers, a reminder's own name — translating those would be wrong).
+ */
+export type ReminderButtonLabel = {
+    kind: 'key';
+    key: string;
+    vars?: Readonly<Record<string, string | number>>;
+} | {
+    kind: 'literal';
+    text: string;
+}
+/**
+ * A list row — `🔔 <name> · <localized schedule>`. Carried as its PARTS rather
+ * than a `key` label because the schedule wording is itself a `t()` lookup, so
+ * the caption can only be composed where `t` lives; a `key` label's `vars` must
+ * already be resolved, which would force this layer to inline English.
+ */
+ | {
+    kind: 'listRow';
+    name: string;
+    descriptor: ReminderScheduleDescriptor;
+};
+/** One inline button, as a plan `bot.ts` turns into `Markup.button.callback`. */
+export interface ReminderButtonPlan {
+    label: ReminderButtonLabel;
+    callbackData: string;
+}
+/** Rows of buttons — the plan form of `Markup.inlineKeyboard`. */
+export type ReminderKeyboardPlan = ReminderButtonPlan[][];
+/**
+ * Wizard `callback_data` prefix. Every wizard button also bakes in the wizard
+ * id, because an inline keyboard stays tappable forever: without it a tap on a
+ * wizard the operator abandoned hours ago would feed picks into whatever wizard
+ * is live now (the same class of bug the `/disconnect` picker's per-message
+ * snapshot and `acl_skip_<fireAt>`'s baked instant guard against).
+ */
+export declare const reminderWizardCallbackPrefix = "rw_";
+/**
+ * Max wizard-id length. Bounded so the longest producible `callback_data` is
+ * provably inside Telegram's 64-byte cap, and so a malformed id can never make
+ * the anchored matcher accept garbage.
+ */
+export declare const reminderWizardIdMaxLength = 12;
+/**
+ * Anchored matcher for `bot.action(...)`. Built from the id-length constant so
+ * the wire format has exactly one definition. The id charset excludes `_`
+ * precisely because `_` is the field separator.
+ */
+export declare const reminderWizardCallbackRe: RegExp;
+/**
+ * @name ReminderWizardAction
+ * @description A decoded wizard tap. `pick*` commits a value, `open*` descends
+ * into a custom grid, and `back`/`cancel` are valid on every step.
+ */
+export type ReminderWizardAction = {
+    kind: 'pickRepeat';
+    repeatKind: ReminderRepeatKind;
+} | {
+    kind: 'openDateGrid';
+} | {
+    kind: 'pickDate';
+    dateIso: string;
+} | {
+    kind: 'pickWeekday';
+    weekday: number;
+} | {
+    kind: 'openDayOfMonthGrid';
+} | {
+    kind: 'pickDayOfMonth';
+    dayOfMonth: number;
+} | {
+    kind: 'pickQuickTime';
+    hour: number;
+    minute: number;
+} | {
+    kind: 'openHourGrid';
+} | {
+    kind: 'pickHour';
+    hour: number;
+} | {
+    kind: 'pickMinute';
+    minute: number;
+} | {
+    kind: 'back';
+} | {
+    kind: 'cancel';
+};
+/** A decoded wizard callback: which wizard it belongs to, and what it asks for. */
+export interface ReminderWizardCallback {
+    wizardId: string;
+    action: ReminderWizardAction;
+}
+/**
+ * @description Mint a wizard id from the caller's clock: base36 of the epoch ms.
+ * Pure (the instant is an argument), 8–9 chars, and monotonically increasing —
+ * so a freshly opened wizard can never collide with the one it replaced, which
+ * is the whole point of the stale-tap guard.
+ */
+export declare function createReminderWizardId(nowMs: number): string;
+export declare function buildReminderRepeatCallback(wizardId: string, repeatKind: ReminderRepeatKind): string;
+export declare function buildReminderDateGridCallback(wizardId: string): string;
+export declare function buildReminderDateCallback(wizardId: string, dateIso: string): string;
+export declare function buildReminderWeekdayCallback(wizardId: string, weekday: number): string;
+export declare function buildReminderDayOfMonthGridCallback(wizardId: string): string;
+export declare function buildReminderDayOfMonthCallback(wizardId: string, dayOfMonth: number): string;
+export declare function buildReminderQuickTimeCallback(wizardId: string, quickTimeIndex: number): string;
+export declare function buildReminderHourGridCallback(wizardId: string): string;
+export declare function buildReminderHourCallback(wizardId: string, hour: number): string;
+export declare function buildReminderMinuteCallback(wizardId: string, minute: number): string;
+export declare function buildReminderBackCallback(wizardId: string): string;
+export declare function buildReminderCancelCallback(wizardId: string): string;
+/**
+ * @description Decode one wizard `callback_data`, or `null` when it is not ours
+ * / malformed / carries an out-of-range argument.
+ *
+ * Range and calendar validation happens HERE rather than at apply time so an
+ * impossible value (weekday `9`, `2026-02-31`, a minute off the 5-minute grid)
+ * can never reach the spec assembler — a forged or truncated callback is
+ * indistinguishable from a stale one to the caller, and both must be inert.
+ */
+export declare function parseReminderWizardCallback(callbackData: string): ReminderWizardCallback | null;
+/** Hub → open the add wizard. */
+export declare const reminderAddCallback = "rmadd";
+/** → the hub screen (from the list). */
+export declare const reminderHubCallback = "rmhub";
+/**
+ * Dismiss the reminders screen (hub / done card): the message is relabelled and
+ * its keyboard dropped. Declared here with the other flat `rm*` ids so the whole
+ * reminder callback namespace has ONE definition site and a future id cannot
+ * silently collide; the row it sits on is composed by the screen builder.
+ */
+export declare const reminderCloseCallback = "rmclose";
+/** Anchored matchers for `bot.action(...)`, beside their builders. */
+export declare const reminderListPageCallbackRe: RegExp;
+export declare const reminderCardCallbackRe: RegExp;
+/**
+ * The id charset mirrors `generateScheduleId` output — `slugify` lowercases and
+ * collapses everything else to hyphens, so lowercase alnum + `-` is the full
+ * alphabet a real reminder id can contain. A forged id still parses and simply
+ * resolves to `notFound` (see {@link getReminderDeleteTarget}).
+ */
+export declare const reminderDeleteCallbackRe: RegExp;
+export declare function buildReminderListPageCallback(page: number): string;
+/** A list row's button — the ABSOLUTE index into the thread's reminder list. */
+export declare function buildReminderCardCallback(reminderIndex: number): string;
+/**
+ * @description The card's delete button. Carries the reminder's OWN id, never a
+ * positional index: deletion is destructive and an old keyboard stays tappable,
+ * so an index resolved against a list that has since changed would delete a
+ * DIFFERENT reminder. A schedule id is `slugify(name)` (≤40) + `-` + a 6-char
+ * suffix, so prefix + id stays well inside the 64-byte cap.
+ */
+export declare function buildReminderDeleteCallback(reminderId: string): string;
+export declare function parseReminderListPageCallback(callbackData: string): number | null;
+export declare function parseReminderCardCallback(callbackData: string): number | null;
+export declare function parseReminderDeleteCallback(callbackData: string): string | null;
+/**
+ * @name ReminderWizardState
+ * @description Everything the wizard has collected. `bot.ts` keeps one of these
+ * per thread and re-renders the SAME message from it on every tap, so the whole
+ * flow occupies exactly one Telegram message.
+ *
+ * Only ONE of `dateIso` / `weekday` / `dayOfMonth` is ever set — which one is
+ * decided by `repeatKind` (`daily` and `weekdays` need none of them).
+ */
+export interface ReminderWizardState {
+    wizardId: string;
+    step: ReminderWizardStep;
+    repeatKind: ReminderRepeatKind | null;
+    /** Local calendar date `YYYY-MM-DD` for a `once` reminder. */
+    dateIso: string | null;
+    /** Cron `dow` (Sunday = 0) for a `weekly` reminder. */
+    weekday: number | null;
+    /** 1–31 for a `monthly` reminder. */
+    dayOfMonth: number | null;
+    /** Set on the `minute` step so its header can render `21:__`. */
+    hour: number | null;
+    minute: number | null;
+    /**
+     * The reminder text the operator already sent, retained so it is NEVER asked
+     * for twice. It is set only when a `once` instant went stale while they were
+     * typing: the wizard then re-asks the TIME alone (see
+     * {@link getReminderStateForRetime}), and the next time pick creates the
+     * reminder straight from this text.
+     */
+    text: string | null;
+}
+/** A fresh wizard, parked on the repeat step with nothing picked. */
+export declare function createReminderWizardState(wizardId: string): ReminderWizardState;
+/**
+ * @description The step that follows the repeat pick. `daily` and `weekdays`
+ * need no second pick at all, so they SKIP straight to the time step — the one
+ * reason this is a function of the state rather than a fixed sequence.
+ */
+export declare function getReminderStepAfterRepeat(repeatKind: ReminderRepeatKind): ReminderWizardStep;
+/**
+ * @description Where `back` lands, or `null` for "leave the wizard and show the
+ * hub" (which is what back means on the first step).
+ *
+ * Reads the repeat kind because the step BEFORE the time step differs per kind
+ * — and is the repeat step itself for `daily` / `weekdays`, which have no second
+ * step to return to.
+ */
+export declare function getReminderPreviousStep(state: ReminderWizardState): ReminderWizardStep | null;
+/**
+ * @description The state as it must look when the wizard RE-ENTERS `step`: the
+ * picks owned by that step and by every later step are cleared, so stepping back
+ * into a screen never silently keeps the value the operator came to change.
+ *
+ * The three date/weekday/day-of-month fields are cleared together because they
+ * are mutually exclusive alternatives of the same (second) step.
+ *
+ * An already-captured `text` is the ONE thing no re-entry clears: the operator
+ * types it exactly once, and re-picking the schedule is not a reason to ask again.
+ */
+export declare function getReminderStateForStep(state: ReminderWizardState, step: ReminderWizardStep): ReminderWizardState;
+/**
+ * @description The state to re-render when the reminder text is already in hand
+ * but the picked `once` instant has gone by while the operator was typing: back on
+ * the TIME step, with the text RETAINED.
+ *
+ * Retaining it is the whole point. The flow is buttons precisely so the operator
+ * types exactly once, and re-entering the text step to collect the same sentence
+ * again defeats that — so only the time is re-asked, and the next time pick creates
+ * the reminder outright (see {@link getReminderActionAfterTime}).
+ */
+export declare function getReminderStateForRetime(state: ReminderWizardState, text: string): ReminderWizardState;
+/**
+ * @name ReminderWizardErrorCode
+ * @description Machine-readable reasons a step cannot be completed, so `bot.ts`
+ * picks the i18n key. `pastTime` is the load-bearing one: «today» plus a time
+ * that has already gone by must SAY so on the time step, never silently roll the
+ * reminder to tomorrow (a locked product decision — a silent roll means the
+ * operator is reminded 24h off what they asked for).
+ *
+ * `invalidDate` and `invalidTime` are deliberately separate: a date that does not
+ * exist sends the operator back to the DATE step, whereas a wall-clock time a DST
+ * spring-forward skips happens on a perfectly good date and must send them back to
+ * the TIME step — one code for both told them to re-pick a date that was fine.
+ */
+export declare const reminderWizardErrorCodes: readonly ["pastTime", "invalidDate", "invalidTime", "textTooLong"];
+export type ReminderWizardErrorCode = (typeof reminderWizardErrorCodes)[number];
+/**
+ * The subset a SPEC assembly can fail with. `textTooLong` is raised when the
+ * reminder text is captured, long after the spec is decidable, so it is excluded
+ * here rather than left representable in a result that can never carry it.
+ */
+export type ReminderSpecErrorCode = Exclude<ReminderWizardErrorCode, 'textTooLong'>;
+/**
+ * @name ReminderWizardTransition
+ * @description What the caller must do after a tap.
+ *  - `render`     — re-render `state.step` into the same message.
+ *  - `awaitText`  — every pick is in; arm the "send me the reminder text" step
+ *                   (a typed message or a voice note).
+ *  - `createNow`  — every pick is in AND the text is already held (the operator
+ *                   sent it before the picked instant went stale): create the
+ *                   reminder immediately, without re-entering the text step.
+ *  - `cancelled`  — terminal; drop the wizard.
+ *  - `backToHub`  — leave the wizard, show the hub.
+ *  - `error`      — re-render `state.step` WITH the error; nothing was committed.
+ *  - `expired`    — a stale/foreign tap: answer "expired" and change NOTHING.
+ */
+export type ReminderWizardTransition = {
+    kind: 'render';
+    state: ReminderWizardState;
+} | {
+    kind: 'awaitText';
+    state: ReminderWizardState;
+} | {
+    kind: 'createNow';
+    state: ReminderWizardState;
+    spec: ScheduleSpec;
+    text: string;
+} | {
+    kind: 'cancelled';
+} | {
+    kind: 'backToHub';
+} | {
+    kind: 'error';
+    code: ReminderWizardErrorCode;
+    state: ReminderWizardState;
+} | {
+    kind: 'expired';
+};
+/**
+ * @name ReminderAfterTimeAction
+ * @description What the wizard does once a time pick has been validated: ASK for
+ * the reminder text (step 4, the normal first pass), or CREATE straight away
+ * because the state already carries it.
+ */
+export type ReminderAfterTimeAction = {
+    kind: 'askText';
+} | {
+    kind: 'createNow';
+    text: string;
+};
+/**
+ * @description Decide whether the text step is still owed. A state that HOLDS the
+ * text is past it: the operator sent it, the picked `once` instant then went stale
+ * while they typed, and this is the replacement time pick — so the reminder is
+ * created from the text already in hand. Re-asking here would make them type the
+ * same note twice, which is exactly what the button flow exists to avoid.
+ */
+export declare function getReminderActionAfterTime(state: ReminderWizardState): ReminderAfterTimeAction;
+/**
+ * @description Apply one tapped `callback_data` to a wizard state.
+ *
+ * Takes the RAW callback string (not a pre-parsed action) so the stale-tap guard
+ * cannot be forgotten at a call site: a tap whose baked wizard id is not this
+ * wizard's — or that belongs to a step this wizard has left — returns `expired`
+ * and mutates nothing.
+ */
+export declare function applyReminderWizardCallback(input: {
+    state: ReminderWizardState;
+    callbackData: string;
+    nowMs: number;
+}): ReminderWizardTransition;
+/**
+ * @description Build the keyboard plan for the wizard's CURRENT step.
+ *
+ * One dispatcher rather than a builder per step because `bot.ts` renders
+ * whatever `state.step` says after every transition — it never needs to know
+ * which screen it is drawing. `nowMs` is required because the date step's
+ * buttons are dated at RENDER time (see {@link buildReminderDateCallback}).
+ */
+export declare function buildReminderStepKeyboard(input: {
+    state: ReminderWizardState;
+    nowMs: number;
+}): ReminderKeyboardPlan;
+/**
+ * @name ReminderSchedulePicks
+ * @description A COMPLETE pick set — what the wizard state holds once every
+ * screen has been answered. A union discriminated by `repeatKind` rather than
+ * one shape with optional fields, so "weekly without a weekday" is not a
+ * representable state and the assembler needs no defensive branches.
+ */
+export type ReminderSchedulePicks = {
+    repeatKind: 'once';
+    dateIso: string;
+    hour: number;
+    minute: number;
+} | {
+    repeatKind: 'daily';
+    hour: number;
+    minute: number;
+} | {
+    repeatKind: 'weekdays';
+    hour: number;
+    minute: number;
+}
+/** `weekday` is a cron `dow` value (Sunday = 0). */
+ | {
+    repeatKind: 'weekly';
+    weekday: number;
+    hour: number;
+    minute: number;
+} | {
+    repeatKind: 'monthly';
+    dayOfMonth: number;
+    hour: number;
+    minute: number;
+};
+/**
+ * @description Lift a complete pick set out of a wizard state, or `null` when a
+ * pick the chosen repeat kind needs is still missing.
+ */
+export declare function getReminderPicksFromState(state: ReminderWizardState): ReminderSchedulePicks | null;
+/** Outcome of {@link buildReminderSpec} — a typed result, never a throw. */
+export type ReminderSpecResult = {
+    ok: true;
+    spec: ScheduleSpec;
+} | {
+    ok: false;
+    code: ReminderSpecErrorCode;
+};
+/**
+ * @description Turn a complete pick set into a {@link ScheduleSpec}.
+ *
+ * The four recurring kinds emit exactly the cron shapes `describeCron`
+ * (`scheduler/recurrence.ts`) renders as words — `m h * * *`, `m h * * 1-5`,
+ * `m h * * d`, `m h D * *`. That is why the wizard offers these five options and
+ * no others: any further shape would surface to the operator as a raw cron
+ * expression. None of them can fire more often than daily, so
+ * `minFireIntervalMs` is unreachable by construction.
+ *
+ * `once` is assembled in HOST-LOCAL time (the operator's `/timezone` is already
+ * applied to `process.env.TZ`) and stored as a UTC ISO instant, which
+ * `new Date(...)` round-trips exactly.
+ */
+export declare function buildReminderSpec(input: {
+    picks: ReminderSchedulePicks;
+    nowMs: number;
+}): ReminderSpecResult;
+/**
+ * @name ReminderScheduleDescriptor
+ * @description A persisted spec, decomposed into the parts a LOCALIZED
+ * rendering needs (list rows, the card). `describeSchedule` in
+ * `scheduler/recurrence.ts` cannot serve this UI: it is English-only by design
+ * (it is interpolated INTO i18n templates), while the reminder screens exist in
+ * 12 locales.
+ *
+ * `raw` is the honest fallback for anything the wizard cannot create — an
+ * agent-made `schedule_*` job may carry any cron shape, including an N-times
+ * budget this descriptor has no field for. Its `text` is the bare cron
+ * expression, rendered verbatim rather than mistranslated into a shape it is not.
+ */
+export type ReminderScheduleDescriptor = {
+    kind: 'daily';
+    time: string;
+} | {
+    kind: 'weekdays';
+    time: string;
+} | {
+    kind: 'weekly';
+    weekday: number;
+    time: string;
+} | {
+    kind: 'monthly';
+    dayOfMonth: number;
+    time: string;
+} | {
+    kind: 'once';
+    dateIso: string;
+    time: string;
+} | {
+    kind: 'raw';
+    text: string;
+};
+/** Decompose a spec for localized rendering; see {@link ReminderScheduleDescriptor}. */
+export declare function getReminderScheduleDescriptor(spec: ScheduleSpec): ReminderScheduleDescriptor;
+/**
+ * Longest reminder TEXT accepted from the operator. The text is interpolated into
+ * the fire announcement and, alongside the schedule and next-run lines, into the
+ * card and the created-screen — all of which are single Telegram messages under the
+ * 4096-character cap. The bound therefore has to leave generous headroom for the
+ * surrounding template in ANY of the 12 locales, which is why it sits far below
+ * that cap rather than just under it. Past it the text is REJECTED, never
+ * truncated: it is the operator's own words, and this all-buttons flow exists so
+ * they type it exactly once.
+ */
+export declare const reminderTextMaxLength = 1000;
+/**
+ * Longest reminder name kept, INCLUDING the ellipsis. Matches `slugify`'s
+ * `slugMaxLength` so the derived name and the id minted from it stay in step.
+ */
+export declare const reminderNameMaxLength = 40;
+/**
+ * Name used when the body text carries no letter or digit (whitespace only,
+ * punctuation only, emoji only). A stable fallback rather than an empty row —
+ * mirrors `slugify`'s `'job'` guarantee, which the id generator relies on.
+ */
+export declare const reminderNameFallback = "reminder";
+/**
+ * Longest reminder text echoed back in the wizard's running summary. The summary
+ * exists so the operator can SEE what was kept after a stale-instant retry — not to
+ * reprint the whole note, which would push the step's question off the screen.
+ */
+export declare const reminderSummaryTextMaxLength = 80;
+/**
+ * @description `text` shortened to at most `maxLength` characters — the ellipsis
+ * counted INSIDE that budget — cut on a word boundary when there is one. `''` when
+ * the budget cannot even hold the ellipsis, leaving the caller to decide what an
+ * empty result means.
+ *
+ * Shared by the derived reminder name, the wizard's text summary and the list-row
+ * button caption, so they shorten identically instead of growing three slightly
+ * different cuts.
+ */
+export declare function getShortenedText(text: string, maxLength: number): string;
+/**
+ * @description Derive a reminder's display name from its body text. The wizard
+ * deliberately never ASKS for a name — one less typing step — so the list rows
+ * and the card show the first words of the reminder itself.
+ *
+ * Whitespace is collapsed (a multi-line body must not render as a ragged row) and
+ * the result never exceeds {@link reminderNameMaxLength}.
+ */
+export declare function getReminderNameFromText(text: string): string;
+/** Reminders listed per page. One row each, so the keyboard stays phone-sized. */
+export declare const reminderListPageSize = 8;
+/**
+ * @name ReminderListRow
+ * @description One reminder as the list/card screens consume it: its id (what a
+ * delete tap carries), its derived display name, and its schedule decomposed for
+ * localized rendering.
+ */
+export interface ReminderListRow {
+    id: string;
+    name: string;
+    descriptor: ReminderScheduleDescriptor;
+}
+/**
+ * @description The hub keyboard: «add» and «list» SIDE BY SIDE on one row (the
+ * locked layout — «close» is a separate row the caller appends). «list» is drawn
+ * only when there is something to list; a list button that opens an empty screen is
+ * a dead end. The count rides as a label var so the caller can render "📋 List (3)".
+ *
+ * `isAddOffered` is the per-thread REMINDER cap (counted apart from the agent's
+ * schedule cap): at the cap there is nothing an «add» tap could create, so the
+ * button is not drawn (same dead-end reasoning as the list button). The caller
+ * owns that comparison — the cap lives in the scheduler store, not here — and it
+ * defaults to offering «add».
+ */
+export declare function buildReminderHubKeyboard(reminderCount: number, options?: {
+    isAddOffered?: boolean;
+}): ReminderKeyboardPlan;
+/**
+ * @name ReminderListPlan
+ * @description One rendered list page. `currentPage` is already CLAMPED by
+ * {@link paginateList}, so a stale page index lands on the last real page
+ * instead of rendering an empty body.
+ */
+export interface ReminderListPlan {
+    /** The reminders visible on this page, in list order. */
+    rows: ReminderListRow[];
+    /** Zero-based, clamped. */
+    currentPage: number;
+    totalPages: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    keyboard: ReminderKeyboardPlan;
+}
+/**
+ * @description Build a list page: one row per reminder, then the prev/next
+ * navigation (only the arrows the page can actually use), then back-to-hub.
+ *
+ * A row's CAPTION is the reminder's name plus its schedule — planned as a `listRow`
+ * label, because the schedule has to be localized and only the caller holds `t`.
+ * The whole list therefore rides the buttons, and the message text stays a short
+ * header (the split the `/model` picker uses).
+ *
+ * Row buttons carry the ABSOLUTE index into `rows` — pagination is the one
+ * index-based thing here, and opening a card is non-destructive. The card's
+ * delete button carries the reminder's own id instead (see
+ * {@link buildReminderDeleteCallback}).
+ */
+export declare function buildReminderListPlan(rows: readonly ReminderListRow[], page: number): ReminderListPlan;
+/**
+ * @description Resolve a tapped list row back to its reminder, or `null` when
+ * the index no longer resolves (the list shrank between render and tap). Stale
+ * keyboards stay tappable forever in Telegram, so an out-of-range index must
+ * answer "expired" rather than open a neighbour — same contract as
+ * `getTimezoneAt`.
+ */
+export declare function getReminderRowAt(rows: readonly ReminderListRow[], reminderIndex: number): ReminderListRow | null;
+/**
+ * @description The list page a row at `reminderIndex` was rendered on — what the
+ * card's back button returns to. Derived from the index rather than carried in
+ * the callback, so the card needs no extra state to come back to where it was
+ * opened from.
+ */
+export declare function getReminderCardBackPage(reminderIndex: number): number;
+/**
+ * @name ReminderCardPlan
+ * @description One reminder's card: the reminder itself plus a keyboard with
+ * delete (id-bound) and a back button that returns to the LIST PAGE the row was
+ * on — derived from its index, so no extra state has to be carried.
+ */
+export interface ReminderCardPlan {
+    row: ReminderListRow;
+    listPage: number;
+    keyboard: ReminderKeyboardPlan;
+}
+/** Build a reminder's card, or `null` for a stale row index. */
+export declare function buildReminderCardPlan(rows: readonly ReminderListRow[], reminderIndex: number): ReminderCardPlan | null;
+/**
+ * @name ReminderDeleteResolution
+ * @description Outcome of resolving a delete tap. `notFound` covers an already
+ * deleted reminder (a double tap, or an old card left open) — the caller says
+ * "gone" instead of deleting whatever now sits where it used to be.
+ */
+export type ReminderDeleteResolution = {
+    kind: 'found';
+    row: ReminderListRow;
+} | {
+    kind: 'notFound';
+};
+/** Resolve a delete tap by the reminder ID baked into its `callback_data`. */
+export declare function getReminderDeleteTarget(rows: readonly ReminderListRow[], reminderId: string): ReminderDeleteResolution;
+/** `{hour: 9, minute: 0}` → `"09:00"`. Locale-neutral, hence a literal label. */
+export declare function formatReminderTime(time: ReminderTimeOfDay): string;
+/** A local `Date` → its calendar date as `YYYY-MM-DD` (never UTC-shifted). */
+export declare function formatReminderDateIso(date: Date): string;
+/** Date-grid button label: `DD.MM` — digits only, so no locale is implied. */
+export declare function formatReminderDayMonth(date: Date): string;
+/**
+ * @description The local calendar date `offsetDays` after the day containing
+ * `nowMs`. Built from the date PARTS rather than by adding 24h so a DST
+ * transition cannot shift the result into the neighbouring day.
+ */
+export declare function getLocalDateAtDayOffset(nowMs: number, offsetDays: number): Date;
+/**
+ * @name ReminderInstantResult
+ * @description The resolved `once` instant, or WHICH of the two picks is at fault.
+ * Two failure codes rather than one because they send the operator to different
+ * screens (see {@link ReminderWizardErrorCode}).
+ */
+export type ReminderInstantResult = {
+    ok: true;
+    instant: Date;
+} | {
+    ok: false;
+    code: 'invalidDate' | 'invalidTime';
+};
+/**
+ * @description The local instant a `once` reminder fires at.
+ *
+ * The calendar date is probed on its OWN midnight instant, independently of the
+ * picked time, so the two causes of failure stay distinguishable: `2026-02-31` is
+ * no date at all (`invalidDate`), while `02:30` on a spring-forward day is a real
+ * date whose wall clock simply skips that hour (`invalidTime`) — the JS `Date`
+ * constructor silently shifts such a time forward instead of refusing it.
+ */
+export declare function createReminderInstant(dateIso: string, hour: number, minute: number): ReminderInstantResult;
+//# sourceMappingURL=reminderWizard.d.ts.map