@sentry/junior-plugin-api 0.81.0 → 0.83.0

package/dist/credentials.d.ts

@@ -101,6 +101,12 @@ export declare class EgressAuthRequired extends Error {
         cause?: unknown;
     });
 }
+/** Deny provider egress before Junior issues credentials for a disallowed operation. */
+export declare class EgressPolicyDenied extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /** Provider account identity resolved by a plugin OAuth hook. */
 export type PluginProviderAccount = z.output<typeof pluginProviderAccountSchema>;
 /** Plugin-defined grant required before Junior can forward one outbound request. */
@@ -110,6 +116,8 @@ export interface PluginEgressRequest {
     /** Capped request body text when the host exposes it for provider-specific grant classification. */
     bodyText?: string;
     method: string;
+    /** Plugin-declared operation this request performs, used for grant classification and diagnostics. */
+    operation?: string;
     url: string;
 }
 export interface EgressHookContext extends PluginContext {

package/dist/hooks.d.ts

@@ -1,5 +1,5 @@
 import type { EgressHookContext, EgressResponseHookContext, IssueCredentialHookContext, PluginCredentialResult, PluginGrant, PluginProviderAccount, ResolveOAuthAccountHookContext } from "./credentials";
-import type { HeartbeatHookContext, HeartbeatResult, OperationalReportHookContext, DashboardRouteRegistrationHookContext, PluginOperationalReportContent, PluginRoute, PluginRouteApp, RouteRegistrationHookContext, SlackConversationLink, SlackConversationLinkHookContext, StorageMigrationContext, StorageMigrationResult } from "./operations";
+import type { HeartbeatHookContext, HeartbeatResult, OperationalReportHookContext, ApiRouteRegistrationHookContext, PluginOperationalReportContent, PluginRoute, PluginRouteApp, RouteRegistrationHookContext, SlackConversationLink, SlackConversationLinkHookContext, StorageMigrationContext, StorageMigrationResult } from "./operations";
 import type { BeforeToolExecuteHookContext, PluginToolDefinition, SandboxPrepareHookContext, ToolRegistrationHookContext } from "./tools";
 import type { PromptMessage, SystemPromptContext, UserPromptContext } from "./prompt";
 export interface PluginHooks {
@@ -11,7 +11,8 @@ export interface PluginHooks {
     issueCredential?(ctx: IssueCredentialHookContext): Promise<PluginCredentialResult> | PluginCredentialResult;
     onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
     operationalReport?(ctx: OperationalReportHookContext): Promise<PluginOperationalReportContent | undefined> | PluginOperationalReportContent | undefined;
-    dashboardRoutes?(ctx: DashboardRouteRegistrationHookContext): PluginRouteApp | undefined;
+    /** Return plugin-owned product API routes mounted under Junior's authenticated plugin namespace. */
+    apiRoutes?(ctx: ApiRouteRegistrationHookContext): PluginRouteApp | undefined;
     resolveOAuthAccount?(ctx: ResolveOAuthAccountHookContext): Promise<PluginProviderAccount | undefined> | PluginProviderAccount | undefined;
     routes?(ctx: RouteRegistrationHookContext): PluginRoute[];
     sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./context";
 export * from "./state";
 export { promptMessageSchema, type PromptMessage, type SystemPromptContext, type UserPromptContext, } from "./prompt";
 export * from "./dispatch";
+export * from "./resource-events";
 export * from "./tasks";
 export * from "./tools";
 export * from "./operations";

package/dist/index.js

@@ -164,29 +164,40 @@ var promptMessageSchema = z2.object({
   text: z2.string().trim().min(1).max(8e3)
 }).strict();
 
-// src/tasks.ts
+// src/resource-events.ts
 import { z as z3 } from "zod";
-var pluginRunTranscriptEntrySchema = z3.discriminatedUnion("type", [
-  z3.object({
-    type: z3.literal("message"),
-    role: z3.enum(["user", "assistant"]),
-    text: z3.string().min(1)
+var subscribableResourceSchema = z3.object({
+  label: z3.string().min(1),
+  provider: z3.string().min(1),
+  resourceRef: z3.string().min(1),
+  suggestedEvents: z3.array(z3.string().min(1)).optional(),
+  supportedEvents: z3.array(z3.string().min(1)),
+  type: z3.string().min(1)
+}).strict();
+
+// src/tasks.ts
+import { z as z4 } from "zod";
+var pluginRunTranscriptEntrySchema = z4.discriminatedUnion("type", [
+  z4.object({
+    type: z4.literal("message"),
+    role: z4.enum(["user", "assistant"]),
+    text: z4.string().min(1)
   }).strict(),
-  z3.object({
-    type: z3.literal("toolResult"),
-    toolName: z3.string().min(1),
-    isError: z3.boolean(),
-    text: z3.string().min(1).optional()
+  z4.object({
+    type: z4.literal("toolResult"),
+    toolName: z4.string().min(1),
+    isError: z4.boolean(),
+    text: z4.string().min(1).optional()
   }).strict()
 ]);
-var pluginRunContextSchema = z3.object({
-  completedAtMs: z3.number().finite(),
-  conversationId: z3.string().min(1),
+var pluginRunContextSchema = z4.object({
+  completedAtMs: z4.number().finite(),
+  conversationId: z4.string().min(1),
   destination: destinationSchema,
   requester: requesterSchema.optional(),
-  runId: z3.string().min(1),
+  runId: z4.string().min(1),
   source: sourceSchema,
-  transcript: z3.array(pluginRunTranscriptEntrySchema)
+  transcript: z4.array(pluginRunTranscriptEntrySchema)
 }).strict();
 
 // src/tools.ts
@@ -197,61 +208,75 @@ var PluginToolInputError = class extends Error {
   }
 };
 
+// src/operations.ts
+import { z as z5 } from "zod";
+var pluginApiRouteRequestContextSchema = z5.object({
+  auth: z5.object({
+    user: z5.object({
+      email: z5.string().nullable().optional(),
+      emailVerified: z5.boolean().optional(),
+      hostedDomain: z5.string().nullable().optional(),
+      name: z5.string().nullable().optional()
+    }).strict()
+  }).strict(),
+  pluginName: nonBlankStringSchema
+}).strict();
+
 // src/credentials.ts
-import { z as z4 } from "zod";
-var pluginProviderNameSchema = z4.string().regex(/^[a-z][a-z0-9-]*$/);
-var pluginGrantNameSchema = z4.string().regex(/^[a-z][a-z0-9.-]*$/);
-var pluginGrantAccessSchema = z4.union([
-  z4.literal("read"),
-  z4.literal("write")
+import { z as z6 } from "zod";
+var pluginProviderNameSchema = z6.string().regex(/^[a-z][a-z0-9-]*$/);
+var pluginGrantNameSchema = z6.string().regex(/^[a-z][a-z0-9.-]*$/);
+var pluginGrantAccessSchema = z6.union([
+  z6.literal("read"),
+  z6.literal("write")
 ]);
-var pluginAuthorizationSchema = z4.object({
+var pluginAuthorizationSchema = z6.object({
   provider: pluginProviderNameSchema,
   scope: nonBlankStringSchema.optional(),
-  type: z4.literal("oauth")
+  type: z6.literal("oauth")
 }).strict();
-var pluginProviderAccountSchema = z4.object({
+var pluginProviderAccountSchema = z6.object({
   id: nonBlankStringSchema,
   label: nonBlankStringSchema.optional(),
   url: nonBlankStringSchema.optional()
 }).strict();
-var pluginStoredTokensSchema = z4.object({
+var pluginStoredTokensSchema = z6.object({
   account: pluginProviderAccountSchema.optional(),
   accessToken: nonBlankStringSchema,
-  expiresAt: z4.number().finite().optional(),
+  expiresAt: z6.number().finite().optional(),
   refreshToken: nonBlankStringSchema,
-  refreshTokenExpiresAt: z4.number().finite().optional(),
+  refreshTokenExpiresAt: z6.number().finite().optional(),
   scope: nonBlankStringSchema.optional()
 }).strict();
-var pluginGrantSchema = z4.object({
+var pluginGrantSchema = z6.object({
   access: pluginGrantAccessSchema,
   name: pluginGrantNameSchema,
   reason: nonBlankStringSchema.optional(),
-  requirements: z4.array(nonBlankStringSchema).min(1).optional()
+  requirements: z6.array(nonBlankStringSchema).min(1).optional()
 }).strict();
-var pluginCredentialHeaderTransformSchema = z4.object({
-  domain: z4.string().min(1),
-  headers: z4.record(z4.string(), z4.string()).refine((headers) => Object.keys(headers).length > 0)
+var pluginCredentialHeaderTransformSchema = z6.object({
+  domain: z6.string().min(1),
+  headers: z6.record(z6.string(), z6.string()).refine((headers) => Object.keys(headers).length > 0)
 }).strict();
-var pluginCredentialLeaseSchema = z4.object({
+var pluginCredentialLeaseSchema = z6.object({
   account: pluginProviderAccountSchema.optional(),
   authorization: pluginAuthorizationSchema.optional(),
-  expiresAt: z4.string().refine((value) => Number.isFinite(Date.parse(value))),
-  headerTransforms: z4.array(pluginCredentialHeaderTransformSchema).min(1)
+  expiresAt: z6.string().refine((value) => Number.isFinite(Date.parse(value))),
+  headerTransforms: z6.array(pluginCredentialHeaderTransformSchema).min(1)
 }).strict();
-var pluginCredentialResultSchema = z4.discriminatedUnion("type", [
-  z4.object({
+var pluginCredentialResultSchema = z6.discriminatedUnion("type", [
+  z6.object({
     lease: pluginCredentialLeaseSchema,
-    type: z4.literal("lease")
+    type: z6.literal("lease")
   }).strict(),
-  z4.object({
+  z6.object({
     authorization: pluginAuthorizationSchema.optional(),
     message: nonBlankStringSchema,
-    type: z4.literal("needed")
+    type: z6.literal("needed")
   }).strict(),
-  z4.object({
+  z6.object({
     message: nonBlankStringSchema,
-    type: z4.literal("unavailable")
+    type: z6.literal("unavailable")
   }).strict()
 ]);
 var EgressAuthRequired = class extends Error {
@@ -262,6 +287,12 @@ var EgressAuthRequired = class extends Error {
     this.authorization = options?.authorization;
   }
 };
+var EgressPolicyDenied = class extends Error {
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "EgressPolicyDenied";
+  }
+};
 
 // src/registration.ts
 var PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
@@ -305,6 +336,7 @@ function defineJuniorPlugin(plugin) {
 }
 export {
   EgressAuthRequired,
+  EgressPolicyDenied,
   PluginToolInputError,
   createLocalSource,
   createSlackSource,
@@ -319,6 +351,7 @@ export {
   localSourceSchema,
   nonBlankStringSchema,
   platformSchema,
+  pluginApiRouteRequestContextSchema,
   pluginAuthorizationSchema,
   pluginCredentialHeaderTransformSchema,
   pluginCredentialLeaseSchema,
@@ -335,5 +368,6 @@ export {
   slackRequesterSchema,
   slackSourceSchema,
   sourceSchema,
-  sourceTypeSchema
+  sourceTypeSchema,
+  subscribableResourceSchema
 };

package/dist/operations.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { PluginContext } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
 import type { PluginReadState, PluginState } from "./state";
@@ -8,7 +9,7 @@ export interface PluginConversationSummary {
     displayTitle: string;
     lastActivityAt: string;
     lastUpdatedAt: string;
-    source?: "api" | "internal" | "local" | "plugin" | "scheduler" | "slack";
+    source?: "api" | "internal" | "local" | "plugin" | "resource_event" | "scheduler" | "slack";
     status: PluginConversationStatus;
 }
 export interface PluginConversations {
@@ -81,13 +82,27 @@ export interface PluginRoute {
     method?: PluginRouteMethod | PluginRouteMethod[];
     path: string;
 }
+/** Fetch-compatible plugin HTTP app mounted by Junior. */
 export type PluginRouteApp = {
-    fetch(request: Request): Promise<Response> | Response;
+    fetch(request: Request, context?: PluginApiRouteRequestContext): Promise<Response> | Response;
 };
 export interface RouteRegistrationHookContext extends PluginContext {
 }
-export interface DashboardRouteRegistrationHookContext extends PluginContext {
-}
+export interface ApiRouteRegistrationHookContext extends PluginContext {
+}
+/** Per-request context Junior passes to authenticated plugin product API routes. */
+export declare const pluginApiRouteRequestContextSchema: z.ZodObject<{
+    auth: z.ZodObject<{
+        user: z.ZodObject<{
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            emailVerified: z.ZodOptional<z.ZodBoolean>;
+            hostedDomain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    pluginName: z.ZodString;
+}, z.core.$strict>;
+export type PluginApiRouteRequestContext = z.output<typeof pluginApiRouteRequestContextSchema>;
 export interface SlackConversationLink {
     url: string;
 }

package/dist/resource-events.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const subscribableResourceSchema: z.ZodObject<{
+    label: z.ZodString;
+    provider: z.ZodString;
+    resourceRef: 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>;

package/dist/tools.d.ts

@@ -36,6 +36,20 @@ export interface PluginSandbox {
         path: string;
     }): Promise<void>;
 }
+export interface PluginEgress {
+    /**
+     * Fetch a provider URL with host-owned credentials.
+     *
+     * The runtime selects and injects credentials for `provider`; plugin code
+     * owns the request shape and response handling. `operation` names the
+     * provider action for grant selection and diagnostics.
+     */
+    fetch(input: {
+        operation: string;
+        provider: string;
+        request: Request;
+    }): Promise<Response>;
+}
 export interface SandboxPrepareHookContext extends PluginContext {
     requester?: Requester;
     sandbox: PluginSandbox;
@@ -102,6 +116,7 @@ interface BaseToolRegistrationHookContext extends PluginContext {
      */
     conversationId?: string;
     embedder: PluginEmbedder;
+    egress: PluginEgress;
     model: PluginModel;
     state: PluginState;
     userText?: string;

package/package.json

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

package/src/credentials.ts

@@ -118,6 +118,14 @@ export class EgressAuthRequired extends Error {
   }
 }
 
+/** Deny provider egress before Junior issues credentials for a disallowed operation. */
+export class EgressPolicyDenied extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, { cause: options?.cause });
+    this.name = "EgressPolicyDenied";
+  }
+}
+
 /** Provider account identity resolved by a plugin OAuth hook. */
 export type PluginProviderAccount = z.output<
   typeof pluginProviderAccountSchema
@@ -131,6 +139,8 @@ export interface PluginEgressRequest {
   /** Capped request body text when the host exposes it for provider-specific grant classification. */
   bodyText?: string;
   method: string;
+  /** Plugin-declared operation this request performs, used for grant classification and diagnostics. */
+  operation?: string;
   url: string;
 }
 

package/src/hooks.ts

@@ -11,7 +11,7 @@ import type {
   HeartbeatHookContext,
   HeartbeatResult,
   OperationalReportHookContext,
-  DashboardRouteRegistrationHookContext,
+  ApiRouteRegistrationHookContext,
   PluginOperationalReportContent,
   PluginRoute,
   PluginRouteApp,
@@ -57,9 +57,8 @@ export interface PluginHooks {
     | Promise<PluginOperationalReportContent | undefined>
     | PluginOperationalReportContent
     | undefined;
-  dashboardRoutes?(
-    ctx: DashboardRouteRegistrationHookContext,
-  ): PluginRouteApp | undefined;
+  /** Return plugin-owned product API routes mounted under Junior's authenticated plugin namespace. */
+  apiRoutes?(ctx: ApiRouteRegistrationHookContext): PluginRouteApp | undefined;
   resolveOAuthAccount?(
     ctx: ResolveOAuthAccountHookContext,
   ):

package/src/index.ts

@@ -8,6 +8,7 @@ export {
   type UserPromptContext,
 } from "./prompt";
 export * from "./dispatch";
+export * from "./resource-events";
 export * from "./tasks";
 export * from "./tools";
 export * from "./operations";

package/src/operations.ts

@@ -1,5 +1,7 @@
+import { z } from "zod";
 import type { PluginContext } from "./context";
 import type { Dispatch, DispatchOptions, DispatchResult } from "./dispatch";
+import { nonBlankStringSchema } from "./schemas";
 import type { PluginReadState, PluginState } from "./state";
 
 export type PluginConversationStatus =
@@ -15,7 +17,14 @@ export interface PluginConversationSummary {
   displayTitle: string;
   lastActivityAt: string;
   lastUpdatedAt: string;
-  source?: "api" | "internal" | "local" | "plugin" | "scheduler" | "slack";
+  source?:
+    | "api"
+    | "internal"
+    | "local"
+    | "plugin"
+    | "resource_event"
+    | "scheduler"
+    | "slack";
   status: PluginConversationStatus;
 }
 
@@ -113,13 +122,40 @@ export interface PluginRoute {
   path: string;
 }
 
+/** Fetch-compatible plugin HTTP app mounted by Junior. */
 export type PluginRouteApp = {
-  fetch(request: Request): Promise<Response> | Response;
+  fetch(
+    request: Request,
+    context?: PluginApiRouteRequestContext,
+  ): Promise<Response> | Response;
 };
 
 export interface RouteRegistrationHookContext extends PluginContext {}
 
-export interface DashboardRouteRegistrationHookContext extends PluginContext {}
+export interface ApiRouteRegistrationHookContext extends PluginContext {}
+
+/** Per-request context Junior passes to authenticated plugin product API routes. */
+export const pluginApiRouteRequestContextSchema = z
+  .object({
+    auth: z
+      .object({
+        user: z
+          .object({
+            email: z.string().nullable().optional(),
+            emailVerified: z.boolean().optional(),
+            hostedDomain: z.string().nullable().optional(),
+            name: z.string().nullable().optional(),
+          })
+          .strict(),
+      })
+      .strict(),
+    pluginName: nonBlankStringSchema,
+  })
+  .strict();
+
+export type PluginApiRouteRequestContext = z.output<
+  typeof pluginApiRouteRequestContextSchema
+>;
 
 export interface SlackConversationLink {
   url: string;

package/src/resource-events.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const subscribableResourceSchema = z
+  .object({
+    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),
+  })
+  .strict();
+
+export type SubscribableResource = z.output<typeof subscribableResourceSchema>;

package/src/tools.ts

@@ -49,6 +49,21 @@ export interface PluginSandbox {
   }): Promise<void>;
 }
 
+export interface PluginEgress {
+  /**
+   * Fetch a provider URL with host-owned credentials.
+   *
+   * The runtime selects and injects credentials for `provider`; plugin code
+   * owns the request shape and response handling. `operation` names the
+   * provider action for grant selection and diagnostics.
+   */
+  fetch(input: {
+    operation: string;
+    provider: string;
+    request: Request;
+  }): Promise<Response>;
+}
+
 export interface SandboxPrepareHookContext extends PluginContext {
   requester?: Requester;
   sandbox: PluginSandbox;
@@ -124,6 +139,7 @@ interface BaseToolRegistrationHookContext extends PluginContext {
    */
   conversationId?: string;
   embedder: PluginEmbedder;
+  egress: PluginEgress;
   model: PluginModel;
   state: PluginState;
   userText?: string;