@lokalise/fastify-extras 30.5.0 → 30.6.0

package/README.md

@@ -402,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
 
@@ -487,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';

package/dist/index.js

@@ -15,6 +15,7 @@ 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';

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;AAClF,OAAO,EACL,0BAA0B,GAG3B,MAAM,4BAA4B,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lokalise/fastify-extras",
-    "version": "30.5.0",
+    "version": "30.6.0",
     "description": "Opinionated set of fastify plugins, commonly used in Lokalise",
     "author": {
         "name": "Lokalise",