umami-compass 0.1.3 → 0.3.0

package/dist/mcp/insights-utils.d.ts

@@ -0,0 +1,206 @@
+import type { z } from "zod";
+import type { UmamiClient } from "../api/client.js";
+import type { Website } from "../api/types.js";
+import type { TimeInput } from "../time.js";
+import { type filtersSchema } from "./schemas.js";
+import { type TrafficChannel } from "./traffic-segmentation.js";
+export declare const TRAFFIC_DIMENSIONS: readonly ["path", "referrer", "country", "device", "channel", "event"];
+export type TrafficDimension = (typeof TRAFFIC_DIMENSIONS)[number];
+export interface TimePeriod {
+    endAt: number;
+    startAt: number;
+}
+export interface WebsiteTotals {
+    bounces: number;
+    pageviews: number;
+    totaltime: number;
+    visitors: number;
+    visits: number;
+}
+export interface WebsiteStats extends WebsiteTotals {
+    comparison?: WebsiteTotals;
+}
+type Filters = z.infer<typeof filtersSchema> | undefined;
+export declare function finiteNumber(value: unknown): number | undefined;
+export declare function parseWebsiteStats(value: unknown): WebsiteStats;
+export declare function percentChange(current: number, comparison: number): number | null;
+export declare function totalsChanges(current: WebsiteTotals, comparison: WebsiteTotals): {
+    [k: string]: {
+        absolute: number;
+        percent: number | null;
+    };
+};
+export declare function isoPeriod(period: TimePeriod): {
+    start: string;
+    end: string;
+};
+export declare function normalizePeriod(start: TimeInput, end: TimeInput, maxRangeDays: number): TimePeriod;
+export declare function comparisonPeriod(current: TimePeriod, mode: "previous" | "year_over_year"): TimePeriod;
+export declare function mapConcurrent<T, R>(values: readonly T[], concurrency: number, operation: (value: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function fetchWebsiteStats(client: UmamiClient, websiteId: string, period: TimePeriod, maxRangeDays: number, filters: Filters, signal?: AbortSignal, excludedReferrers?: readonly string[]): Promise<WebsiteStats>;
+export interface TrafficComparisonInput {
+    channel?: TrafficChannel;
+    comparison: TimePeriod;
+    current: TimePeriod;
+    dimensions: readonly TrafficDimension[];
+    excludedReferrers?: readonly string[];
+    filters?: Filters;
+    limit: number;
+    maxRangeDays: number;
+    signal?: AbortSignal;
+    website: Pick<Website, "domain" | "id" | "name">;
+}
+export declare function compareTraffic(client: UmamiClient, input: TrafficComparisonInput): Promise<{
+    dataStatus: "available" | "empty";
+    website: Pick<Website, "domain" | "id" | "name">;
+    channel?: "affiliate" | "direct" | "email" | "llm" | "organicSearch" | "organicShopping" | "organicSocial" | "organicVideo" | "paidAds" | "paidSearch" | "paidShopping" | "paidSocial" | "paidVideo" | "referral" | "sms" | undefined;
+    currentPeriod: {
+        start: string;
+        end: string;
+    };
+    comparisonPeriod: {
+        start: string;
+        end: string;
+    };
+    current: WebsiteTotals;
+    comparison: WebsiteTotals;
+    changes: {
+        [k: string]: {
+            absolute: number;
+            percent: number | null;
+        };
+    };
+    direction: string;
+    explanation: string;
+    breakdownMeasure: string;
+    breakdowns: ({
+        dimension: "channel";
+        status: "available";
+        measure: "visitors";
+        rows: {
+            name: string;
+            current: number;
+            comparison: number;
+            delta: number;
+            percent: number | null;
+            direction: string;
+        }[];
+        dataQuality: {
+            currentRowsTruncated: boolean;
+            comparisonRowsTruncated: boolean;
+            omittedUncertainRows: number;
+        };
+        error?: undefined;
+    } | {
+        dimension: "country" | "device" | "event" | "path" | "referrer";
+        status: "available";
+        measure: "visitors";
+        rows: {
+            name: string;
+            current: number;
+            comparison: number;
+            delta: number;
+            percent: number | null;
+            direction: string;
+        }[];
+        dataQuality: {
+            currentRowsTruncated: boolean;
+            comparisonRowsTruncated: boolean;
+            omittedUncertainRows: number;
+            candidateRowsTruncated: boolean;
+            candidateRows: number;
+            omittedUnsupportedRows: number;
+            fanoutRequests: number;
+        };
+        error?: undefined;
+    } | {
+        dimension: "country" | "device" | "event" | "path" | "referrer";
+        status: "available";
+        measure: "visitors";
+        rows: {
+            name: string;
+            current: number;
+            comparison: number;
+            delta: number;
+            percent: number | null;
+            direction: string;
+        }[];
+        dataQuality: {
+            currentRowsTruncated: boolean;
+            comparisonRowsTruncated: boolean;
+            omittedUncertainRows: number;
+        };
+        error?: undefined;
+    } | {
+        measure?: undefined;
+        rows?: undefined;
+        dataQuality?: undefined;
+        dimension: "channel" | "country" | "device" | "event" | "path" | "referrer";
+        status: "unavailable";
+        error: {
+            code: import("../api/errors.js").UmamiErrorCode;
+            message: string;
+            retryable: boolean;
+            status?: number;
+        };
+    })[];
+    leadingObservedChanges: {
+        name: string;
+        current: number;
+        comparison: number;
+        delta: number;
+        percent: number | null;
+        direction: string;
+        dimension: "channel" | "country" | "device" | "event" | "path" | "referrer";
+    }[];
+    dataQuality: {
+        comparisonBaselineZero: boolean;
+        currentPageviews: number;
+        comparisonPageviews: number;
+        unavailableDimensions: ("channel" | "country" | "device" | "event" | "path" | "referrer")[];
+        truncatedDimensions: ("channel" | "country" | "device" | "event" | "path" | "referrer")[];
+        omittedUncertainRows: number;
+    };
+}>;
+export declare function comparePerformance(client: UmamiClient, input: {
+    comparison: TimePeriod;
+    current: TimePeriod;
+    filters?: Filters;
+    signal?: AbortSignal;
+    timezone: string;
+    websiteId: string;
+}): Promise<{
+    error?: undefined;
+    status: "available" | "empty";
+    currentSampleCount: number;
+    comparisonSampleCount: number;
+    minimumSampleCount: number;
+    sampleSufficient: boolean;
+    changes: {
+        [k: string]: {
+            currentP75: number;
+            comparisonP75: number;
+            absolute: number;
+            percent: number | null;
+            impact: string;
+            material: boolean;
+            currentRating: "good" | "needs_improvement" | "poor";
+            comparisonRating: "good" | "needs_improvement" | "poor";
+        };
+    };
+} | {
+    currentSampleCount?: undefined;
+    comparisonSampleCount?: undefined;
+    minimumSampleCount?: undefined;
+    sampleSufficient?: undefined;
+    changes?: undefined;
+    status: string;
+    error: {
+        code: import("../api/errors.js").UmamiErrorCode;
+        message: string;
+        retryable: boolean;
+        status?: number;
+    };
+}>;
+export {};
+//# sourceMappingURL=insights-utils.d.ts.map

package/dist/mcp/insights-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-utils.d.ts","sourceRoot":"","sources":["../../src/mcp/insights-utils.ts"],"names":[],"mappings":"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"}