@carlonicora/nextjs-jsonapi 1.141.3 → 1.143.0

package/dist/features/tokenusage/index.d.ts

@@ -0,0 +1,388 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { A as ApiDataInterface, J as JsonApiHydratedDataInterface } from '../../ApiDataInterface-BcZeXy5X.js';
+import { A as AbstractApiData } from '../../tokenusage-admin.module-5wJ_tZTj.js';
+export { b as TokenUsageAdminBreakdownModule, T as TokenUsageAdminSummaryModule, a as TokenUsageAdminTimelineModule } from '../../tokenusage-admin.module-5wJ_tZTj.js';
+import { A as AbstractService } from '../../AbstractService-Cew0PD0L.js';
+import '../../ApiRequestDataTypeInterface-CYEcRUrh.js';
+import '../../types-bsm8Fp55.js';
+import 'lucide-react';
+
+interface TokenUsageAdminBreakdownInterface extends ApiDataInterface {
+    get label(): string;
+    get sublabel(): string | undefined;
+    get cost(): number;
+    get credits(): number;
+    get tokensIn(): number;
+    get tokensOut(): number;
+    get cached(): number;
+    get calls(): number;
+    /** Company dimension only. */
+    get activeUsers(): number | undefined;
+    /** Company dimension only. */
+    get monthlyCredits(): number | undefined;
+    /** Company dimension only. */
+    get availableMonthlyCredits(): number | undefined;
+}
+
+interface TokenUsageAdminSummaryInterface extends ApiDataInterface {
+    /** "customer" | "platform" | "total" */
+    get scope(): string;
+    /** "current" | "previous" */
+    get window(): string;
+    get cost(): number;
+    get credits(): number;
+    get tokensIn(): number;
+    get tokensOut(): number;
+    get cached(): number;
+    get calls(): number;
+}
+
+interface TokenUsageAdminTimelineInterface extends ApiDataInterface {
+    /** Backend declares this `type: "date"`, so it is a Date in memory. */
+    get bucket(): Date;
+    get series(): string;
+    get cost(): number;
+    get credits(): number;
+    get tokensIn(): number;
+    get tokensOut(): number;
+    get cached(): number;
+    get calls(): number;
+}
+
+type Granularity = "day" | "week" | "month";
+type StackBy = "scope" | "type" | "company";
+type Dimension = "company" | "user" | "operation";
+type Scope = "customer" | "platform";
+type Metric = "cost" | "credits" | "tokens";
+type TokenUsageAdminFilters = {
+    /** ISO 8601 instant. */
+    from: string;
+    /** ISO 8601 instant. */
+    to: string;
+    companyId?: string;
+};
+type TokenUsageAdminSummaryInput = {
+    id: string;
+    scope: string;
+    window: string;
+    cost: number;
+    credits: number;
+    tokensIn: number;
+    tokensOut: number;
+    cached: number;
+    calls: number;
+};
+type TokenUsageAdminTimelineInput = {
+    id: string;
+    /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+    bucket: Date;
+    series: string;
+    cost: number;
+    credits: number;
+    tokensIn: number;
+    tokensOut: number;
+    cached: number;
+    calls: number;
+};
+type TokenUsageAdminBreakdownInput = {
+    id: string;
+    label: string;
+    sublabel?: string;
+    cost: number;
+    credits: number;
+    tokensIn: number;
+    tokensOut: number;
+    cached: number;
+    calls: number;
+    activeUsers?: number;
+    monthlyCredits?: number;
+    availableMonthlyCredits?: number;
+};
+
+type TokenUsageAdminFilterState = {
+    /** ISO 8601 instant. */
+    from: string;
+    /** ISO 8601 instant. */
+    to: string;
+    granularity: Granularity;
+    stackBy: StackBy;
+    companyId?: string;
+    metric: Metric;
+};
+interface TokenUsageAdminContextType {
+    summary: TokenUsageAdminSummaryInterface[];
+    timeline: TokenUsageAdminTimelineInterface[];
+    byCompany: TokenUsageAdminBreakdownInterface[];
+    byUser: TokenUsageAdminBreakdownInterface[];
+    /** Platform-side spend split by operation. Always empty in single-customer mode. */
+    /** Platform spend by operation — empty in single-customer mode. */
+    byOperation: TokenUsageAdminBreakdownInterface[];
+    /** Customer spend by operation — the customer-side mirror of byOperation. */
+    byCustomerOperation: TokenUsageAdminBreakdownInterface[];
+    companies: {
+        id: string;
+        label: string;
+    }[];
+    filters: TokenUsageAdminFilterState;
+    /** Merges a partial patch into the current filters; every key is optional. */
+    setFilters: (next: Partial<TokenUsageAdminFilterState>) => void;
+    /** `true` once a company filter is applied — the platform panels are meaningless then. */
+    singleCustomerMode: boolean;
+    isLoading: boolean;
+    error: string | null;
+}
+type TokenUsageAdminProviderProps = {
+    children: ReactNode;
+    /** Pre-select a company, which puts the page in single-customer mode from the first render. */
+    initialCompanyId?: string;
+    /** ISO 8601 instant. Defaults to the start of the current month. */
+    initialFrom?: string;
+    /** ISO 8601 instant. Defaults to now. */
+    initialTo?: string;
+    /** Rows per ranked panel. Defaults to 10. */
+    topN?: number;
+};
+/**
+ * Owns every filter the administrative token-usage page reads, fetches the five
+ * panels behind it, and publishes the filter bar into the page title bar.
+ *
+ * The filter bar is rendered into `title.functions` here — NOT in the container —
+ * because `RoundPageContainer`'s title bar reads `title.functions` from
+ * `SharedContext`, and a descendant cannot inject nodes into an ancestor's
+ * provider value. That is why the filter state lives at this level.
+ */
+declare const TokenUsageAdminProvider: ({ children, initialCompanyId, initialFrom, initialTo, topN, }: TokenUsageAdminProviderProps) => React.JSX.Element;
+declare const useTokenUsageAdmin: () => TokenUsageAdminContextType;
+
+/**
+ * Page body for the administrative token-usage dashboard.
+ *
+ * Stateless by design — every value it renders comes from
+ * `useTokenUsageAdmin()`. The filter bar is deliberately NOT here: it belongs to
+ * the page title bar, which `RoundPageContainer` fills from `SharedContext`, so
+ * the provider publishes it (see TokenUsageAdminContext).
+ */
+declare function TokenUsageAdminContainer(): React.JSX.Element;
+
+type FilterState = {
+    from: string;
+    to: string;
+    granularity: Granularity;
+    companyId?: string;
+    metric: Metric;
+};
+type Props$3 = FilterState & {
+    companies: {
+        id: string;
+        label: string;
+    }[];
+    /** Receives ONLY the keys that changed. */
+    onChange: (next: Partial<FilterState>) => void;
+};
+/**
+ * The single control row above the KPI tiles.
+ *
+ * It is deliberately stateless: every control reports the one key it changed and
+ * the owning context re-fetches. Keeping the whole filter state in one place is
+ * what lets the page issue a single coordinated batch of requests instead of one
+ * per control.
+ */
+declare function TokenUsageAdminFilterBar({ granularity, companyId, metric, companies, onChange }: Props$3): React.JSX.Element;
+
+type Props$2 = {
+    /** The six summary rows: {customer, platform, total} × {current, previous}. */
+    summary: TokenUsageAdminSummaryInterface[];
+    metric: Metric;
+    /** True when a company filter is applied — platform spend is then meaningless. */
+    singleCustomerMode: boolean;
+};
+/**
+ * The KPI header of the administrative token-usage page.
+ *
+ * Two lead tiles carry the cost centres — customer spend and platform spend —
+ * each with its delta against the equal-length preceding window. Three
+ * supporting tiles below carry the totals that give those two numbers context.
+ *
+ * The backend always returns both windows, which is why no tile has to branch on
+ * a missing row: an absent scope is simply zero-filled here.
+ */
+declare function TokenUsageAdminTiles({ summary, metric, singleCustomerMode }: Props$2): React.JSX.Element;
+
+type Props$1 = {
+    /** Ranked rows, already ordered descending by the backend, "other" last. */
+    rows: TokenUsageAdminBreakdownInterface[];
+    metric: Metric;
+    /** Italian copy shown when there is nothing to rank. */
+    emptyLabel: string;
+    /**
+     * Whether `row.label` is an operation TYPE (vocabulary the consuming app
+     * translates) rather than an entity NAME (data, rendered verbatim).
+     *
+     * Company and user rows carry names — translating them would be nonsense — so
+     * this defaults to false and only the platform-by-operation panel opts in.
+     */
+    labelsAreOperationTypes?: boolean;
+};
+/**
+ * A ranked horizontal bar list — "who spent the most".
+ *
+ * This does a MAGNITUDE job, not a categorical one, so colour comes from a
+ * single sequential ramp indexed by RANK POSITION, never from a categorical
+ * palette keyed by entity. That is deliberate: a filter change reorders the
+ * rows, and rank-indexed colour simply re-shades them instead of repainting a
+ * company into another company's identity hue.
+ *
+ * There is exactly one series, so there is no legend: every bar is
+ * direct-labelled with its value and its share of the total.
+ */
+declare function TokenUsageRankedBar({ rows, metric, emptyLabel, labelsAreOperationTypes }: Props$1): React.JSX.Element;
+
+type Props = {
+    rows: TokenUsageAdminBreakdownInterface[];
+    metric: Metric;
+};
+/**
+ * The numeric detail behind the ranked bars: every row, every metric column.
+ *
+ * The bars answer "who is biggest"; this answers "why". Sorting is client-side
+ * because the whole ranked set — top-N plus the "other" rollup — is already in
+ * memory, so a round trip would buy nothing.
+ */
+declare function TokenUsageBreakdownTable({ rows, metric }: Props): React.JSX.Element;
+
+type TokenUsageTimelineChartProps = {
+    rows: TokenUsageAdminTimelineInterface[];
+    metric: Metric;
+    stackBy: StackBy;
+    className?: string;
+};
+/**
+ * Usage over time as a stacked bar chart.
+ *
+ * Colour does an IDENTITY job here — each stacked segment is a series, not a
+ * magnitude — so it draws the fixed categorical order from `../lib/palette` and
+ * never generates or cycles a hue: series past the ceiling are summed into a
+ * single "other" segment painted in the palette's neutral.
+ *
+ * The palette's light-mode validator run carries a sub-3:1 contrast WARN on
+ * three slots, which obliges a relief channel. That is why the legend and the
+ * value-carrying tooltip below are not optional decoration: they are what makes
+ * the low-contrast fills readable.
+ */
+declare function TokenUsageTimelineChart({ rows, metric, stackBy, className }: TokenUsageTimelineChartProps): React.JSX.Element;
+
+/**
+ * One row of the administrative summary: a cost centre observed over one time
+ * window. Six rows are returned per request — scope crossed with window — so the
+ * KPI tiles can render a value and its delta without a second call.
+ */
+declare class TokenUsageAdminSummary extends AbstractApiData implements TokenUsageAdminSummaryInterface {
+    private _scope;
+    private _window;
+    private _cost;
+    private _credits;
+    private _tokensIn;
+    private _tokensOut;
+    private _cached;
+    private _calls;
+    get scope(): string;
+    get window(): string;
+    get cost(): number;
+    get credits(): number;
+    get tokensIn(): number;
+    get tokensOut(): number;
+    get cached(): number;
+    get calls(): number;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: TokenUsageAdminSummaryInput): any;
+}
+
+/**
+ * One (bucket, series) cell of the usage-over-time chart. Rows arrive flat; the
+ * chart pivots them into stacked columns.
+ */
+declare class TokenUsageAdminTimeline extends AbstractApiData implements TokenUsageAdminTimelineInterface {
+    private _bucket;
+    private _series;
+    private _cost;
+    private _credits;
+    private _tokensIn;
+    private _tokensOut;
+    private _cached;
+    private _calls;
+    get bucket(): Date;
+    get series(): string;
+    get cost(): number;
+    get credits(): number;
+    get tokensIn(): number;
+    get tokensOut(): number;
+    get cached(): number;
+    get calls(): number;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: TokenUsageAdminTimelineInput): any;
+}
+
+/**
+ * One ranked row of a breakdown. The same shape serves all three dimensions —
+ * company, user and operation — which is why the three "by-X" views collapse
+ * into a single `breakdown?dimension=` call.
+ *
+ * `activeUsers` / `monthlyCredits` / `availableMonthlyCredits` are populated only
+ * for `dimension=company`; they are absent on user and operation rows.
+ */
+declare class TokenUsageAdminBreakdown extends AbstractApiData implements TokenUsageAdminBreakdownInterface {
+    private _label;
+    private _sublabel?;
+    private _cost;
+    private _credits;
+    private _tokensIn;
+    private _tokensOut;
+    private _cached;
+    private _calls;
+    private _activeUsers?;
+    private _monthlyCredits?;
+    private _availableMonthlyCredits?;
+    get label(): string;
+    get sublabel(): string | undefined;
+    get cost(): number;
+    get credits(): number;
+    get tokensIn(): number;
+    get tokensOut(): number;
+    get cached(): number;
+    get calls(): number;
+    get activeUsers(): number | undefined;
+    get monthlyCredits(): number | undefined;
+    get availableMonthlyCredits(): number | undefined;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: TokenUsageAdminBreakdownInput): any;
+}
+
+declare class TokenUsageAdminService extends AbstractService {
+    /** Six rows: {customer, platform, total} × {current, previous}. */
+    static getSummary(filters: TokenUsageAdminFilters): Promise<TokenUsageAdminSummaryInterface[]>;
+    static getTimeline(params: TokenUsageAdminFilters & {
+        granularity: Granularity;
+        stackBy: StackBy;
+    }): Promise<TokenUsageAdminTimelineInterface[]>;
+    static getBreakdown(params: TokenUsageAdminFilters & {
+        dimension: Dimension;
+        scope: Scope;
+        limit?: number;
+    }): Promise<TokenUsageAdminBreakdownInterface[]>;
+}
+
+/**
+ * The fixed namespace of i18n keys the administrative token-usage feature reads
+ * via useTranslations/getTranslations. Consuming apps must define each entry in
+ * their messages/<locale>.json — this list is the contract between the package
+ * and the app.
+ *
+ * One key is NOT listed because it is resolved from data rather than from a
+ * fixed string: the timeline chart labels each series through
+ * `token_usage.types.<camelCase>` and falls back to the raw series key when the
+ * app has no entry, so that namespace stays the app's own vocabulary.
+ */
+declare const TOKEN_USAGE_ADMIN_I18N_KEYS: readonly ["token_usage.admin.title", "token_usage.admin.customer_spend", "token_usage.admin.platform_spend", "token_usage.admin.total_cost", "token_usage.admin.avg_per_call", "token_usage.admin.cache_hit", "token_usage.admin.vs_previous", "token_usage.admin.usage_over_time", "token_usage.admin.by_company", "token_usage.admin.by_user", "token_usage.admin.customer_by_operation", "token_usage.admin.platform_by_operation", "token_usage.admin.detail", "token_usage.admin.other", "token_usage.admin.no_data", "token_usage.admin.all_companies", "token_usage.admin.granularity.label", "token_usage.admin.granularity.day", "token_usage.admin.granularity.week", "token_usage.admin.granularity.month", "token_usage.admin.metric.label", "token_usage.admin.metric.cost", "token_usage.admin.metric.credits", "token_usage.admin.metric.tokens", "token_usage.admin.stack_by", "token_usage.admin.stack.scope", "token_usage.admin.stack.type", "token_usage.admin.stack.company", "token_usage.admin.columns.label", "token_usage.admin.columns.sublabel", "token_usage.admin.columns.calls", "token_usage.admin.columns.tokens_in", "token_usage.admin.columns.tokens_out", "token_usage.admin.columns.cost", "token_usage.admin.columns.credits", "token_usage.admin.columns.share", "token_usage.admin.columns.active_users", "token_usage.series.other", "token_usage.timeline.empty"];
+
+export { type Dimension, type Granularity, type Metric, type Scope, type StackBy, TOKEN_USAGE_ADMIN_I18N_KEYS, TokenUsageAdminBreakdown, type TokenUsageAdminBreakdownInput, type TokenUsageAdminBreakdownInterface, TokenUsageAdminContainer, type TokenUsageAdminContextType, TokenUsageAdminFilterBar, type TokenUsageAdminFilterState, type TokenUsageAdminFilters, TokenUsageAdminProvider, TokenUsageAdminService, TokenUsageAdminSummary, type TokenUsageAdminSummaryInput, type TokenUsageAdminSummaryInterface, TokenUsageAdminTiles, TokenUsageAdminTimeline, type TokenUsageAdminTimelineInput, type TokenUsageAdminTimelineInterface, TokenUsageBreakdownTable, TokenUsageRankedBar, TokenUsageTimelineChart, useTokenUsageAdmin };