@trigger.dev/core 4.5.10 → 4.5.12

package/dist/esm/v3/schemas/reports.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+// Shared contract for `GET /api/v1/reports/:key`: the period grammar and the `format=json` body.
+// The view model is semantic, not a UI tree: reasons are codes the renderer resolves to prose.
+const PERIOD_UNIT_MS = { m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
+const MAX_PERIOD_MS = 90 * 864e5; // 90d
+/** A positive integer plus `m`, `h`, `d` or `w`, capped at 90d. Reports bucket by whole minutes. */
+export const ReportPeriodSchema = z
+    .string()
+    .regex(/^[1-9]\d*[mhdw]$/, "period must be a shorthand like '30m', '1h' or '7d' — minutes (m), hours (h), days (d) or weeks (w); seconds are not supported")
+    .refine(
+// The regex guarantees the last char is a known unit; `?? 0` just satisfies the type checker.
+(p) => Number(p.slice(0, -1)) * (PERIOD_UNIT_MS[p.slice(-1)] ?? 0) <= MAX_PERIOD_MS, "period is too large (max 90d)");
+/** The response encodings the endpoint can render. `json` returns a `ReportViewModel`. */
+export const ReportFormatSchema = z.enum(["markdown", "json", "ansi"]);
+export const ReportSeveritySchema = z.enum(["ok", "warn", "crit"]);
+export const ReportUnitSchema = z.enum(["ms", "count", "ratio", "perMin"]);
+/** A code resolved to a human string by the renderer's message table. */
+export const ReportReasonCodeSchema = z.string();
+/** A key into `ReportViewModel.links`, so a recommendation can point at a URL. */
+export const ReportLinkKeySchema = z.string();
+export const ReportDeltaSchema = z.object({
+    dir: z.enum(["up", "down", "flat"]),
+    /** rounded value/normal multiplier; renderer decides whether to print "6×". */
+    mult: z.number().optional(),
+});
+export const ReportMetricSeriesSchema = z.object({
+    points: z.array(z.number()),
+    /** "estimated" = a proxy (e.g. pending backlog), shown informational-only. */
+    kind: z.enum(["measured", "estimated"]),
+});
+export const ReportMetricSchema = z.object({
+    /** A code, e.g. "start_latency_p95"; the messages map turns it into the label. */
+    id: z.string(),
+    value: z.number(),
+    unit: ReportUnitSchema,
+    aggregation: z.enum(["p95", "rate", "ratio", "count"]).optional(),
+    /** baseline; renderer formats "(normal ~7s)". */
+    normal: z.number().optional(),
+    delta: ReportDeltaSchema.optional(),
+    series: ReportMetricSeriesSchema.optional(),
+    /** named sub-values for composite metrics (e.g. throughput { done, triggered }). */
+    breakdown: z.record(z.number()).optional(),
+    /** shown on a cause line INSTEAD of "(normal ~x)", e.g. "pinned 40 of last 60 min". */
+    annotation: z.object({ code: ReportReasonCodeSchema, value: z.number().optional() }).optional(),
+    /** "unknown" means `value` is a placeholder a consumer must not read as real. Absent = measured. */
+    availability: z.enum(["measured", "unknown"]).optional(),
+    severity: ReportSeveritySchema,
+});
+export const ReportRecommendationSchema = z.object({
+    code: ReportReasonCodeSchema,
+    link: ReportLinkKeySchema.optional(),
+});
+/** A footer line: an action, or the "do nothing" option (carries value). */
+export const ReportFooterEntrySchema = z.object({
+    code: ReportReasonCodeSchema,
+    link: ReportLinkKeySchema.optional(),
+    /** a computed fact (e.g. drainMinutes), never invented. */
+    value: z.number().optional(),
+});
+/** A ruled-out cause + its evidence, e.g. "not your code" (never emitted without evidence). */
+export const ReportExclusionSchema = z.object({
+    code: ReportReasonCodeSchema,
+    evidence: z.record(z.number()).optional(),
+});
+/** A measured fact backing the verdict. `ReportExclusion` states what the problem isn't. */
+export const ReportObservationSchema = z.object({
+    code: ReportReasonCodeSchema,
+    evidence: z.record(z.number()).optional(),
+});
+export const ReportFindingSchema = z.object({
+    /** "flow" | "execution" | "liveness" | future "infrastructure" | "billing" */
+    type: z.string(),
+    severity: ReportSeveritySchema,
+    /** Code for the state or cause, e.g. "env_limit_saturation" | "healthy". */
+    reason: ReportReasonCodeSchema,
+    /** Code for the "read:" line. Built last, may span findings. */
+    read: ReportReasonCodeSchema.optional(),
+    /** metric ids this finding covers, in causal order when degraded. */
+    metricIds: z.array(z.string()),
+    /** A single primary action. */
+    recommendation: ReportRecommendationSchema.optional(),
+    /** optional parenthetical — same shape as recommendation. */
+    hedge: ReportRecommendationSchema.optional(),
+    /** contiguous breach window of the driving metric -> "(last 40 min)". */
+    anomalyWindow: z.object({ minutes: z.number(), touchesEnd: z.boolean() }).optional(),
+    /** Which dimension and key own the problem. `of` is the denominator label the renderer prints. */
+    attribution: z
+        .object({ dim: z.string(), key: z.string(), share: z.number(), of: z.string() })
+        .optional(),
+    /** Ruled-out causes and evidence, rendered under the `read:` line. */
+    exclusions: z.array(ReportExclusionSchema).optional(),
+    /** Supporting facts, rendered under the `read:` line after the exclusions. */
+    observations: z.array(ReportObservationSchema).optional(),
+});
+export const ReportSummaryStatementSchema = z.object({
+    findingType: z.string(),
+    severity: ReportSeveritySchema,
+    /** Renders from (findingType, severity) unless a reason is present. */
+    reason: ReportReasonCodeSchema.optional(),
+});
+export const ReportLinkSchema = z.object({
+    key: ReportLinkKeySchema,
+    label: z.string(),
+    url: z.string(),
+});
+export const ReportViewModelSchema = z.object({
+    /** "health" | "cost" | … */
+    title: z.string(),
+    /** "prod" */
+    scope: z.string(),
+    /** "last 1h" */
+    period: z.string(),
+    /** "vs your 7d normal" */
+    baselineLabel: z.string().optional(),
+    /** ISO string. Passed in, never read from the clock inside interpret. */
+    generatedAt: z.string(),
+    /** live window length in minutes — lets the renderer say "of last 60 min". */
+    windowMinutes: z.number(),
+    summary: z.object({
+        severity: ReportSeveritySchema,
+        statements: z.array(ReportSummaryStatementSchema),
+    }),
+    findings: z.array(ReportFindingSchema),
+    metrics: z.array(ReportMetricSchema),
+    /** dense structured payload for agents. */
+    facts: z.record(z.unknown()),
+    links: z.array(ReportLinkSchema),
+    /** dominant finding's action + optional "do nothing" option. Max two entries. */
+    footer: z.array(ReportFooterEntrySchema),
+});
+//# sourceMappingURL=reports.js.map

package/dist/esm/v3/schemas/reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.js","sourceRoot":"","sources":["../../../../src/v3/schemas/reports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iGAAiG;AACjG,+FAA+F;AAE/F,MAAM,cAAc,GAA2B,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;AACxF,MAAM,aAAa,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC,MAAM;AAExC,oGAAoG;AACpG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,EAAE;KACR,KAAK,CACJ,kBAAkB,EAClB,gIAAgI,CACjI;KACA,MAAM;AACL,8FAA8F;AAC9F,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,aAAa,EACnF,+BAA+B,CAChC,CAAC;AAIJ,0FAA0F;AAC1F,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAIvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAGnE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAG3E,yEAAyE;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;AAGjD,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;AAG9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,+EAA+E;IAC/E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC3B,8EAA8E;IAC9E,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;CACxC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,kFAAkF;IAClF,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;IACjE,iDAAiD;IACjD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,KAAK,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACnC,MAAM,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAC3C,oFAAoF;IACpF,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC1C,uFAAuF;IACvF,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC/F,oGAAoG;IACpG,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxD,QAAQ,EAAE,oBAAoB;CAC/B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,IAAI,EAAE,sBAAsB;IAC5B,IAAI,EAAE,mBAAmB,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAGH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,sBAAsB;IAC5B,IAAI,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IACpC,2DAA2D;IAC3D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAGH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,sBAAsB;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAGH,4FAA4F;AAC5F,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,sBAAsB;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,8EAA8E;IAC9E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,oBAAoB;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,sBAAsB;IAC9B,gEAAgE;IAChE,IAAI,EAAE,sBAAsB,CAAC,QAAQ,EAAE;IACvC,qEAAqE;IACrE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9B,+BAA+B;IAC/B,cAAc,EAAE,0BAA0B,CAAC,QAAQ,EAAE;IACrD,6DAA6D;IAC7D,KAAK,EAAE,0BAA0B,CAAC,QAAQ,EAAE;IAC5C,yEAAyE;IACzE,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpF,kGAAkG;IAClG,WAAW,EAAE,CAAC;SACX,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;SAC/E,QAAQ,EAAE;IACb,sEAAsE;IACtE,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IACrD,8EAA8E;IAC9E,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,QAAQ,EAAE;CAC1D,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,oBAAoB;IAC9B,uEAAuE;IACvE,MAAM,EAAE,sBAAsB,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,GAAG,EAAE,mBAAmB;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;CAChB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,4BAA4B;IAC5B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,aAAa;IACb,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,gBAAgB;IAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,0BAA0B;IAC1B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,yEAAyE;IACzE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,8EAA8E;IAC9E,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IAEzB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,QAAQ,EAAE,oBAAoB;QAC9B,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,4BAA4B,CAAC;KAClD,CAAC;IACF,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACpC,2CAA2C;IAC3C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IAChC,iFAAiF;IACjF,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;CACzC,CAAC,CAAC"}