@outloud/adonisjs-sentry 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present, Outloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# AdonisJS Sentry
+
+Sentry integration for [AdonisJS](https://adonisjs.com/) version 6/7.
+
+<p>
+
+[![typescript-image]][typescript-url]
+[![npm-image]][npm-url]
+[![npm-download-image]][npm-download-url]
+[![license-image]][license-url]
+
+</p>
+
+---
+## Getting Started
+
+Install the package from the npm registry and configure it.
+
+```bash
+node ace add @outloud/adonisjs-sentry
+```
+
+See `config/sentry.ts` for available configuration options.
+
+## Usage
+
+The package will automatically register a middleware and configure the Sentry SDK.
+
+```ts
+import type { HttpContext } from '@adonisjs/core/http'
+import sentry from '@outloud/adonisjs-sentry/service'
+
+export default class HelloController {
+  greet({ params, response}: HttpContext) {
+    sentry.captureMessage(`Hello, ${params.name}!`)
+
+    return response.ok({ message: `Hello, ${params.name}!` })
+  }
+}
+```
+
+The SDK is automatically scoped to the current request.
+
+```ts
+import { inject } from '@adonisjs/core'
+import sentry from '@outloud/adonisjs-sentry/service'
+
+@inject()
+export class GreetingService {  
+  greet(name: string) {
+    sentry.captureMessage(`Hello, ${name}!`)
+    
+    return `Hello, ${name}!`
+  }
+}
+```
+
+### Capturing Errors
+
+You can capture errors by calling the `captureException` method on the SDK inside your exception handler.
+
+```ts
+import sentry from '@outloud/adonisjs-sentry/service'
+
+export default class HttpExceptionHandler extends ExceptionHandler {
+  // ...
+
+  async report(error: unknown, ctx: HttpContext) {
+    if (this.shouldReport(error as any)) {
+      sentry.captureException(error)
+    }
+
+    return super.report(error, ctx)
+  }
+}
+```
+
+### Assigning User Context
+
+You can assign user context to the Sentry SDK by calling the `setUser` method on the SDK once you are logged in.
+
+```ts
+import sentry from '@outloud/adonisjs-sentry/service'
+
+export default class SilentAuthMiddleware {
+  async handle(ctx: HttpContext, next: NextFn) {
+    // We are authenticating the user
+    await ctx.auth.check()
+
+    // If the user is authenticated, we assign the user context to Sentry
+    if (ctx.auth.isAuthenticated) {
+      const user = ctx.auth.getUserOrFail()
+      
+      sentry.setUser({
+        id: user.id, 
+        email: user.email, 
+        username: user.username,
+      });
+    }
+    
+    return await next();
+  }
+}
+```
+
+### Adding Integrations
+
+Sentry provides multiple integrations to enhance the data captured by the SDK. You can add integrations by changing the `integrations` array inside the configuration `config/sentry.ts`.
+
+For example, if you want to add profiling to your application, you can add the `Profiler` integration.
+
+```sh
+npm install @sentry/profiling-node
+```
+
+```ts
+// config/sentry.ts
+
+import { nodeProfilingIntegration } from '@sentry/profiling-node';
+
+export default defineConfig({
+  // ...
+  integrations: [nodeProfilingIntegration()],
+  profilesSampleRate: 0.2,
+})
+```
+
+[npm-image]: https://badgen.net/npm/v/@outloud/adonisjs-sentry/latest
+[npm-url]: https://npmjs.org/package/@outloud/adonisjs-sentry "npm"
+
+[npm-download-image]: https://badgen.net/npm/dm/@outloud/adonisjs-sentry
+[npm-download-url]: https://npmcharts.com/compare/@outloud/adonisjs-sentry?minimal=true "downloads"
+
+[typescript-image]: https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white
+[typescript-url]: https://www.typescriptlang.org "TypeScript"
+
+[license-image]: https://img.shields.io/npm/l/@outloud/adonisjs-sentry.svg?sanitize=true
+[license-url]: LICENSE.md "license"

package/dist/providers/sentry.provider.d.ts

@@ -0,0 +1,11 @@
+import { ApplicationService } from "@adonisjs/core/types";
+
+//#region providers/sentry.provider.d.ts
+declare class SentryProvider {
+  protected app: ApplicationService;
+  constructor(app: ApplicationService);
+  register(): void;
+  boot(): void;
+}
+//#endregion
+export { SentryProvider as default };

package/dist/providers/sentry.provider.js

@@ -0,0 +1,18 @@
+import * as Sentry from "@sentry/node";
+
+//#region providers/sentry.provider.ts
+var SentryProvider = class {
+	constructor(app) {
+		this.app = app;
+	}
+	register() {
+		this.app.container.singleton("sentry", () => Sentry);
+	}
+	boot() {
+		const config = this.app.config.get("sentry", {});
+		if (config.enabled && config.dsn) Sentry.init(config);
+	}
+};
+
+//#endregion
+export { SentryProvider as default };

package/dist/services/sentry.d.ts

@@ -0,0 +1,6 @@
+import { Sentry as SentryImpl } from "../src/types.js";
+
+//#region services/sentry.d.ts
+declare let sentry: SentryImpl;
+//#endregion
+export { sentry as default };

package/dist/services/sentry.js

@@ -0,0 +1,10 @@
+import app from "@adonisjs/core/services/app";
+
+//#region services/sentry.ts
+let sentry;
+await app?.booted(async () => {
+	sentry = await app.container.make("sentry");
+});
+
+//#endregion
+export { sentry as default };

package/dist/src/config.d.ts

@@ -0,0 +1,6 @@
+import { SentryConfig } from "./types.js";
+
+//#region src/config.d.ts
+declare function defineConfig<T extends SentryConfig>(config: T): T;
+//#endregion
+export { defineConfig };

package/dist/src/config.js

@@ -0,0 +1,7 @@
+//#region src/config.ts
+function defineConfig(config) {
+	return config;
+}
+
+//#endregion
+export { defineConfig };

package/dist/src/configure.d.ts

@@ -0,0 +1,9 @@
+import Configure from "@adonisjs/core/commands/configure";
+
+//#region src/configure.d.ts
+/**
+ * Configures the package
+ */
+declare function configure(command: Configure): Promise<void>;
+//#endregion
+export { configure };

package/dist/src/configure.js

@@ -0,0 +1,40 @@
+import { stubsRoot } from "../stubs/main.js";
+
+//#region src/configure.ts
+/**
+* Configures the package
+*/
+async function configure(command) {
+	const codemods = await command.createCodemods();
+	/**
+	* Publish config file
+	*/
+	await codemods.makeUsingStub(stubsRoot, "config/sentry.stub", {});
+	/**
+	* Define environment variables
+	*/
+	await codemods.defineEnvVariables({ SENTRY_DSN: "<your_dsn_url>" });
+	/**
+	* Define environment variables validations
+	*/
+	await codemods.defineEnvValidations({
+		variables: { SENTRY_DSN: "Env.schema.string.optional()" },
+		leadingComment: "Variables for configuring @outloud/adonisjs-sentry package"
+	});
+	/**
+	* Register middleware
+	*/
+	await codemods.registerMiddleware("router", [{
+		path: "@outloud/adonisjs-sentry/middleware",
+		position: "before"
+	}]);
+	/**
+	* Register provider
+	*/
+	await codemods.updateRcFile((rcFile) => {
+		rcFile.addProvider("@outloud/adonisjs-sentry/provider");
+	});
+}
+
+//#endregion
+export { configure };

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import { configure } from "./configure.js";
+import { defineConfig } from "./config.js";
+export { configure, defineConfig };

package/dist/src/index.js

@@ -0,0 +1,4 @@
+import { configure } from "./configure.js";
+import { defineConfig } from "./config.js";
+
+export { configure, defineConfig };

package/dist/src/middleware.d.ts

@@ -0,0 +1,9 @@
+import { HttpContext } from "@adonisjs/core/http";
+import { NextFn } from "@adonisjs/core/types/http";
+
+//#region src/middleware.d.ts
+declare class SentryMiddleware {
+  handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}
+//#endregion
+export { SentryMiddleware as default };

package/dist/src/middleware.js

@@ -0,0 +1,14 @@
+import * as Sentry from "@sentry/node";
+
+//#region src/middleware.ts
+var SentryMiddleware = class {
+	async handle(ctx, next) {
+		const activeSpan = Sentry.getActiveSpan();
+		const rootSpan = activeSpan && Sentry.getRootSpan(activeSpan);
+		if (rootSpan) Sentry.updateSpanName(rootSpan, ctx.routeKey || "unknown");
+		return next();
+	}
+};
+
+//#endregion
+export { SentryMiddleware as default };

package/dist/src/types.d.ts

@@ -0,0 +1,16 @@
+import * as Sentry from "@sentry/node";
+
+//#region src/types.d.ts
+type SentryImpl = typeof Sentry;
+interface SentryConfig extends Sentry.NodeOptions {
+  /** Enable or disable Sentry */
+  enabled: boolean;
+  dsn?: string;
+}
+declare module '@adonisjs/core/types' {
+  interface ContainerBindings {
+    sentry: typeof Sentry;
+  }
+}
+//#endregion
+export { type SentryImpl as Sentry, SentryConfig };

package/dist/src/types.js

@@ -0,0 +1 @@
+export {  };

package/dist/stubs/config/sentry.stub

@@ -0,0 +1,30 @@
+{{{
+  exports({ to: app.configPath('sentry.ts') })
+}}}
+
+import env from '#start/env'
+import app from '@adonisjs/core/services/app'
+import { defineConfig } from '@outloud/adonisjs-sentry'
+
+export default defineConfig({
+  /** Enable or disable Sentry */
+  enabled: app.inProduction,
+
+  /** The environment Sentry is running in */
+  environment: app.nodeEnvironment,
+
+  /** The DSN of the project */
+  dsn: env.get('SENTRY_DSN'),
+
+  /**
+   * Additional integrations to use with the Sentry SDK
+   * @see https://docs.sentry.io/platforms/javascript/guides/node/configuration/integrations/#available-integrations
+   */
+  integrations: [],
+
+  /**
+   * The sample rate of traces to send to Sentry
+   * @see https://docs.sentry.io/platforms/javascript/guides/node/configuration/sampling
+   */
+  tracesSampleRate: 0.2,
+})

package/dist/stubs/main.d.ts

@@ -0,0 +1,4 @@
+//#region stubs/main.d.ts
+declare const stubsRoot: string;
+//#endregion
+export { stubsRoot };

package/dist/stubs/main.js

@@ -0,0 +1,5 @@
+//#region stubs/main.ts
+const stubsRoot = import.meta.dirname;
+
+//#endregion
+export { stubsRoot };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@outloud/adonisjs-sentry",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Sentry integration for AdonisJS 6/7.",
+  "homepage": "https://github.com/madebyoutloud/adonisjs-sentry",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/madebyoutloud/adonisjs-sentry.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "imports": {
+    "#/*": "./src/*.js"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./middleware": "./dist/src/middleware.js",
+    "./provider": "./dist/providers/sentry.provider.js",
+    "./service": "./dist/services/sentry.js",
+    "./services/*": "./dist/services/*.js",
+    "./types": "./dist/src/types.js"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^6 || ^7"
+  },
+  "devDependencies": {
+    "@adonisjs/core": "^6.19.0",
+    "@japa/assert": "^4.1.1",
+    "@japa/runner": "^4.4.0",
+    "@outloud/eslint-config": "^2.1.3",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@types/node": "^22.2.0",
+    "copyfiles": "^2.4.1",
+    "eslint": "^9.39.2",
+    "reflect-metadata": "^0.2.2",
+    "release-it": "^19.2.4",
+    "tsdown": "^0.20.1"
+  },
+  "dependencies": {
+    "@sentry/node": "^10"
+  },
+  "scripts": {
+    "pretest": "pnpm lint && pnpm typecheck",
+    "test": "pnpm quick:test",
+    "quick:test": "node --enable-source-maps --import=@poppinss/ts-exec --no-warnings bin/test.ts",
+    "lint": "eslint . --ext=.ts",
+    "lint:fix": "eslint --fix . --ext=.ts",
+    "typecheck": "tsc --noEmit",
+    "copy:templates": "copyfiles \"stubs/**/*.stub\" dist",
+    "build": "tsdown && pnpm run copy:templates",
+    "release": "release-it"
+  }
+}