@cubos/agent-sdk 0.0.1152175 → 0.0.1153146

package/dist/admin/index.d.ts

@@ -7,10 +7,10 @@ import { channelsApi } from "./channels.js";
 import { clientToolsApi } from "./client-tools.js";
 import { componentLibrariesApi } from "./component-libraries.js";
 import { conversationsAdminApi } from "./conversations.js";
-import { costMetricsApi, instanceCostMetricsApi } from "./cost-metrics.js";
 import { apiKeysApi, pluginsApi, sharedProvidersApi, tenantsApi } from "./global.js";
 import { knowledgeBasesApi } from "./knowledge-bases.js";
 import { mcpsApi } from "./mcps.js";
+import { instanceMetricsApi, metricsApi } from "./metrics.js";
 import { skillsApi } from "./skills.js";
 import { backgroundTasksApi, scheduledRunsApi, taskTemplatesApi } from "./task-templates.js";
 import { userRolesApi, usersApi, userTokensApi } from "./users.js";
@@ -46,7 +46,7 @@ export interface TenantScope {
     backgroundTasks: ReturnType<typeof backgroundTasksApi>;
     conversations: ReturnType<typeof conversationsAdminApi>;
     clientTools: ReturnType<typeof clientToolsApi>;
-    costMetrics: ReturnType<typeof costMetricsApi>;
+    metrics: ReturnType<typeof metricsApi>;
 }
 export interface AdminClient {
     health(signal?: AbortSignal): Promise<Schemas["Health"]>;
@@ -55,7 +55,7 @@ export interface AdminClient {
     apiKeys: ReturnType<typeof apiKeysApi>;
     sharedProviders: ReturnType<typeof sharedProvidersApi>;
     plugins: ReturnType<typeof pluginsApi>;
-    costMetrics: ReturnType<typeof instanceCostMetricsApi>;
+    metrics: ReturnType<typeof instanceMetricsApi>;
     tenant(slug: string): TenantScope;
     /** Escape hatch for a route the SDK hasn't wrapped yet. Paths are absolute
      * (`/api/v1/…`) and auth is applied for you. */

package/dist/admin/metrics.d.ts

@@ -0,0 +1,172 @@
+import type { Transport } from "../http.js";
+import type { Schemas } from "../schemas.js";
+export type MetricId = Schemas["Metric"];
+export type Dimension = Schemas["Dimension"];
+export type Granularity = Schemas["Granularity"];
+export type MetricsInclude = Schemas["Include"];
+export type MetricsCatalog = Schemas["MetricsCatalog"];
+export type MetricInfo = Schemas["MetricInfo"];
+export type MetricsCompleteness = Schemas["Completeness"];
+/** A metric as asked for: its id, or `{ id }`. The object form is where a
+ * parameterised metric (a quantile, say) will take its parameters. */
+export type MetricSpec = MetricId | {
+    readonly id: MetricId;
+};
+/** The id a spec names. */
+export type MetricIdOf<S> = S extends MetricId ? S : S extends {
+    readonly id: infer I extends MetricId;
+} ? I : never;
+/** The values a dimension is restricted to. `none` also keeps the rows where
+ * the dimension has no value. A filter listing nothing is refused by the
+ * server — leave the dimension out to keep every value. */
+export interface MetricsFilter {
+    readonly in?: readonly string[];
+    readonly none?: boolean;
+}
+export type MetricsFilters<Dim extends Dimension = Dimension> = {
+    readonly [D in Dim]?: MetricsFilter;
+};
+export type MetricsOrderBy<M extends MetricId, D extends Dimension> = {
+    readonly metric: M;
+    readonly direction?: "asc" | "desc";
+} | {
+    readonly dimension: D;
+    readonly direction?: "asc" | "desc";
+};
+/**
+ * A metrics query. Every type parameter is inferred from the literal you
+ * pass, which is what types the result: the metrics you ask for are the keys
+ * of each row's `values`, the dimensions you group by are the keys of its
+ * `dimensions`, a granularity adds `bucket` (and `buckets`), and `include`
+ * adds `totals` and `labels`.
+ */
+export interface MetricsQuery<S extends readonly MetricSpec[] = readonly MetricSpec[], D extends readonly Dimension[] = readonly Dimension[], G extends Granularity | null = Granularity | null, I extends readonly MetricsInclude[] = readonly MetricsInclude[], Dim extends Dimension = Dimension> {
+    readonly metrics: S;
+    /** Inclusive; rounded down to the hour. Default: 30 days before `to`. */
+    readonly from?: Date | string;
+    /** Exclusive; rounded up to the hour. Default: the end of the current hour. */
+    readonly to?: Date | string;
+    /** IANA zone buckets are cut in. Default `UTC`. */
+    readonly timezone?: string;
+    /** Omit (or `null`) for one row per group over the whole interval — and,
+     * with no `groupBy` either, exactly one row. */
+    readonly granularity?: G;
+    readonly groupBy?: D;
+    readonly filters?: MetricsFilters<Dim>;
+    /** Within a bucket; rows always go bucket by bucket. Default: the first
+     * metric, descending. */
+    readonly orderBy?: readonly MetricsOrderBy<MetricIdOf<S[number]>, D[number]>[];
+    /** 1 to 10 000. Default 1 000. */
+    readonly limit?: number;
+    readonly cursor?: string | null;
+    readonly include?: I;
+}
+type Values<M extends MetricId> = {
+    readonly [K in M]: number;
+};
+type Dims<D extends Dimension> = {
+    readonly [K in D]: string | null;
+};
+/** `yes` when the literal certainly holds `K`, `no` when it certainly does
+ * not, `maybe` when the type is too wide to tell (an `Include[]` variable). */
+type Has<I extends readonly unknown[], K> = number extends I["length"] ? "maybe" : K extends I[number] ? "yes" : "no";
+type BucketField<G> = [G] extends [null] ? unknown : [G] extends [Granularity] ? {
+    readonly bucket: string;
+} : {
+    readonly bucket?: string;
+};
+export type MetricsRow<M extends MetricId = MetricId, D extends Dimension = Dimension, G extends Granularity | null = Granularity | null> = BucketField<G> & {
+    /** Every grouped dimension; `null` for the rows where it has no value. */
+    readonly dimensions: Dims<D>;
+    readonly values: Values<M>;
+};
+/** With neither `groupBy` nor `granularity`, the server answers exactly one
+ * row — so its type is a one-tuple and `rows[0]` needs no check. */
+type Rows<M extends MetricId, D extends readonly Dimension[], G> = D extends readonly [] ? [G] extends [null] ? readonly [MetricsRow<M, never, null>] : readonly MetricsRow<M, never, G & (Granularity | null)>[] : readonly MetricsRow<M, D[number], G & (Granularity | null)>[];
+/** A name for an id; which fields are set depends on the dimension. */
+export interface EntityLabel {
+    readonly slug?: string;
+    readonly display_name?: string | null;
+    /** A user's first channel identity (a phone, a handle). */
+    readonly primary_identifier?: string | null;
+    /** A provider's type (`openai`, `anthropic`, …). */
+    readonly provider_type?: string;
+}
+type LabeledDimension = "tenant" | "user" | "agent" | "provider";
+type Labels<D extends Dimension> = {
+    readonly [K in Extract<D, LabeledDimension>]?: Readonly<Record<string, EntityLabel>>;
+};
+type Optional<Present extends "yes" | "no" | "maybe", T> = Present extends "yes" ? T : Present extends "no" ? unknown : Partial<T>;
+export type MetricsResult<S extends readonly MetricSpec[] = readonly MetricSpec[], D extends readonly Dimension[] = readonly Dimension[], G extends Granularity | null = Granularity | null, I extends readonly MetricsInclude[] = readonly MetricsInclude[]> = {
+    /** The query as answered: defaults filled in, the interval rounded to whole
+     * hours. */
+    readonly query: Schemas["ResolvedQuery"];
+    readonly columns: readonly Schemas["Column"][];
+    readonly rows: Rows<MetricIdOf<S[number]>, D, G>;
+    /** Pass back as `cursor`, with the same query, for the next page. */
+    readonly next_cursor: string | null;
+    readonly completeness: MetricsCompleteness;
+} & ([G] extends [null] ? unknown : [G] extends [Granularity] ? {
+    readonly buckets: readonly string[];
+} : {
+    readonly buckets?: readonly string[];
+}) & Optional<Has<I, "totals">, {
+    readonly totals: {
+        readonly values: Values<MetricIdOf<S[number]>>;
+    };
+}> & Optional<Has<I, "labels">, {
+    readonly labels: Labels<D[number]>;
+}>;
+export interface DimensionValuesQuery<Dim extends Dimension = Dimension> {
+    /** Ranks the values, and is what `metric_value` holds. */
+    readonly metric: MetricId;
+    readonly from?: Date | string;
+    readonly to?: Date | string;
+    readonly timezone?: string;
+    /** The page's other filters; this dimension's own is ignored. */
+    readonly filters?: MetricsFilters<Dim>;
+    /** Keep values whose id or name contains this, case-insensitively. */
+    readonly search?: string;
+    readonly limit?: number;
+    readonly cursor?: string | null;
+}
+export interface DimensionValues {
+    readonly values: readonly {
+        /** `null` is the rows with no value — filter on it with `none`. */
+        readonly value: string | null;
+        readonly label?: EntityLabel;
+        readonly metric_value: number;
+    }[];
+    readonly next_cursor: string | null;
+}
+/** The whole instance's metrics. Root only. */
+export declare function instanceMetricsApi(t: Transport): {
+    /** The metrics this credential may read here: unit, aggregation,
+     * dimensions, finest granularity, completeness. */
+    catalog: (signal?: AbortSignal) => Promise<{
+        dimensions: import("../generated/schema.js").components["schemas"]["DimensionInfo"][];
+        metrics: import("../generated/schema.js").components["schemas"]["MetricInfo"][];
+    }>;
+    query: <const S extends readonly MetricSpec[], const D extends readonly ("agent" | "kind" | "model" | "provider" | "tenant" | "user")[] = [], G extends Granularity | null = null, const I extends readonly MetricsInclude[] = []>(q: MetricsQuery<S, D, G, I, "agent" | "kind" | "model" | "provider" | "tenant" | "user">, signal?: AbortSignal) => Promise<MetricsResult<S, D, G, I>>;
+    /** Every row of the query, following the cursor page by page. */
+    queryAll<const S extends readonly MetricSpec[], const D extends readonly ("agent" | "kind" | "model" | "provider" | "tenant" | "user")[] = [], G extends Granularity | null = null>(q: Omit<MetricsQuery<S, D, G, [], "agent" | "kind" | "model" | "provider" | "tenant" | "user">, "cursor" | "include">, signal?: AbortSignal): AsyncGenerator<Rows<MetricIdOf<S[number]>, D, G>[number], any, any>;
+    /** The values `dimension` takes in a slice, ranked by a metric — what a
+     * filter can offer given the page's other filters. */
+    dimensionValues: (dimension: "agent" | "kind" | "model" | "provider" | "tenant" | "user", q: DimensionValuesQuery<"agent" | "kind" | "model" | "provider" | "tenant" | "user">, signal?: AbortSignal) => Promise<DimensionValues>;
+};
+/** One tenant's metrics; there is no `tenant` dimension in this scope. */
+export declare function metricsApi(t: Transport, tenantSlug: string): {
+    /** The metrics this credential may read here: unit, aggregation,
+     * dimensions, finest granularity, completeness. */
+    catalog: (signal?: AbortSignal) => Promise<{
+        dimensions: import("../generated/schema.js").components["schemas"]["DimensionInfo"][];
+        metrics: import("../generated/schema.js").components["schemas"]["MetricInfo"][];
+    }>;
+    query: <const S extends readonly MetricSpec[], const D extends readonly ("agent" | "kind" | "model" | "provider" | "user")[] = [], G extends Granularity | null = null, const I extends readonly MetricsInclude[] = []>(q: MetricsQuery<S, D, G, I, "agent" | "kind" | "model" | "provider" | "user">, signal?: AbortSignal) => Promise<MetricsResult<S, D, G, I>>;
+    /** Every row of the query, following the cursor page by page. */
+    queryAll<const S extends readonly MetricSpec[], const D extends readonly ("agent" | "kind" | "model" | "provider" | "user")[] = [], G extends Granularity | null = null>(q: Omit<MetricsQuery<S, D, G, [], "agent" | "kind" | "model" | "provider" | "user">, "cursor" | "include">, signal?: AbortSignal): AsyncGenerator<Rows<MetricIdOf<S[number]>, D, G>[number], any, any>;
+    /** The values `dimension` takes in a slice, ranked by a metric — what a
+     * filter can offer given the page's other filters. */
+    dimensionValues: (dimension: "agent" | "kind" | "model" | "provider" | "user", q: DimensionValuesQuery<"agent" | "kind" | "model" | "provider" | "user">, signal?: AbortSignal) => Promise<DimensionValues>;
+};
+export {};