@theholocron/holocron-plugin-sentry 5.0.0-alpha.221 → 5.0.0-alpha.223

package/dist/index.d.mts

@@ -1,7 +1,17 @@
-import { AuthError, Errors, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
+import { AuthError, EnsureRelayInput, EnsureRelayResult, Errors, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
 import { SentryClient, SentryClientOptions, createSentryClient } from "@theholocron/sentry-client";
 //#region src/auth.d.ts
 declare const resolveToken: (input?: ResolveTokenInput) => string;
+/**
+ * The token for the Comlink relay: an integration, its client secret and an alert rule need more than the general token
+ * (`alerts:write`, `org:write`, `event:read`), so it has its own.
+ */
+declare const resolveComlinkToken: (input?: ResolveTokenInput) => string;
+/**
+ * The token for the relay: the Comlink one when there is one, else the general Sentry token as the last resort. The
+ * fallback only helps if the general token happens to carry the scopes; otherwise Sentry's answer names what is missing.
+ */
+declare function resolveRelayToken(input?: ResolveTokenInput): string;
 //#endregion
 //#region src/capabilities/errors.d.ts
 interface SentryErrorsOptions {
@@ -13,9 +23,14 @@ interface SentryErrorsOptions {
 declare class SentryErrors implements Errors {
   private readonly client;
   private readonly opts;
+  /** The client for the relay, made with the Comlink token (see `resolveRelayToken`). */
+  private readonly relayClient;
   readonly key: "errors";
   readonly providerName = "sentry";
-  constructor(client: () => SentryClient, opts: SentryErrorsOptions);
+  constructor(client: () => SentryClient, opts: SentryErrorsOptions,
+  /** The client for the relay, made with the Comlink token (see `resolveRelayToken`). */
+  relayClient?: () => SentryClient);
+  ensureRelay(input: EnsureRelayInput): Promise<EnsureRelayResult>;
   describe(): Promise<{
     provider: string;
     envKeys: string[];
@@ -60,6 +75,8 @@ interface SentryPluginOptions extends ResolveTokenInput, SentryErrorsOptions {
 interface PluginContext {
   options: SentryPluginOptions;
   client: () => SentryClient;
+  /** The client for the Comlink relay: its own token (`sentry.comlink`), the general one only as a last resort. */
+  relayClient: () => SentryClient;
 }
 declare function createContext(options: SentryPluginOptions): PluginContext;
 declare function errors(ctx: PluginContext): Errors;
@@ -71,4 +88,4 @@ declare function createPlugin(options: SentryPluginOptions): {
 };
 declare const AUTH_HINT: string;
 //#endregion
-export { AUTH_HINT, AuthError, PluginContext, type ResolveTokenInput, type SentryClient, type SentryClientOptions, SentryErrors, type SentryErrorsOptions, SentryPluginOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createSentryClient, errors, resolveToken, verifyToken };
+export { AUTH_HINT, AuthError, PluginContext, type ResolveTokenInput, type SentryClient, type SentryClientOptions, SentryErrors, type SentryErrorsOptions, SentryPluginOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createSentryClient, errors, resolveComlinkToken, resolveRelayToken, resolveToken, verifyToken };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { AuthError, ProviderApiError, createFeatureResolver, createResolveToken } from "@theholocron/cli";
 import { createSentryClient } from "@theholocron/sentry-client";
 import { errorMessage } from "@theholocron/misc-utils";
 //#region src/auth.ts
@@ -8,16 +8,232 @@ const resolveToken = createResolveToken({
 	keyringService: "sentry",
 	errorMessage: "no Sentry auth token found. Pass --token <TOKEN>, set HOLOCRON_SENTRY_TOKEN / SENTRY_AUTH_TOKEN, or run: holocron auth set sentry <TOKEN>"
 });
+/**
+* The token for the Comlink relay: an integration, its client secret and an alert rule need more than the general token
+* (`alerts:write`, `org:write`, `event:read`), so it has its own.
+*/
+const resolveComlinkToken = createFeatureResolver({
+	envName: "HOLOCRON_SENTRY_COMLINK_TOKEN",
+	keyringKey: "sentry.comlink",
+	vendor: "Sentry"
+});
+/**
+* The token for the relay: the Comlink one when there is one, else the general Sentry token as the last resort. The
+* fallback only helps if the general token happens to carry the scopes; otherwise Sentry's answer names what is missing.
+*/
+function resolveRelayToken(input = {}) {
+	try {
+		return resolveComlinkToken(input);
+	} catch (err) {
+		if (!(err instanceof AuthError)) throw err;
+		return resolveToken(input);
+	}
+}
+//#endregion
+//#region src/capabilities/relay.ts
+/** What the integration needs to read: the alert's event. It is also why reading its secret needs the same scope. */
+const INTEGRATION_SCOPES = ["event:read"];
+const DEFAULT_FREQUENCY = 5;
+/** The alert action that sends through an integration: it points at the integration's numeric app id. */
+const sentryAppAction = (appId) => ({
+	type: "sentry_app",
+	config: {
+		targetType: "sentry_app",
+		targetIdentifier: String(appId)
+	},
+	data: {}
+});
+const targetsApp = (action, appId) => action.type === "sentry_app" && String(action.config["targetIdentifier"]) === String(appId);
+/** A workflow as Sentry returned it, as the body to send back (the nested ids are not part of an update). */
+function toInput(wf) {
+	return {
+		name: wf.name,
+		enabled: wf.enabled,
+		environment: wf.environment,
+		config: wf.config,
+		detectorIds: wf.detectorIds,
+		triggers: {
+			logicType: wf.triggers.logicType,
+			conditions: wf.triggers.conditions.map((c) => ({
+				type: c.type,
+				comparison: c.comparison,
+				conditionResult: c.conditionResult
+			}))
+		},
+		actionFilters: wf.actionFilters.map((f) => ({
+			logicType: f.logicType,
+			conditions: f.conditions.map((c) => ({
+				type: c.type,
+				comparison: c.comparison,
+				conditionResult: c.conditionResult
+			})),
+			actions: f.actions.map((a) => ({
+				type: a.type,
+				config: a.config,
+				data: a.data
+			}))
+		}))
+	};
+}
+/** Sentry's own "high priority issues" rule, which is the default for a new alert. */
+function newWorkflow(name, frequency, detectorIds, appId) {
+	return {
+		name,
+		enabled: true,
+		environment: null,
+		config: { frequency },
+		detectorIds,
+		triggers: {
+			logicType: "any-short",
+			conditions: [{
+				type: "new_high_priority_issue",
+				comparison: true,
+				conditionResult: true
+			}, {
+				type: "existing_high_priority_issue",
+				comparison: true,
+				conditionResult: true
+			}]
+		},
+		actionFilters: [{
+			logicType: "all",
+			conditions: [],
+			actions: [sentryAppAction(appId)]
+		}]
+	};
+}
+/** The integration: found by name, made if missing, and its webhook and alert action brought in line. */
+async function ensureIntegration(client, org, input) {
+	const existing = (await client.sentryApps.list(org)).find((a) => a.name === input.name);
+	if (!existing) return {
+		app: await client.sentryApps.create(org, {
+			name: input.name,
+			scopes: INTEGRATION_SCOPES,
+			webhookUrl: input.webhookUrl,
+			isAlertable: true
+		}),
+		created: true,
+		updated: []
+	};
+	const updated = [];
+	if (existing.webhookUrl !== input.webhookUrl) updated.push("webhook URL");
+	if (!existing.isAlertable) updated.push("alert action");
+	const scopes = [.../* @__PURE__ */ new Set([...existing.scopes, ...INTEGRATION_SCOPES])];
+	if (scopes.length !== existing.scopes.length) updated.push("scopes");
+	if (updated.length === 0) return {
+		app: existing,
+		created: false,
+		updated
+	};
+	return {
+		app: await client.sentryApps.update(existing.slug, {
+			name: existing.name,
+			scopes,
+			webhookUrl: input.webhookUrl,
+			isAlertable: true
+		}),
+		created: false,
+		updated
+	};
+}
+/** The issue stream detector of each project, so a wrong project fails before anything is changed. */
+async function detectorsFor(client, org, slugs) {
+	const [projects, detectors] = await Promise.all([client.projects.list(org), client.workflows.detectors(org)]);
+	return slugs.map((slug) => {
+		const project = projects.find((p) => p.slug === slug);
+		if (!project) throw new Error(`Sentry project \`${slug}\` was not found in ${org}`);
+		const detector = detectors.find((d) => d.projectId === project.id && d.type === "issue_stream");
+		if (!detector) throw new Error(`Sentry project \`${slug}\` has no issue stream detector to attach an alert to`);
+		return detector.id;
+	});
+}
+/** The alert rule: one workflow for every project, found by name, made if missing, reconciled if not. */
+async function ensureRule(client, org, input, appId, detectorIds) {
+	const workflows = await client.workflows.list(org);
+	const frequency = input.rule.frequency ?? DEFAULT_FREQUENCY;
+	const existing = workflows.find((w) => w.name === input.rule.name);
+	if (!existing) {
+		await client.workflows.create(org, newWorkflow(input.rule.name, frequency, detectorIds, appId));
+		return {
+			created: true,
+			updated: []
+		};
+	}
+	const next = toInput(existing);
+	const updated = [];
+	if (!existing.enabled) {
+		next.enabled = true;
+		updated.push("enabled");
+	}
+	if (input.rule.frequency !== void 0 && existing.config.frequency !== input.rule.frequency) {
+		next.config = {
+			...existing.config,
+			frequency: input.rule.frequency
+		};
+		updated.push("frequency");
+	}
+	const missing = detectorIds.filter((id) => !existing.detectorIds.includes(id));
+	if (missing.length > 0) {
+		next.detectorIds = [...existing.detectorIds, ...missing];
+		updated.push("projects");
+	}
+	if (!existing.actionFilters.some((f) => f.actions.some((a) => targetsApp(a, appId)))) {
+		const open = next.actionFilters.find((f) => f.conditions.length === 0);
+		if (open) open.actions.push(sentryAppAction(appId));
+		else next.actionFilters.push({
+			logicType: "all",
+			conditions: [],
+			actions: [sentryAppAction(appId)]
+		});
+		updated.push("action");
+	}
+	if (updated.length === 0) return {
+		created: false,
+		updated
+	};
+	await client.workflows.update(org, existing.id, next);
+	return {
+		created: false,
+		updated
+	};
+}
+/** The signing secret, if the token may see it: a new integration's answer omits it, so it is read again. */
+async function secretOf(client, app) {
+	if (app.clientSecret) return app.clientSecret;
+	return (await client.sentryApps.get(app.slug)).clientSecret || void 0;
+}
+async function ensureSentryRelay(client, org, input) {
+	if (input.projects.length === 0) throw new Error("relay needs at least one Sentry project to alert on");
+	const detectorIds = await detectorsFor(client, org, input.projects);
+	const integration = await ensureIntegration(client, org, input);
+	const install = (await client.sentryApps.installations(org)).find((i) => i.app.slug === integration.app.slug);
+	if (!install) throw new Error(`the integration \`${integration.app.name}\` is not installed on ${org}`);
+	const rule = await ensureRule(client, org, input, install.app.sentryAppId, detectorIds);
+	const clientSecret = await secretOf(client, integration.app);
+	return {
+		integration: {
+			created: integration.created,
+			updated: integration.updated
+		},
+		rule,
+		...clientSecret ? { clientSecret } : {}
+	};
+}
 //#endregion
 //#region src/capabilities/errors.ts
 var SentryErrors = class {
 	client;
 	opts;
+	relayClient;
 	key = "errors";
 	providerName = "sentry";
-	constructor(client, opts) {
+	constructor(client, opts, relayClient = client) {
 		this.client = client;
 		this.opts = opts;
+		this.relayClient = relayClient;
+	}
+	async ensureRelay(input) {
+		return ensureSentryRelay(this.relayClient(), this.requireOrg(), input);
 	}
 	async describe() {
 		return {
@@ -94,12 +310,18 @@ async function verifyToken(token, opts = {}) {
 //#region src/index.ts
 function createContext(options) {
 	let client;
+	let relayClient;
 	return {
 		options,
 		client: () => client ??= createSentryClient({
 			token: resolveToken(options),
 			baseUrl: options.baseUrl,
 			fetch: options.fetch
+		}),
+		relayClient: () => relayClient ??= createSentryClient({
+			token: resolveRelayToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
 		})
 	};
 }
@@ -107,7 +329,7 @@ function errors(ctx) {
 	return new SentryErrors(ctx.client, {
 		org: ctx.options.org,
 		team: ctx.options.team
-	});
+	}, ctx.relayClient);
 }
 function createPlugin(options) {
 	const ctx = createContext(options);
@@ -118,4 +340,4 @@ function createPlugin(options) {
 }
 const AUTH_HINT = "generate an auth token at https://sentry.io/settings/account/api/auth-tokens/ with project:read, project:write, and org:read scopes, then run: holocron auth set sentry <TOKEN>";
 //#endregion
-export { AUTH_HINT, AuthError, SentryErrors, createContext, createPlugin, createSentryClient, errors, resolveToken, verifyToken };
+export { AUTH_HINT, AuthError, SentryErrors, createContext, createPlugin, createSentryClient, errors, resolveComlinkToken, resolveRelayToken, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-sentry",
-  "version": "5.0.0-alpha.221",
+  "version": "5.0.0-alpha.223",
   "description": "Holocron plugin for Sentry. Implements the errors capability against Sentry's management API — project provisioning and DSN retrieval.",
   "keywords": [
     "errors",
@@ -33,7 +33,7 @@
     "@theholocron/eslint-config": "^8.8.2",
     "@theholocron/http-client": "^1.43.1",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/sentry-client": "^1.43.1",
+    "@theholocron/sentry-client": "^1.54.0",
     "@theholocron/tsconfig": "^8.8.2",
     "@theholocron/tsdown-config": "^8.8.2",
     "@theholocron/vitest-config": "^8.8.2",
@@ -48,12 +48,12 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.221"
+    "@theholocron/cli": "5.0.0-alpha.223"
   },
   "peerDependencies": {
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/sentry-client": "^1.43.1",
-    "@theholocron/cli": "5.0.0-alpha.221"
+    "@theholocron/sentry-client": "^1.54.0",
+    "@theholocron/cli": "5.0.0-alpha.223"
   },
   "peerDependenciesMeta": {
     "@theholocron/sentry-client": {}