@sentry/junior-plugin-api 0.198.0 → 0.199.0

package/src/resource-events.ts

@@ -1,320 +0,0 @@
-import { z } from "zod";
-
-export const RESOURCE_EVENT_SUMMARY_MAX_LENGTH = 4_000;
-export const RESOURCE_EVENT_TEXT_MAX_LENGTH = 8_000;
-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 data from the plugin. The agent should not look these up again. */
-export const resourceEventDataSchema = z
-  .record(z.string(), z.unknown())
-  .superRefine((value, context) => {
-    const keys = Object.keys(value);
-    if (keys.length > RESOURCE_EVENT_DATA_MAX_KEYS) {
-      context.addIssue({
-        code: "custom",
-        message: `Resource event data may include at most ${RESOURCE_EVENT_DATA_MAX_KEYS} keys.`,
-      });
-    }
-    const jsonBytes = new TextEncoder().encode(
-      JSON.stringify(value),
-    ).byteLength;
-    if (jsonBytes > RESOURCE_EVENT_DATA_MAX_JSON_BYTES) {
-      context.addIssue({
-        code: "custom",
-        message: `Resource event data may be at most ${RESOURCE_EVENT_DATA_MAX_JSON_BYTES} JSON bytes.`,
-      });
-    }
-  });
-
-/** 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.",
-  );
-
-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,
-        z.string().trim().min(1).max(RESOURCE_EVENT_GUIDANCE_MAX_LENGTH),
-      )
-      .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);
-    });
-    for (const eventType of Object.keys(resourceType.guidance ?? {})) {
-      if (!supported.has(eventType)) {
-        context.addIssue({
-          code: "custom",
-          message: `Guidance resource event type "${eventType}" is not supported.`,
-          path: ["guidance", 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),
-    namespace: z.string().min(1),
-    suggestedEvents: z.array(resourceEventTypeSchema).optional(),
-    supportedEvents: z.array(resourceEventTypeSchema),
-    type: resourceTypeSchema,
-  })
-  .strict();
-
-export type SubscribableResource = z.output<typeof subscribableResourceSchema>;
-
-/** Result returned after a temporary resource subscription is created. */
-export const resourceEventSubscriptionResultSchema = z
-  .object({
-    events: z.array(resourceEventTypeSchema).min(1),
-    id: z.string().min(1),
-  })
-  .strict();
-
-export type ResourceEventSubscriptionResult = z.output<
-  typeof resourceEventSubscriptionResultSchema
->;
-
-export const resourceEventInputSchema = z
-  .object({
-    eventKey: z.string().min(1),
-    eventType: resourceEventTypeSchema,
-    identifier: z.string().min(1),
-    occurredAtMs: z.number().finite(),
-    terminal: z.boolean().optional(),
-    trustedSummary: z
-      .string()
-      .min(1)
-      .transform((value) => value.slice(0, RESOURCE_EVENT_SUMMARY_MAX_LENGTH)),
-    /** Trusted structured facts. Prefer ids and urls over long prose. */
-    data: resourceEventDataSchema.optional(),
-    untrustedText: z
-      .string()
-      .transform((value) => value.slice(0, RESOURCE_EVENT_TEXT_MAX_LENGTH))
-      .optional(),
-  })
-  .strict();
-
-export type ResourceEventData = z.output<typeof resourceEventDataSchema>;
-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 under the owning plugin's namespace. */
-  publish(event: ResourceEventInput): Promise<void>;
-  /**
-   * Return match keys used by active watches or event tasks for these
-   * identifiers and event types. Plugins use this to load optional trusted
-   * data only when a filter needs it.
-   */
-  neededMatchKeys?(input: {
-    eventTypes: string[];
-    identifiers: string[];
-  }): Promise<string[]>;
-}

package/src/schemas.ts

@@ -1,348 +0,0 @@
-import { z } from "zod";
-
-const slackTeamIdSchema = z.string().regex(/^T[A-Z0-9]+$/);
-const slackConversationIdSchema = z.string().regex(/^(C|G|D)[A-Z0-9]+$/);
-const localConversationIdSchema = z
-  .string()
-  .regex(/^local:[a-z0-9_-]+:[a-z0-9][a-z0-9_-]*$/);
-/** Exact non-blank actor user id that rejects the sentinel "unknown". */
-export const actorUserIdSchema = z
-  .string()
-  .min(1)
-  .refine(
-    (value) => value === value.trim() && value.toLowerCase() !== "unknown",
-  );
-const exactActorUserIdSchema = actorUserIdSchema;
-
-export const nonBlankStringSchema = z
-  .string()
-  .refine((value) => value.trim().length > 0);
-const exactNonBlankStringSchema = nonBlankStringSchema.refine(
-  (value) => value === value.trim(),
-);
-
-/** Fields shared by every Location. */
-const baseLocationSchema = z
-  .object({
-    /** Stable SQL identity used by Location configuration and reporting. */
-    id: nonBlankStringSchema,
-    provider: exactNonBlankStringSchema,
-  })
-  .strict();
-
-/** Complete Slack Location associated with a Conversation. */
-export const slackLocationSchema = baseLocationSchema
-  .extend({
-    provider: z.literal("slack"),
-    teamId: slackTeamIdSchema,
-    channelId: slackConversationIdSchema,
-    threadTs: exactNonBlankStringSchema.optional(),
-  })
-  .strict();
-
-/** Complete Location types supported by Junior. */
-export const locationSchema = z.discriminatedUnion("provider", [
-  slackLocationSchema,
-]);
-
-/** Runtime platform names supported by plugin public contracts. */
-export const platformSchema = z.enum(["slack", "local"]);
-
-/** Runtime source visibility visible to plugins. */
-export const sourceVisibilitySchema = z.enum(["public", "private"]);
-
-/** Provider-neutral visibility of a routed destination. */
-export const destinationVisibilitySchema = z.enum(["public", "private"]);
-
-const slackAddressSchema = z
-  .object({
-    platform: z.literal("slack"),
-    teamId: slackTeamIdSchema,
-    channelId: slackConversationIdSchema,
-  })
-  .strict();
-
-/** Runtime-owned Slack address for routing future work or side effects. */
-export const slackDestinationSchema = slackAddressSchema;
-
-/** Runtime-owned local CLI conversation address. */
-export const localDestinationSchema = z
-  .object({
-    platform: z.literal("local"),
-    conversationId: localConversationIdSchema,
-  })
-  .strict();
-
-/** Runtime-owned provider-neutral address for routing future work or side effects. */
-export const destinationSchema = z.discriminatedUnion("platform", [
-  slackDestinationSchema,
-  localDestinationSchema,
-]);
-
-/** Runtime-owned Slack input Source. */
-export const slackSourceSchema = z
-  .object({
-    kind: z.literal("slack"),
-    teamId: slackTeamIdSchema,
-    channelId: slackConversationIdSchema,
-    visibility: sourceVisibilitySchema,
-    messageTs: nonBlankStringSchema.optional(),
-    threadTs: nonBlankStringSchema.optional(),
-  })
-  .strict();
-
-/** Runtime-owned local CLI input Source. */
-export const localSourceSchema = z
-  .object({
-    kind: z.literal("local"),
-    visibility: z.literal("private"),
-    conversationId: localConversationIdSchema,
-  })
-  .strict();
-
-/** Runtime-owned dashboard input Source. */
-export const webSourceSchema = z
-  .object({
-    kind: z.literal("web"),
-    visibility: sourceVisibilitySchema,
-    // Web can continue any existing conversation id, including Slack roots.
-    conversationId: exactNonBlankStringSchema,
-  })
-  .strict();
-
-/** Runtime-owned Resource event input Source. */
-export const resourceEventSourceSchema = z
-  .object({
-    kind: z.literal("resource_event"),
-    eventKey: exactNonBlankStringSchema,
-    eventType: exactNonBlankStringSchema,
-    identifier: exactNonBlankStringSchema,
-    namespace: exactNonBlankStringSchema,
-  })
-  .strict();
-
-/** Runtime-owned Scheduled task input Source. */
-export const scheduledTaskSourceSchema = z
-  .object({ kind: z.literal("scheduled_task") })
-  .strict();
-
-/** Runtime-owned Event task input Source. */
-export const eventTaskSourceSchema = z
-  .object({ kind: z.literal("event_task") })
-  .strict();
-
-/** Runtime-owned Plugin dispatch input Source. */
-export const pluginDispatchSourceSchema = z
-  .object({ kind: z.literal("plugin_dispatch") })
-  .strict();
-
-/** Runtime-owned Agent invocation input Source. */
-export const agentInvocationSourceSchema = z
-  .object({ kind: z.literal("agent_invocation") })
-  .strict();
-
-const currentSourceSchema = z.discriminatedUnion("kind", [
-  slackSourceSchema,
-  localSourceSchema,
-  webSourceSchema,
-  resourceEventSourceSchema,
-  scheduledTaskSourceSchema,
-  eventTaskSourceSchema,
-  pluginDispatchSourceSchema,
-  agentInvocationSourceSchema,
-]);
-
-function normalizeStoredSource(value: unknown): unknown {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return value;
-  }
-  const source = value as Record<string, unknown>;
-  if ("kind" in source || !("platform" in source)) {
-    return value;
-  }
-  if (
-    source.platform !== "slack" &&
-    source.platform !== "local" &&
-    source.platform !== "web"
-  ) {
-    return value;
-  }
-  const { location: _location, platform: kind, ...fields } = source;
-  return { ...fields, kind };
-}
-
-/** Runtime-owned input Source. Stored `platform` and Location fields normalize on read. */
-// TODO(dcramer): Remove stored Source normalization after deployed SQL, Redis,
-// queue, and OAuth values can only contain `kind` and no Location copy.
-export const sourceSchema = z.preprocess(
-  normalizeStoredSource,
-  currentSourceSchema,
-);
-
-/** Stable user credential subject shape accepted from plugins. */
-export const pluginCredentialSubjectSchema = z.discriminatedUnion(
-  "allowedWhen",
-  [
-    z
-      .object({
-        type: z.literal("user"),
-        userId: exactActorUserIdSchema,
-        allowedWhen: z.literal("private-direct-conversation"),
-      })
-      .strict(),
-    z
-      .object({
-        type: z.literal("user"),
-        userId: exactActorUserIdSchema,
-        allowedWhen: z.literal("scheduled-task"),
-        taskId: exactNonBlankStringSchema,
-      })
-      .strict(),
-  ],
-);
-
-/** Shared exact actor profile fields for platform-scoped actors. */
-const actorProfileSchema = {
-  email: nonBlankStringSchema.optional(),
-  fullName: nonBlankStringSchema.optional(),
-  userId: exactActorUserIdSchema,
-  userName: nonBlankStringSchema.optional(),
-};
-
-export const slackActorSchema = z
-  .object({
-    ...actorProfileSchema,
-    platform: z.literal("slack"),
-    teamId: slackTeamIdSchema,
-  })
-  .strict();
-
-export const localActorSchema = z
-  .object({
-    ...actorProfileSchema,
-    platform: z.literal("local"),
-  })
-  .strict();
-
-export const webActorSchema = z
-  .object({
-    ...actorProfileSchema,
-    platform: z.literal("web"),
-  })
-  .strict();
-
-export const systemActorSchema = z
-  .object({
-    platform: z.literal("system"),
-    name: exactActorUserIdSchema,
-  })
-  .strict();
-
-// TODO(dcramer): Separate actor kind from provider platform.
-// System actors should not use `platform: "system"`.
-/** Runtime-provided actor identity visible to plugin hooks. */
-export const actorSchema = z.discriminatedUnion("platform", [
-  slackActorSchema,
-  localActorSchema,
-  webActorSchema,
-  systemActorSchema,
-]);
-
-/** Core-owned provider account linked to a user when verified. */
-export const identitySchema = z
-  .object({
-    displayName: nonBlankStringSchema.optional(),
-    handle: nonBlankStringSchema.optional(),
-    id: exactNonBlankStringSchema,
-    provider: exactNonBlankStringSchema,
-    providerSubjectId: exactNonBlankStringSchema,
-    providerTenantId: exactNonBlankStringSchema.optional(),
-  })
-  .strict();
-
-/** Core-owned person with every linked provider identity. */
-export const userSchema = z
-  .object({
-    displayName: nonBlankStringSchema.optional(),
-    email: nonBlankStringSchema.max(320),
-    id: exactNonBlankStringSchema,
-    identities: z.array(identitySchema).max(100),
-  })
-  .strict();
-
-const dispatchMetadataSchema = z
-  .record(z.string(), z.string())
-  .superRefine((metadata, ctx) => {
-    const entries = Object.entries(metadata);
-    if (entries.length > 20) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: "Dispatch metadata has too many keys",
-      });
-      return;
-    }
-    for (const [key, value] of entries) {
-      if (!key.trim()) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "Dispatch metadata values must be strings",
-          path: [key],
-        });
-        continue;
-      }
-      if (key.length > 128) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "Dispatch metadata key exceeds the maximum length",
-          path: [key],
-        });
-      }
-      if (/[\r\n]/.test(key)) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "Dispatch metadata keys must be single-line strings",
-          path: [key],
-        });
-      }
-      if (/[\r\n]/.test(value)) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "Dispatch metadata values must be single-line strings",
-          path: [key],
-        });
-      }
-      if (value.length > 512) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "Dispatch metadata value exceeds the maximum length",
-          path: [key],
-        });
-      }
-    }
-  });
-
-/** Compact destination-visible context explaining what produced a reply. */
-export const replyAttributionSchema = z
-  .object({
-    label: exactNonBlankStringSchema
-      .pipe(z.string().max(48))
-      .refine((value) => !/[\r\n]/.test(value)),
-    detail: exactNonBlankStringSchema
-      .pipe(z.string().max(128))
-      .refine((value) => !/[\r\n]/.test(value))
-      .optional(),
-  })
-  .strict();
-
-/** Plugin dispatch request accepted by Junior core. */
-export const dispatchOptionsSchema = z
-  .object({
-    idempotencyKey: nonBlankStringSchema.pipe(z.string().max(512)),
-    credentialSubject: pluginCredentialSubjectSchema.optional(),
-    destination: slackDestinationSchema,
-    destinationVisibility: destinationVisibilitySchema,
-    input: nonBlankStringSchema.pipe(z.string().max(32_000)),
-    metadata: dispatchMetadataSchema.optional(),
-    replyAttribution: replyAttributionSchema.optional(),
-  })
-  .strict();

package/src/state.ts

@@ -1,15 +0,0 @@
-export interface PluginState {
-  delete(key: string): Promise<void>;
-  get<T = unknown>(key: string): Promise<T | undefined>;
-  set(key: string, value: unknown, ttlMs?: number): Promise<void>;
-  setIfNotExists(key: string, value: unknown, ttlMs?: number): Promise<boolean>;
-  withLock<T>(
-    key: string,
-    ttlMs: number,
-    callback: () => Promise<T>,
-  ): Promise<T>;
-}
-
-export interface PluginReadState {
-  get<T = unknown>(key: string): Promise<T | undefined>;
-}