@lokalise/fastify-extras 30.4.0 → 30.6.0

package/README.md

@@ -64,6 +64,24 @@ The `getRequestIdFastifyAppConfig()` method is exported and returns:
 
 Which can be passed to Fastify during instantiation.
 
+The `getFastifyAppLoggingConfig(appLogLevel, requestLoggingLevels?)` method is exported and returns Fastify configuration for request logging. It accepts:
+
+- `appLogLevel`, the application log level from your app configuration;
+- `requestLoggingLevels` (optional), an array of log levels that should enable request logging. Defaults to `['debug', 'trace', 'info']`.
+
+This method returns a `disableRequestLogging` configuration that:
+- Enables request logging only when the app log level is in `requestLoggingLevels`;
+- Automatically skips logging for service utility endpoints (`/`, `/health`, `/ready`, `/live`, `/metrics`).
+
+Example usage:
+```typescript
+import { getFastifyAppLoggingConfig } from '@lokalise/fastify-extras'
+
+const app = fastify({
+  ...getFastifyAppLoggingConfig(appConfig.logLevel),
+})
+```
+
 ### Public Healthcheck Plugin
 
 Plugin to monitor app status through public healthcheck.
@@ -384,9 +402,11 @@ The plugin decorates your Fastify instance with a `Amplitude`, which you can inj
 > "@amplitude/analytics-types": "*"
 > ```
 
-Additionally, you have the option to enhance the safety and accuracy of your events and properties by wrapping your `Amplitude` instance with `AmplitudeAdapter`.
+**Related utilities:**
 
-> 📘Check [`AmplitudeAdapter.spec.ts](./lib/plugins/amplitude/amplitudePlugin.spec.ts) for a practical example
+- `AmplitudeAdapter` - A type-safe wrapper that validates events using Zod schemas before sending them to Amplitude
+- `FakeAmplitude` - A utility class for testing environments that doesn't send events to Amplitude
+See the [Amplitude utilities section](#amplitude) for detailed documentation and examples.
 
 ### Strip Trailing Slash Plugin
 
@@ -469,6 +489,119 @@ When an uncaught exception occurs, the plugin:
 
 ## Utilities
 
+### amplitude
+
+#### FakeAmplitude
+
+`FakeAmplitude` is a utility class that extends `Amplitude` but doesn't send any events to Amplitude. This is useful for
+testing environments or when you want to disable event tracking without changing your application code.
+
+Example usage:
+
+```typescript
+import { FakeAmplitude } from '@lokalise/fastify-extras'
+
+// In your test or development environment
+const amplitude = new FakeAmplitude()
+
+// track() will not send any events
+amplitude.track({
+  event_type: 'button_clicked',
+  user_id: 'user-123',
+})
+```
+
+The `track()` method returns a promise that resolves to `null` immediately, maintaining the same interface as the real
+`Amplitude` class without actually sending data.
+
+#### AmplitudeAdapter
+
+`AmplitudeAdapter` is a type-safe wrapper around `Amplitude` that uses Zod schemas to validate events before sending them.
+This ensures that all events sent to Amplitude conform to predefined schemas, catching errors at compile-time and runtime.
+
+**Key features:**
+
+- Type-safe event tracking with TypeScript
+- Automatic validation using Zod schemas
+- Prevents sending malformed events to Amplitude
+
+**Example usage:**
+
+```typescript
+import { z } from 'zod'
+import { AmplitudeAdapter, AMPLITUDE_BASE_MESSAGE_SCHEMA, Amplitude } from '@lokalise/fastify-extras'
+import type { AmplitudeMessage } from '@lokalise/fastify-extras'
+
+// Define your event schemas
+const eventSchemas = {
+  buttonClicked: {
+    schema: AMPLITUDE_BASE_MESSAGE_SCHEMA.extend({
+      event_type: z.literal('button_clicked'),
+      event_properties: z.object({
+        button_id: z.string(),
+        page: z.string(),
+      }),
+    }),
+  },
+  userSignedUp: {
+    schema: AMPLITUDE_BASE_MESSAGE_SCHEMA.extend({
+      event_type: z.literal('user_signed_up'),
+      event_properties: z.object({
+        plan: z.enum(['free', 'premium']),
+      }),
+    }),
+  },
+} as const satisfies Record<string, AmplitudeMessage>
+
+const eventSchemaValues = Object.values(eventSchemas)
+type SupportedEvents = typeof eventSchemaValues
+
+// Create the adapter
+const amplitude = new Amplitude(true)
+const amplitudeAdapter = new AmplitudeAdapter<SupportedEvents>({ amplitude })
+
+// Track events with type safety
+amplitudeAdapter.track(eventSchemas.buttonClicked, {
+  user_id: 'user-123',
+  event_properties: {
+    button_id: 'submit-btn',
+    page: '/checkout',
+  },
+})
+
+// With groups
+amplitudeAdapter.track(eventSchemas.userSignedUp, {
+  user_id: 'user-456',
+  groups: { company: 'acme-corp' },
+  event_properties: {
+    plan: 'premium',
+  },
+})
+```
+
+**Schema validation:**
+
+The `AMPLITUDE_BASE_MESSAGE_SCHEMA` provides the base schema that all events must extend. It requires:
+
+- `event_type`: A literal string identifying the event
+- `user_id`: A non-empty string or the literal `'SYSTEM'`
+- `groups` (optional): A record of group names to values
+
+When defining custom events, extend this base schema with your specific `event_type` and `event_properties`:
+
+```typescript
+const myEventSchema = AMPLITUDE_BASE_MESSAGE_SCHEMA.extend({
+  event_type: z.literal('my_custom_event'),
+  event_properties: z.object({
+    // Your custom properties with validation
+    count: z.number().int().positive(),
+    status: z.enum(['active', 'inactive']),
+  }),
+})
+```
+
+If validation fails, a `ZodError` will be thrown, preventing invalid data from being sent to Amplitude.
+
 ### route-utilities
 
 #### authPreHandlers

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export { commonSyncHealthcheckPlugin } from './plugins/healthcheck/commonSyncHea
 export type { CommonSyncHealthcheckPluginOptions } from './plugins/healthcheck/commonSyncHealthcheckPlugin.ts';
 export { amplitudePlugin, type AmplitudeConfig, type CreateApiTrackingEventFn, } from './plugins/amplitude/amplitudePlugin.js';
 export { Amplitude } from './plugins/amplitude/Amplitude.js';
+export { FakeAmplitude } from './plugins/amplitude/FakeAmplitude.js';
 export { AmplitudeAdapter, AMPLITUDE_BASE_MESSAGE_SCHEMA, type AmplitudeMessage, type AmplitudeAdapterDependencies, } from './plugins/amplitude/AmplitudeAdapter.js';
 export type { FastifyReplyWithPayload } from './types.js';
 export { stripTrailingSlashPlugin } from './plugins/stripTrailingSlashPlugin.js';
@@ -38,4 +39,4 @@ export { createErrorHandler, isZodError, type ErrorResponseObject } from './erro
 export type { ErrorHandlerParams, FreeformRecord } from './errors/errorHandler.js';
 export { generateJwtToken, decodeJwtToken } from './jwt-utils/tokenUtils.js';
 export { createStaticTokenAuthPreHandler } from './route-utils/authPreHandlers.js';
-export type { AnyFastifyInstance, CommonFastifyInstance } from './plugins/pluginsCommon.js';
+export { getFastifyAppLoggingConfig, type AnyFastifyInstance, type CommonFastifyInstance, } from './plugins/pluginsCommon.js';

package/dist/index.js

@@ -15,10 +15,12 @@ export { startupHealthcheckPlugin } from './plugins/healthcheck/startupHealthche
 export { commonSyncHealthcheckPlugin } from "./plugins/healthcheck/commonSyncHealthcheckPlugin.js";
 export { amplitudePlugin, } from './plugins/amplitude/amplitudePlugin.js';
 export { Amplitude } from './plugins/amplitude/Amplitude.js';
+export { FakeAmplitude } from './plugins/amplitude/FakeAmplitude.js';
 export { AmplitudeAdapter, AMPLITUDE_BASE_MESSAGE_SCHEMA, } from './plugins/amplitude/AmplitudeAdapter.js';
 export { stripTrailingSlashPlugin } from './plugins/stripTrailingSlashPlugin.js';
 export { unhandledExceptionPlugin, commonErrorObjectResolver, } from './plugins/unhandledExceptionPlugin.js';
 export { createErrorHandler, isZodError } from './errors/errorHandler.js';
 export { generateJwtToken, decodeJwtToken } from './jwt-utils/tokenUtils.js';
 export { createStaticTokenAuthPreHandler } from './route-utils/authPreHandlers.js';
+export { getFastifyAppLoggingConfig, } from './plugins/pluginsCommon.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,GACf,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,2CAA2C,CAAA;AAGlD,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,+CAA+C,CAAA;AAGtD,OAAO,EACL,qCAAqC,EACrC,+BAA+B,GAChC,MAAM,oDAAoD,CAAA;AAG3D,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,0CAA0C,CAAA;AAGjD,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,mDAAmD,CAAA;AAO1D,OAAO,EAAE,mCAAmC,EAAE,MAAM,6DAA6D,CAAA;AAEjH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAEtE,OAAO,EACL,yBAAyB,EACzB,kCAAkC,GACnC,MAAM,+CAA+C,CAAA;AAGtD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAM1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kDAAkD,CAAA;AAO1F,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAA;AAG7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,kDAAkD,CAAA;AAG1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAA;AAG5F,OAAO,EAAE,2BAA2B,EAAE,MAAM,sDAAsD,CAAA;AAGlG,OAAO,EACL,eAAe,GAGhB,MAAM,wCAAwC,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AAC5D,OAAO,EACL,gBAAgB,EAChB,6BAA6B,GAG9B,MAAM,yCAAyC,CAAA;AAIhD,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAA;AAEhF,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uCAAuC,CAAA;AAG9C,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAA4B,MAAM,0BAA0B,CAAA;AAGnG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAE5E,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,GACf,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,2CAA2C,CAAA;AAGlD,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,+CAA+C,CAAA;AAGtD,OAAO,EACL,qCAAqC,EACrC,+BAA+B,GAChC,MAAM,oDAAoD,CAAA;AAG3D,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,0CAA0C,CAAA;AAGjD,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,mDAAmD,CAAA;AAO1D,OAAO,EAAE,mCAAmC,EAAE,MAAM,6DAA6D,CAAA;AAEjH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAEtE,OAAO,EACL,yBAAyB,EACzB,kCAAkC,GACnC,MAAM,+CAA+C,CAAA;AAGtD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAM1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kDAAkD,CAAA;AAO1F,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAA;AAG7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,kDAAkD,CAAA;AAG1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAA;AAG5F,OAAO,EAAE,2BAA2B,EAAE,MAAM,sDAAsD,CAAA;AAGlG,OAAO,EACL,eAAe,GAGhB,MAAM,wCAAwC,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAA;AACpE,OAAO,EACL,gBAAgB,EAChB,6BAA6B,GAG9B,MAAM,yCAAyC,CAAA;AAIhD,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAA;AAEhF,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,uCAAuC,CAAA;AAG9C,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAA4B,MAAM,0BAA0B,CAAA;AAGnG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAE5E,OAAO,EAAE,+BAA+B,EAAE,MAAM,kCAAkC,CAAA;AAClF,OAAO,EACL,0BAA0B,GAG3B,MAAM,4BAA4B,CAAA"}

package/dist/plugins/amplitude/FakeAmplitude.d.ts

@@ -0,0 +1,7 @@
+import type { AmplitudeReturn, Result } from '@amplitude/analytics-types';
+import type { BaseEvent } from '@amplitude/analytics-types/lib/esm/base-event.d.ts';
+import { Amplitude } from './Amplitude.ts';
+export declare class FakeAmplitude extends Amplitude {
+    constructor();
+    track(_: BaseEvent): AmplitudeReturn<Result | null>;
+}

package/dist/plugins/amplitude/FakeAmplitude.js

@@ -0,0 +1,12 @@
+import { Amplitude } from "./Amplitude.js";
+export class FakeAmplitude extends Amplitude {
+    constructor() {
+        super(false);
+    }
+    track(_) {
+        return {
+            promise: Promise.resolve(null),
+        };
+    }
+}
+//# sourceMappingURL=FakeAmplitude.js.map

package/dist/plugins/amplitude/FakeAmplitude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeAmplitude.js","sourceRoot":"","sources":["../../../lib/plugins/amplitude/FakeAmplitude.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C;QACE,KAAK,CAAC,KAAK,CAAC,CAAA;IACd,CAAC;IAEQ,KAAK,CAAC,CAAY;QACzB,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;SAC/B,CAAA;IACH,CAAC;CACF"}

package/dist/plugins/pluginsCommon.d.ts

@@ -1,4 +1,5 @@
-import type { CommonLogger } from '@lokalise/node-core';
-import type { FastifyInstance, FastifyTypeProviderDefault, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault } from 'fastify';
+import type { AppConfig, CommonLogger } from '@lokalise/node-core';
+import type { FastifyInstance, FastifyServerOptions, FastifyTypeProviderDefault, RawReplyDefaultExpression, RawRequestDefaultExpression, RawServerDefault } from 'fastify';
 export type CommonFastifyInstance = FastifyInstance<RawServerDefault, RawRequestDefaultExpression, RawReplyDefaultExpression, CommonLogger, FastifyTypeProviderDefault>;
 export type AnyFastifyInstance = FastifyInstance<any, any, any, any, any>;
+export declare function getFastifyAppLoggingConfig(appLogLevel: AppConfig['logLevel'], requestLoggingLevels?: string[]): Pick<FastifyServerOptions, 'disableRequestLogging'>;

package/dist/plugins/pluginsCommon.js

@@ -1,2 +1,12 @@
-export {};
+// Service utility endpoints to exclude from request logging
+const REQUEST_LOGGING_SKIP_PATHS = new Set(['/', '/health', '/ready', '/live', '/metrics']);
+const REQUEST_LOGGING_LEVELS = ['debug', 'trace', 'info'];
+export function getFastifyAppLoggingConfig(appLogLevel, requestLoggingLevels = REQUEST_LOGGING_LEVELS) {
+    const enableRequestLogging = requestLoggingLevels.includes(appLogLevel);
+    return {
+        disableRequestLogging: enableRequestLogging
+            ? (req) => REQUEST_LOGGING_SKIP_PATHS.has(req.url)
+            : true,
+    };
+}
 //# sourceMappingURL=pluginsCommon.js.map

package/dist/plugins/pluginsCommon.js.map

@@ -1 +1 @@
-{"version":3,"file":"pluginsCommon.js","sourceRoot":"","sources":["../../lib/plugins/pluginsCommon.ts"],"names":[],"mappings":""}
+{"version":3,"file":"pluginsCommon.js","sourceRoot":"","sources":["../../lib/plugins/pluginsCommon.ts"],"names":[],"mappings":"AAqBA,4DAA4D;AAC5D,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAA;AAC3F,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;AAEzD,MAAM,UAAU,0BAA0B,CACxC,WAAkC,EAClC,oBAAoB,GAAG,sBAAsB;IAE7C,MAAM,oBAAoB,GAAG,oBAAoB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IACvE,OAAO;QACL,qBAAqB,EAAE,oBAAoB;YACzC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,0BAA0B,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;YAClD,CAAC,CAAC,IAAI;KACT,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lokalise/fastify-extras",
-    "version": "30.4.0",
+    "version": "30.6.0",
     "description": "Opinionated set of fastify plugins, commonly used in Lokalise",
     "author": {
         "name": "Lokalise",
@@ -52,7 +52,7 @@
         "@lokalise/node-core": ">=14.0.0",
         "@opentelemetry/api": ">=1.9.0",
         "bullmq": "^5.19.0",
-        "fastify": "^5.5.0",
+        "fastify": "^5.7.1",
         "fastify-type-provider-zod": ">=6.0.0",
         "ioredis": "^5.7.0",
         "newrelic": ">=11.13.0",
@@ -72,11 +72,11 @@
         "@types/node": "^24.7.0",
         "@vitest/coverage-v8": "^3.2.4",
         "auto-changelog": "^2.4.0",
-        "bullmq": "^5.61.0",
-        "fastify": "^5.6.1",
+        "bullmq": "^5.67.1",
+        "fastify": "^5.7.2",
         "fastify-type-provider-zod": "^6.0.0",
         "ioredis": "^5.6.1",
-        "newrelic": "13.9.2",
+        "newrelic": "13.10.0",
         "pino": "^10.0.0",
         "pino-pretty": "^13.1.1",
         "rimraf": "^6.0.1",