@sentry/junior-plugin-api 0.126.0 → 0.127.0

package/dist/index.js

@@ -276,24 +276,94 @@ function definePromptContext(definition) {
 
 // src/resource-events.ts
 import { z as z5 } from "zod";
+var RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4e3;
+var RESOURCE_EVENT_TEXT_MAX_LENGTH = 8e3;
+var resourceEventTypeSchema = z5.string().regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/).describe(
+  "Canonical dotted event type, such as issue.closed or pull_request.review.changes_requested."
+);
+var resourceTypeSchema = z5.string().regex(/^[a-z][a-z0-9_]*$/).describe(
+  "Canonical plugin-defined resource type, such as issue or pull_request."
+);
+var pluginResourceEventTypeSchema = z5.object({
+  type: resourceTypeSchema,
+  supportedEvents: z5.array(resourceEventTypeSchema).min(1),
+  suggestedEvents: z5.array(resourceEventTypeSchema).optional()
+}).strict().superRefine((resourceType, context) => {
+  const supported = /* @__PURE__ */ new Set();
+  resourceType.supportedEvents.forEach((eventType, index) => {
+    if (supported.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Duplicate supported resource event type "${eventType}".`,
+        path: ["supportedEvents", index]
+      });
+    }
+    supported.add(eventType);
+  });
+  const suggested = /* @__PURE__ */ new Set();
+  resourceType.suggestedEvents?.forEach((eventType, index) => {
+    if (suggested.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Duplicate suggested resource event type "${eventType}".`,
+        path: ["suggestedEvents", index]
+      });
+    }
+    if (!supported.has(eventType)) {
+      context.addIssue({
+        code: "custom",
+        message: `Suggested resource event type "${eventType}" is not supported.`,
+        path: ["suggestedEvents", index]
+      });
+    }
+    suggested.add(eventType);
+  });
+});
+var pluginResourceEventsSchema = z5.object({
+  resourceTypes: z5.array(pluginResourceEventTypeSchema).min(1),
+  isEnabled: z5.function({ input: [], output: z5.boolean() }).optional(),
+  normalizeIdentifier: z5.function({ input: [z5.string()], output: z5.string() }).optional()
+}).strict().superRefine((registration, context) => {
+  const seen = /* @__PURE__ */ new Set();
+  registration.resourceTypes.forEach((resourceType, index) => {
+    if (seen.has(resourceType.type)) {
+      context.addIssue({
+        code: "custom",
+        message: `Duplicate resource type "${resourceType.type}".`,
+        path: ["resourceTypes", index, "type"]
+      });
+    }
+    seen.add(resourceType.type);
+  });
+});
+function normalizeResourceEventIdentifier(registration, identifier) {
+  const trimmed = identifier.trim();
+  const normalized = (registration?.normalizeIdentifier?.(trimmed) ?? trimmed).trim();
+  if (!normalized) {
+    throw new Error("Resource event identifier must not normalize to empty");
+  }
+  return normalized;
+}
 var subscribableResourceSchema = z5.object({
+  identifier: z5.string().min(1),
   label: z5.string().min(1),
-  provider: z5.string().min(1),
-  resourceRef: z5.string().min(1),
-  suggestedEvents: z5.array(z5.string().min(1)).optional(),
-  supportedEvents: z5.array(z5.string().min(1)),
-  type: z5.string().min(1)
+  namespace: z5.string().min(1),
+  suggestedEvents: z5.array(resourceEventTypeSchema).optional(),
+  supportedEvents: z5.array(resourceEventTypeSchema),
+  type: resourceTypeSchema
 }).strict();
-var resourceEventSchema = z5.object({
+var resourceEventInputSchema = z5.object({
   eventKey: z5.string().min(1),
-  eventType: z5.string().min(1),
+  eventType: resourceEventTypeSchema,
+  identifier: z5.string().min(1),
   occurredAtMs: z5.number().finite(),
-  provider: z5.string().min(1),
-  resourceRef: z5.string().min(1),
   terminal: z5.boolean().optional(),
-  trustedSummary: z5.string().min(1),
-  untrustedText: z5.string().optional()
+  trustedSummary: z5.string().min(1).transform((value) => value.slice(0, RESOURCE_EVENT_SUMMARY_MAX_LENGTH)),
+  untrustedText: z5.string().transform((value) => value.slice(0, RESOURCE_EVENT_TEXT_MAX_LENGTH)).optional()
 }).strict();
+var resourceEventSchema = resourceEventInputSchema.extend({
+  namespace: z5.string().min(1)
+});
 
 // src/tasks.ts
 import { z as z6 } from "zod";
@@ -597,6 +667,14 @@ function defineJuniorPlugin(plugin) {
       `Junior plugin "${name}" conversationEvents must be an array.`
     );
   }
+  if (plugin.resourceEvents !== void 0) {
+    const parsed = pluginResourceEventsSchema.safeParse(plugin.resourceEvents);
+    if (!parsed.success) {
+      throw new Error(`Junior plugin "${name}" resourceEvents is invalid.`, {
+        cause: parsed.error
+      });
+    }
+  }
   const conversationEventIds = /* @__PURE__ */ new Set();
   for (const event of plugin.conversationEvents ?? []) {
     if (!event || typeof event !== "object" && typeof event !== "function" || typeof event.parse !== "function" || typeof event.renderEvent !== "function") {
@@ -707,6 +785,8 @@ export {
   EgressPolicyDenied,
   PluginToolInputError,
   REQUIRED_TOOL_ANNOTATION_KEYS,
+  RESOURCE_EVENT_SUMMARY_MAX_LENGTH,
+  RESOURCE_EVENT_TEXT_MAX_LENGTH,
   actorSchema,
   conversationAnnotationInputSchema,
   conversationEventIconSchema,
@@ -728,6 +808,7 @@ export {
   localSourceSchema,
   missingToolAnnotationKeys,
   nonBlankStringSchema,
+  normalizeResourceEventIdentifier,
   platformSchema,
   pluginApiRouteRequestContextSchema,
   pluginAuthorizationSchema,
@@ -737,6 +818,8 @@ export {
   pluginCredentialSubjectSchema,
   pluginGrantSchema,
   pluginProviderAccountSchema,
+  pluginResourceEventTypeSchema,
+  pluginResourceEventsSchema,
   pluginRunContextSchema,
   pluginRunTranscriptEntrySchema,
   pluginRunTranscriptProvenanceSchema,
@@ -752,8 +835,11 @@ export {
   promptContextSchema,
   promptMessageSchema,
   replyAttributionSchema,
+  resourceEventInputSchema,
   resourceEventSchema,
+  resourceEventTypeSchema,
   resourceLinkAnnotationSchema,
+  resourceTypeSchema,
   slackActorSchema,
   slackDestinationSchema,
   slackSourceSchema,

package/dist/registration.d.ts

@@ -4,6 +4,7 @@ import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
 import type { PluginUserPageDefinition } from "./user-pages";
+import { type PluginResourceEvents } from "./resource-events";
 export interface PluginModelConfig {
     /** Host model family used when no explicit structured model id is configured. */
     structuredModel?: "default" | "fast";
@@ -17,6 +18,7 @@ export type PluginRegistrationInput = {
     manifest: PluginManifest;
     model?: PluginModelConfig;
     packageName?: string;
+    resourceEvents?: PluginResourceEvents;
     tasks?: PluginTasks;
     userPages?: PluginUserPageDefinition[];
 };

package/dist/resource-events.d.ts

@@ -1,25 +1,58 @@
 import { z } from "zod";
+export declare const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4000;
+export declare const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8000;
+/** Canonical dotted event type published and selected across plugins. */
+export declare const resourceEventTypeSchema: z.ZodString;
+export declare const resourceTypeSchema: z.ZodString;
+export declare const pluginResourceEventTypeSchema: z.ZodObject<{
+    type: z.ZodString;
+    supportedEvents: z.ZodArray<z.ZodString>;
+    suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const pluginResourceEventsSchema: z.ZodObject<{
+    resourceTypes: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        supportedEvents: z.ZodArray<z.ZodString>;
+        suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    isEnabled: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodBoolean>>;
+    normalizeIdentifier: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodString>>;
+}, z.core.$strict>;
+export type PluginResourceEventType = z.output<typeof pluginResourceEventTypeSchema>;
+export type PluginResourceEvents = z.output<typeof pluginResourceEventsSchema>;
+/** Apply a plugin's identifier convention at resource-event boundaries. */
+export declare function normalizeResourceEventIdentifier(registration: Pick<PluginResourceEvents, "normalizeIdentifier"> | undefined, identifier: string): string;
 export declare const subscribableResourceSchema: z.ZodObject<{
+    identifier: z.ZodString;
     label: z.ZodString;
-    provider: z.ZodString;
-    resourceRef: z.ZodString;
+    namespace: z.ZodString;
     suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
     supportedEvents: z.ZodArray<z.ZodString>;
     type: z.ZodString;
 }, z.core.$strict>;
 export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
+export declare const resourceEventInputSchema: z.ZodObject<{
+    eventKey: z.ZodString;
+    eventType: z.ZodString;
+    identifier: z.ZodString;
+    occurredAtMs: z.ZodNumber;
+    terminal: z.ZodOptional<z.ZodBoolean>;
+    trustedSummary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    untrustedText: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+export type ResourceEventInput = z.output<typeof resourceEventInputSchema>;
 export declare const resourceEventSchema: z.ZodObject<{
     eventKey: z.ZodString;
     eventType: z.ZodString;
+    identifier: z.ZodString;
     occurredAtMs: z.ZodNumber;
-    provider: z.ZodString;
-    resourceRef: z.ZodString;
     terminal: z.ZodOptional<z.ZodBoolean>;
-    trustedSummary: z.ZodString;
-    untrustedText: z.ZodOptional<z.ZodString>;
+    trustedSummary: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    untrustedText: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    namespace: z.ZodString;
 }, z.core.$strict>;
 export type ResourceEvent = z.output<typeof resourceEventSchema>;
 export interface ResourceEventPublisher {
-    /** Publish one normalized event whose provider matches the owning plugin name. */
-    publish(event: ResourceEvent): Promise<void>;
+    /** Publish one normalized event under the owning plugin's namespace. */
+    publish(event: ResourceEventInput): Promise<void>;
 }

package/package.json

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

package/src/registration.ts

@@ -4,6 +4,10 @@ import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
 import type { PluginUserPageDefinition } from "./user-pages";
+import {
+  pluginResourceEventsSchema,
+  type PluginResourceEvents,
+} from "./resource-events";
 
 export interface PluginModelConfig {
   /** Host model family used when no explicit structured model id is configured. */
@@ -19,6 +23,7 @@ export type PluginRegistrationInput = {
   manifest: PluginManifest;
   model?: PluginModelConfig;
   packageName?: string;
+  resourceEvents?: PluginResourceEvents;
   tasks?: PluginTasks;
   userPages?: PluginUserPageDefinition[];
 };
@@ -87,6 +92,14 @@ export function defineJuniorPlugin(
       `Junior plugin "${name}" conversationEvents must be an array.`,
     );
   }
+  if (plugin.resourceEvents !== undefined) {
+    const parsed = pluginResourceEventsSchema.safeParse(plugin.resourceEvents);
+    if (!parsed.success) {
+      throw new Error(`Junior plugin "${name}" resourceEvents is invalid.`, {
+        cause: parsed.error,
+      });
+    }
+  }
   const conversationEventIds = new Set<string>();
   for (const event of plugin.conversationEvents ?? []) {
     if (

package/src/resource-events.ts

@@ -1,34 +1,145 @@
 import { z } from "zod";
 
+export const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4_000;
+export const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8_000;
+
+/** Canonical dotted event type published and selected across plugins. */
+export const resourceEventTypeSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/)
+  .describe(
+    "Canonical dotted event type, such as issue.closed or pull_request.review.changes_requested.",
+  );
+
+export const resourceTypeSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9_]*$/)
+  .describe(
+    "Canonical plugin-defined resource type, such as issue or pull_request.",
+  );
+
+export const pluginResourceEventTypeSchema = z
+  .object({
+    type: resourceTypeSchema,
+    supportedEvents: z.array(resourceEventTypeSchema).min(1),
+    suggestedEvents: z.array(resourceEventTypeSchema).optional(),
+  })
+  .strict()
+  .superRefine((resourceType, context) => {
+    const supported = new Set<string>();
+    resourceType.supportedEvents.forEach((eventType, index) => {
+      if (supported.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate supported resource event type "${eventType}".`,
+          path: ["supportedEvents", index],
+        });
+      }
+      supported.add(eventType);
+    });
+    const suggested = new Set<string>();
+    resourceType.suggestedEvents?.forEach((eventType, index) => {
+      if (suggested.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate suggested resource event type "${eventType}".`,
+          path: ["suggestedEvents", index],
+        });
+      }
+      if (!supported.has(eventType)) {
+        context.addIssue({
+          code: "custom",
+          message: `Suggested resource event type "${eventType}" is not supported.`,
+          path: ["suggestedEvents", index],
+        });
+      }
+      suggested.add(eventType);
+    });
+  });
+
+export const pluginResourceEventsSchema = z
+  .object({
+    resourceTypes: z.array(pluginResourceEventTypeSchema).min(1),
+    isEnabled: z.function({ input: [], output: z.boolean() }).optional(),
+    normalizeIdentifier: z
+      .function({ input: [z.string()], output: z.string() })
+      .optional(),
+  })
+  .strict()
+  .superRefine((registration, context) => {
+    const seen = new Set<string>();
+    registration.resourceTypes.forEach((resourceType, index) => {
+      if (seen.has(resourceType.type)) {
+        context.addIssue({
+          code: "custom",
+          message: `Duplicate resource type "${resourceType.type}".`,
+          path: ["resourceTypes", index, "type"],
+        });
+      }
+      seen.add(resourceType.type);
+    });
+  });
+
+export type PluginResourceEventType = z.output<
+  typeof pluginResourceEventTypeSchema
+>;
+export type PluginResourceEvents = z.output<typeof pluginResourceEventsSchema>;
+
+/** Apply a plugin's identifier convention at resource-event boundaries. */
+export function normalizeResourceEventIdentifier(
+  registration: Pick<PluginResourceEvents, "normalizeIdentifier"> | undefined,
+  identifier: string,
+): string {
+  const trimmed = identifier.trim();
+  const normalized = (
+    registration?.normalizeIdentifier?.(trimmed) ?? trimmed
+  ).trim();
+  if (!normalized) {
+    throw new Error("Resource event identifier must not normalize to empty");
+  }
+  return normalized;
+}
+
 export const subscribableResourceSchema = z
   .object({
+    identifier: z.string().min(1),
     label: z.string().min(1),
-    provider: z.string().min(1),
-    resourceRef: z.string().min(1),
-    suggestedEvents: z.array(z.string().min(1)).optional(),
-    supportedEvents: z.array(z.string().min(1)),
-    type: z.string().min(1),
+    namespace: z.string().min(1),
+    suggestedEvents: z.array(resourceEventTypeSchema).optional(),
+    supportedEvents: z.array(resourceEventTypeSchema),
+    type: resourceTypeSchema,
   })
   .strict();
 
 export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
 
-export const resourceEventSchema = z
+export const resourceEventInputSchema = z
   .object({
     eventKey: z.string().min(1),
-    eventType: z.string().min(1),
+    eventType: resourceEventTypeSchema,
+    identifier: z.string().min(1),
     occurredAtMs: z.number().finite(),
-    provider: z.string().min(1),
-    resourceRef: z.string().min(1),
     terminal: z.boolean().optional(),
-    trustedSummary: z.string().min(1),
-    untrustedText: z.string().optional(),
+    trustedSummary: z
+      .string()
+      .min(1)
+      .transform((value) => value.slice(0, RESOURCE_EVENT_SUMMARY_MAX_LENGTH)),
+    untrustedText: z
+      .string()
+      .transform((value) => value.slice(0, RESOURCE_EVENT_TEXT_MAX_LENGTH))
+      .optional(),
   })
   .strict();
 
+export type ResourceEventInput = z.output<typeof resourceEventInputSchema>;
+
+export const resourceEventSchema = resourceEventInputSchema.extend({
+  namespace: z.string().min(1),
+});
+
 export type ResourceEvent = z.output<typeof resourceEventSchema>;
 
 export interface ResourceEventPublisher {
-  /** Publish one normalized event whose provider matches the owning plugin name. */
-  publish(event: ResourceEvent): Promise<void>;
+  /** Publish one normalized event under the owning plugin's namespace. */
+  publish(event: ResourceEventInput): Promise<void>;
 }