@sentry/junior-plugin-api 0.74.1 → 0.75.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.74.1",
+  "version": "0.75.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -22,6 +22,7 @@
     "src"
   ],
   "dependencies": {
+    "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/context.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import {
+  destinationSchema,
+  localRequesterSchema,
+  requesterSchema,
+  slackRequesterSchema,
+  sourceSchema,
+} from "./schemas";
+import type { PluginDb } from "./database";
+
+export type Requester = z.output<typeof requesterSchema>;
+export type SlackRequester = z.output<typeof slackRequesterSchema>;
+export type LocalRequester = z.output<typeof localRequesterSchema>;
+export type Source = z.output<typeof sourceSchema>;
+export type SlackSource = Extract<Source, { platform: "slack" }>;
+export type LocalSource = Extract<Source, { platform: "local" }>;
+
+export type Destination = z.output<typeof destinationSchema>;
+
+export type SlackDestination = Extract<Destination, { platform: "slack" }>;
+
+export type LocalDestination = Extract<Destination, { platform: "local" }>;
+
+export interface PluginMetadata {
+  name: string;
+}
+
+export interface PluginLogger {
+  error(message: string, metadata?: Record<string, unknown>): void;
+  info(message: string, metadata?: Record<string, unknown>): void;
+  warn(message: string, metadata?: Record<string, unknown>): void;
+}
+
+export interface PluginContext {
+  /** Shared database connection for plugins that declare database access. */
+  db?: PluginDb;
+  log: PluginLogger;
+  plugin: PluginMetadata;
+}
+
+interface BaseInvocationContext {
+  /**
+   * Opaque Junior conversation/session identity for this invocation.
+   * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+   */
+  conversationId?: string;
+}
+
+export interface SlackInvocationContext extends BaseInvocationContext {
+  /** Runtime-owned default outbound destination for this invocation, if any. */
+  destination?: SlackDestination;
+  requester?: SlackRequester;
+  /** Runtime-owned source where the invocation came from. */
+  source: SlackSource;
+}
+
+export interface LocalInvocationContext extends BaseInvocationContext {
+  /** Runtime-owned default outbound destination for this invocation, if any. */
+  destination?: LocalDestination;
+  requester?: LocalRequester;
+  /** Runtime-owned source where the invocation came from. */
+  source: LocalSource;
+}
+
+export type InvocationContext = LocalInvocationContext | SlackInvocationContext;
+
+/** Narrow a runtime destination to the Slack-specific address shape. */
+export function isSlackDestination(
+  destination: Destination | undefined,
+): destination is SlackDestination {
+  return destination?.platform === "slack";
+}

package/src/credentials.ts

@@ -0,0 +1,200 @@
+import { z } from "zod";
+import type { PluginContext } from "./context";
+import { nonBlankStringSchema, pluginCredentialSubjectSchema } from "./schemas";
+
+const pluginProviderNameSchema = z.string().regex(/^[a-z][a-z0-9-]*$/);
+const pluginGrantNameSchema = z.string().regex(/^[a-z][a-z0-9.-]*$/);
+const pluginGrantAccessSchema = z.union([
+  z.literal("read"),
+  z.literal("write"),
+]);
+
+/** Runtime schema for provider authorization a plugin may request. */
+export const pluginAuthorizationSchema = z
+  .object({
+    provider: pluginProviderNameSchema,
+    scope: nonBlankStringSchema.optional(),
+    type: z.literal("oauth"),
+  })
+  .strict();
+
+/** Runtime schema for a provider account attached to stored OAuth tokens. */
+export const pluginProviderAccountSchema = z
+  .object({
+    id: nonBlankStringSchema,
+    label: nonBlankStringSchema.optional(),
+    url: nonBlankStringSchema.optional(),
+  })
+  .strict();
+
+/** Runtime schema for a plugin-defined outbound credential grant. */
+export const pluginGrantSchema = z
+  .object({
+    access: pluginGrantAccessSchema,
+    name: pluginGrantNameSchema,
+    reason: nonBlankStringSchema.optional(),
+    requirements: z.array(nonBlankStringSchema).min(1).optional(),
+  })
+  .strict();
+
+/** Runtime schema for plugin-issued header mutations. */
+export const pluginCredentialHeaderTransformSchema = z
+  .object({
+    domain: z.string().min(1),
+    headers: z
+      .record(z.string(), z.string())
+      .refine((headers) => Object.keys(headers).length > 0),
+  })
+  .strict();
+
+/** Runtime schema for a short-lived plugin-issued credential lease. */
+export const pluginCredentialLeaseSchema = z
+  .object({
+    account: pluginProviderAccountSchema.optional(),
+    authorization: pluginAuthorizationSchema.optional(),
+    expiresAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
+    headerTransforms: z.array(pluginCredentialHeaderTransformSchema).min(1),
+  })
+  .strict();
+
+/** Runtime schema for the result returned by a plugin credential hook. */
+export const pluginCredentialResultSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      lease: pluginCredentialLeaseSchema,
+      type: z.literal("lease"),
+    })
+    .strict(),
+  z
+    .object({
+      authorization: pluginAuthorizationSchema.optional(),
+      message: nonBlankStringSchema,
+      type: z.literal("needed"),
+    })
+    .strict(),
+  z
+    .object({
+      message: nonBlankStringSchema,
+      type: z.literal("unavailable"),
+    })
+    .strict(),
+]);
+
+export type PluginCredentialSubject = z.output<
+  typeof pluginCredentialSubjectSchema
+>;
+
+export type PluginGrantAccess = z.output<typeof pluginGrantAccessSchema>;
+
+/** Provider authorization Junior can start when a plugin-owned grant is missing. */
+export type PluginAuthorization = z.output<typeof pluginAuthorizationSchema>;
+
+/** Interrupt sandbox egress so Junior can start provider authorization. */
+export class EgressAuthRequired extends Error {
+  authorization?: PluginAuthorization;
+
+  constructor(
+    message: string,
+    options?: {
+      authorization?: PluginAuthorization;
+      cause?: unknown;
+    },
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = "EgressAuthRequired";
+    this.authorization = options?.authorization;
+  }
+}
+
+/** 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. */
+export type PluginGrant = z.output<typeof pluginGrantSchema>;
+
+/** Request details available while selecting the grant for sandbox egress. */
+export interface PluginEgressRequest {
+  /** Capped request body text when the host exposes it for provider-specific grant classification. */
+  bodyText?: string;
+  method: string;
+  url: string;
+}
+
+export interface EgressHookContext extends PluginContext {
+  request: PluginEgressRequest;
+}
+
+export interface PluginEgressResponse {
+  /** Snapshot of upstream response headers; mutations do not affect pass-through. */
+  headers: Headers;
+  readText(maxBytes: number): Promise<string | undefined>;
+  status: number;
+}
+
+export interface EgressResponseHookContext extends PluginContext {
+  grant: PluginGrant;
+  permissionDenied(message: string): void;
+  request: Omit<PluginEgressRequest, "bodyText">;
+  response: PluginEgressResponse;
+}
+
+/** Header mutations a plugin-issued credential lease may apply to owned domains. */
+export type PluginCredentialHeaderTransform = z.output<
+  typeof pluginCredentialHeaderTransformSchema
+>;
+
+/** Short-lived credential headers issued by a plugin for a selected grant. */
+export type PluginCredentialLease = z.output<
+  typeof pluginCredentialLeaseSchema
+>;
+
+export type PluginCredentialResult = z.output<
+  typeof pluginCredentialResultSchema
+>;
+
+export type PluginCredentialActor =
+  | {
+      type: "system";
+      id: string;
+    }
+  | {
+      type: "user";
+      userId: string;
+    };
+
+export interface PluginResolvedCredentialUser {
+  type: "user";
+  userId: string;
+}
+
+export interface PluginStoredTokens {
+  account?: PluginProviderAccount;
+  accessToken: string;
+  expiresAt?: number;
+  refreshToken: string;
+  scope?: string;
+}
+
+export interface PluginUserTokenSlot {
+  get(): Promise<PluginStoredTokens | undefined>;
+  set(tokens: PluginStoredTokens): Promise<void>;
+  userId: string;
+}
+
+export interface PluginTokenStore {
+  credentialSubject?: PluginUserTokenSlot;
+  currentUser?: PluginUserTokenSlot;
+}
+
+export interface ResolveOAuthAccountHookContext extends PluginContext {
+  tokens: PluginStoredTokens;
+}
+
+export interface IssueCredentialHookContext extends PluginContext {
+  actor: PluginCredentialActor;
+  credentialSubject?: PluginResolvedCredentialUser;
+  grant: PluginGrant;
+  tokens: PluginTokenStore;
+}

package/src/database.ts

@@ -0,0 +1,22 @@
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import type { PgQueryResultHKT } from "drizzle-orm/pg-core/session";
+
+export type PluginDrizzleDatabase = PgDatabase<
+  PgQueryResultHKT,
+  Record<string, never>
+>;
+
+export interface PluginDb {
+  delete: PluginDrizzleDatabase["delete"];
+  execute(statement: string, params?: readonly unknown[]): Promise<void>;
+  insert: PluginDrizzleDatabase["insert"];
+  query<T = unknown>(
+    statement: string,
+    params?: readonly unknown[],
+  ): Promise<T[]>;
+  select: PluginDrizzleDatabase["select"];
+  transaction<T>(callback: (tx: PluginDb) => Promise<T>): Promise<T>;
+  update: PluginDrizzleDatabase["update"];
+}
+
+export type PluginDatabaseConfig = Record<string, never>;

package/src/dispatch.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { dispatchOptionsSchema } from "./schemas";
+
+export type DispatchOptions = z.output<typeof dispatchOptionsSchema>;
+
+export interface DispatchResult {
+  id: string;
+  status: "created" | "already_exists";
+}
+
+export interface Dispatch {
+  errorMessage?: string;
+  id: string;
+  resultMessageTs?: string;
+  status:
+    | "pending"
+    | "running"
+    | "awaiting_resume"
+    | "completed"
+    | "failed"
+    | "blocked";
+}

package/src/hooks.ts

@@ -0,0 +1,67 @@
+import type {
+  EgressHookContext,
+  EgressResponseHookContext,
+  IssueCredentialHookContext,
+  PluginCredentialResult,
+  PluginGrant,
+  PluginProviderAccount,
+  ResolveOAuthAccountHookContext,
+} from "./credentials";
+import type {
+  HeartbeatHookContext,
+  HeartbeatResult,
+  OperationalReportHookContext,
+  PluginOperationalReportContent,
+  PluginRoute,
+  RouteRegistrationHookContext,
+  SlackConversationLink,
+  SlackConversationLinkHookContext,
+  StorageMigrationContext,
+  StorageMigrationResult,
+} from "./operations";
+import type {
+  BeforeToolExecuteHookContext,
+  PluginToolDefinition,
+  SandboxPrepareHookContext,
+  ToolRegistrationHookContext,
+} from "./tools";
+
+export interface PluginHooks {
+  beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+  grantForEgress?(
+    ctx: EgressHookContext,
+  ): Promise<PluginGrant | undefined> | PluginGrant | undefined;
+  heartbeat?(
+    ctx: HeartbeatHookContext,
+  ): Promise<HeartbeatResult | void> | HeartbeatResult | void;
+  issueCredential?(
+    ctx: IssueCredentialHookContext,
+  ): Promise<PluginCredentialResult> | PluginCredentialResult;
+  onEgressResponse?(ctx: EgressResponseHookContext): Promise<void> | void;
+  operationalReport?(
+    ctx: OperationalReportHookContext,
+  ):
+    | Promise<PluginOperationalReportContent | undefined>
+    | PluginOperationalReportContent
+    | undefined;
+  resolveOAuthAccount?(
+    ctx: ResolveOAuthAccountHookContext,
+  ):
+    | Promise<PluginProviderAccount | undefined>
+    | PluginProviderAccount
+    | undefined;
+  routes?(ctx: RouteRegistrationHookContext): PluginRoute[];
+  sandboxPrepare?(ctx: SandboxPrepareHookContext): Promise<void> | void;
+  slackConversationLink?(
+    ctx: SlackConversationLinkHookContext,
+  ): SlackConversationLink | undefined;
+  tools?(
+    ctx: ToolRegistrationHookContext,
+  ): Record<string, PluginToolDefinition>;
+  migrateStorage?(
+    ctx: StorageMigrationContext,
+  ):
+    | Promise<StorageMigrationResult | undefined>
+    | StorageMigrationResult
+    | undefined;
+}