@sentry/junior-plugin-api 0.181.1 → 0.182.0

package/dist/index.js

@@ -357,10 +357,90 @@ var resourceEventTypeSchema = z5.string().regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z
 var resourceTypeSchema = z5.string().regex(/^[a-z][a-z0-9_]*$/).describe(
   "Canonical plugin-defined resource type, such as issue or pull_request."
 );
+var RESOURCE_EVENT_MATCH_FIELD_NAME = /^[a-z][a-zA-Z0-9]*$/;
+var resourceEventMatchFieldSchema = z5.object({
+  kind: z5.enum(["boolean", "string", "number"]),
+  description: z5.string().trim().min(1).max(200),
+  enum: z5.array(z5.string().min(1)).min(1).optional()
+}).strict().superRefine((field, context) => {
+  if (field.enum && field.kind !== "string") {
+    context.addIssue({
+      code: "custom",
+      message: 'Resource event match field enum requires kind "string".',
+      path: ["enum"]
+    });
+  }
+});
+var resourceEventMatchFieldsSchema = z5.record(z5.string().regex(RESOURCE_EVENT_MATCH_FIELD_NAME), resourceEventMatchFieldSchema).superRefine((fields, context) => {
+  if (Object.keys(fields).length > RESOURCE_EVENT_DATA_MAX_KEYS) {
+    context.addIssue({
+      code: "custom",
+      message: `Resource event match keys may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`
+    });
+  }
+});
+var resourceEventMatchSchema = z5.record(
+  z5.string().regex(RESOURCE_EVENT_MATCH_FIELD_NAME),
+  z5.union([
+    z5.boolean(),
+    z5.number().finite(),
+    z5.string().min(1),
+    z5.array(z5.union([z5.number().finite(), z5.string().min(1)])).min(1)
+  ])
+).superRefine((match, context) => {
+  if (Object.keys(match).length > RESOURCE_EVENT_DATA_MAX_KEYS) {
+    context.addIssue({
+      code: "custom",
+      message: `Resource event match may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`
+    });
+  }
+  for (const [key, value] of Object.entries(match)) {
+    if (!Array.isArray(value)) continue;
+    if (value.some((entry) => typeof entry === "boolean")) {
+      context.addIssue({
+        code: "custom",
+        message: `Resource event match field "${key}" cannot use a boolean list.`,
+        path: [key]
+      });
+    }
+  }
+});
+function stableMatchValue(value) {
+  if (!Array.isArray(value)) return value;
+  return [...value].sort((left, right) => {
+    if (typeof left === "number" && typeof right === "number") {
+      return left - right;
+    }
+    return String(left).localeCompare(String(right));
+  });
+}
+function stableResourceEventMatchKey(match) {
+  if (!match || Object.keys(match).length === 0) return "";
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(match).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => [key, stableMatchValue(value)])
+    )
+  );
+}
+function resourceEventMatches(match, data) {
+  if (!match || Object.keys(match).length === 0) return true;
+  if (!data) return false;
+  for (const [key, expected] of Object.entries(match)) {
+    const actual = data[key];
+    if (actual === void 0) return false;
+    if (Array.isArray(expected)) {
+      if (!expected.some((value) => Object.is(value, actual))) return false;
+      continue;
+    }
+    if (!Object.is(expected, actual)) return false;
+  }
+  return true;
+}
 var pluginResourceEventTypeSchema = z5.object({
   type: resourceTypeSchema,
   supportedEvents: z5.array(resourceEventTypeSchema).min(1),
   suggestedEvents: z5.array(resourceEventTypeSchema).optional(),
+  matchFields: resourceEventMatchFieldsSchema.optional(),
   guidance: z5.record(
     resourceEventTypeSchema,
     z5.string().trim().min(1).max(RESOURCE_EVENT_GUIDANCE_MAX_LENGTH)
@@ -945,6 +1025,10 @@ export {
   replyAttributionSchema,
   resourceEventDataSchema,
   resourceEventInputSchema,
+  resourceEventMatchFieldSchema,
+  resourceEventMatchFieldsSchema,
+  resourceEventMatchSchema,
+  resourceEventMatches,
   resourceEventSchema,
   resourceEventSubscriptionResultSchema,
   resourceEventTypeSchema,
@@ -955,6 +1039,7 @@ export {
   slackSourceSchema,
   sourceSchema,
   sourceVisibilitySchema,
+  stableResourceEventMatchKey,
   subscribableResourceSchema,
   systemActorSchema,
   toolApprovalModeSchema,

package/dist/resource-events.d.ts

@@ -4,15 +4,51 @@ export declare const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8000;
 export declare const RESOURCE_EVENT_DATA_MAX_KEYS = 32;
 export declare const RESOURCE_EVENT_DATA_MAX_JSON_BYTES = 4000;
 export declare const RESOURCE_EVENT_GUIDANCE_MAX_LENGTH = 1000;
-/** Small trusted facts from the plugin. The agent should not look these up again. */
+/** Small trusted data from the plugin. The agent should not look these up again. */
 export declare const resourceEventDataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 /** Canonical dotted event type published and selected across plugins. */
 export declare const resourceEventTypeSchema: z.ZodString;
 export declare const resourceTypeSchema: z.ZodString;
+/** One exact value a watch or event task may require on trusted event data. */
+export declare const resourceEventMatchFieldSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+    }>;
+    description: z.ZodString;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const resourceEventMatchFieldsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    kind: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+    }>;
+    description: z.ZodString;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+/** Exact trusted values required before a watch or event task runs. */
+export declare const resourceEventMatchSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>]>>;
+export type ResourceEventMatch = z.output<typeof resourceEventMatchSchema>;
+export type ResourceEventMatchFields = z.output<typeof resourceEventMatchFieldsSchema>;
+/** Stable JSON for one match object. List order does not matter. */
+export declare function stableResourceEventMatchKey(match: ResourceEventMatch | undefined): string;
+/** Return whether trusted event data matches one exact match object. */
+export declare function resourceEventMatches(match: ResourceEventMatch | undefined, data: ResourceEventData | undefined): boolean;
 export declare const pluginResourceEventTypeSchema: z.ZodObject<{
     type: z.ZodString;
     supportedEvents: z.ZodArray<z.ZodString>;
     suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    matchFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+        }>;
+        description: z.ZodString;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
     guidance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 export declare const pluginResourceEventsSchema: z.ZodObject<{
@@ -20,6 +56,15 @@ export declare const pluginResourceEventsSchema: z.ZodObject<{
         type: z.ZodString;
         supportedEvents: z.ZodArray<z.ZodString>;
         suggestedEvents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        matchFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            kind: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+            }>;
+            description: z.ZodString;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
         guidance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>;
     isEnabled: z.ZodOptional<z.ZodFunction<z.ZodTuple<readonly [], null>, z.ZodBoolean>>;

package/package.json

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

package/src/resource-events.ts

@@ -6,7 +6,7 @@ export const RESOURCE_EVENT_DATA_MAX_KEYS = 32;
 export const RESOURCE_EVENT_DATA_MAX_JSON_BYTES = 4_000;
 export const RESOURCE_EVENT_GUIDANCE_MAX_LENGTH = 1_000;
 
-/** Small trusted facts from the plugin. The agent should not look these up again. */
+/** Small trusted data from the plugin. The agent should not look these up again. */
 export const resourceEventDataSchema = z
   .record(z.string(), z.unknown())
   .superRefine((value, context) => {
@@ -43,11 +43,122 @@ export const resourceTypeSchema = z
     "Canonical plugin-defined resource type, such as issue or pull_request.",
   );
 
+const RESOURCE_EVENT_MATCH_FIELD_NAME =
+  /^[a-z][a-zA-Z0-9]*$/;
+
+/** One exact value a watch or event task may require on trusted event data. */
+export const resourceEventMatchFieldSchema = z
+  .object({
+    kind: z.enum(["boolean", "string", "number"]),
+    description: z.string().trim().min(1).max(200),
+    enum: z.array(z.string().min(1)).min(1).optional(),
+  })
+  .strict()
+  .superRefine((field, context) => {
+    if (field.enum && field.kind !== "string") {
+      context.addIssue({
+        code: "custom",
+        message: 'Resource event match field enum requires kind "string".',
+        path: ["enum"],
+      });
+    }
+  });
+
+export const resourceEventMatchFieldsSchema = z
+  .record(z.string().regex(RESOURCE_EVENT_MATCH_FIELD_NAME), resourceEventMatchFieldSchema)
+  .superRefine((fields, context) => {
+    if (Object.keys(fields).length > RESOURCE_EVENT_DATA_MAX_KEYS) {
+      context.addIssue({
+        code: "custom",
+        message: `Resource event match keys may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`,
+      });
+    }
+  });
+
+/** Exact trusted values required before a watch or event task runs. */
+export const resourceEventMatchSchema = z
+  .record(
+    z.string().regex(RESOURCE_EVENT_MATCH_FIELD_NAME),
+    z.union([
+      z.boolean(),
+      z.number().finite(),
+      z.string().min(1),
+      z.array(z.union([z.number().finite(), z.string().min(1)])).min(1),
+    ]),
+  )
+  .superRefine((match, context) => {
+    if (Object.keys(match).length > RESOURCE_EVENT_DATA_MAX_KEYS) {
+      context.addIssue({
+        code: "custom",
+        message: `Resource event match may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`,
+      });
+    }
+    for (const [key, value] of Object.entries(match)) {
+      if (!Array.isArray(value)) continue;
+      if (value.some((entry) => typeof entry === "boolean")) {
+        context.addIssue({
+          code: "custom",
+          message: `Resource event match field "${key}" cannot use a boolean list.`,
+          path: [key],
+        });
+      }
+    }
+  });
+
+export type ResourceEventMatch = z.output<typeof resourceEventMatchSchema>;
+export type ResourceEventMatchFields = z.output<
+  typeof resourceEventMatchFieldsSchema
+>;
+
+function stableMatchValue(value: ResourceEventMatch[string]): unknown {
+  if (!Array.isArray(value)) return value;
+  return [...value].sort((left, right) => {
+    if (typeof left === "number" && typeof right === "number") {
+      return left - right;
+    }
+    return String(left).localeCompare(String(right));
+  });
+}
+
+/** Stable JSON for one match object. List order does not matter. */
+export function stableResourceEventMatchKey(
+  match: ResourceEventMatch | undefined,
+): string {
+  if (!match || Object.keys(match).length === 0) return "";
+  return JSON.stringify(
+    Object.fromEntries(
+      Object.entries(match)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => [key, stableMatchValue(value)]),
+    ),
+  );
+}
+
+/** Return whether trusted event data matches one exact match object. */
+export function resourceEventMatches(
+  match: ResourceEventMatch | undefined,
+  data: ResourceEventData | undefined,
+): boolean {
+  if (!match || Object.keys(match).length === 0) return true;
+  if (!data) return false;
+  for (const [key, expected] of Object.entries(match)) {
+    const actual = data[key];
+    if (actual === undefined) return false;
+    if (Array.isArray(expected)) {
+      if (!expected.some((value) => Object.is(value, actual))) return false;
+      continue;
+    }
+    if (!Object.is(expected, actual)) return false;
+  }
+  return true;
+}
+
 export const pluginResourceEventTypeSchema = z
   .object({
     type: resourceTypeSchema,
     supportedEvents: z.array(resourceEventTypeSchema).min(1),
     suggestedEvents: z.array(resourceEventTypeSchema).optional(),
+    matchFields: resourceEventMatchFieldsSchema.optional(),
     guidance: z
       .record(
         resourceEventTypeSchema,