@sigil-dev/plugin-sentry 0.8.6 → 0.9.1

package/README.md

@@ -1,15 +1,80 @@
-# plugin-sentry
+# @sigil-dev/plugin-sentry
 
-To install dependencies:
+Integrates [Sentry](https://sentry.io) with Grimoire. Captures errors and fatal log entries, optionally captures warnings, and reports worker crashes with worker context attached.
 
-```bash
-bun install
+## Installation
+
+```sh
+bun add @sigil-dev/plugin-sentry @sentry/bun
+```
+
+## Usage
+
+```ts
+import { defineConfig } from "@sigil-dev/grimoire";
+import { sentryPlugin } from "@sigil-dev/plugin-sentry";
+
+export default defineConfig({
+  plugins: [
+    sentryPlugin({
+      dsn: process.env.SENTRY_DSN!,
+    }),
+  ],
+});
+```
+
+## Options
+
+```ts
+interface SentryPluginOptions {
+  /** Sentry DSN. Required. */
+  dsn: string;
+  /** Also capture warn-level log entries as Sentry messages. Default: false. */
+  captureWarns?: boolean;
+  /** Return false to suppress a log entry from being sent to Sentry. */
+  beforeSend?: (entry: LogEntry) => boolean;
+  /** Additional options passed directly to Sentry.init(). */
+  sentryOptions?: Record<string, unknown>;
+}
 ```
 
-To run:
+## What gets captured
+
+| Event | Sentry level | Notes |
+|---|---|---|
+| `log.error(...)` | `error` | Captures as exception with scope + worker tags. |
+| `log.fatal(...)` | `fatal` | Same as error. |
+| `log.warn(...)` | `warning` | Only if `captureWarns: true`. |
+| Worker crash | `error` | Captured as message with worker name and mode tags. |
+
+All captured events include request context (`url`, `method`) set via `Sentry.setContext` on each request.
+
+## Filtering events
 
-```bash
-bun run index.ts
+Use `beforeSend` to suppress specific entries:
+
+```ts
+sentryPlugin({
+  dsn: process.env.SENTRY_DSN!,
+  beforeSend(entry) {
+    // don't send expected 404s to Sentry
+    if (entry.message.includes("Not Found")) return false;
+    return true;
+  },
+})
 ```
 
-This project was created using `bun init` in bun v1.3.14. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## Passing additional Sentry options
+
+Any option accepted by `Sentry.init()` can be passed via `sentryOptions`:
+
+```ts
+sentryPlugin({
+  dsn: process.env.SENTRY_DSN!,
+  sentryOptions: {
+    environment: process.env.NODE_ENV,
+    release: process.env.GIT_SHA,
+    tracesSampleRate: 0.2,
+  },
+})
+```

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@sigil-dev/plugin-sentry",
-  "version": "0.8.6",
+  "version": "0.9.1",
   "description": "Sentry error tracking plugin for grimoire",
   "type": "module",
+  "private": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -19,7 +20,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@sigil-dev/grimoire": "0.8.6",
+    "@sigil-dev/grimoire": "0.9.1",
     "@sentry/bun": "^8.0.0"
   },
   "peerDependencies": {