@domino-sdk/relay 1.54.0 → 1.56.0

package/dist/chunk-ULQU7KC4.js

@@ -0,0 +1,704 @@
+import {
+  identifier,
+  resourceHandle,
+  responseShape
+} from "./chunk-BHHUSBSD.js";
+
+// src/youtube.ts
+import * as z from "zod";
+var youtubeShortsNamespace = "youtube-shorts";
+var youtubeShortBodySchema = z.object({
+  title: z.string(),
+  description: z.string(),
+  tags: z.array(z.string()),
+  durationSeconds: z.number().int().nonnegative(),
+  /** When the video was published, epoch milliseconds. */
+  publishedAt: z.number().int().nonnegative()
+});
+var youtubeShortMetrics = ["views", "likes", "comments"];
+
+// src/tiktok.ts
+import * as z2 from "zod";
+var tiktokVideosNamespace = "tiktok-videos";
+var tiktokVideoBodySchema = z2.object({
+  title: z2.string(),
+  /** The creator's caption, `video_description` in TikTok's API. */
+  description: z2.string(),
+  durationSeconds: z2.number().int().nonnegative(),
+  width: z2.number().int().nonnegative(),
+  height: z2.number().int().nonnegative(),
+  /** When the video was posted, epoch milliseconds. */
+  createdAt: z2.number().int().nonnegative(),
+  /** TikTok's shareable link to the video. */
+  shareUrl: z2.string(),
+  /** Whether the creator labelled the video as AI-generated content. */
+  isAigc: z2.boolean()
+});
+var tiktokVideoMetrics = [
+  "views",
+  "likes",
+  "comments",
+  "shares"
+];
+
+// src/server/analytics.ts
+import * as z3 from "zod";
+function once(build) {
+  let built;
+  return () => built ??= build();
+}
+function lazyShape(builders) {
+  const shape = {};
+  for (const [key, build] of Object.entries(builders)) {
+    Object.defineProperty(shape, key, {
+      get: once(build),
+      enumerable: true,
+      configurable: true
+    });
+  }
+  return shape;
+}
+var analyticsRanges = ["7d", "30d", "90d", "all"];
+var amount = once(() => z3.number().int().safe());
+var amounts = once(() => z3.array(amount()));
+var instant = once(() => z3.iso.datetime({ offset: true }));
+var bucket = once(
+  () => z3.object({
+    /** The period's label in its time zone, such as `2026-10-08@Europe/Budapest` or `2026-W41@UTC`. */
+    key: z3.string(),
+    start: instant(),
+    end: instant()
+  })
+);
+var range = once(
+  () => z3.object({
+    key: z3.enum(analyticsRanges),
+    from: instant(),
+    /** Now, by the database's clock, when the read ran. */
+    to: instant(),
+    bucket: z3.enum(["day", "week"]),
+    /** The project calendar's time zone now. Buckets before a time zone change follow the old one. */
+    timeZone: z3.string(),
+    buckets: z3.array(bucket())
+  })
+);
+var previousRange = once(
+  () => z3.object({ from: instant(), to: instant() }).optional()
+);
+var analyticsQuerySchema = z3.strictObject(
+  lazyShape({
+    range: () => z3.enum(analyticsRanges),
+    /** A point ledger's key or ID. Defaults to the first ledger that is not archived. */
+    ledger: () => identifier.optional()
+  })
+);
+var metric = once(
+  () => z3.object({
+    total: amount(),
+    previousTotal: amount().optional(),
+    series: amounts()
+  })
+);
+var optionalMetric = once(() => metric().optional());
+var quest = once(
+  () => z3.object({
+    quest: identifier,
+    title: z3.string(),
+    /** Attempts created in the range. */
+    attempts: amount(),
+    /** Completions in the range that were never revoked. */
+    completions: amount(),
+    /** Attempts decided in the range: accepted, progressed or rejected. */
+    decided: amount(),
+    /** Attempts rejected in the range. */
+    rejected: amount(),
+    /** Attempts created in the range that went to staff review. */
+    needsReview: amount(),
+    /** `rejected ÷ decided`, or null below 10 decided attempts. */
+    rejectionRate: z3.number().min(0).max(1).nullable(),
+    /**
+     * The 5 most common rejections, most frequent first. Rejections with a code (an evaluator's
+     * reject code or one Relay writes, such as `budget-exhausted`) group by it, and `reason` is the
+     * latest rejection's reason; rejections without one group by their exact reason.
+     */
+    topReasons: z3.array(
+      z3.object({
+        reason: z3.string(),
+        code: z3.string().nullable(),
+        count: amount()
+      })
+    ),
+    /** Rejections by who made them: the evaluator, staff, an exhausted budget, an expired deferral. */
+    rejectionsBySource: z3.object({
+      evaluator: amount(),
+      staff: amount(),
+      budget: amount(),
+      expired: amount()
+    }),
+    /** Attempts and completions per bucket. */
+    series: z3.object({ attempts: amounts(), completions: amounts() })
+  })
+);
+var analyticsReadSchema = z3.object(
+  lazyShape({
+    range,
+    previous: previousRange,
+    members: () => z3.object({
+      /** Members who joined the project. */
+      signUps: metric(),
+      /** Distinct members with an attempt; the total counts each member once over the range. */
+      active: metric()
+    }),
+    quests: () => z3.object({
+      attempts: metric(),
+      completions: metric(),
+      rejections: metric(),
+      needsReview: metric(),
+      /** Quests with activity in the range, most attempted first. */
+      byQuest: z3.array(quest())
+    }),
+    points: () => z3.object({
+      /** The project's point ledgers, oldest first. */
+      ledgers: z3.array(
+        z3.object({ key: identifier, name: z3.string(), archived: z3.boolean() })
+      ),
+      /** The ledger this section reads, or null when the project has none to read. */
+      ledger: identifier.nullable(),
+      /** Whether the ledger has a spend entry. `spent` and `net` are present only when it does. */
+      hasSpending: z3.boolean(),
+      /** Points in award entries. */
+      awarded: metric(),
+      /** Points in spend entries, as a positive number. */
+      spent: optionalMetric(),
+      /** Every entry's signed amount: awards, spends, adjustments and reversals. */
+      net: optionalMetric(),
+      /** Distinct members awarded points; the total counts each member once over the range. */
+      membersEarning: metric()
+    }),
+    /** Fulfilled offer redemptions. Present only when the project has an offer. */
+    offers: () => z3.object({
+      redemptions: metric(),
+      /** Every offer, most redeemed first. */
+      byOffer: z3.array(
+        z3.object({
+          offer: identifier,
+          title: z3.string(),
+          redemptions: amount(),
+          series: amounts()
+        })
+      )
+    }).optional(),
+    /** Present only when the project has a referral program. */
+    referrals: () => z3.object({
+      /** Referrals accepted. */
+      accepted: metric(),
+      /** Active qualifications, by when they first qualified; suspended referrals still count. */
+      qualified: metric(),
+      /**
+       * Of the referrals accepted in the range (and in the range before), how many have an
+       * active qualification now, each counted once; suspended referrals still count.
+       * `acceptedQualified.total ÷ accepted.total` is the share of the range's friends who have
+       * qualified since, never above 1.
+       */
+      acceptedQualified: z3.object({
+        total: amount(),
+        previousTotal: amount().optional()
+      })
+    }).optional(),
+    /** Present only in the test environment. */
+    testEnvironment: () => z3.object({
+      /** When a test member was last reset, deleting their history, or null. */
+      lastResetAt: instant().nullable(),
+      /** Test members whose clock is advanced, so their activity can be dated in the future. */
+      shiftedClockMembers: amount()
+    }).optional()
+  })
+);
+var analyticsBreakdowns = [
+  "quest",
+  "source",
+  "reason",
+  "offer",
+  "program",
+  "group",
+  "tracker",
+  "outcome",
+  "leaderboard"
+];
+var analyticsFilters = [
+  "quest",
+  "tracker",
+  "group",
+  "offer",
+  "program",
+  "leaderboard"
+];
+var analyticsCharts = ["number", "line", "bar", "table"];
+var counts = ["number", "line", "bar", "table"];
+var rates = ["number", "line", "table"];
+var periodic = ["number", "bar", "table"];
+var questFilters = ["quest", "group", "tracker"];
+var analyticsCatalog = {
+  "members.signUps": {
+    definition: "Members who joined the project, by when they joined.",
+    kind: "count",
+    breakdowns: [],
+    filters: ["group"],
+    charts: counts,
+    ledger: false
+  },
+  "members.active": {
+    definition: "Distinct members with an attempt, by when it was created; the total counts each member once.",
+    kind: "distinct",
+    breakdowns: [],
+    filters: ["group"],
+    charts: counts,
+    ledger: false
+  },
+  "quests.attempts": {
+    definition: "Attempts, by when they were created.",
+    kind: "count",
+    breakdowns: ["quest"],
+    filters: questFilters,
+    charts: counts,
+    ledger: false
+  },
+  "quests.completions": {
+    definition: "Quest completions never revoked, by when they completed.",
+    kind: "count",
+    breakdowns: ["quest"],
+    filters: questFilters,
+    charts: counts,
+    ledger: false
+  },
+  "quests.needsReview": {
+    definition: "Attempts the evaluator sent to staff review, by when they were created, whatever staff decided later.",
+    kind: "count",
+    breakdowns: ["quest"],
+    filters: questFilters,
+    charts: counts,
+    ledger: false
+  },
+  "quests.rejections": {
+    definition: "Rejected attempts, by when they were decided.",
+    kind: "count",
+    breakdowns: ["quest", "source", "reason"],
+    filters: questFilters,
+    charts: counts,
+    ledger: false
+  },
+  "quests.rejectionRate": {
+    definition: "Rejected attempts divided by decided attempts (accepted, progressed or rejected), by when they were decided; empty below 10 decided.",
+    kind: "rate",
+    breakdowns: ["quest"],
+    filters: questFilters,
+    charts: rates,
+    ledger: false,
+    minimumDenominator: 10
+  },
+  "points.awarded": {
+    definition: "Points in the ledger's award entries, by effective date.",
+    kind: "count",
+    breakdowns: [],
+    filters: ["group"],
+    charts: counts,
+    ledger: true
+  },
+  "points.spent": {
+    definition: "Points in the ledger's spend entries, as a positive number, by effective date.",
+    kind: "count",
+    breakdowns: [],
+    filters: ["group"],
+    charts: counts,
+    ledger: true
+  },
+  "points.net": {
+    definition: "Every entry's signed amount in the ledger, by effective date; a reversal takes its original entry's date.",
+    kind: "count",
+    breakdowns: [],
+    filters: ["group"],
+    charts: counts,
+    ledger: true
+  },
+  "points.membersEarning": {
+    definition: "Distinct members awarded more than 0 points in the ledger, by effective date; the total counts each member once.",
+    kind: "distinct",
+    breakdowns: [],
+    filters: ["group"],
+    charts: counts,
+    ledger: true
+  },
+  "offers.redemptions": {
+    definition: "Fulfilled offer redemptions, by when they were redeemed.",
+    kind: "count",
+    breakdowns: ["offer"],
+    filters: ["offer", "group"],
+    charts: counts,
+    ledger: false
+  },
+  "referrals.accepted": {
+    definition: "Accepted referrals, by when they were accepted. A referral belongs to no program, so it takes no program breakdown or filter.",
+    kind: "count",
+    breakdowns: [],
+    filters: [],
+    charts: counts,
+    ledger: false
+  },
+  "referrals.qualified": {
+    definition: "Active referral qualifications, one per program and friend, by when they first qualified; suspended referrals count.",
+    kind: "count",
+    breakdowns: ["program"],
+    filters: ["program"],
+    charts: counts,
+    ledger: false
+  },
+  "referrals.qualificationRate": {
+    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.",
+    kind: "rate",
+    breakdowns: ["program"],
+    filters: ["program"],
+    charts: rates,
+    ledger: false,
+    minimumDenominator: 10
+  },
+  "groups.joins": {
+    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.",
+    kind: "count",
+    breakdowns: ["group"],
+    filters: ["group"],
+    charts: counts,
+    ledger: false
+  },
+  "groups.leaves": {
+    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.",
+    kind: "count",
+    breakdowns: ["group"],
+    filters: ["group"],
+    charts: counts,
+    ledger: false
+  },
+  "trackers.records": {
+    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.",
+    kind: "count",
+    breakdowns: ["outcome", "tracker"],
+    filters: ["tracker"],
+    charts: counts,
+    ledger: false
+  },
+  "leaderboards.settledParticipants": {
+    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.",
+    kind: "count",
+    breakdowns: ["leaderboard"],
+    filters: ["leaderboard"],
+    charts: periodic,
+    ledger: false
+  }
+};
+var analyticsMetricIds = Object.keys(
+  analyticsCatalog
+);
+var analyticsCatalogSchema = z3.object(
+  lazyShape({
+    metrics: () => z3.array(
+      z3.object({
+        id: z3.string(),
+        definition: z3.string(),
+        kind: z3.enum(["count", "distinct", "rate"]),
+        breakdowns: z3.array(z3.string()),
+        filters: z3.array(z3.string()),
+        charts: z3.array(z3.string()),
+        ledger: z3.boolean(),
+        /** For a rate, the denominator below which a value is empty. */
+        minimumDenominator: amount().optional()
+      })
+    )
+  })
+);
+var analyticsQueryLimit = 100;
+var analyticsMetricQuerySchema = z3.strictObject(
+  lazyShape({
+    metric: () => z3.string().min(1).max(100),
+    range: () => z3.enum(analyticsRanges),
+    breakdown: () => z3.string().min(1).max(100).optional(),
+    /** Each filter names one key or a list of keys; a list matches any of them. */
+    filter: () => z3.record(
+      z3.string().min(1).max(100),
+      z3.union([identifier, z3.array(identifier).min(1).max(100)])
+    ).optional(),
+    /** A point ledger's key or ID, archived ledgers included. Points metrics need one. */
+    ledger: () => identifier.optional(),
+    /** Breakdown rows to return, 1 to 100 (default 100); the rest are summed into `other`. */
+    limit: () => z3.number().int().optional()
+  })
+);
+var measureNumber = once(() => z3.number().nullable());
+var measure = once(() => ({
+  total: measureNumber(),
+  previousTotal: measureNumber().optional(),
+  series: z3.array(measureNumber())
+}));
+var analyticsMetricResultSchema = z3.object(
+  lazyShape({
+    metric: () => z3.string(),
+    /** How the value reads: a `count`, a `distinct` count of members, or a `rate` from 0 to 1. */
+    kind: () => z3.enum(["count", "distinct", "rate"]),
+    range,
+    previous: previousRange,
+    /** The point ledger a points metric read, by key. */
+    ledger: () => identifier.optional(),
+    /** The metric over everything the filters match, every breakdown row included. */
+    value: () => z3.object(measure()),
+    breakdown: () => z3.object({
+      dimension: z3.string(),
+      /**
+       * Sorted by total, largest first (an empty rate last), at most `limit`. Every matching
+       * quest, offer, program, group, tracker or leaderboard that is not archived has a row, and an archived one has a row
+       * when it has activity in the range or the range before.
+       */
+      rows: z3.array(
+        z3.object({
+          /** The resource's key (its ID when it has none), the source, the outcome, or the reason's code or text. */
+          key: z3.string(),
+          title: z3.string(),
+          archived: z3.boolean(),
+          ...measure()
+        })
+      ),
+      /** The rows past `limit`, summed; for a rate, their summed numerators over denominators. */
+      other: z3.object({ rows: amount(), ...measure() }).optional()
+    }).optional()
+  })
+);
+
+// src/dashboards.ts
+import * as z4 from "zod";
+var dashboardLimits = { panels: 24, dashboards: 20 };
+var defaultPanelWidths = {
+  number: 1,
+  line: 2,
+  bar: 2,
+  table: 4
+};
+var title = z4.string().trim().min(1).max(120);
+var description = z4.string().trim().min(1).max(500);
+var filterValue = z4.union([identifier, z4.array(identifier).min(1).max(100)]);
+var filter = z4.record(z4.string().min(1).max(100), filterValue);
+var panelFields = {
+  key: identifier,
+  title,
+  description: description.optional(),
+  /** A metric ID from the catalog (`analytics.catalog`). */
+  metric: z4.string().min(1).max(100),
+  breakdown: z4.string().min(1).max(100).optional(),
+  /** Each filter names one key or a list of keys; a list matches any of them. */
+  filter: filter.optional(),
+  /** The point ledger a points metric reads, by key. */
+  ledger: identifier.optional(),
+  chart: z4.enum(analyticsCharts)
+};
+var dashboardPanelAuthoringSchema = z4.strictObject({
+  ...panelFields,
+  width: z4.number().int().min(1).max(4).optional()
+});
+var dashboardAuthoringSchema = z4.strictObject({
+  key: identifier,
+  title,
+  description: description.optional(),
+  /** The range the dashboard opens with. Defaults to `30d`. */
+  defaultRange: z4.enum(analyticsRanges).optional(),
+  /** Orders dashboards in lists: by position, those without one last, then by title. */
+  position: z4.number().int().min(0).max(1e3).optional(),
+  sections: z4.array(
+    z4.strictObject({
+      title: title.optional(),
+      panels: z4.array(dashboardPanelAuthoringSchema).min(1).max(100)
+    })
+  ).min(1).max(100)
+});
+var dashboardDefinitionSchema = z4.strictObject({
+  key: identifier,
+  title,
+  description: description.optional(),
+  defaultRange: z4.enum(analyticsRanges),
+  position: z4.number().int().min(0).max(1e3).optional(),
+  sections: z4.array(
+    z4.strictObject({
+      title: title.optional(),
+      panels: z4.array(
+        z4.strictObject({
+          ...panelFields,
+          width: z4.number().int().min(1).max(4)
+        })
+      )
+    })
+  )
+});
+var dashboardArtifactSchema = z4.union([
+  dashboardAuthoringSchema,
+  z4.object({ code: z4.string().min(1).max(2e6) }).strict()
+]);
+function normalizeDashboard(input) {
+  const dashboard = dashboardAuthoringSchema.parse(input);
+  return dashboardDefinitionSchema.parse({
+    key: dashboard.key,
+    title: dashboard.title,
+    ...dashboard.description === void 0 ? {} : { description: dashboard.description },
+    defaultRange: dashboard.defaultRange ?? "30d",
+    ...dashboard.position === void 0 ? {} : { position: dashboard.position },
+    sections: dashboard.sections.map((section) => ({
+      ...section.title === void 0 ? {} : { title: section.title },
+      panels: section.panels.map((panel) => ({
+        ...panel,
+        width: panel.width ?? defaultPanelWidths[panel.chart]
+      }))
+    }))
+  });
+}
+function dashboardPanels(dashboard) {
+  return dashboard.sections.flatMap((section) => [...section.panels]);
+}
+function dashboardIssue(dashboard) {
+  const panels = dashboard.sections.flatMap((section) => [...section.panels]);
+  const where = `dashboard "${dashboard.key}"`;
+  if (panels.length > dashboardLimits.panels) {
+    return {
+      code: "too-many-panels",
+      message: `The ${where} has ${panels.length} panels; a dashboard holds at most ${dashboardLimits.panels}.`
+    };
+  }
+  const keys = /* @__PURE__ */ new Set();
+  for (const panel of panels) {
+    const at = `Panel "${panel.key}" of ${where}`;
+    if (keys.has(panel.key)) {
+      return {
+        code: "duplicate-key",
+        panel: panel.key,
+        message: `The ${where} has two panels with the key "${panel.key}".`
+      };
+    }
+    keys.add(panel.key);
+    if (!Object.hasOwn(analyticsCatalog, panel.metric)) {
+      return {
+        code: "unknown-metric",
+        panel: panel.key,
+        message: `${at} names the unknown metric "${panel.metric}". Run domino analytics metrics for the catalog.`
+      };
+    }
+    const entry = analyticsCatalog[panel.metric];
+    if (panel.breakdown !== void 0 && !entry.breakdowns.includes(panel.breakdown)) {
+      return {
+        code: "breakdown-not-accepted",
+        panel: panel.key,
+        message: `${at}: ${panel.metric} has no "${panel.breakdown}" breakdown; it takes ${entry.breakdowns.join(", ") || "none"}.`
+      };
+    }
+    for (const name of Object.keys(panel.filter ?? {})) {
+      if (!entry.filters.includes(name)) {
+        return {
+          code: "filter-not-accepted",
+          panel: panel.key,
+          message: `${at}: ${panel.metric} takes no "${name}" filter; it takes ${entry.filters.join(", ") || "none"}.`
+        };
+      }
+    }
+    if (!entry.charts.includes(panel.chart)) {
+      return {
+        code: "chart-not-accepted",
+        panel: panel.key,
+        message: `${at}: ${panel.metric} can't be drawn as "${panel.chart}"; it takes ${entry.charts.join(", ")}.`
+      };
+    }
+    if (panel.chart === "number" && panel.breakdown !== void 0) {
+      return {
+        code: "breakdown-not-accepted",
+        panel: panel.key,
+        message: `${at}: a number panel shows one value and takes no breakdown.`
+      };
+    }
+    if (panel.chart === "table" && panel.breakdown === void 0) {
+      return {
+        code: "breakdown-required",
+        panel: panel.key,
+        message: `${at}: a table panel needs a breakdown; ${panel.metric} takes ${entry.breakdowns.join(", ") || "none"}.`
+      };
+    }
+    if (entry.ledger && panel.ledger === void 0) {
+      return {
+        code: "ledger-required",
+        panel: panel.key,
+        message: `${at}: ${panel.metric} needs a point ledger; set ledger to its key.`
+      };
+    }
+    if (!entry.ledger && panel.ledger !== void 0) {
+      return {
+        code: "ledger-not-accepted",
+        panel: panel.key,
+        message: `${at}: ${panel.metric} reads no point ledger; remove ledger.`
+      };
+    }
+  }
+  return null;
+}
+var dashboardPreviewSchema = responseShape(
+  z4.object({
+    key: identifier,
+    title: z4.string(),
+    /** `unchanged`: the definition equals the published one, and publishing writes no version. */
+    change: z4.enum(["created", "updated", "unchanged"]),
+    definition: dashboardDefinitionSchema
+  })
+);
+var keyOf = (reference) => typeof reference === "string" ? reference : reference.key;
+function defineDashboard(input) {
+  const authored = dashboardAuthoringSchema.parse({
+    ...input,
+    sections: input.sections.map((section) => ({
+      ...section,
+      panels: section.panels.map((panel) => ({
+        ...panel,
+        ...panel.ledger === void 0 ? {} : { ledger: keyOf(panel.ledger) },
+        ...panel.filter === void 0 ? {} : {
+          filter: Object.fromEntries(
+            Object.entries(panel.filter).map(([name, value]) => [
+              name,
+              Array.isArray(value) ? value.map(keyOf) : keyOf(value)
+            ])
+          )
+        }
+      }))
+    }))
+  });
+  return resourceHandle("dashboard", authored);
+}
+
+export {
+  youtubeShortsNamespace,
+  youtubeShortBodySchema,
+  youtubeShortMetrics,
+  tiktokVideosNamespace,
+  tiktokVideoBodySchema,
+  tiktokVideoMetrics,
+  analyticsRanges,
+  analyticsQuerySchema,
+  analyticsReadSchema,
+  analyticsBreakdowns,
+  analyticsFilters,
+  analyticsCharts,
+  analyticsCatalog,
+  analyticsMetricIds,
+  analyticsCatalogSchema,
+  analyticsQueryLimit,
+  analyticsMetricQuerySchema,
+  analyticsMetricResultSchema,
+  dashboardLimits,
+  defaultPanelWidths,
+  dashboardPanelAuthoringSchema,
+  dashboardAuthoringSchema,
+  dashboardDefinitionSchema,
+  dashboardArtifactSchema,
+  normalizeDashboard,
+  dashboardPanels,
+  dashboardIssue,
+  dashboardPreviewSchema,
+  defineDashboard
+};