@sentry/junior-plugin-api 0.117.0 → 0.119.0

package/README.md

@@ -8,6 +8,11 @@ exported TypeScript types and runtime validators are authoritative.
 Use `defineJuniorPlugin({ manifest, hooks, tasks, cli, model })`. A plugin name
 is a lowercase identifier and is unique within the enabled app plugin set.
 
+Packages with JavaScript registration export one callable factory named
+`<domain>Plugin`, such as `githubPlugin(options?)`. Do not use a public
+`create<Domain>Plugin` alias or export a prebuilt registration. Call the factory
+even when it accepts no options.
+
 A plugin may instead be a declarative `plugin.yaml` package when it has no
 host-executed hooks. Do not combine an inline manifest with a second YAML
 definition for the same plugin.
@@ -21,7 +26,8 @@ The manifest declares runtime metadata such as:
 - provider domains, grants, OAuth, API-header transformations, and safe command
   environment placeholders;
 - runtime dependencies and snapshot installation steps;
-- configuration fields.
+- configuration fields;
+- signed-in user pages backed by core-owned discovery and read routes.
 
 Manifest values are validated before runtime activation. Secret deployment
 values remain host-only; sandbox-exposed command environment must be explicitly
@@ -39,6 +45,18 @@ reports, and other typed hook surfaces exported by this package.
 - Tool hooks return model-visible schemas aligned with their executor inputs.
 - Host-owned structured model and embedding calls do not expose provider
   credentials to plugins.
+- User page readers receive the signed-in email plus runtime-owned actors linked
+  to that user. Plugins return bounded data and do not mount their own page
+  routes or browser code.
+
+## User Pages
+
+Register signed-in pages through `userPages` beside `hooks`, `tasks`, and `cli`.
+Each definition owns its navigation metadata and `read(ctx)` function, so a
+page cannot be advertised without an implementation. Core owns discovery,
+authentication, actor resolution, routing, response validation, and rendering.
+The initial response type is the bounded `list` page; add another core-rendered
+type only when a concrete product need proves it.
 
 ## Durable Work
 

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export * from "./hooks";
 export * from "./cli";
 export * from "./manifest";
 export * from "./registration";
+export * from "./user-pages";

package/dist/index.js

@@ -462,6 +462,7 @@ var EgressPolicyDenied = class extends Error {
 
 // src/registration.ts
 var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+var USER_PAGE_ID_RE = /^[a-z][a-z0-9-]*$/;
 function defineJuniorPlugin(plugin) {
   if ("pluginConfig" in plugin) {
     throw new Error(
@@ -496,10 +497,69 @@ function defineJuniorPlugin(plugin) {
       `Junior plugin "${name}" manifest.description is required.`
     );
   }
+  if (plugin.userPages !== void 0 && !Array.isArray(plugin.userPages)) {
+    throw new Error(`Junior plugin "${name}" userPages must be an array.`);
+  }
+  const userPageIds = /* @__PURE__ */ new Set();
+  for (const page of plugin.userPages ?? []) {
+    if (!page || typeof page !== "object") {
+      throw new Error(`Junior plugin "${name}" user pages must be objects.`);
+    }
+    if (typeof page.id !== "string" || page.id.length > 64 || !USER_PAGE_ID_RE.test(page.id)) {
+      throw new Error(
+        `Junior plugin "${name}" user page id "${page.id}" must be a lowercase identifier.`
+      );
+    }
+    if (userPageIds.has(page.id)) {
+      throw new Error(
+        `Junior plugin "${name}" has duplicate user page id "${page.id}".`
+      );
+    }
+    if (typeof page.label !== "string" || !page.label.trim() || page.label.length > 80 || typeof page.description !== "string" || !page.description.trim() || page.description.length > 500) {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires label and description.`
+      );
+    }
+    if (typeof page.read !== "function") {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires a read function.`
+      );
+    }
+    userPageIds.add(page.id);
+  }
   return {
     ...plugin
   };
 }
+
+// src/user-pages.ts
+import { z as z9 } from "zod";
+var userPageIdSchema = nonBlankStringSchema.max(64).regex(/^[a-z][a-z0-9-]*$/);
+var userPageLabelSchema = nonBlankStringSchema.max(80);
+var userPageDescriptionSchema = nonBlankStringSchema.max(500);
+var pluginUserPageMetadataSchema = z9.object({
+  label: nonBlankStringSchema.max(80),
+  value: nonBlankStringSchema.max(500)
+}).strict();
+var pluginUserPageRecordSchema = z9.object({
+  description: nonBlankStringSchema.max(1e3).optional(),
+  id: nonBlankStringSchema.max(128),
+  metadata: z9.array(pluginUserPageMetadataSchema).max(8).optional(),
+  title: nonBlankStringSchema.max(4e3)
+}).strict();
+var pluginUserPageContentSchema = z9.object({
+  emptyText: nonBlankStringSchema.max(500).optional(),
+  records: z9.array(pluginUserPageRecordSchema).max(100),
+  type: z9.literal("list")
+}).strict();
+var pluginUserPageLinkSchema = z9.object({
+  description: userPageDescriptionSchema,
+  id: userPageIdSchema,
+  label: userPageLabelSchema,
+  pluginDisplayName: nonBlankStringSchema.max(200),
+  pluginName: nonBlankStringSchema.max(100)
+}).strict();
+var pluginUserPageLinksSchema = z9.array(pluginUserPageLinkSchema);
 export {
   EgressAuthRequired,
   EgressPolicyDenied,
@@ -537,6 +597,9 @@ export {
   pluginToolContinuationSchema,
   pluginToolErrorSchema,
   pluginToolResultSchema,
+  pluginUserPageContentSchema,
+  pluginUserPageLinkSchema,
+  pluginUserPageLinksSchema,
   promptContextSchema,
   promptMessageSchema,
   resourceEventSchema,

package/dist/registration.d.ts

@@ -2,6 +2,7 @@ import type { PluginCliDefinition } from "./cli";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
+import type { PluginUserPageDefinition } from "./user-pages";
 export interface PluginModelConfig {
     /** Host model family used when no explicit structured model id is configured. */
     structuredModel?: "default" | "fast";
@@ -15,6 +16,7 @@ export type PluginRegistrationInput = {
     model?: PluginModelConfig;
     packageName?: string;
     tasks?: PluginTasks;
+    userPages?: PluginUserPageDefinition[];
 };
 export interface PluginRegistration extends PluginRegistrationInput {
 }

package/dist/user-pages.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Core-rendered plugin user pages.
+ *
+ * Plugins own bounded data projection; Junior owns viewer authorization,
+ * routing, response validation, and browser rendering.
+ */
+import { z } from "zod";
+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>;
+    records: z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>>>;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+    type: z.ZodLiteral<"list">;
+}, z.core.$strict>;
+/** Validated content for the current core-rendered list page type. */
+export type PluginUserPageContent = z.output<typeof pluginUserPageContentSchema>;
+export declare const pluginUserPageLinkSchema: z.ZodObject<{
+    description: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodString;
+    pluginDisplayName: z.ZodString;
+    pluginName: z.ZodString;
+}, z.core.$strict>;
+export declare const pluginUserPageLinksSchema: z.ZodArray<z.ZodObject<{
+    description: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodString;
+    pluginDisplayName: z.ZodString;
+    pluginName: z.ZodString;
+}, z.core.$strict>>;
+/** Safe navigation metadata for one registered plugin user page. */
+export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
+/** Runtime-owned actor shapes that may belong to an authenticated viewer. */
+export type PluginUserPageActor = SlackActor | LocalActor;
+/** Trusted host context supplied while reading one plugin user page. */
+export interface PluginUserPageContext extends PluginContext {
+    viewer: {
+        actors: PluginUserPageActor[];
+        email: string;
+    };
+}
+/** Navigation metadata and reader for one core-rendered plugin user page. */
+export interface PluginUserPageDefinition {
+    description: string;
+    id: string;
+    label: string;
+    read(ctx: PluginUserPageContext): Promise<PluginUserPageContent> | PluginUserPageContent;
+}

package/package.json

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

package/src/index.ts

@@ -23,3 +23,4 @@ export * from "./hooks";
 export * from "./cli";
 export * from "./manifest";
 export * from "./registration";
+export * from "./user-pages";

package/src/registration.ts

@@ -2,6 +2,7 @@ import type { PluginCliDefinition } from "./cli";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
+import type { PluginUserPageDefinition } from "./user-pages";
 
 export interface PluginModelConfig {
   /** Host model family used when no explicit structured model id is configured. */
@@ -17,11 +18,13 @@ export type PluginRegistrationInput = {
   model?: PluginModelConfig;
   packageName?: string;
   tasks?: PluginTasks;
+  userPages?: PluginUserPageDefinition[];
 };
 
 export interface PluginRegistration extends PluginRegistrationInput {}
 
 const PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
+const USER_PAGE_ID_RE = /^[a-z][a-z0-9-]*$/;
 
 /** Define one Junior plugin registration for app and build-time wiring. */
 export function defineJuniorPlugin(
@@ -66,6 +69,47 @@ export function defineJuniorPlugin(
       `Junior plugin "${name}" manifest.description is required.`,
     );
   }
+  if (plugin.userPages !== undefined && !Array.isArray(plugin.userPages)) {
+    throw new Error(`Junior plugin "${name}" userPages must be an array.`);
+  }
+  const userPageIds = new Set<string>();
+  for (const page of plugin.userPages ?? []) {
+    if (!page || typeof page !== "object") {
+      throw new Error(`Junior plugin "${name}" user pages must be objects.`);
+    }
+    if (
+      typeof page.id !== "string" ||
+      page.id.length > 64 ||
+      !USER_PAGE_ID_RE.test(page.id)
+    ) {
+      throw new Error(
+        `Junior plugin "${name}" user page id "${page.id}" must be a lowercase identifier.`,
+      );
+    }
+    if (userPageIds.has(page.id)) {
+      throw new Error(
+        `Junior plugin "${name}" has duplicate user page id "${page.id}".`,
+      );
+    }
+    if (
+      typeof page.label !== "string" ||
+      !page.label.trim() ||
+      page.label.length > 80 ||
+      typeof page.description !== "string" ||
+      !page.description.trim() ||
+      page.description.length > 500
+    ) {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires label and description.`,
+      );
+    }
+    if (typeof page.read !== "function") {
+      throw new Error(
+        `Junior plugin "${name}" user page "${page.id}" requires a read function.`,
+      );
+    }
+    userPageIds.add(page.id);
+  }
   return {
     ...plugin,
   };

package/src/user-pages.ts

@@ -0,0 +1,81 @@
+/**
+ * Core-rendered plugin user pages.
+ *
+ * Plugins own bounded data projection; Junior owns viewer authorization,
+ * routing, response validation, and browser rendering.
+ */
+import { z } from "zod";
+import type { LocalActor, PluginContext, SlackActor } from "./context";
+import { nonBlankStringSchema } from "./schemas";
+
+const userPageIdSchema = nonBlankStringSchema
+  .max(64)
+  .regex(/^[a-z][a-z0-9-]*$/);
+const userPageLabelSchema = nonBlankStringSchema.max(80);
+const userPageDescriptionSchema = nonBlankStringSchema.max(500);
+
+const pluginUserPageMetadataSchema = z
+  .object({
+    label: nonBlankStringSchema.max(80),
+    value: nonBlankStringSchema.max(500),
+  })
+  .strict();
+
+const pluginUserPageRecordSchema = z
+  .object({
+    description: nonBlankStringSchema.max(1_000).optional(),
+    id: nonBlankStringSchema.max(128),
+    metadata: z.array(pluginUserPageMetadataSchema).max(8).optional(),
+    title: nonBlankStringSchema.max(4_000),
+  })
+  .strict();
+
+/** Bounded list content returned by a plugin-owned user page. */
+export const pluginUserPageContentSchema = z
+  .object({
+    emptyText: nonBlankStringSchema.max(500).optional(),
+    records: z.array(pluginUserPageRecordSchema).max(100),
+    type: z.literal("list"),
+  })
+  .strict();
+
+/** Validated content for the current core-rendered list page type. */
+export type PluginUserPageContent = z.output<
+  typeof pluginUserPageContentSchema
+>;
+
+export const pluginUserPageLinkSchema = z
+  .object({
+    description: userPageDescriptionSchema,
+    id: userPageIdSchema,
+    label: userPageLabelSchema,
+    pluginDisplayName: nonBlankStringSchema.max(200),
+    pluginName: nonBlankStringSchema.max(100),
+  })
+  .strict();
+
+export const pluginUserPageLinksSchema = z.array(pluginUserPageLinkSchema);
+
+/** Safe navigation metadata for one registered plugin user page. */
+export type PluginUserPageLink = z.output<typeof pluginUserPageLinkSchema>;
+
+/** Runtime-owned actor shapes that may belong to an authenticated viewer. */
+export type PluginUserPageActor = SlackActor | LocalActor;
+
+/** Trusted host context supplied while reading one plugin user page. */
+export interface PluginUserPageContext extends PluginContext {
+  viewer: {
+    actors: PluginUserPageActor[];
+    email: string;
+  };
+}
+
+/** Navigation metadata and reader for one core-rendered plugin user page. */
+export interface PluginUserPageDefinition {
+  description: string;
+  id: string;
+  label: string;
+  read(
+    ctx: PluginUserPageContext,
+  ): Promise<PluginUserPageContent> | PluginUserPageContent;
+}