@sentry/junior-plugin-api 0.123.0 → 0.124.1

package/README.md

@@ -60,6 +60,9 @@ Register signed-in pages through `userPages` beside `hooks`, `tasks`, and `cli`.
 Each definition owns its navigation metadata and `read(ctx, input)` function,
 so a page cannot be advertised without an implementation. List readers receive
 validated search and cursor input and may return an opaque continuation cursor.
+Set `navigation: "primary"` for a top-level dashboard navigation item. The
+default `profile` placement keeps account-oriented pages in the signed-in user
+menu. Junior always renders core System navigation after plugin pages.
 Records may expose bounded `DELETE` actions inside their own authenticated
 plugin API namespace. Core owns discovery, authentication, actor resolution,
 routing, response validation, rendering, confirmation, and query state.
@@ -88,9 +91,10 @@ routing, response validation, rendering, confirmation, and query state.
 Register plugin-owned event definitions through `conversationEvents`. A
 definition owns one local name, version, content schema, and `renderEvent()`
 projection. The active plugin context supplies the namespace, so plugins cannot
-emit native events or impersonate another plugin. Stored events remain durable
-when a plugin is removed, but normal transcript projection skips definitions
-that are not currently registered.
+emit native events or impersonate another plugin. The `junior` plugin name is
+reserved for host-owned native events. Stored events remain durable when a
+plugin is removed, but normal transcript projection skips definitions that are
+not currently registered.
 
 ## Database
 

package/dist/index.js

@@ -570,6 +570,11 @@ function defineJuniorPlugin(plugin) {
       `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`
     );
   }
+  if (name === "junior") {
+    throw new Error(
+      'Junior plugin registration name "junior" is reserved for native host events.'
+    );
+  }
   if (typeof manifest.displayName !== "string" || !manifest.displayName.trim()) {
     throw new Error(
       `Junior plugin "${name}" manifest.displayName is required.`
@@ -623,6 +628,11 @@ function defineJuniorPlugin(plugin) {
         `Junior plugin "${name}" user page "${page.id}" requires label and description.`
       );
     }
+    if (page.navigation !== void 0 && page.navigation !== "primary" && page.navigation !== "profile") {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" navigation must be "primary" or "profile".`
+      );
+    }
     if (typeof page.read !== "function") {
       throw new Error(
         `Junior plugin "${name}" user page "${page.id}" requires a read function.`
@@ -640,6 +650,13 @@ import { z as z10 } from "zod";
 var userPageIdSchema = nonBlankStringSchema.max(64).regex(/^[a-z][a-z0-9-]*$/);
 var userPageLabelSchema = nonBlankStringSchema.max(80);
 var userPageDescriptionSchema = nonBlankStringSchema.max(500);
+var userPageNavigationSchema = z10.enum(["primary", "profile"]);
+var pluginUserPageMetricSchema = z10.object({
+  detail: nonBlankStringSchema.max(500).optional(),
+  label: nonBlankStringSchema.max(80),
+  tone: z10.enum(["good", "neutral", "warning"]).optional(),
+  value: nonBlankStringSchema.max(120)
+}).strict();
 var pluginUserPageMetadataSchema = z10.object({
   label: nonBlankStringSchema.max(80),
   value: nonBlankStringSchema.max(500)
@@ -660,6 +677,7 @@ var pluginUserPageRecordSchema = z10.object({
 }).strict();
 var pluginUserPageContentSchema = z10.object({
   emptyText: nonBlankStringSchema.max(500).optional(),
+  metrics: z10.array(pluginUserPageMetricSchema).max(6).optional(),
   nextCursor: nonBlankStringSchema.max(1e3).optional(),
   records: z10.array(pluginUserPageRecordSchema).max(100),
   searchPlaceholder: nonBlankStringSchema.max(120).optional(),
@@ -669,12 +687,14 @@ var pluginUserPageLinkSchema = z10.object({
   description: userPageDescriptionSchema,
   id: userPageIdSchema,
   label: userPageLabelSchema,
+  navigation: userPageNavigationSchema,
   pluginDisplayName: nonBlankStringSchema.max(200),
   pluginName: nonBlankStringSchema.max(100)
 }).strict();
 var pluginUserPageLinksSchema = z10.array(pluginUserPageLinkSchema);
 var pluginUserPageInputSchema = z10.object({
   cursor: nonBlankStringSchema.max(1e3).optional(),
+  filter: nonBlankStringSchema.max(64).optional(),
   limit: z10.number().int().min(1).max(50),
   query: z10.string().trim().max(200).optional()
 }).strict();

package/dist/user-pages.d.ts

@@ -9,6 +9,16 @@ import type { LocalActor, PluginContext, SlackActor } from "./context";
 /** Bounded list content returned by a plugin-owned user page. */
 export declare const pluginUserPageContentSchema: z.ZodObject<{
     emptyText: z.ZodOptional<z.ZodString>;
+    metrics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        detail: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            warning: "warning";
+            good: "good";
+            neutral: "neutral";
+        }>>;
+        value: z.ZodString;
+    }, z.core.$strict>>>;
     nextCursor: z.ZodOptional<z.ZodString>;
     records: z.ZodArray<z.ZodObject<{
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -38,6 +48,10 @@ export declare const pluginUserPageLinkSchema: z.ZodObject<{
     description: z.ZodString;
     id: z.ZodString;
     label: z.ZodString;
+    navigation: z.ZodEnum<{
+        primary: "primary";
+        profile: "profile";
+    }>;
     pluginDisplayName: z.ZodString;
     pluginName: z.ZodString;
 }, z.core.$strict>;
@@ -45,6 +59,10 @@ export declare const pluginUserPageLinksSchema: z.ZodArray<z.ZodObject<{
     description: z.ZodString;
     id: z.ZodString;
     label: z.ZodString;
+    navigation: z.ZodEnum<{
+        primary: "primary";
+        profile: "profile";
+    }>;
     pluginDisplayName: z.ZodString;
     pluginName: z.ZodString;
 }, z.core.$strict>>;
@@ -53,6 +71,7 @@ export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
 /** Validated query state passed to one plugin user page reader. */
 export declare const pluginUserPageInputSchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodString>;
     limit: z.ZodNumber;
     query: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -71,5 +90,7 @@ export interface PluginUserPageDefinition {
     description: string;
     id: string;
     label: string;
+    /** Dashboard navigation surface where this page is linked. */
+    navigation?: "primary" | "profile";
     read(ctx: PluginUserPageContext, input: PluginUserPageInput): Promise<PluginUserPageContent> | PluginUserPageContent;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.123.0",
+  "version": "0.124.1",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/registration.ts

@@ -55,6 +55,11 @@ export function defineJuniorPlugin(
       `Junior plugin registration name "${name}" must be a lowercase plugin identifier.`,
     );
   }
+  if (name === "junior") {
+    throw new Error(
+      'Junior plugin registration name "junior" is reserved for native host events.',
+    );
+  }
   if (
     typeof manifest.displayName !== "string" ||
     !manifest.displayName.trim()
@@ -133,6 +138,15 @@ export function defineJuniorPlugin(
         `Junior plugin "${name}" user page "${page.id}" requires label and description.`,
       );
     }
+    if (
+      page.navigation !== undefined &&
+      page.navigation !== "primary" &&
+      page.navigation !== "profile"
+    ) {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" navigation must be "primary" or "profile".`,
+      );
+    }
     if (typeof page.read !== "function") {
       throw new Error(
         `Junior plugin "${name}" user page "${page.id}" requires a read function.`,

package/src/user-pages.ts

@@ -13,6 +13,16 @@ const userPageIdSchema = nonBlankStringSchema
   .regex(/^[a-z][a-z0-9-]*$/);
 const userPageLabelSchema = nonBlankStringSchema.max(80);
 const userPageDescriptionSchema = nonBlankStringSchema.max(500);
+const userPageNavigationSchema = z.enum(["primary", "profile"]);
+
+const pluginUserPageMetricSchema = z
+  .object({
+    detail: nonBlankStringSchema.max(500).optional(),
+    label: nonBlankStringSchema.max(80),
+    tone: z.enum(["good", "neutral", "warning"]).optional(),
+    value: nonBlankStringSchema.max(120),
+  })
+  .strict();
 
 const pluginUserPageMetadataSchema = z
   .object({
@@ -47,6 +57,7 @@ const pluginUserPageRecordSchema = z
 export const pluginUserPageContentSchema = z
   .object({
     emptyText: nonBlankStringSchema.max(500).optional(),
+    metrics: z.array(pluginUserPageMetricSchema).max(6).optional(),
     nextCursor: nonBlankStringSchema.max(1_000).optional(),
     records: z.array(pluginUserPageRecordSchema).max(100),
     searchPlaceholder: nonBlankStringSchema.max(120).optional(),
@@ -64,6 +75,7 @@ export const pluginUserPageLinkSchema = z
     description: userPageDescriptionSchema,
     id: userPageIdSchema,
     label: userPageLabelSchema,
+    navigation: userPageNavigationSchema,
     pluginDisplayName: nonBlankStringSchema.max(200),
     pluginName: nonBlankStringSchema.max(100),
   })
@@ -78,6 +90,7 @@ export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
 export const pluginUserPageInputSchema = z
   .object({
     cursor: nonBlankStringSchema.max(1_000).optional(),
+    filter: nonBlankStringSchema.max(64).optional(),
     limit: z.number().int().min(1).max(50),
     query: z.string().trim().max(200).optional(),
   })
@@ -101,6 +114,8 @@ export interface PluginUserPageDefinition {
   description: string;
   id: string;
   label: string;
+  /** Dashboard navigation surface where this page is linked. */
+  navigation?: "primary" | "profile";
   read(
     ctx: PluginUserPageContext,
     input: PluginUserPageInput,