vibe-usage-cli 0.0.0-stage → 0.1.1

package/build/shared/account-state.js

@@ -0,0 +1,75 @@
+// States of an account read just now with a working sign-in: quota, or none to report.
+export const HEALTHY_STATUSES = new Set(['ok', 'no_limits_reported']);
+// Whether a limit with `remaining` percent left is low at the user's threshold.
+export const isLowQuota = (remaining, threshold) => remaining !== null && remaining <= threshold;
+// States where the useful next step is signing in or opening the provider's app.
+const SIGN_IN_STATUSES = new Set([
+    'auth_missing',
+    'auth_invalid',
+    'auth_expired',
+    'auth_rejected',
+    'keychain_unavailable',
+    'app_closed'
+]);
+// States that pass by themselves: the next read is already on its way.
+const WAITING_STATUSES = new Set([
+    'pending',
+    'rate_limited',
+    'transport_error',
+    'request_timeout',
+    'server_closed',
+    'rpc_timeout',
+    'process_timeout',
+    'local_service_unavailable'
+]);
+// Signing in helps when the source said so, or when an account was never read for a reason
+// that does not pass by itself.
+export const needsSignIn = (account) => SIGN_IN_STATUSES.has(account.status) || (!account.windows.length && !WAITING_STATUSES.has(account.status));
+// `active` is the source's headline choice, not whether the limit binds (see selection.ts).
+const isKnown = (window) => !window.stale && window.section !== 'details' && window.remainingPercent !== null;
+const tightest = (windows) => [...windows].sort((p, q) => p.remainingPercent - q.remainingPercent)[0] ?? null;
+// A window without a reported length counts as the longest.
+const length = (window) => window.durationMinutes ?? Number.POSITIVE_INFINITY;
+function limits(account) {
+    const known = account.windows.filter(isKnown);
+    const whole = known.filter(w => !w.scope && !w.partial);
+    const pool = whole.length ? whole : known;
+    const shortest = Math.min(...pool.map(length));
+    const window = tightest(pool.filter(w => length(w) === shortest));
+    // The other limit may be one model's or part of the account's: spent, it stops that work, so
+    // it is shown. Only a limit on the whole account runs the account out first, though.
+    const other = window ? tightest(known.filter(w => w !== window)) : null;
+    const tighter = window && other && !other.partial && other.remainingPercent < window.remainingPercent ? other : null;
+    return { window, other, tighter };
+}
+function noteFor(account) {
+    if (account.status === 'pending')
+        return 'reading';
+    if (account.status === 'app_closed')
+        return 'openApp';
+    if (account.status === 'no_limits_reported')
+        return 'noLimits';
+    if (WAITING_STATUSES.has(account.status))
+        return 'waiting';
+    return needsSignIn(account) ? 'signIn' : 'noData';
+}
+// One line per account of the tool, its main account first.
+export function compactLines(state, lowQuotaPercent) {
+    return [...state.accounts]
+        .sort((a, b) => Number(b.primary) - Number(a.primary))
+        .map(account => {
+        const measured = account.status === 'ok' || (account.status === 'stale' && Boolean(account.fetchedAt));
+        const { window, other, tighter } = measured ? limits(account) : { window: null, other: null, tighter: null };
+        const isLow = (limit) => isLowQuota(limit?.remainingPercent ?? null, lowQuotaPercent);
+        return {
+            account,
+            window,
+            other,
+            tighter,
+            stale: account.status === 'stale',
+            low: isLow(window),
+            tighterLow: isLow(tighter),
+            note: window ? null : noteFor(account)
+        };
+    });
+}

package/build/shared/catalog.d.ts

@@ -0,0 +1,85 @@
+import type { MessageKey } from './i18n/index.ts';
+export declare const APP_NAME = "Vibe Usage";
+export declare const APP_SLUG = "vibe-usage";
+export declare const APP_REPOSITORY = "mustafacagri/vibe-usage";
+export declare const PROVIDER_IDS: readonly ["claude", "codex", "cursor", "antigravity"];
+export type ProviderId = (typeof PROVIDER_IDS)[number];
+export interface Provider {
+    readonly id: ProviderId;
+    readonly name: string;
+    readonly glyph: string;
+    readonly acceptsModel: boolean;
+}
+export declare const PROVIDERS: readonly Provider[];
+export declare const PROFILE_DIRS: {
+    readonly claude: ".claude";
+    readonly codex: ".codex";
+};
+export type ProfileProviderId = keyof typeof PROFILE_DIRS;
+export declare const isProfileProvider: (id: ProviderId) => id is ProfileProviderId;
+export declare const PROFILE_PROVIDER_IDS: readonly ProfileProviderId[];
+export declare const PROFILE_ENV: {
+    readonly claude: "CLAUDE_CONFIG_DIR";
+    readonly codex: "CODEX_HOME";
+};
+export declare const AUTO = "auto";
+export type Auto = typeof AUTO;
+export declare const ACCOUNT_ID_PATTERN: RegExp;
+export declare const accountId: (providerId: ProviderId, key: string) => string;
+export declare const DEFAULT_ACCOUNT_KEY = "default";
+export declare const MAX_DISMISSED_ACCOUNTS = 100;
+export declare const MAX_LABEL_LENGTH = 80;
+export declare const MODEL_ID_PATTERN: RegExp;
+export declare const CLAUDE_PERMISSION_MODES: readonly ["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"];
+export type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODES)[number];
+export declare const CLAUDE_EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type ClaudeEffortLevel = (typeof CLAUDE_EFFORT_LEVELS)[number];
+export declare const isOneOf: <T>(values: readonly T[], value: unknown) => value is T;
+export declare const ACCOUNT_LABEL_KEYS: readonly ["accountA", "accountB", "defaultAccount", "newAccount"];
+export declare const ACCOUNT_ORIGINS: readonly ["discovered", "user", "pending"];
+export declare const AUTO_CONTINUE: readonly ["off", "accounts", "tools"];
+export declare const INHERIT = "inherit";
+export declare const AUTOMATION_MODES: readonly ["off", "ask", "auto"];
+export declare const SUGGESTION_KINDS: readonly ["low", "return", "reopen"];
+export declare const TRANSITION_STATUSES: readonly ["offered", "dispatching", "dispatched", "failed", "interrupted", "dismissed"];
+export declare const LOW_QUOTA_PERCENT = 20;
+export declare const LOW_QUOTA_RANGE: {
+    readonly min: 1;
+    readonly max: 99;
+    readonly choices: readonly [5, 10, 15, 20, 25, 30, 40, 50];
+};
+export declare const REFRESH_INTERVAL_SECONDS: {
+    readonly min: 30;
+    readonly max: 900;
+    readonly default: 120;
+    readonly choices: readonly [60, 120, 300, 600];
+};
+export declare const MINUTES: {
+    readonly HOUR: 60;
+    readonly DAY: 1440;
+    readonly FIVE_HOURS: 300;
+    readonly WEEK: 10080;
+};
+export declare const DURATION_MS: {
+    readonly SECOND: 1000;
+    readonly MINUTE: 60000;
+    readonly HOUR: 3600000;
+    readonly DAY: 86400000;
+};
+export declare const CLAUDE_SESSION_ENV_KEYS: readonly string[];
+export declare const CREDENTIAL_ENV_KEYS: readonly string[];
+export declare function providerById(id: ProviderId): Provider;
+export declare function isProviderId(value: unknown): value is ProviderId;
+export declare function normalizeProviderOrder(order: unknown): ProviderId[];
+export declare const displayOrder: (settings: {
+    homeOrder?: unknown;
+    providerOrder: unknown;
+}) => ProviderId[];
+export interface PeriodLabel {
+    labelKey: MessageKey;
+    labelParams?: {
+        n: number;
+    };
+    durationMinutes?: number;
+}
+export declare function durationLabel(minutes: unknown): PeriodLabel;

package/build/shared/catalog.js

@@ -0,0 +1,125 @@
+// The product name: window and tray titles, the data folder, launched terminals and briefs.
+export const APP_NAME = 'Vibe Usage';
+// The product's name in identifiers: its repository, files it saves, and how it names itself to services.
+export const APP_SLUG = 'vibe-usage';
+// The GitHub repository releases are published to (`owner/name`).
+export const APP_REPOSITORY = `mustafacagri/${APP_SLUG}`;
+export const PROVIDER_IDS = ['claude', 'codex', 'cursor', 'antigravity'];
+const PROVIDER_DETAILS = {
+    claude: { name: 'Claude', glyph: '◈', acceptsModel: true },
+    codex: { name: 'Codex', glyph: '✺', acceptsModel: true },
+    cursor: { name: 'Cursor', glyph: '✦', acceptsModel: true },
+    antigravity: { name: 'Antigravity', glyph: '▲', acceptsModel: false }
+};
+export const PROVIDERS = PROVIDER_IDS.map(id => ({ id, ...PROVIDER_DETAILS[id] }));
+// Tools that keep one sign-in per profile folder, the default one in the home directory.
+// Further accounts live in sibling folders (`.codex-work`) or in any folder the user adds.
+export const PROFILE_DIRS = { claude: '.claude', codex: '.codex' };
+export const isProfileProvider = (id) => Object.hasOwn(PROFILE_DIRS, id);
+export const PROFILE_PROVIDER_IDS = PROVIDER_IDS.filter(isProfileProvider);
+// The variable that points each of those tools at a profile folder other than the default one.
+export const PROFILE_ENV = { claude: 'CLAUDE_CONFIG_DIR', codex: 'CODEX_HOME' };
+export const AUTO = 'auto';
+export const ACCOUNT_ID_PATTERN = /^[a-zA-Z0-9:@._+-]{1,120}$/;
+// An account's id: its tool, and a key that tells it from the tool's other accounts.
+export const accountId = (providerId, key) => `${providerId}:${key}`;
+// The key of the account a tool uses when nothing selects another.
+export const DEFAULT_ACCOUNT_KEY = 'default';
+export const MAX_DISMISSED_ACCOUNTS = 100;
+export const MAX_LABEL_LENGTH = 80;
+// A model id as CLIs accept it (`opus`, `gpt-5.6-terra`, `sonnet[1m]`). It must start
+// alphanumeric so that it can never be read as a command-line flag.
+export const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:/[\]-]{0,99}$/;
+// Claude Code's `--permission-mode` and `--effort` values.
+export const CLAUDE_PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'auto', 'dontAsk', 'bypassPermissions'];
+export const CLAUDE_EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+// Whether `value` is one of `values`: the guard for every list of literals below.
+export const isOneOf = (values, value) => values.some(entry => entry === value);
+// Each list is the one owner of its values; the type of the same name in types.ts derives from it.
+// Account names the app supplies; the UI translates them.
+export const ACCOUNT_LABEL_KEYS = ['accountA', 'accountB', 'defaultAccount', 'newAccount'];
+export const ACCOUNT_ORIGINS = ['discovered', 'user', 'pending'];
+export const AUTO_CONTINUE = ['off', 'accounts', 'tools'];
+// What a project's own choice is when it leaves the matter to the app-wide setting.
+export const INHERIT = 'inherit';
+// How the app takes a step it may take by itself: never, after asking, or on its own.
+export const AUTOMATION_MODES = ['off', 'ask', 'auto'];
+export const SUGGESTION_KINDS = ['low', 'return', 'reopen'];
+export const TRANSITION_STATUSES = ['offered', 'dispatching', 'dispatched', 'failed', 'interrupted', 'dismissed'];
+// A limit at or below this share is shown as low and, when the user opted in, notified.
+export const LOW_QUOTA_PERCENT = 20;
+// The values each numeric setting may take, and the ones the window offers; a saved value
+// outside the offered ones (from an imported file) is offered too.
+export const LOW_QUOTA_RANGE = { min: 1, max: 99, choices: [5, 10, 15, 20, 25, 30, 40, 50] };
+export const REFRESH_INTERVAL_SECONDS = { min: 30, max: 900, default: 120, choices: [60, 120, 300, 600] };
+export const MINUTES = { HOUR: 60, DAY: 1440, FIVE_HOURS: 300, WEEK: 10080 };
+// The same units in milliseconds, for times and ages.
+export const DURATION_MS = { SECOND: 1000, MINUTE: 60_000, HOUR: 3_600_000, DAY: 86_400_000 };
+// What Claude Code sets for the processes it starts. A Claude Code that inherits them takes itself
+// for a child session of another one and saves nothing: no transcript, no entry in the profile's
+// session list. The app may itself run under Claude Code (started from one of its terminals), so
+// they are never passed on.
+export const CLAUDE_SESSION_ENV_KEYS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_SESSION_ATTENDED',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_EXECPATH',
+    'CLAUDE_CODE_MESSAGING_SOCKET',
+    'CLAUDE_CODE_MESSAGING_TOKEN',
+    'CLAUDE_PID',
+    'CLAUDE_EFFORT',
+    'AI_AGENT',
+    'TRACEPARENT'
+];
+// Environment variables that would make a launched CLI or a quota probe use credentials,
+// endpoints or profiles other than the account the user selected.
+export const CREDENTIAL_ENV_KEYS = [
+    'ANTHROPIC_API_KEY',
+    'ANTHROPIC_AUTH_TOKEN',
+    'ANTHROPIC_BASE_URL',
+    'ANTHROPIC_PROFILE',
+    'ANTHROPIC_VERTEX_PROJECT_ID',
+    'ANTHROPIC_BEDROCK_BASE_URL',
+    'CLAUDE_CODE_OAUTH_TOKEN',
+    'CLAUDE_SECURESTORAGE_CONFIG_DIR',
+    'CLAUDE_CODE_USE_BEDROCK',
+    'CLAUDE_CODE_USE_VERTEX',
+    'CLAUDE_CODE_USE_FOUNDRY',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'OPENAI_API_KEY',
+    'OPENAI_BASE_URL',
+    PROFILE_ENV.codex,
+    'CODEX_API_KEY',
+    'CODEX_ACCESS_TOKEN',
+    'ACCESS_TOKEN',
+    'CURSOR_API_KEY'
+];
+export function providerById(id) {
+    return { id, ...PROVIDER_DETAILS[id] };
+}
+export function isProviderId(value) {
+    return typeof value === 'string' && Object.hasOwn(PROVIDER_DETAILS, value);
+}
+// A complete, duplicate-free order: known entries first, then any provider left out.
+export function normalizeProviderOrder(order) {
+    const known = Array.isArray(order) ? order.filter(isProviderId) : [];
+    return [...new Set([...known, ...PROVIDER_IDS])];
+}
+// The order the window and the tray list tools in: the user's own, else the fallback order.
+export const displayOrder = (settings) => normalizeProviderOrder(settings.homeOrder ?? settings.providerOrder);
+// Semantic label for a quota window length; wording lives in i18n.
+export function durationLabel(minutes) {
+    if (typeof minutes !== 'number' || !Number.isFinite(minutes) || minutes <= 0)
+        return { labelKey: 'labelNoPeriodReported' };
+    if (minutes === MINUTES.WEEK)
+        return { labelKey: 'labelWeekly', durationMinutes: minutes };
+    if (minutes >= 2 * MINUTES.DAY && minutes % MINUTES.DAY === 0)
+        return { labelKey: 'labelNDays', labelParams: { n: minutes / MINUTES.DAY }, durationMinutes: minutes };
+    if (minutes % MINUTES.HOUR === 0)
+        return { labelKey: 'labelNHours', labelParams: { n: minutes / MINUTES.HOUR }, durationMinutes: minutes };
+    return { labelKey: 'labelNMins', labelParams: { n: minutes }, durationMinutes: minutes };
+}

package/build/shared/format.d.ts

@@ -0,0 +1,40 @@
+import { type Params, type Translate } from './i18n/index.ts';
+import { type ProviderId } from './catalog.ts';
+import type { Account, MeasuredAccount, QuotaWindow } from './types.ts';
+export interface FormatContext {
+    t: Translate;
+    locale: string;
+    now?: number;
+}
+export declare function formatPercent(value: number, locale: string): string;
+export declare function formatDuration(ms: number, locale: string): string;
+export interface WindowView {
+    label: string;
+    value: string;
+    percent: number | null;
+    detail: string;
+    reset: string;
+    resetAt: string;
+}
+export declare function describeWindow(window: QuotaWindow, { t, locale, now }: FormatContext): WindowView;
+type AccountNaming = Pick<MeasuredAccount, 'label' | 'labelKey' | 'signedInAs'>;
+export declare const formatAccountName: (account: AccountNaming, t: Translate) => string;
+export declare const hasOwnName: (account: AccountNaming) => boolean;
+export declare const LAUNCH_MESSAGES: {
+    readonly app: "handoverApp";
+    readonly terminal: "handoverTerminal";
+};
+export declare const toolLabel: (providerId: ProviderId, model: string | null | undefined) => string;
+export declare const SUGGESTION_BUTTONS: {
+    readonly low: "suggestionContinueBtn";
+    readonly return: "suggestionReturnBtn";
+    readonly reopen: "suggestionReopenBtn";
+};
+export declare function successorName(from: ProviderId, to: {
+    providerId: ProviderId;
+    accountId: string | null;
+}, accounts: readonly Account[], t: Translate): string;
+export declare function formatAge(timestamp: number, { t, locale, now }: FormatContext): string;
+export declare function formatFreshness(iso: string | undefined, status: string, context: FormatContext): string;
+export declare function describeCode(code: string, t: Translate, params?: Params): string;
+export {};

package/build/shared/format.js

@@ -0,0 +1,134 @@
+// Presentation shared by the renderer and the CLI: turns language-neutral snapshot data into
+// display text. Wording comes from the injected `t`; numbers, money and durations from Intl
+// in the given locale.
+import { hasKey } from "./i18n/index.js";
+import { DURATION_MS, providerById } from "./catalog.js";
+// Countdown granularity: coarser as the distance grows (42m · 3h 11m · 49h · 4d 5h).
+const MINUTE_PRECISION_UNTIL_MINUTES = 10 * 60;
+const HOURS_ONLY_UNTIL_MINUTES = 72 * 60;
+// CLDR's narrow units are ambiguous in some languages (tr: '3s 11d' = 3 hours 11 minutes;
+// ja falls back to Latin '3h11m'), so these use the short style.
+const SHORT_DURATION_LANGUAGES = /^(tr|de|nl|ja)\b/i;
+const AMOUNT_FIELDS = ['used', 'limit', 'remaining', 'bonus'];
+const AMOUNT_KEYS = { used: 'amountUsed', limit: 'amountLimit', remaining: 'amountRemaining', bonus: 'amountBonus' };
+const CENTS_PER_DOLLAR = 100;
+const CURRENCY = 'USD';
+const isNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const clampPercent = (value) => (isNumber(value) ? Math.max(0, Math.min(100, value)) : null);
+export function formatPercent(value, locale) {
+    return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 }).format(value / 100);
+}
+function formatMoney(cents, locale) {
+    return new Intl.NumberFormat(locale, { style: 'currency', currency: CURRENCY }).format(cents / CENTS_PER_DOLLAR);
+}
+function durationParts(ms) {
+    const minutes = Math.max(1, Math.round(Math.max(0, ms) / DURATION_MS.MINUTE));
+    if (minutes < 60)
+        return { minutes };
+    if (minutes < MINUTE_PRECISION_UNTIL_MINUTES)
+        return { hours: Math.floor(minutes / 60), minutes: minutes % 60 };
+    const hours = Math.round(minutes / 60);
+    if (minutes < HOURS_ONLY_UNTIL_MINUTES)
+        return { hours };
+    return { days: Math.floor(hours / 24), hours: hours % 24 };
+}
+export function formatDuration(ms, locale) {
+    const parts = Object.fromEntries(Object.entries(durationParts(ms)).filter(([, value]) => value));
+    const style = SHORT_DURATION_LANGUAGES.test(locale) ? 'short' : 'narrow';
+    return new Intl.DurationFormat(locale, { style }).format(parts);
+}
+function formatDate(date, locale) {
+    return new Intl.DateTimeFormat(locale, { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit', hour12: false }).format(date);
+}
+// A window whose model scope the source marks inactive: its numbers are not an entitlement.
+const isPassive = (window) => window.active === false && Boolean(window.scope);
+function windowLabel(window, t) {
+    const base = window.labelKey ? t(window.labelKey, window.labelParams) : (window.label ?? window.id);
+    return window.group === 'team' ? `${t('labelTeam')} · ${base}` : base;
+}
+function windowValue(window, t, locale) {
+    if (isPassive(window)) {
+        const used = clampPercent(window.usedPercent);
+        return used === null ? t('passiveSource') : t('percentUsed', { n: formatPercent(used, locale) });
+    }
+    if (window.valueKey)
+        return t(window.valueKey);
+    if (window.amounts) {
+        const { remaining } = window.amounts;
+        return isNumber(remaining) ? t('amountLeft', { n: formatMoney(remaining, locale) }) : t('amountNotReported');
+    }
+    const remaining = clampPercent(window.remainingPercent);
+    return remaining === null ? t('noData') : t('percentRemaining', { n: formatPercent(remaining, locale) });
+}
+function amountsDetail(amounts, t, locale) {
+    return AMOUNT_FIELDS.flatMap(field => {
+        const cents = amounts[field];
+        return isNumber(cents) ? [t(AMOUNT_KEYS[field], { n: formatMoney(cents, locale) })] : [];
+    }).join(' · ');
+}
+function windowDetail(window, t, locale) {
+    if (window.amounts)
+        return amountsDetail(window.amounts, t, locale);
+    if (window.detailKey)
+        return t(window.detailKey);
+    return isPassive(window) ? t('passiveSourceDetail') : '';
+}
+export function describeWindow(window, { t, locale, now = Date.now() }) {
+    const resetDate = window.resetsAt ? new Date(window.resetsAt) : null;
+    const resetMs = resetDate?.getTime();
+    const hasReset = resetDate !== null && isNumber(resetMs);
+    const reset = hasReset ? (resetMs - now <= 0 ? t('resetsNow') : t('resetsIn', { time: formatDuration(resetMs - now, locale) })) : '';
+    return {
+        label: windowLabel(window, t),
+        value: windowValue(window, t, locale),
+        percent: isPassive(window) || window.amounts || window.valueKey ? null : clampPercent(window.remainingPercent),
+        detail: windowDetail(window, t, locale),
+        reset,
+        resetAt: hasReset ? t('resetsAt', { date: formatDate(resetDate, locale) }) : ''
+    };
+}
+const FALLBACK_ACCOUNT_NAME = 'defaultAccount';
+export const formatAccountName = (account, t) => account.label ?? account.signedInAs ?? t(account.labelKey ?? FALLBACK_ACCOUNT_NAME);
+// Whether the account has a name of its own, rather than the fallback every account shares.
+export const hasOwnName = (account) => account.label !== undefined || account.signedInAs !== undefined || (account.labelKey ?? FALLBACK_ACCOUNT_NAME) !== FALLBACK_ACCOUNT_NAME;
+// What is said once a tool started, by how it started.
+export const LAUNCH_MESSAGES = { app: 'handoverApp', terminal: 'handoverTerminal' };
+// A tool, with the model it was started with when one was chosen.
+export const toolLabel = (providerId, model) => model ? `${providerById(providerId).name} · ${model}` : providerById(providerId).name;
+// What a suggestion's button says, in the window and in its notification.
+export const SUGGESTION_BUTTONS = {
+    low: 'suggestionContinueBtn',
+    return: 'suggestionReturnBtn',
+    reopen: 'suggestionReopenBtn'
+};
+// Who continues the work: another account of the same tool by its name, another tool by its.
+export function successorName(from, to, accounts, t) {
+    const account = accounts.find(a => a.id === to.accountId);
+    return to.providerId === from && account ? formatAccountName(account, t) : providerById(to.providerId).name;
+}
+export function formatAge(timestamp, { t, locale, now = Date.now() }) {
+    const ms = now - timestamp;
+    return ms < DURATION_MS.MINUTE ? t('justNow') : t('agoTime', { time: formatDuration(ms, locale) });
+}
+export function formatFreshness(iso, status, context) {
+    const { t } = context;
+    if (!iso)
+        return t('notMeasuredYet');
+    const fetchedAt = Date.parse(iso);
+    if (!Number.isFinite(fetchedAt))
+        return t('measurementTimeUnknown');
+    const age = formatAge(fetchedAt, context);
+    return status === 'stale' ? t('staleAge', { age }) : age;
+}
+// Message for an error or status code: app errors, then provider status codes, then a generic
+// line for internal codes that have no user-facing wording. Codes arrive as plain strings
+// from other processes, so they are checked against the catalogue at run time.
+export function describeCode(code, t, params) {
+    const error = `error_${code}`;
+    const status = `status_${code}`;
+    if (hasKey(error))
+        return t(error, params);
+    if (hasKey(status))
+        return t(status, params);
+    return t('error_unexpected');
+}

package/build/shared/i18n/index.d.ts

@@ -0,0 +1,12 @@
+import type { MessageKey, Messages } from './messages.ts';
+export type { MessageKey } from './messages.ts';
+export declare const SUPPORTED_LANGUAGES: readonly ["en", "tr", "de", "es", "fr", "it", "pt", "nl", "pl", "ja", "ko", "zh", "ru"];
+export type Language = (typeof SUPPORTED_LANGUAGES)[number];
+export declare const DEFAULT_LANGUAGE: Language;
+export declare const LOCALES: Readonly<Record<Language, Messages>>;
+export type Params = Readonly<Record<string, string | number>>;
+export type Translate = (key: MessageKey, params?: Params) => string;
+export declare function isLanguage(value: unknown): value is Language;
+export declare function hasKey(key: string): key is MessageKey;
+export declare function translate(language: string, key: MessageKey, params?: Params): string;
+export declare const translator: (language: string) => Translate;

package/build/shared/i18n/index.js

@@ -0,0 +1,40 @@
+import { de } from "./locales/de.js";
+import { en } from "./locales/en.js";
+import { es } from "./locales/es.js";
+import { fr } from "./locales/fr.js";
+import { it } from "./locales/it.js";
+import { ja } from "./locales/ja.js";
+import { ko } from "./locales/ko.js";
+import { nl } from "./locales/nl.js";
+import { pl } from "./locales/pl.js";
+import { pt } from "./locales/pt.js";
+import { ru } from "./locales/ru.js";
+import { tr } from "./locales/tr.js";
+import { zh } from "./locales/zh.js";
+export const SUPPORTED_LANGUAGES = ['en', 'tr', 'de', 'es', 'fr', 'it', 'pt', 'nl', 'pl', 'ja', 'ko', 'zh', 'ru'];
+export const DEFAULT_LANGUAGE = 'en';
+export const LOCALES = { en, tr, de, es, fr, it, pt, nl, pl, ja, ko, zh, ru };
+const PLURAL_SUFFIX = '_other';
+const PLURAL_FAMILIES = new Set(Object.keys(en)
+    .filter(key => key.endsWith(PLURAL_SUFFIX))
+    .map(key => key.slice(0, -PLURAL_SUFFIX.length)));
+const isPluralKey = (key) => PLURAL_FAMILIES.has(key);
+export function isLanguage(value) {
+    return typeof value === 'string' && Object.hasOwn(LOCALES, value);
+}
+// Key names computed at run time (`error_<code>`) are checked before lookup.
+export function hasKey(key) {
+    return Object.hasOwn(en, key) || isPluralKey(key);
+}
+// A plural key resolves by `params.n`; without a number it uses the `_other` form.
+function pluralText(language, key, n) {
+    const table = LOCALES[language];
+    const category = typeof n === 'number' ? new Intl.PluralRules(language).select(n) : 'other';
+    return (category === 'other' ? undefined : table[`${key}_${category}`]) ?? table[`${key}_other`];
+}
+export function translate(language, key, params = {}) {
+    const resolved = isLanguage(language) ? language : DEFAULT_LANGUAGE;
+    const text = isPluralKey(key) ? pluralText(resolved, key, params.n) : LOCALES[resolved][key];
+    return Object.entries(params).reduce((result, [name, value]) => result.replaceAll(`{${name}}`, String(value)), text);
+}
+export const translator = (language) => (key, params) => translate(language, key, params);

package/build/shared/i18n/locales/de.d.ts

@@ -0,0 +1,2 @@
+import type { Messages } from '../messages.ts';
+export declare const de: Messages;