@domino-sdk/relay 1.54.0 → 1.55.0

package/dist/analytics-URV-mxjH.d.ts

@@ -0,0 +1,482 @@
+import * as z from 'zod';
+
+/**
+ * The ranges `analytics.read` covers. Each ends now: `7d`, `30d` and `90d` are that many project
+ * calendar days, today included, and `all` starts on the day of the project's earliest dated record:
+ * its first membership, or an older record such as a completion imported with its original date.
+ */
+declare const analyticsRanges: readonly ["7d", "30d", "90d", "all"];
+type AnalyticsRange = (typeof analyticsRanges)[number];
+/** What `analytics.read` reads: one range and, for the points section, one point ledger. */
+declare const analyticsQuerySchema: z.ZodObject<{
+    range: z.ZodEnum<{
+        "7d": "7d";
+        "30d": "30d";
+        "90d": "90d";
+        all: "all";
+    }>;
+    ledger: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** @compat input */
+type AnalyticsQuery = z.input<typeof analyticsQuerySchema>;
+/**
+ * A project's activity in one environment over one range, bucketed by project-calendar day (`7d`,
+ * `30d`) or week (`90d`, `all`, weeks from Monday, the first and last clipped to the range). Every
+ * metric counts what Relay's records say now: a completion revoked later, or a redemption
+ * canceled later, leaves the bucket it was in.
+ */
+declare const analyticsReadSchema: z.ZodObject<{
+    range: z.ZodObject<{
+        key: z.ZodEnum<{
+            "7d": "7d";
+            "30d": "30d";
+            "90d": "90d";
+            all: "all";
+        }>;
+        from: z.ZodISODateTime;
+        to: z.ZodISODateTime;
+        bucket: z.ZodEnum<{
+            day: "day";
+            week: "week";
+        }>;
+        timeZone: z.ZodString;
+        buckets: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            start: z.ZodISODateTime;
+            end: z.ZodISODateTime;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    previous: z.ZodOptional<z.ZodObject<{
+        from: z.ZodISODateTime;
+        to: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    members: z.ZodObject<{
+        signUps: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        active: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    quests: z.ZodObject<{
+        attempts: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        completions: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        rejections: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        needsReview: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        byQuest: z.ZodArray<z.ZodObject<{
+            quest: z.ZodString;
+            title: z.ZodString;
+            attempts: z.ZodNumber;
+            completions: z.ZodNumber;
+            decided: z.ZodNumber;
+            rejected: z.ZodNumber;
+            needsReview: z.ZodNumber;
+            rejectionRate: z.ZodNullable<z.ZodNumber>;
+            topReasons: z.ZodArray<z.ZodObject<{
+                reason: z.ZodString;
+                code: z.ZodNullable<z.ZodString>;
+                count: z.ZodNumber;
+            }, z.core.$strip>>;
+            rejectionsBySource: z.ZodObject<{
+                evaluator: z.ZodNumber;
+                staff: z.ZodNumber;
+                budget: z.ZodNumber;
+                expired: z.ZodNumber;
+            }, z.core.$strip>;
+            series: z.ZodObject<{
+                attempts: z.ZodArray<z.ZodNumber>;
+                completions: z.ZodArray<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    points: z.ZodObject<{
+        ledgers: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            name: z.ZodString;
+            archived: z.ZodBoolean;
+        }, z.core.$strip>>;
+        ledger: z.ZodNullable<z.ZodString>;
+        hasSpending: z.ZodBoolean;
+        awarded: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        spent: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+        net: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+        membersEarning: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    offers: z.ZodOptional<z.ZodObject<{
+        redemptions: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        byOffer: z.ZodArray<z.ZodObject<{
+            offer: z.ZodString;
+            title: z.ZodString;
+            redemptions: z.ZodNumber;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    referrals: z.ZodOptional<z.ZodObject<{
+        accepted: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        qualified: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+            series: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+        acceptedQualified: z.ZodObject<{
+            total: z.ZodNumber;
+            previousTotal: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    testEnvironment: z.ZodOptional<z.ZodObject<{
+        lastResetAt: z.ZodNullable<z.ZodISODateTime>;
+        shiftedClockMembers: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AnalyticsRead = z.infer<typeof analyticsReadSchema>;
+/** One metric over the range: `{ total, previousTotal?, series }`. */
+type AnalyticsMetric = AnalyticsRead["members"]["signUps"];
+/** One quest's activity over the range. */
+type AnalyticsQuest = AnalyticsRead["quests"]["byQuest"][number];
+/**
+ * How a breakdown splits a metric: by quest, offer, referral program, group, tracker or
+ * leaderboard; for rejections by `source` (evaluator, staff, budget, expired) or `reason` (the
+ * rejection code, else the exact text); for tracker outcomes by `outcome` (admitted or skipped).
+ */
+declare const analyticsBreakdowns: readonly ["quest", "source", "reason", "offer", "program", "group", "tracker", "outcome", "leaderboard"];
+type AnalyticsBreakdown = (typeof analyticsBreakdowns)[number];
+/**
+ * What a filter narrows to: quests, offers, referral programs or leaderboards by key or ID, the
+ * quests a tracker triggers (on `trackers.records`, that tracker's outcomes), or the members
+ * currently in a group (on `groups.joins` and `groups.leaves`, the changes in that group).
+ */
+declare const analyticsFilters: readonly ["quest", "tracker", "group", "offer", "program", "leaderboard"];
+type AnalyticsFilter = (typeof analyticsFilters)[number];
+/** How a panel can draw a metric. `bar` stacks a breakdown's rows. */
+declare const analyticsCharts: readonly ["number", "line", "bar", "table"];
+type AnalyticsChart = (typeof analyticsCharts)[number];
+/**
+ * How a metric's total relates to its buckets: `count` sums them, `distinct` counts each member
+ * once over the range, and `rate` divides a numerator by a denominator, empty (`null`) below
+ * `minimumDenominator`.
+ */
+type AnalyticsMetricKind = "count" | "distinct" | "rate";
+/** One metric of the catalog: what it counts, how it can be split and narrowed, and drawn. */
+type AnalyticsCatalogEntry = {
+    readonly definition: string;
+    readonly kind: AnalyticsMetricKind;
+    readonly breakdowns: readonly AnalyticsBreakdown[];
+    readonly filters: readonly AnalyticsFilter[];
+    readonly charts: readonly AnalyticsChart[];
+    /** Points metrics read one point ledger, which every query of them names. */
+    readonly ledger: boolean;
+    readonly minimumDenominator?: number;
+};
+/**
+ * Relay's closed metric catalog (docs/adr/0021-closed-metric-catalog.md). `analytics.query` reads
+ * one of these by ID, and `analytics.catalog` lists them; there is no other analytics query.
+ */
+declare const analyticsCatalog: {
+    readonly "members.signUps": {
+        readonly definition: "Members who joined the project, by when they joined.";
+        readonly kind: "count";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "members.active": {
+        readonly definition: "Distinct members with an attempt, by when it was created; the total counts each member once.";
+        readonly kind: "distinct";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "quests.attempts": {
+        readonly definition: "Attempts, by when they were created.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["quest"];
+        readonly filters: readonly ["quest", "group", "tracker"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "quests.completions": {
+        readonly definition: "Quest completions never revoked, by when they completed.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["quest"];
+        readonly filters: readonly ["quest", "group", "tracker"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "quests.needsReview": {
+        readonly definition: "Attempts the evaluator sent to staff review, by when they were created, whatever staff decided later.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["quest"];
+        readonly filters: readonly ["quest", "group", "tracker"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "quests.rejections": {
+        readonly definition: "Rejected attempts, by when they were decided.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["quest", "source", "reason"];
+        readonly filters: readonly ["quest", "group", "tracker"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "quests.rejectionRate": {
+        readonly definition: "Rejected attempts divided by decided attempts (accepted, progressed or rejected), by when they were decided; empty below 10 decided.";
+        readonly kind: "rate";
+        readonly breakdowns: readonly ["quest"];
+        readonly filters: readonly ["quest", "group", "tracker"];
+        readonly charts: readonly ["number", "line", "table"];
+        readonly ledger: false;
+        readonly minimumDenominator: 10;
+    };
+    readonly "points.awarded": {
+        readonly definition: "Points in the ledger's award entries, by effective date.";
+        readonly kind: "count";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: true;
+    };
+    readonly "points.spent": {
+        readonly definition: "Points in the ledger's spend entries, as a positive number, by effective date.";
+        readonly kind: "count";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: true;
+    };
+    readonly "points.net": {
+        readonly definition: "Every entry's signed amount in the ledger, by effective date; a reversal takes its original entry's date.";
+        readonly kind: "count";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: true;
+    };
+    readonly "points.membersEarning": {
+        readonly definition: "Distinct members awarded more than 0 points in the ledger, by effective date; the total counts each member once.";
+        readonly kind: "distinct";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: true;
+    };
+    readonly "offers.redemptions": {
+        readonly definition: "Fulfilled offer redemptions, by when they were redeemed.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["offer"];
+        readonly filters: readonly ["offer", "group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "referrals.accepted": {
+        readonly definition: "Accepted referrals, by when they were accepted. A referral belongs to no program, so it takes no program breakdown or filter.";
+        readonly kind: "count";
+        readonly breakdowns: readonly [];
+        readonly filters: readonly [];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "referrals.qualified": {
+        readonly definition: "Active referral qualifications, one per program and friend, by when they first qualified; suspended referrals count.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["program"];
+        readonly filters: readonly ["program"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "referrals.qualificationRate": {
+        readonly definition: "Of the referrals accepted in a bucket, the share whose friend has an active qualification now (in the program, for a program row or filter), by acceptance; empty below 10 accepted.";
+        readonly kind: "rate";
+        readonly breakdowns: readonly ["program"];
+        readonly filters: readonly ["program"];
+        readonly charts: readonly ["number", "line", "table"];
+        readonly ledger: false;
+        readonly minimumDenominator: 10;
+    };
+    readonly "groups.joins": {
+        readonly definition: "Members added to a group, by when they were added. A change that left membership as it was, and a membership recorded without a date, don't count. The group filter keeps changes in those groups.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["group"];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "groups.leaves": {
+        readonly definition: "Members removed from a group, by when they were removed. A change that left membership as it was, and a membership recorded without a date, don't count. The group filter keeps changes in those groups.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["group"];
+        readonly filters: readonly ["group"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "trackers.records": {
+        readonly definition: "Tracker trigger outcomes, one per quest and record observation, by when the record was observed, counted by their current outcome (admitted or skipped). A retry overwrites an outcome, so a bucket shows today's outcome of its records, not the outcome they had then.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["outcome", "tracker"];
+        readonly filters: readonly ["tracker"];
+        readonly charts: readonly ["number", "line", "bar", "table"];
+        readonly ledger: false;
+    };
+    readonly "leaderboards.settledParticipants": {
+        readonly definition: "Participants in leaderboard settlements, one per member and settlement, by the settlement's cutoff. Pending and approved settlements count; a rejected settlement leaves its bucket.";
+        readonly kind: "count";
+        readonly breakdowns: readonly ["leaderboard"];
+        readonly filters: readonly ["leaderboard"];
+        readonly charts: readonly ["number", "bar", "table"];
+        readonly ledger: false;
+    };
+};
+type AnalyticsMetricId = keyof typeof analyticsCatalog;
+declare const analyticsMetricIds: AnalyticsMetricId[];
+/** `analytics.catalog`: every metric with its definition, breakdowns, filters and charts. */
+declare const analyticsCatalogSchema: z.ZodObject<{
+    metrics: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        definition: z.ZodString;
+        kind: z.ZodEnum<{
+            count: "count";
+            distinct: "distinct";
+            rate: "rate";
+        }>;
+        breakdowns: z.ZodArray<z.ZodString>;
+        filters: z.ZodArray<z.ZodString>;
+        charts: z.ZodArray<z.ZodString>;
+        ledger: z.ZodBoolean;
+        minimumDenominator: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AnalyticsCatalog = z.infer<typeof analyticsCatalogSchema>;
+/** A breakdown or query returns up to this many rows; the rest are summed into `other`. */
+declare const analyticsQueryLimit = 100;
+/**
+ * What `analytics.query` reads on the wire. The metric, breakdown and filter names are checked by
+ * Relay against the catalog, which answers a coded 422, so the schema takes any name here; the
+ * typed input is `AnalyticsMetricQuery`.
+ */
+declare const analyticsMetricQuerySchema: z.ZodObject<{
+    metric: z.ZodString;
+    range: z.ZodEnum<{
+        "7d": "7d";
+        "30d": "30d";
+        "90d": "90d";
+        all: "all";
+    }>;
+    breakdown: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    ledger: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** One metric over a range, at most one breakdown, filters, and for points metrics the ledger. */
+type AnalyticsMetricQuery = {
+    metric: AnalyticsMetricId;
+    range: AnalyticsRange;
+    breakdown?: AnalyticsBreakdown;
+    filter?: Partial<Record<AnalyticsFilter, string | readonly string[]>>;
+    ledger?: string;
+    limit?: number;
+};
+/** `analytics.query`: one metric over the range, and its breakdown rows when it is broken down. */
+declare const analyticsMetricResultSchema: z.ZodObject<{
+    metric: z.ZodString;
+    kind: z.ZodEnum<{
+        count: "count";
+        distinct: "distinct";
+        rate: "rate";
+    }>;
+    range: z.ZodObject<{
+        key: z.ZodEnum<{
+            "7d": "7d";
+            "30d": "30d";
+            "90d": "90d";
+            all: "all";
+        }>;
+        from: z.ZodISODateTime;
+        to: z.ZodISODateTime;
+        bucket: z.ZodEnum<{
+            day: "day";
+            week: "week";
+        }>;
+        timeZone: z.ZodString;
+        buckets: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            start: z.ZodISODateTime;
+            end: z.ZodISODateTime;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    previous: z.ZodOptional<z.ZodObject<{
+        from: z.ZodISODateTime;
+        to: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    ledger: z.ZodOptional<z.ZodString>;
+    value: z.ZodObject<{
+        total: z.ZodNullable<z.ZodNumber>;
+        previousTotal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        series: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>;
+    breakdown: z.ZodOptional<z.ZodObject<{
+        dimension: z.ZodString;
+        rows: z.ZodArray<z.ZodObject<{
+            total: z.ZodNullable<z.ZodNumber>;
+            previousTotal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            series: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+            key: z.ZodString;
+            title: z.ZodString;
+            archived: z.ZodBoolean;
+        }, z.core.$strip>>;
+        other: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNullable<z.ZodNumber>;
+            previousTotal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            series: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+            rows: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AnalyticsMetricResult = z.infer<typeof analyticsMetricResultSchema>;
+type AnalyticsBreakdownRow = NonNullable<AnalyticsMetricResult["breakdown"]>["rows"][number];
+
+export { type AnalyticsMetricId as A, analyticsCatalog as a, type AnalyticsQuery as b, type AnalyticsRead as c, type AnalyticsCatalog as d, type AnalyticsMetricQuery as e, type AnalyticsMetricResult as f, type AnalyticsBreakdown as g, type AnalyticsBreakdownRow as h, type AnalyticsCatalogEntry as i, type AnalyticsChart as j, type AnalyticsFilter as k, type AnalyticsMetric as l, type AnalyticsMetricKind as m, type AnalyticsQuest as n, type AnalyticsRange as o, analyticsBreakdowns as p, analyticsCatalogSchema as q, analyticsCharts as r, analyticsFilters as s, analyticsMetricIds as t, analyticsMetricQuerySchema as u, analyticsMetricResultSchema as v, analyticsQueryLimit as w, analyticsQuerySchema as x, analyticsRanges as y, analyticsReadSchema as z };

package/dist/{attempt-captures-QC4kTA44.d.ts → attempt-captures-CxxO7DeD.d.ts}

@@ -1,4 +1,4 @@
-import { O as OpenIdentityKind } from './schema-BJ9bOgpN.js';
+import { O as OpenIdentityKind } from './schema-C4m9RhCR.js';
 import * as z from 'zod';
 
 /** One capability call of the captured evaluation run, as Relay stored it. */