Release v0.4.0 (#27)

* Add onEvent observability hooks to all middleware packages (#18)

* Add onEvent observability hooks to all middleware packages

Enable logging, metrics, and monitoring by passing an onEvent callback
to createDeviceRouter(). Emits profile:classify, profile:store,
bot:reject, and error events with timing data. Callbacks are
fire-and-forget with built-in error isolation so they never disrupt
request handling.

* Fix endpoint error event losing sessionToken and handle malformed JSON in Hono

Hoist sessionToken before try block in all 4 endpoint handlers so the
catch block preserves the generated UUID for new sessions instead of
re-reading from the cookie (which is undefined for first requests).

Catch malformed JSON in Hono endpoint separately to return 400 instead
of falling through to the generic 500 handler.

Strengthen onEvent tests: assert event.error object and message in all
error tests, assert event.signals in all bot:reject tests.

* Add observability example with Grafana dashboard and Prometheus metrics (#20)

New examples/observability/ directory with a Docker Compose stack
(Express + Redis + Prometheus + Grafana) demonstrating all 6 Prometheus
metrics wired to the onEvent hook, including the new hint_total counter.
The Grafana dashboard is auto-provisioned with 12 panels across 4 rows.

* Add GitHub funding configuration

* Add docs for rate limiting, profile versioning, Client Hints compat, and meta-frameworks

- New docs/meta-frameworks.md: integration guide for Next.js, Remix, SvelteKit
  using classifyFromHeaders and deriveHints directly from @device-router/types
- Add Client Hints browser compatibility table to getting-started.md
- Add rate limiting and profile versioning notes to deployment production checklist
- Add threshold versioning callout under Custom Thresholds in getting-started.md
- Link meta-frameworks guide from README docs index

* Add test for async callback rejection in emitEvent

Covers the async () => { throw } case that exercises the
result.then(undefined, () => {}) swallowing path.

* Document Express default error handler stack trace leak

Malformed JSON to the probe endpoint triggers Express's default error
handler before DeviceRouter code runs, exposing stack traces. Added a
production checklist note pointing to custom error handler docs.

* Add npm package metadata (repository, homepage, bugs, keywords)

All 7 published packages now include repository, homepage, bugs, keywords,
and description fields so npm pages link back to GitHub and are discoverable
via search.

* Add sideEffects, default export condition, funding, provenance, and community docs

- Add sideEffects: false to all packages for tree shaking
- Add default condition to exports maps for edge/Bun/Deno compat
- Add funding field linking to GitHub Sponsors
- Add provenance: true to publishConfig and --provenance to publish workflow
- Add browser field and ./browser export alias to probe package
- Add SECURITY.md with vulnerability reporting policy
- Add CODE_OF_CONDUCT.md (Contributor Covenant 2.1)

* Fix DeviceProfile.signals type to reflect stored shape (#23)

Middleware endpoints strip userAgent and viewport before storing, but
DeviceProfile.signals was typed as RawSignals — making TypeScript claim
those fields might exist when they never will. Add StoredSignals type
alias (Omit<RawSignals, 'userAgent' | 'viewport'>) and use it instead.

* Bump the dev-deps group with 2 updates (#21)

Bumps the dev-deps group with 2 updates: [eslint](https://github.com/eslint/eslint) and [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/typescript-eslint).


Updates `eslint` from 10.0.1 to 10.0.2
- [Release notes](https://github.com/eslint/eslint/releases)
- [Commits](eslint/eslint@v10.0.1...v10.0.2)

Updates `typescript-eslint` from 8.56.0 to 8.56.1
- [Release notes](https://github.com/typescript-eslint/typescript-eslint/releases)
- [Changelog](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/typescript-eslint/CHANGELOG.md)
- [Commits](https://github.com/typescript-eslint/typescript-eslint/commits/v8.56.1/packages/typescript-eslint)

---
updated-dependencies:
- dependency-name: eslint
  dependency-version: 10.0.2
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: dev-deps
- dependency-name: typescript-eslint
  dependency-version: 8.56.1
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: dev-deps
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Bump hono from 4.12.1 to 4.12.2 in the prod-deps group (#22)

Bumps the prod-deps group with 1 update: [hono](https://github.com/honojs/hono).


Updates `hono` from 4.12.1 to 4.12.2
- [Release notes](https://github.com/honojs/hono/releases)
- [Commits](honojs/hono@v4.12.1...v4.12.2)

---
updated-dependencies:
- dependency-name: hono
  dependency-version: 4.12.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: prod-deps
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Align Fastify middleware API shape with Express, Hono, and Koa (#24)

createDeviceRouter() now returns { middleware, probeEndpoint, injectionMiddleware? }
instead of { plugin, pluginOptions, probeEndpoint, injectionHook? }.
Removes the unused pluginOptions (always {}) from the public API.
Renames createInjectionHook to createInjectionMiddleware for consistency.

* Add server-side diagnostic warnings for missing probe data (#25)

* Fix npm badge link to point to package page instead of search

* Add server-side diagnostic warnings for missing probe data

Surface misconfigurations server-side since the probe client has no
room for error reporting within its 1 KB budget. Three strategies, all
gated behind NODE_ENV !== 'production':

- Startup: log the expected probe endpoint path via console.info
- Runtime: one-time console.warn after 50 middleware hits with zero
  probe submissions
- onEvent: emit structured diagnostic:no-probe-data event through the
  existing onEvent callback

* Verify dist artifacts exist before npm publish

Prevents publishing empty packages if the build silently fails to emit
.js or .d.ts files.

* Document threshold immutability constraint in deployment guide

Expand the brief production checklist mention into a dedicated section
with four mitigation strategies: shorten TTL, flush storage, rotate
cookie name, or do nothing when only numeric boundaries change.

* Bump v0.4.0 — fix misleading threshold staleness docs

Classification runs on every request using current thresholds, so
threshold changes take effect immediately. Removed incorrect
flush/TTL/cookie-rotation mitigation strategies from deployment guide.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Author: SimplyLiz

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: SimplyLiz
+buy_me_a_coffee: simplyliz

.github/workflows/publish.yml

@@ -33,6 +33,15 @@ jobs:
 
       - run: pnpm format:check
 
+      - name: Verify dist artifacts exist
+        run: |
+          for pkg in types probe storage middleware-express middleware-fastify middleware-hono middleware-koa; do
+            if ! ls packages/$pkg/dist/*.js &>/dev/null || ! ls packages/$pkg/dist/*.d.ts &>/dev/null; then
+              echo "Missing dist artifacts in packages/$pkg"
+              exit 1
+            fi
+          done
+
       - name: Validate version matches tag
         run: |
           TAG_VERSION="${GITHUB_REF_NAME#v}"
@@ -42,7 +51,7 @@ jobs:
             exit 1
           fi
 
-      - run: pnpm -r publish --no-git-checks --access public
+      - run: pnpm -r publish --no-git-checks --access public --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.4.0 (2026-02-24)
+
+### Features
+
+- **Observability hooks** — New `onEvent` callback option on all middleware packages. Emits `profile:classify`, `profile:store`, `bot:reject`, and `error` events for plugging in logging, metrics, and monitoring without middleware wrapping. Callbacks are fire-and-forget with built-in error isolation
+
+### Documentation
+
+- **Observability example** — New `examples/observability/` with Docker Compose stack (Express + Redis + Prometheus + Grafana), all 6 Prometheus metrics wired to `onEvent`, and a pre-built Grafana dashboard. Adds `device_router_hint_total` metric for tracking hint activation rates
+- **Meta-framework integration guide** — New `docs/meta-frameworks.md` covering Next.js (App Router), Remix, and SvelteKit integration using `classifyFromHeaders` and `deriveHints` directly from `@device-router/types`
+- **Client Hints browser compatibility** — Added browser compatibility table to the Getting Started guide documenting which Client Hints headers are available on Chrome, Edge, Safari, and Firefox, and what happens when headers are missing
+- **Rate limiting** — Added production checklist note that the probe endpoint has no built-in rate limiting and should be protected via reverse proxy or framework-level rate limiter
+- **Threshold staleness fix** — Corrected deployment guide: threshold changes take effect immediately since classification runs on every request. Removed misleading flush/TTL/cookie-rotation mitigation strategies
+
 ## 0.3.0 (2026-02-23)
 
 ### Breaking Changes

CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a welcoming experience for everyone,
+regardless of background or identity.
+
+## Our Standards
+
+Examples of positive behavior:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal attacks
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Project maintainers are responsible for clarifying standards of acceptable behavior and will take
+appropriate action in response to unacceptable behavior. Instances of unacceptable behavior may be
+reported via the contact information on the [GitHub profile](https://github.com/SimplyLiz).
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

README.md

@@ -1,6 +1,6 @@
 # DeviceRouter
 
-[![npm](https://img.shields.io/npm/v/@device-router/types?label=npm&color=cb3837)](https://www.npmjs.com/search?q=%40device-router)
+[![npm](https://img.shields.io/npm/v/@device-router/types?label=npm&color=cb3837)](https://www.npmjs.com/package/@device-router/types)
 [![CI](https://img.shields.io/github/actions/workflow/status/SimplyLiz/DeviceRouter/ci.yml?branch=main&label=CI)](https://github.com/SimplyLiz/DeviceRouter/actions/workflows/ci.yml)
 [![bundle size](https://img.shields.io/badge/probe-~1%20KB%20gzipped-blue)](https://github.com/SimplyLiz/DeviceRouter/tree/main/packages/probe)
 [![license](https://img.shields.io/github/license/SimplyLiz/DeviceRouter)](https://github.com/SimplyLiz/DeviceRouter/blob/main/LICENSE)
@@ -175,6 +175,23 @@ When `classifyFromHeaders` is enabled, mobile/tablet/desktop detection happens f
 
 See [Getting Started — First-Request Handling](docs/getting-started.md#first-request-handling) for details.
 
+## Observability
+
+Plug in logging and metrics with a single callback — no middleware wrapping needed:
+
+```typescript
+const { middleware, probeEndpoint } = createDeviceRouter({
+  storage,
+  onEvent: (event) => {
+    if (event.type === 'profile:classify') {
+      logger.info('classified', { source: event.source, cpu: event.tiers.cpu });
+    }
+  },
+});
+```
+
+Events: `profile:classify`, `profile:store`, `bot:reject`, `error`. See the [Observability guide](docs/observability.md).
+
 ## Packages
 
 | Package                                                               | Description                                           | Size              |
@@ -220,17 +237,20 @@ pnpm dev
 
 Open http://localhost:3000 — the probe runs on first load, refresh to see your detected profile. Use `?force=lite` or `?force=full` to preview each mode without a real device.
 
-| Framework | Guide                                                       | Example                                  |
-| --------- | ----------------------------------------------------------- | ---------------------------------------- |
-| Express   | [Quick Start](docs/getting-started.md#quick-start--express) | [express-basic](examples/express-basic/) |
-| Fastify   | [Quick Start](docs/getting-started.md#quick-start--fastify) | [fastify-basic](examples/fastify-basic/) |
-| Hono      | [Quick Start](docs/getting-started.md#quick-start--hono)    | [hono-basic](examples/hono-basic/)       |
-| Koa       | [Quick Start](docs/getting-started.md#quick-start--koa)     | [koa-basic](examples/koa-basic/)         |
+| Framework     | Guide                                                       | Example                                  |
+| ------------- | ----------------------------------------------------------- | ---------------------------------------- |
+| Express       | [Quick Start](docs/getting-started.md#quick-start--express) | [express-basic](examples/express-basic/) |
+| Fastify       | [Quick Start](docs/getting-started.md#quick-start--fastify) | [fastify-basic](examples/fastify-basic/) |
+| Hono          | [Quick Start](docs/getting-started.md#quick-start--hono)    | [hono-basic](examples/hono-basic/)       |
+| Koa           | [Quick Start](docs/getting-started.md#quick-start--koa)     | [koa-basic](examples/koa-basic/)         |
+| Observability | [Observability guide](docs/observability.md)                | [observability](examples/observability/) |
 
 ## Documentation
 
 - [Getting Started](docs/getting-started.md)
+- [Observability](docs/observability.md) — Logging, metrics, and monitoring hooks
 - [Deployment Guide](docs/deployment.md) — Docker, Cloudflare Workers, serverless
+- [Meta-Framework Integration](docs/meta-frameworks.md) — Next.js, Remix, SvelteKit
 - [Profile Schema Reference](docs/profile-schema.md)
 - API Reference: [types](docs/api/types.md) | [probe](docs/api/probe.md) | [storage](docs/api/storage.md) | [express](docs/api/middleware-express.md) | [fastify](docs/api/middleware-fastify.md) | [hono](docs/api/middleware-hono.md) | [koa](docs/api/middleware-koa.md)
 

SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.3.x   | Yes       |
+| < 0.3   | No        |
+
+## Reporting a Vulnerability
+
+If you discover a security issue, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, please email security concerns to the maintainers via the contact information on the
+[GitHub profile](https://github.com/SimplyLiz). Include:
+
+- A description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+You can expect an initial response within 72 hours. We will work with you to understand the issue
+and coordinate a fix before any public disclosure.
+
+## Scope
+
+This policy applies to all packages in the `@device-router/*` scope published to npm, as well as
+the source code in this repository.

docs/api/middleware-express.md

@@ -21,20 +21,21 @@ app.use(middleware);
 
 ### Options
 
-| Option                | Type                                   | Default                  | Description                                                  |
-| --------------------- | -------------------------------------- | ------------------------ | ------------------------------------------------------------ |
-| `storage`             | `StorageAdapter`                       | required                 | Storage backend                                              |
-| `cookieName`          | `string`                               | `'dr_session'`           | Session cookie name                                          |
-| `cookiePath`          | `string`                               | `'/'`                    | Cookie path                                                  |
-| `cookieSecure`        | `boolean`                              | `false`                  | Set `Secure` flag on the session cookie                      |
-| `ttl`                 | `number`                               | `86400`                  | Profile TTL in seconds                                       |
-| `rejectBots`          | `boolean`                              | `true`                   | Reject bot/crawler probe submissions (returns 403)           |
-| `thresholds`          | `TierThresholds`                       | built-in defaults        | Custom tier classification thresholds (validated at startup) |
-| `injectProbe`         | `boolean`                              | `false`                  | Auto-inject probe script into HTML responses                 |
-| `probePath`           | `string`                               | `'/device-router/probe'` | Custom probe endpoint path for injected script               |
-| `probeNonce`          | `string \| ((req: Request) => string)` | —                        | CSP nonce for the injected script tag                        |
-| `fallbackProfile`     | `FallbackProfile`                      | —                        | Fallback profile for first requests without probe data       |
-| `classifyFromHeaders` | `boolean`                              | `false`                  | Classify from UA/Client Hints on first request               |
+| Option                | Type                                   | Default                  | Description                                                               |
+| --------------------- | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------- |
+| `storage`             | `StorageAdapter`                       | required                 | Storage backend                                                           |
+| `cookieName`          | `string`                               | `'dr_session'`           | Session cookie name                                                       |
+| `cookiePath`          | `string`                               | `'/'`                    | Cookie path                                                               |
+| `cookieSecure`        | `boolean`                              | `false`                  | Set `Secure` flag on the session cookie                                   |
+| `ttl`                 | `number`                               | `86400`                  | Profile TTL in seconds                                                    |
+| `rejectBots`          | `boolean`                              | `true`                   | Reject bot/crawler probe submissions (returns 403)                        |
+| `thresholds`          | `TierThresholds`                       | built-in defaults        | Custom tier classification thresholds (validated at startup)              |
+| `injectProbe`         | `boolean`                              | `false`                  | Auto-inject probe script into HTML responses                              |
+| `probePath`           | `string`                               | `'/device-router/probe'` | Custom probe endpoint path for injected script                            |
+| `probeNonce`          | `string \| ((req: Request) => string)` | —                        | CSP nonce for the injected script tag                                     |
+| `fallbackProfile`     | `FallbackProfile`                      | —                        | Fallback profile for first requests without probe data                    |
+| `classifyFromHeaders` | `boolean`                              | `false`                  | Classify from UA/Client Hints on first request                            |
+| `onEvent`             | `OnEventCallback`                      | —                        | Observability callback for logging/metrics ([guide](../observability.md)) |
 
 ### Returns