@carlonicora/nestjs-neo4jsonapi 1.116.0 → 1.118.0

package/dist/foundations/tokenusage/repositories/tokenusage.admin.repository.d.ts

@@ -0,0 +1,73 @@
+import { ClsService } from "nestjs-cls";
+import { AbstractRepository } from "../../../core/neo4j/abstracts/abstract.repository";
+import { Neo4jService } from "../../../core/neo4j/services/neo4j.service";
+import { SecurityService } from "../../../core/security/services/security.service";
+import { TokenUsageAdminBreakdownEntity } from "../entities/tokenusage-admin-breakdown";
+import { TokenUsageAdminSummaryEntity } from "../entities/tokenusage-admin-summary";
+import { TokenUsageAdminTimelineEntity } from "../entities/tokenusage-admin-timeline";
+import { TokenUsage, TokenUsageDescriptor } from "../entities/tokenusage";
+/**
+ * Cross-tenant reporting queries behind /tokenusages/administration/*.
+ *
+ * Extends AbstractRepository for the shared Neo4j/security/CLS plumbing and the
+ * descriptor typing; none of the inherited finders are used, for the reasons in
+ * the file header, and it deliberately does NOT override onModuleInit — the
+ * :TokenUsage indexes belong to TokenUsageRepository.
+ *
+ * EVERY traversal constrains its target label — `->(:Company)`, `->(:User)`.
+ * The write bug fixed in tokenusage.repository.ts left 12,237 label-less nodes
+ * on exactly these two relationships; an unconstrained match returns them.
+ */
+export declare class TokenUsageAdminRepository extends AbstractRepository<TokenUsage, typeof TokenUsageDescriptor.relationships> {
+    protected readonly descriptor: import("../../..").EntityDescriptor<TokenUsage, {}>;
+    constructor(neo4j: Neo4jService, securityService: SecurityService, clsService: ClsService);
+    /**
+     * Six rows: {customer, platform, total} × {current, previous}. The previous
+     * window is the equal-length span immediately preceding `from`, which is what
+     * the KPI tiles' deltas are computed against.
+     */
+    findSummary(params: {
+        from: string;
+        to: string;
+        companyId?: string;
+    }): Promise<TokenUsageAdminSummaryEntity[]>;
+    findTimeline(params: {
+        from: string;
+        to: string;
+        granularity: "day" | "week" | "month";
+        stackBy: "scope" | "type" | "company";
+        companyId?: string;
+    }): Promise<TokenUsageAdminTimelineEntity[]>;
+    /**
+     * Ranked rows, descending by cost, truncated to `limit` with the exact
+     * remainder folded into a single "other" row. The full ordered set is fetched
+     * and sliced in JS so the remainder is exact rather than a second query's
+     * approximation. Above ~1000 companies, move the LIMIT into Cypher and take
+     * the remainder from findSummary() instead.
+     */
+    findBreakdown(params: {
+        from: string;
+        to: string;
+        dimension: "company" | "user" | "operation";
+        scope: "customer" | "platform";
+        companyId?: string;
+        limit: number;
+    }): Promise<TokenUsageAdminBreakdownEntity[]>;
+    /** Scalar rollup split by cost centre for one window. */
+    private _scopeTotals;
+    /**
+     * Guarantees both cost centres are present (zero-filled when a window has no
+     * rows) and appends their sum as the "total" scope, so the tiles never have to
+     * branch on a missing row.
+     */
+    private _withTotal;
+    /** The equal-length span immediately preceding `from`. */
+    private _previousWindow;
+    /**
+     * Resolves a granularity to the `date.truncate` unit it may emit. Throws
+     * rather than interpolating anything the table does not know about.
+     */
+    private _truncationUnit;
+    private _metrics;
+}
+//# sourceMappingURL=tokenusage.admin.repository.d.ts.map

package/dist/foundations/tokenusage/repositories/tokenusage.admin.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenusage.admin.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/tokenusage/repositories/tokenusage.admin.repository.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,8BAA8B,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,EAEL,6BAA6B,EAC9B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAuC1E;;;;;;;;;;;GAWG;AACH,qBACa,yBAA0B,SAAQ,kBAAkB,CAC/D,UAAU,EACV,OAAO,oBAAoB,CAAC,aAAa,CAC1C;IACC,SAAS,CAAC,QAAQ,CAAC,UAAU,sDAAwB;gBAEzC,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU;IAIzF;;;;OAIG;IACG,WAAW,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,4BAA4B,EAAE,CAAC;IAW9G,YAAY,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;QACtC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;QACtC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,6BAA6B,EAAE,CAAC;IA+D5C;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;QAC5C,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;QAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,8BAA8B,EAAE,CAAC;IAqH7C,yDAAyD;YAC3C,YAAY;IAkC1B;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA8BlB,0DAA0D;IAC1D,OAAO,CAAC,eAAe;IAOvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,QAAQ;CAUjB"}

package/dist/foundations/tokenusage/repositories/tokenusage.admin.repository.js

@@ -0,0 +1,342 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenUsageAdminRepository = void 0;
+// nja-lint-ignore-file: cross-tenant administrative read repository.
+//
+// Every query here deliberately omits buildDefaultMatch(): that helper scopes to
+// the CALLER's company via CLS, which is exactly wrong for a platform-wide admin
+// dashboard. Access is gated instead by the controller's JwtAuthGuard +
+// @Roles(Administrator) (see tokenusage.admin.controller.ts). Rollup RETURNs are
+// scalar columns, not graph nodes, so readOne()/readMany() cannot map them —
+// entityFactory.createGraphList expects nodes. Same shape and same rationale as
+// apps/api/src/features/administration/platform-kpi/repositories/platform-kpi.read.repository.ts.
+//
+// The architecture gate raises a FILE-LEVEL manual-query-no-company-scope finding
+// on this shape; per-line ignores do not clear it, so this header note is the
+// documented resolution.
+const common_1 = require("@nestjs/common");
+const nestjs_cls_1 = require("nestjs-cls");
+const define_entity_1 = require("../../../common/helpers/define-entity");
+const abstract_repository_1 = require("../../../core/neo4j/abstracts/abstract.repository");
+const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
+const security_service_1 = require("../../../core/security/services/security.service");
+const tokenusage_admin_timeline_1 = require("../entities/tokenusage-admin-timeline");
+const tokenusage_1 = require("../entities/tokenusage");
+const tokenusage_meta_1 = require("../entities/tokenusage.meta");
+const NODE = tokenusage_meta_1.tokenUsageMeta.nodeName; // "tokenusage"
+/**
+ * The `date.truncate` units this repository is allowed to emit, keyed by the
+ * granularity it accepts. A lookup rather than a raw interpolation of the
+ * caller's string: nothing that did not come from this table can ever reach the
+ * query text.
+ */
+const TRUNCATION_UNITS = {
+    week: "week",
+    month: "month",
+};
+const toNumber = (v) => {
+    if (v === null || v === undefined)
+        return 0;
+    if (typeof v === "number")
+        return v;
+    if (typeof v.toNumber === "function")
+        return v.toNumber();
+    return Number(v) || 0;
+};
+const round = (v, dp) => {
+    const f = 10 ** dp;
+    return Math.round(v * f) / f;
+};
+/**
+ * Cross-tenant reporting queries behind /tokenusages/administration/*.
+ *
+ * Extends AbstractRepository for the shared Neo4j/security/CLS plumbing and the
+ * descriptor typing; none of the inherited finders are used, for the reasons in
+ * the file header, and it deliberately does NOT override onModuleInit — the
+ * :TokenUsage indexes belong to TokenUsageRepository.
+ *
+ * EVERY traversal constrains its target label — `->(:Company)`, `->(:User)`.
+ * The write bug fixed in tokenusage.repository.ts left 12,237 label-less nodes
+ * on exactly these two relationships; an unconstrained match returns them.
+ */
+let TokenUsageAdminRepository = class TokenUsageAdminRepository extends abstract_repository_1.AbstractRepository {
+    constructor(neo4j, securityService, clsService) {
+        super(neo4j, securityService, clsService);
+        this.descriptor = tokenusage_1.TokenUsageDescriptor;
+    }
+    /**
+     * Six rows: {customer, platform, total} × {current, previous}. The previous
+     * window is the equal-length span immediately preceding `from`, which is what
+     * the KPI tiles' deltas are computed against.
+     */
+    async findSummary(params) {
+        const previous = this._previousWindow(params.from, params.to);
+        const [current, prior] = await Promise.all([
+            this._scopeTotals({ from: params.from, to: params.to, companyId: params.companyId }),
+            this._scopeTotals({ from: previous.from, to: previous.to, companyId: params.companyId }),
+        ]);
+        return [...this._withTotal(current, "current"), ...this._withTotal(prior, "previous")];
+    }
+    async findTimeline(params) {
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            from: params.from,
+            to: params.to,
+            companyId: params.companyId ?? null,
+            // Cypher accepts a parameter for date.truncate's unit (verified against
+            // DozerDB 5.26), so the granularity is bound rather than interpolated —
+            // the "always parameterised, never interpolated" guardrail applies here
+            // even though _truncationUnit() already whitelists the value.
+            granularity: params.granularity === "day" ? null : this._truncationUnit(params.granularity),
+        };
+        const bucket = params.granularity === "day" ? `date(${NODE}.createdAt)` : `date.truncate($granularity, ${NODE}.createdAt)`;
+        const series = params.stackBy === "type"
+            ? `${NODE}.tokenUsageType`
+            : params.stackBy === "company"
+                ? `coalesce(c.name, 'platform')`
+                : `CASE WHEN c IS NULL THEN 'platform' ELSE 'customer' END`;
+        query.query += `
+      MATCH (${NODE}:${tokenusage_meta_1.tokenUsageMeta.labelName})
+      WHERE ${NODE}.createdAt >= datetime($from) AND ${NODE}.createdAt <= datetime($to)
+      OPTIONAL MATCH (${NODE})-[:BELONGS_TO]->(c:Company)
+      WITH ${NODE}, c
+      WHERE $companyId IS NULL OR c.id = $companyId
+      WITH ${bucket} AS bucket, ${series} AS series, ${NODE}
+      RETURN bucket                                  AS bucket,
+             series                                  AS series,
+             sum(toFloat(${NODE}.cost))              AS cost,
+             sum(toFloat(${NODE}.credits))           AS credits,
+             sum(toInteger(${NODE}.inputTokens))     AS tokensIn,
+             sum(toInteger(${NODE}.outputTokens))    AS tokensOut,
+             sum(toInteger(${NODE}.cachedInputTokens)) AS cached,
+             count(${NODE})                          AS calls
+      ORDER BY bucket ASC, series ASC
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        // The driver hands back a native Neo4j Date. convertFieldValue is the
+        // framework's single implementation of the descriptor-typed read-path
+        // conversion — the same one the auto-generated mapper() uses. Never
+        // toString() it in Cypher, never re-format it here. The field type is read
+        // off the descriptor so the two can never drift.
+        const bucketType = tokenusage_admin_timeline_1.TokenUsageAdminTimelineDescriptor.fields.bucket?.type ?? "date";
+        return result.records.map((r) => {
+            const bucketValue = (0, define_entity_1.convertFieldValue)(r.get("bucket"), bucketType);
+            const seriesValue = r.get("series");
+            return {
+                id: `${bucketValue}|${seriesValue}`,
+                bucket: bucketValue,
+                series: seriesValue,
+                ...this._metrics(r),
+            };
+        });
+    }
+    /**
+     * Ranked rows, descending by cost, truncated to `limit` with the exact
+     * remainder folded into a single "other" row. The full ordered set is fetched
+     * and sliced in JS so the remainder is exact rather than a second query's
+     * approximation. Above ~1000 companies, move the LIMIT into Cypher and take
+     * the remainder from findSummary() instead.
+     */
+    async findBreakdown(params) {
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            from: params.from,
+            to: params.to,
+            companyId: params.companyId ?? null,
+        };
+        const companyMatch = params.scope === "customer"
+            ? `MATCH (${NODE})-[:BELONGS_TO]->(c:Company)`
+            : `OPTIONAL MATCH (${NODE})-[:BELONGS_TO]->(c:Company)\n      WITH ${NODE}, c\n      WHERE c IS NULL`;
+        // activeUsers is only meaningful for the company dimension; the optional
+        // match is emitted only there so the other dimensions do not pay for it.
+        const activeUserMatch = params.dimension === "company" ? `OPTIONAL MATCH (${NODE})-[:TRIGGERED_BY]->(u:User)` : "";
+        let grouping;
+        let projection;
+        if (params.dimension === "company") {
+            // `u` is carried through the WITH: dropping it here would leave
+            // count(DISTINCT u) referencing an out-of-scope variable.
+            grouping = `WITH ${NODE}, c AS grp, u`;
+            projection = `
+             grp.id                          AS id,
+             grp.name                        AS label,
+             null                            AS sublabel,
+             count(DISTINCT u)               AS activeUsers,
+             head(collect(grp.monthlyCredits))          AS monthlyCredits,
+             head(collect(grp.availableMonthlyCredits)) AS availableMonthlyCredits,`;
+        }
+        else if (params.dimension === "user") {
+            grouping = `MATCH (${NODE})-[:TRIGGERED_BY]->(u:User)\n      WITH ${NODE}, c, u AS grp`;
+            projection = `
+             grp.id                          AS id,
+             coalesce(grp.name, grp.email)   AS label,
+             head(collect(c.name))           AS sublabel,
+             null                            AS activeUsers,
+             null                            AS monthlyCredits,
+             null                            AS availableMonthlyCredits,`;
+        }
+        else {
+            grouping = `WITH ${NODE}, c, ${NODE}.tokenUsageType AS grp`;
+            projection = `
+             grp                             AS id,
+             grp                             AS label,
+             null                            AS sublabel,
+             null                            AS activeUsers,
+             null                            AS monthlyCredits,
+             null                            AS availableMonthlyCredits,`;
+        }
+        query.query += `
+      MATCH (${NODE}:${tokenusage_meta_1.tokenUsageMeta.labelName})
+      WHERE ${NODE}.createdAt >= datetime($from) AND ${NODE}.createdAt <= datetime($to)
+      ${companyMatch}
+      WITH ${NODE}, c
+      WHERE $companyId IS NULL OR c.id = $companyId
+      ${activeUserMatch}
+      ${grouping}
+      RETURN ${projection}
+             sum(toFloat(${NODE}.cost))              AS cost,
+             sum(toFloat(${NODE}.credits))           AS credits,
+             sum(toInteger(${NODE}.inputTokens))     AS tokensIn,
+             sum(toInteger(${NODE}.outputTokens))    AS tokensOut,
+             sum(toInteger(${NODE}.cachedInputTokens)) AS cached,
+             count(${NODE})                          AS calls
+      ORDER BY cost DESC
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        const all = result.records.map((r) => {
+            const sublabel = r.get("sublabel");
+            const activeUsers = r.get("activeUsers");
+            const monthlyCredits = r.get("monthlyCredits");
+            const availableMonthlyCredits = r.get("availableMonthlyCredits");
+            return {
+                id: r.get("id"),
+                label: r.get("label") ?? r.get("id"),
+                ...(sublabel ? { sublabel: sublabel } : {}),
+                ...(activeUsers === null || activeUsers === undefined ? {} : { activeUsers: toNumber(activeUsers) }),
+                ...(monthlyCredits === null || monthlyCredits === undefined
+                    ? {}
+                    : { monthlyCredits: toNumber(monthlyCredits) }),
+                ...(availableMonthlyCredits === null || availableMonthlyCredits === undefined
+                    ? {}
+                    : { availableMonthlyCredits: toNumber(availableMonthlyCredits) }),
+                ...this._metrics(r),
+            };
+        });
+        if (all.length <= params.limit)
+            return all;
+        const top = all.slice(0, params.limit);
+        const tail = all.slice(params.limit);
+        const other = {
+            id: "other",
+            label: "other",
+            cost: round(tail.reduce((s, r) => s + r.cost, 0), 4),
+            credits: round(tail.reduce((s, r) => s + r.credits, 0), 2),
+            tokensIn: tail.reduce((s, r) => s + r.tokensIn, 0),
+            tokensOut: tail.reduce((s, r) => s + r.tokensOut, 0),
+            cached: tail.reduce((s, r) => s + r.cached, 0),
+            calls: tail.reduce((s, r) => s + r.calls, 0),
+        };
+        return [...top, other];
+    }
+    /** Scalar rollup split by cost centre for one window. */
+    async _scopeTotals(params) {
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            from: params.from,
+            to: params.to,
+            companyId: params.companyId ?? null,
+        };
+        query.query += `
+      MATCH (${NODE}:${tokenusage_meta_1.tokenUsageMeta.labelName})
+      WHERE ${NODE}.createdAt >= datetime($from) AND ${NODE}.createdAt <= datetime($to)
+      OPTIONAL MATCH (${NODE})-[:BELONGS_TO]->(c:Company)
+      WITH ${NODE}, c
+      WHERE $companyId IS NULL OR c.id = $companyId
+      WITH CASE WHEN c IS NULL THEN 'platform' ELSE 'customer' END AS scope, ${NODE}
+      RETURN scope                                   AS scope,
+             sum(toFloat(${NODE}.cost))              AS cost,
+             sum(toFloat(${NODE}.credits))           AS credits,
+             sum(toInteger(${NODE}.inputTokens))     AS tokensIn,
+             sum(toInteger(${NODE}.outputTokens))    AS tokensOut,
+             sum(toInteger(${NODE}.cachedInputTokens)) AS cached,
+             count(${NODE})                          AS calls
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        return result.records.map((r) => ({ scope: r.get("scope"), ...this._metrics(r) }));
+    }
+    /**
+     * Guarantees both cost centres are present (zero-filled when a window has no
+     * rows) and appends their sum as the "total" scope, so the tiles never have to
+     * branch on a missing row.
+     */
+    _withTotal(rows, window) {
+        const zero = { cost: 0, credits: 0, tokensIn: 0, tokensOut: 0, cached: 0, calls: 0 };
+        const find = (scope) => rows.find((r) => r.scope === scope) ?? { scope, ...zero };
+        const customer = find("customer");
+        const platform = find("platform");
+        const total = {
+            scope: "total",
+            cost: round(customer.cost + platform.cost, 4),
+            credits: round(customer.credits + platform.credits, 2),
+            tokensIn: customer.tokensIn + platform.tokensIn,
+            tokensOut: customer.tokensOut + platform.tokensOut,
+            cached: customer.cached + platform.cached,
+            calls: customer.calls + platform.calls,
+        };
+        return [customer, platform, total].map((r) => ({
+            id: `${r.scope}|${window}`,
+            scope: r.scope,
+            window,
+            cost: r.cost,
+            credits: r.credits,
+            tokensIn: r.tokensIn,
+            tokensOut: r.tokensOut,
+            cached: r.cached,
+            calls: r.calls,
+        }));
+    }
+    /** The equal-length span immediately preceding `from`. */
+    _previousWindow(from, to) {
+        const fromMs = new Date(from).getTime();
+        const toMs = new Date(to).getTime();
+        const span = Math.max(0, toMs - fromMs);
+        return { from: new Date(fromMs - span).toISOString(), to: new Date(fromMs).toISOString() };
+    }
+    /**
+     * Resolves a granularity to the `date.truncate` unit it may emit. Throws
+     * rather than interpolating anything the table does not know about.
+     */
+    _truncationUnit(granularity) {
+        const unit = TRUNCATION_UNITS[granularity];
+        if (!unit)
+            throw new Error(`Unsupported timeline granularity: ${granularity}`);
+        return unit;
+    }
+    _metrics(record) {
+        return {
+            cost: round(toNumber(record.get("cost")), 4),
+            credits: round(toNumber(record.get("credits")), 2),
+            tokensIn: toNumber(record.get("tokensIn")),
+            tokensOut: toNumber(record.get("tokensOut")),
+            cached: toNumber(record.get("cached")),
+            calls: toNumber(record.get("calls")),
+        };
+    }
+};
+exports.TokenUsageAdminRepository = TokenUsageAdminRepository;
+exports.TokenUsageAdminRepository = TokenUsageAdminRepository = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [neo4j_service_1.Neo4jService, security_service_1.SecurityService, nestjs_cls_1.ClsService])
+], TokenUsageAdminRepository);
+//# sourceMappingURL=tokenusage.admin.repository.js.map

package/dist/foundations/tokenusage/repositories/tokenusage.admin.repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenusage.admin.repository.js","sourceRoot":"","sources":["../../../../src/foundations/tokenusage/repositories/tokenusage.admin.repository.ts"],"names":[],"mappings":"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"}

package/dist/foundations/tokenusage/repositories/tokenusage.repository.d.ts

@@ -1,8 +1,36 @@
 import { ClsService } from "nestjs-cls";
+import { JsonApiCursorInterface } from "../../../core/jsonapi/interfaces/jsonapi.cursor.interface";
 import { AbstractRepository } from "../../../core/neo4j/abstracts/abstract.repository";
 import { Neo4jService } from "../../../core/neo4j/services/neo4j.service";
 import { SecurityService } from "../../../core/security/services/security.service";
 import { TokenUsage, TokenUsageDescriptor } from "../../tokenusage/entities/tokenusage";
+/**
+ * A single row of the date + operation-type usage aggregation.
+ *
+ * Not an entity shape: the aggregation returns grouped scalars, so it
+ * deliberately bypasses the serialiser (`readMany`) — there is nothing to map
+ * onto `TokenUsage`.
+ */
+export interface TokenUsageAggregated {
+    date: string;
+    tokenUsageType: string;
+    totalCredits: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCost: number;
+    count: number;
+}
+/**
+ * The single-row totals of the usage summary. Same non-entity rationale as
+ * `TokenUsageAggregated`.
+ */
+export interface TokenUsageSummary {
+    totalCredits: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCost: number;
+    count: number;
+}
 /**
  * TokenUsage repository.
  *
@@ -13,15 +41,33 @@ import { TokenUsage, TokenUsageDescriptor } from "../../tokenusage/entities/toke
  * never by a registry lookup: Nest constructs providers long before
  * `onModuleInit`, where models are registered.
  *
- * `onModuleInit` is INHERITED rather than declared: `AbstractRepository.onModuleInit`
- * emits `CREATE CONSTRAINT tokenusage_id IF NOT EXISTS FOR (tokenusage:TokenUsage)
+ * `onModuleInit` DELEGATES to `AbstractRepository.onModuleInit` first, which emits
+ * `CREATE CONSTRAINT tokenusage_id IF NOT EXISTS FOR (tokenusage:TokenUsage)
  * REQUIRE tokenusage.id IS UNIQUE` from `descriptor.constraints` — byte-identical to
  * the constraint this repository used to declare by hand — plus the FULLTEXT index
- * derived from the descriptor's string fields.
+ * derived from the descriptor's string fields. It then adds the one index the
+ * descriptor cannot express; see the override below.
  */
 export declare class TokenUsageRepository extends AbstractRepository<TokenUsage, typeof TokenUsageDescriptor.relationships> {
     protected readonly descriptor: import("../../..").EntityDescriptor<TokenUsage, {}>;
     constructor(neo4j: Neo4jService, securityService: SecurityService, clsService: ClsService);
+    /**
+     * Adds the range index every date-filtered finder here depends on —
+     * findByCompany, findAggregatedByDateAndType, findUsageSummary, and the
+     * cross-tenant admin queries in TokenUsageAdminRepository. Without it each of
+     * them scans the whole :TokenUsage label, which is the fastest-growing label
+     * in the database.
+     *
+     * There is no declarative way to express a non-FULLTEXT index via
+     * defineEntity(): EntityDescriptor.indexes is hard-coded to the string-field
+     * fulltext index, and AbstractRepository.onModuleInit only acts on
+     * type === "FULLTEXT". Hence the explicit override — same pattern, and same
+     * stated reason, as UserActivityRepository.
+     *
+     * super.onModuleInit() MUST be called first: it creates the descriptor-derived
+     * id constraint and fulltext index. Dropping it would silently remove both.
+     */
+    onModuleInit(): Promise<void>;
     /**
      * Custom create (KEPT — "non-standard relationships" rule): USED_FOR's target is
      * polymorphic (any entity label — Content, Chunk, Conversation, ...), which the
@@ -39,8 +85,37 @@ export declare class TokenUsageRepository extends AbstractRepository<TokenUsage,
         outputTokens: number;
         cachedInputTokens?: number;
         cost?: number;
+        credits?: number;
         relationshipId: string;
         relationshipType: string;
     }): Promise<void>;
+    /**
+     * Custom list (KEPT — date-range + tokenUsageType filtering is not expressible via the
+     * inherited descriptor-driven find()). Reuses buildDefaultMatch()/buildReturnStatement()
+     * for company scoping and security consistency.
+     */
+    findByCompany(params: {
+        startDate?: string;
+        endDate?: string;
+        tokenUsageType?: string;
+        cursor?: JsonApiCursorInterface;
+    }): Promise<TokenUsage[]>;
+    /**
+     * Aggregation query (KEPT — "aggregations" rule): returns grouped totals, not
+     * TokenUsage entities, so it intentionally bypasses readMany()/the serialiser — there
+     * is nothing to map onto the entity type.
+     */
+    findAggregatedByDateAndType(params: {
+        startDate?: string;
+        endDate?: string;
+    }): Promise<TokenUsageAggregated[]>;
+    /**
+     * Aggregation query (KEPT — see findAggregatedByDateAndType above), single-row totals.
+     */
+    findUsageSummary(params: {
+        startDate?: string;
+        endDate?: string;
+    }): Promise<TokenUsageSummary>;
+    private toNumber;
 }
 //# sourceMappingURL=tokenusage.repository.d.ts.map

package/dist/foundations/tokenusage/repositories/tokenusage.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokenusage.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/tokenusage/repositories/tokenusage.repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAGxF;;;;;;;;;;;;;;;GAeG;AACH,qBACa,oBAAqB,SAAQ,kBAAkB,CAAC,UAAU,EAAE,OAAO,oBAAoB,CAAC,aAAa,CAAC;IACjH,SAAS,CAAC,QAAQ,CAAC,UAAU,sDAAwB;gBAEzC,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU;IAIzF;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,IAAI,CAAC;CAkClB"}
+{"version":3,"file":"tokenusage.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/tokenusage/repositories/tokenusage.repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,2DAA2D,CAAC;AACnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAGxF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,oBAAqB,SAAQ,kBAAkB,CAAC,UAAU,EAAE,OAAO,oBAAoB,CAAC,aAAa,CAAC;IACjH,SAAS,CAAC,QAAQ,CAAC,UAAU,sDAAwB;gBAEzC,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU;IAIzF;;;;;;;;;;;;;;;OAeG;IACY,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5C;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,EAAE;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjB;;;;OAIG;IACG,aAAa,CAAC,MAAM,EAAE;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,sBAAsB,CAAC;KACjC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA6BzB;;;;OAIG;IACG,2BAA2B,CAAC,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IA2CpH;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4CpG,OAAO,CAAC,QAAQ;CAMjB"}