@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/dist/insights-usage.js

@@ -0,0 +1,608 @@
+import {
+  ModelProcessingGeography
+} from "./chunk-A3LXWVYU.js";
+import {
+  boolean,
+  dateTime,
+  nonEmptyString,
+  nonnegativeInteger,
+  nullableString,
+  optionalBoolean,
+  string,
+  uuid
+} from "./chunk-AQYDZUJV.js";
+import {
+  defineSchema
+} from "./chunk-56SNIMDO.js";
+
+// src/insights-usage.ts
+import { z } from "zod";
+var SafeCount = /* @__PURE__ */ defineSchema(
+  () => nonnegativeInteger.max(Number.MAX_SAFE_INTEGER)
+);
+var UtcDateTime = /* @__PURE__ */ defineSchema(() => dateTime);
+var Identifier = /* @__PURE__ */ defineSchema(() => uuid);
+var OpaqueKey = /* @__PURE__ */ defineSchema(() => nonEmptyString);
+var InsightsUsageRange = /* @__PURE__ */ defineSchema(
+  () => z.enum(["today", "week", "month", "30d", "90d", "ytd", "custom"])
+);
+var InsightsSiteUsageQuery = /* @__PURE__ */ defineSchema(
+  () => z.object({ range: z.enum(["today", "week", "month", "30d", "90d", "ytd"]).default("month") }).strict()
+);
+var InsightsSiteUsageRow = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    siteId: Identifier.nullable(),
+    title: string,
+    kind: z.enum(["site", "restricted", "other"]),
+    calls: SafeCount,
+    pricedCalls: SafeCount,
+    /** Settled negative model-usage ledger entries, not a provider price. */
+    chargedMicros: SafeCount,
+    /** Recorded API-equivalent estimates across all payment paths. */
+    apiEquivalentMicros: SafeCount,
+    subscriptionApiEquivalentMicros: SafeCount,
+    ownKeyApiEquivalentMicros: SafeCount
+  }).strict()
+);
+var InsightsSiteUsageResponse = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    workspaceId: Identifier,
+    range: InsightsSiteUsageQuery.shape.range,
+    windowStart: UtcDateTime,
+    windowEnd: UtcDateTime,
+    rows: z.array(InsightsSiteUsageRow).max(201)
+  }).strict()
+);
+var InsightsUsageGroupBy = /* @__PURE__ */ defineSchema(
+  () => z.enum([
+    "model",
+    "provider",
+    "payer",
+    "plan",
+    "workspace",
+    "project",
+    "session",
+    "rootSession",
+    "person",
+    "schedule",
+    "source"
+  ])
+);
+var InsightsUsageSource = /* @__PURE__ */ defineSchema(
+  () => z.enum(["web", "api", "slack", "schedule", "agent", "other"])
+);
+var UtcDay = /* @__PURE__ */ defineSchema(
+  () => string.regex(/^\d{4}-\d{2}-\d{2}$/).refine((value) => {
+    const instant = Date.parse(`${value}T00:00:00Z`);
+    return !value.startsWith("0000-") && Number.isFinite(instant) && new Date(instant).toISOString().slice(0, 10) === value;
+  }, "Expected a real UTC calendar date in years 0001 through 9999 (YYYY-MM-DD)")
+);
+var CustomUtcDateTime = /* @__PURE__ */ defineSchema(
+  () => UtcDateTime.refine(
+    (value) => !value.startsWith("0000-"),
+    "Custom UTC boundaries must use years 0001 through 9999"
+  )
+);
+var DAY_MS = 864e5;
+var CUSTOM_MAX_DAYS = 370;
+function customWindow(from, to) {
+  if (!UtcDay.safeParse(from).success || !UtcDay.safeParse(to).success) return void 0;
+  const start = Date.parse(`${from}T00:00:00Z`);
+  const end = Date.parse(`${to}T00:00:00Z`) + DAY_MS;
+  if (start >= end || end - start > CUSTOM_MAX_DAYS * DAY_MS) return void 0;
+  const priorStart = start - (end - start);
+  const windows = {
+    windowStart: new Date(start).toISOString(),
+    windowEnd: new Date(end).toISOString(),
+    priorWindowStart: new Date(priorStart).toISOString(),
+    priorWindowEnd: new Date(start).toISOString()
+  };
+  if (!Object.values(windows).every((value) => CustomUtcDateTime.safeParse(value).success))
+    return void 0;
+  return { ...windows, bucket: end - start <= 2 * DAY_MS ? "hour" : "day" };
+}
+var CustomDates = /* @__PURE__ */ defineSchema(
+  () => z.object({ from: UtcDay, to: UtcDay }).strict().refine(
+    (value) => customWindow(value.from, value.to) !== void 0,
+    "Custom days must be ordered, span at most 370 days and have representable current/prior windows"
+  )
+);
+function resolveInsightsUsageCustomWindow(dates) {
+  const parsed = CustomDates.parse(dates);
+  return customWindow(parsed.from, parsed.to);
+}
+function validateWindowQuery(value, context) {
+  if (value.range === "custom") {
+    if (value.from === void 0 || value.to === void 0) {
+      context.addIssue({
+        code: "custom",
+        path: [value.from === void 0 ? "from" : "to"],
+        message: "Custom range requires both from and to"
+      });
+    } else if (customWindow(value.from, value.to) === void 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["to"],
+        message: "Custom days must be ordered, span at most 370 days and have representable current/prior windows"
+      });
+    }
+  } else if (value.from !== void 0 || value.to !== void 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["range"],
+      message: "from/to are only valid with range=custom"
+    });
+  }
+}
+var InsightsUsagePayer = /* @__PURE__ */ defineSchema(
+  () => z.union([z.literal("opengeni_credits"), z.literal("subscription"), z.literal("own_key")])
+);
+var InsightsUsageModelKey = /* @__PURE__ */ defineSchema(
+  () => string.regex(/^[^/\s]+\/\S+$/)
+);
+function repeated(item) {
+  return z.union([string, z.array(string).min(1)]).transform((value, context) => {
+    const entries = (Array.isArray(value) ? value : [value]).flatMap(
+      (part) => part.split(",").map((entry) => entry.trim())
+    );
+    const parsed = z.array(item).min(1).safeParse(entries);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        context.addIssue({ code: "custom", path: issue.path, message: issue.message });
+      }
+      return z.NEVER;
+    }
+    return parsed.data;
+  }).optional();
+}
+function queryLimit(max) {
+  return z.union([z.number(), string.regex(/^\d+$/).transform(Number)]).pipe(SafeCount.min(1).max(max)).default(50);
+}
+var QueryBoolean = /* @__PURE__ */ defineSchema(
+  () => z.union([boolean, z.enum(["true", "false"])]).transform((value) => value === true || value === "true")
+);
+var Filters = {
+  range: InsightsUsageRange.default("week"),
+  from: UtcDay.optional(),
+  to: UtcDay.optional(),
+  /** At workspace scope this intersects the path workspace; it never expands scope. */
+  workspaceId: repeated(Identifier),
+  provider: repeated(OpaqueKey),
+  model: repeated(InsightsUsageModelKey),
+  payer: repeated(InsightsUsagePayer),
+  /** Recorded opaque plan key; missing historical snapshots use unknown, not today's plan. */
+  plan: repeated(OpaqueKey),
+  source: repeated(InsightsUsageSource),
+  projectId: repeated(z.union([Identifier, z.literal("unfiled")])),
+  /** Authorized owner/member facet key, not a hidden causal initiator. */
+  person: repeated(OpaqueKey),
+  /** Leaf session and root chat selectors are deliberately separate. */
+  sessionId: repeated(Identifier),
+  rootSessionId: repeated(Identifier),
+  scheduleId: repeated(Identifier)
+};
+var WorkspaceInsightsUsageQuery = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    ...Filters,
+    groupBy: InsightsUsageGroupBy.default("model"),
+    seriesGroups: QueryBoolean.optional(),
+    limit: queryLimit(200)
+  }).strict().superRefine(validateWindowQuery)
+);
+var OrganizationInsightsUsageQuery = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    ...Filters,
+    groupBy: InsightsUsageGroupBy.default("model"),
+    seriesGroups: QueryBoolean.optional(),
+    limit: queryLimit(200)
+  }).strict().superRefine(validateWindowQuery)
+);
+var InsightsUsageQuery = OrganizationInsightsUsageQuery;
+var WorkspaceInsightsCallsQuery = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    ...Filters,
+    cursor: OpaqueKey.optional(),
+    limit: queryLimit(100)
+  }).strict().superRefine(validateWindowQuery)
+);
+var OrganizationInsightsCallsQuery = WorkspaceInsightsCallsQuery;
+var InsightsCallsQuery = OrganizationInsightsCallsQuery;
+var InsightsUsageTokens = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    uncachedInput: SafeCount,
+    cacheRead: SafeCount,
+    cacheWrite: SafeCount,
+    output: SafeCount,
+    reasoning: SafeCount
+  }).strict()
+);
+var InsightsUsageClassMicros = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    uncachedInput: SafeCount,
+    cacheRead: SafeCount,
+    cacheWrite: SafeCount,
+    output: SafeCount
+  }).strict()
+);
+var PayerMeasures = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    calls: SafeCount,
+    chargedMicros: SafeCount,
+    listMicros: SafeCount
+  }).strict()
+);
+function classTotal(value) {
+  return BigInt(value.uncachedInput) + BigInt(value.cacheRead) + BigInt(value.cacheWrite) + BigInt(value.output);
+}
+var InsightsUsageMeasures = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    calls: SafeCount,
+    tokenKnownCalls: SafeCount,
+    cacheKnownCalls: SafeCount,
+    cacheWriteKnownCalls: SafeCount,
+    /** Priced calls covered by exact snapshots OR flagged recorded-total allocations. */
+    listClassKnownCalls: SafeCount,
+    tokens: InsightsUsageTokens,
+    /** Actual debit ledger, not a model price that may exceed a clipped debit. */
+    chargedMicros: SafeCount,
+    listMicros: SafeCount,
+    listByClassMicros: InsightsUsageClassMicros.nullable(),
+    /** True when any covered class values allocate a historical recorded total. */
+    listByClassApprox: boolean,
+    pricedCalls: SafeCount,
+    byPayer: z.object({
+      opengeni_credits: PayerMeasures,
+      subscription: PayerMeasures,
+      own_key: PayerMeasures
+    }).strict()
+  }).strict().superRefine((value, context) => {
+    for (const field of [
+      "tokenKnownCalls",
+      "cacheKnownCalls",
+      "cacheWriteKnownCalls",
+      "pricedCalls"
+    ]) {
+      if (value[field] > value.calls) {
+        context.addIssue({
+          code: "custom",
+          path: [field],
+          message: "Known calls cannot exceed calls"
+        });
+      }
+    }
+    if (value.listClassKnownCalls > value.pricedCalls) {
+      context.addIssue({
+        code: "custom",
+        path: ["listClassKnownCalls"],
+        message: "Class coverage cannot exceed priced calls"
+      });
+    }
+    if (value.listByClassMicros !== null) {
+      const coveredTotal = classTotal(value.listByClassMicros);
+      if (coveredTotal > BigInt(value.listMicros) || value.listClassKnownCalls === value.pricedCalls && coveredTotal !== BigInt(value.listMicros)) {
+        context.addIssue({
+          code: "custom",
+          path: ["listByClassMicros"],
+          message: "Covered classes cannot exceed the recorded total; complete coverage must preserve it exactly"
+        });
+      }
+    }
+    for (const field of ["calls", "chargedMicros", "listMicros"]) {
+      const total = Object.values(value.byPayer).reduce(
+        (sum, payer) => sum + BigInt(payer[field]),
+        0n
+      );
+      if (total !== BigInt(value[field])) {
+        context.addIssue({
+          code: "custom",
+          path: ["byPayer"],
+          message: `Payer ${field} must sum to the total`
+        });
+      }
+    }
+  })
+);
+var InsightsUsageScope = /* @__PURE__ */ defineSchema(
+  () => z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("workspace"), accountId: Identifier, workspaceId: Identifier }).strict(),
+    z.object({ kind: z.literal("organization"), accountId: Identifier, workspaceId: z.null() }).strict()
+  ])
+);
+var InsightsUsageGroup = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    /** Private/personal keys remain kind-scoped; named source keys are the source value. */
+    key: OpaqueKey,
+    kind: z.enum([
+      "item",
+      "other",
+      "deleted",
+      "private",
+      "personal",
+      "unfiled",
+      "service",
+      "restricted"
+    ]),
+    label: string,
+    provider: OpaqueKey.optional(),
+    model: OpaqueKey.optional(),
+    workspaceId: Identifier.optional(),
+    /** Only an already-authorized people facet key; permits person-only amount selection. */
+    personKey: OpaqueKey.optional(),
+    you: optionalBoolean,
+    measures: InsightsUsageMeasures
+  }).strict()
+);
+var SeriesGroup = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    chargedMicros: SafeCount,
+    listMicros: SafeCount,
+    tokens: InsightsUsageTokens,
+    calls: SafeCount,
+    byPayer: InsightsUsageMeasures.shape.byPayer
+  }).strict().superRefine((value, context) => {
+    for (const field of ["calls", "chargedMicros", "listMicros"]) {
+      const total = Object.values(value.byPayer).reduce(
+        (sum, payer) => sum + BigInt(payer[field]),
+        0n
+      );
+      if (total !== BigInt(value[field])) {
+        context.addIssue({
+          code: "custom",
+          path: ["byPayer"],
+          message: `Payer ${field} must sum to the total`
+        });
+      }
+    }
+  })
+);
+var InsightsUsageSeriesPoint = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    start: UtcDateTime,
+    measures: InsightsUsageMeasures,
+    /** Top six active groups plus remainder; source uses other:folded to avoid other collisions. */
+    groups: z.record(string, SeriesGroup).refine(
+      (value) => Object.keys(value).length <= 7 && Object.keys(value).filter((key) => key !== "other" && key !== "other:folded").length <= 6,
+      {
+        message: "Series may include at most six groups plus other"
+      }
+    ).optional()
+  }).strict()
+);
+var InsightsUsageFacets = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    workspaces: z.array(
+      z.object({ id: Identifier, name: string, personal: boolean }).strict()
+    ),
+    providers: z.array(OpaqueKey),
+    models: z.array(z.object({ provider: OpaqueKey, model: OpaqueKey }).strict()),
+    payers: z.array(OpaqueKey),
+    /** Recorded opaque plan keys, with unknown for absent snapshots. */
+    plans: z.array(OpaqueKey).default([]),
+    /** Capability marker: omit until source/custom support is actually implemented. */
+    sources: z.array(InsightsUsageSource).optional(),
+    projects: z.array(z.object({ id: Identifier, name: string }).strict()),
+    people: z.array(
+      z.object({ key: OpaqueKey, name: nullableString, you: boolean }).strict()
+    ),
+    schedules: z.array(z.object({ id: Identifier, name: string }).strict())
+  }).strict()
+);
+var InsightsUsageResponse = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    scope: InsightsUsageScope,
+    range: InsightsUsageRange,
+    windowStart: UtcDateTime,
+    windowEnd: UtcDateTime,
+    priorWindowStart: UtcDateTime,
+    priorWindowEnd: UtcDateTime,
+    bucket: z.enum(["hour", "day"]),
+    generatedAt: UtcDateTime,
+    dataThrough: UtcDateTime.nullable(),
+    totals: InsightsUsageMeasures,
+    /** Null for truly empty prior windows; ledger-only money survives missing call facts. */
+    prior: InsightsUsageMeasures.nullable(),
+    groupBy: InsightsUsageGroupBy,
+    groups: z.array(InsightsUsageGroup),
+    groupCount: SafeCount,
+    groupsTruncated: boolean,
+    series: z.array(InsightsUsageSeriesPoint),
+    facets: InsightsUsageFacets
+  }).strict().superRefine((value, context) => {
+    const windowStart = Date.parse(value.windowStart);
+    const windowEnd = Date.parse(value.windowEnd);
+    const priorWindowStart = Date.parse(value.priorWindowStart);
+    const priorWindowEnd = Date.parse(value.priorWindowEnd);
+    if (windowStart > windowEnd) {
+      context.addIssue({
+        code: "custom",
+        path: ["windowEnd"],
+        message: "Window end must not precede start"
+      });
+    }
+    if (priorWindowStart > priorWindowEnd) {
+      context.addIssue({
+        code: "custom",
+        path: ["priorWindowEnd"],
+        message: "Prior window end must not precede start"
+      });
+    }
+    if (windowStart === windowEnd) {
+      if (value.totals.calls !== 0 || value.totals.chargedMicros !== 0 || value.totals.listMicros !== 0 || Object.values(value.totals.tokens).some((tokens) => tokens !== 0)) {
+        context.addIssue({
+          code: "custom",
+          path: ["totals"],
+          message: "Zero-length windows must have empty measures"
+        });
+      }
+      if (value.groups.length !== 0 || value.groupCount !== 0 || value.groupsTruncated) {
+        context.addIssue({
+          code: "custom",
+          path: ["groups"],
+          message: "Zero-length windows must have no groups"
+        });
+      }
+      if (value.series.length !== 0) {
+        context.addIssue({
+          code: "custom",
+          path: ["series"],
+          message: "Zero-length windows must have no series points"
+        });
+      }
+    }
+    if (priorWindowStart === priorWindowEnd && value.prior !== null) {
+      context.addIssue({
+        code: "custom",
+        path: ["prior"],
+        message: "Zero-length prior windows must have null measures"
+      });
+    }
+    const expectedBucket = value.range === "custom" ? windowEnd - windowStart <= 2 * DAY_MS ? "hour" : "day" : value.range === "today" ? "hour" : "day";
+    if (value.bucket !== expectedBucket) {
+      context.addIssue({
+        code: "custom",
+        path: ["bucket"],
+        message: "Bucket is automatic for the range"
+      });
+    }
+    if (value.prior?.calls === 0 && value.prior.chargedMicros === 0 && value.prior.listMicros === 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["prior"],
+        message: "Prior without recorded calls or money must be null"
+      });
+    }
+    if (value.range === "custom") {
+      for (const field of [
+        "windowStart",
+        "windowEnd",
+        "priorWindowStart",
+        "priorWindowEnd"
+      ]) {
+        if (!CustomUtcDateTime.safeParse(value[field]).success) {
+          context.addIssue({
+            code: "custom",
+            path: [field],
+            message: "Custom UTC boundaries must use years 0001 through 9999"
+          });
+        }
+      }
+      if (windowStart === windowEnd || windowEnd - windowStart > CUSTOM_MAX_DAYS * DAY_MS || windowStart % DAY_MS !== 0 || windowEnd % DAY_MS !== 0 || priorWindowStart !== windowStart - (windowEnd - windowStart) || priorWindowEnd !== windowStart) {
+        context.addIssue({
+          code: "custom",
+          path: ["windowEnd"],
+          message: "Custom windows must span at most 370 complete UTC days with an immediate equal-duration prior"
+        });
+      }
+    }
+    if (value.groupBy === "source") {
+      for (const [index, group] of value.groups.entries()) {
+        if (group.kind === "item" && !InsightsUsageSource.safeParse(group.key).success) {
+          context.addIssue({
+            code: "custom",
+            path: ["groups", index, "key"],
+            message: "Named source keys must equal their source value"
+          });
+        }
+        if (group.kind === "other" && group.key !== "other:folded") {
+          context.addIssue({
+            code: "custom",
+            path: ["groups", index, "key"],
+            message: "Source remainder must use other:folded, distinct from the other source"
+          });
+        }
+      }
+      for (const [index, point] of value.series.entries()) {
+        if (point.groups && Object.keys(point.groups).filter((key) => key !== "other:folded").length > 6) {
+          context.addIssue({
+            code: "custom",
+            path: ["series", index, "groups"],
+            message: "Source series permits six named groups plus other:folded"
+          });
+        }
+      }
+    }
+    const peopleKeys = new Set(value.facets.people.map((person) => person.key));
+    for (const [index, group] of value.groups.entries()) {
+      if (group.personKey !== void 0 && !peopleKeys.has(group.personKey)) {
+        context.addIssue({
+          code: "custom",
+          path: ["groups", index, "personKey"],
+          message: "Person amount keys must come from the authorized people facets"
+        });
+      }
+    }
+  })
+);
+var InsightsCall = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    id: Identifier,
+    occurredAt: UtcDateTime,
+    workspaceId: Identifier,
+    sessionId: Identifier.nullable(),
+    sessionTitle: nullableString,
+    sessionKind: z.enum(["visible", "private", "deleted"]),
+    personKey: OpaqueKey.nullable(),
+    provider: OpaqueKey,
+    model: OpaqueKey,
+    payer: InsightsUsagePayer,
+    tokens: InsightsUsageTokens.nullable(),
+    chargedMicros: SafeCount,
+    listMicros: SafeCount.nullable(),
+    listByClassMicros: InsightsUsageClassMicros.nullable(),
+    /**
+     * Where the route that served the call processed it. Null for calls
+     * recorded before calls carried a processing residency; unknown is never EU.
+     * Undefined in responses from servers older than this release.
+     */
+    processingGeography: ModelProcessingGeography.nullable()
+  }).strict().superRefine((value, context) => {
+    if (value.sessionKind === "private" && (value.sessionId !== null || value.sessionTitle !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["sessionKind"],
+        message: "Private calls expose no session id or title"
+      });
+    }
+    if (value.listByClassMicros !== null && (value.listMicros === null || classTotal(value.listByClassMicros) !== BigInt(value.listMicros))) {
+      context.addIssue({
+        code: "custom",
+        path: ["listByClassMicros"],
+        message: "Call list classes must sum to its recorded listMicros"
+      });
+    }
+  })
+);
+var InsightsCallsResponse = /* @__PURE__ */ defineSchema(
+  () => z.object({
+    calls: z.array(InsightsCall).max(100),
+    nextCursor: OpaqueKey.nullable()
+  }).strict()
+);
+export {
+  InsightsCall,
+  InsightsCallsQuery,
+  InsightsCallsResponse,
+  InsightsSiteUsageQuery,
+  InsightsSiteUsageResponse,
+  InsightsSiteUsageRow,
+  InsightsUsageClassMicros,
+  InsightsUsageFacets,
+  InsightsUsageGroup,
+  InsightsUsageGroupBy,
+  InsightsUsageMeasures,
+  InsightsUsageModelKey,
+  InsightsUsagePayer,
+  InsightsUsageQuery,
+  InsightsUsageRange,
+  InsightsUsageResponse,
+  InsightsUsageScope,
+  InsightsUsageSeriesPoint,
+  InsightsUsageSource,
+  InsightsUsageTokens,
+  OrganizationInsightsCallsQuery,
+  OrganizationInsightsUsageQuery,
+  WorkspaceInsightsCallsQuery,
+  WorkspaceInsightsUsageQuery,
+  resolveInsightsUsageCustomWindow
+};
+//# sourceMappingURL=insights-usage.js.map