@clipboard-health/ai-rules 0.3.1 → 0.3.3

package/backend/AGENTS.md

@@ -13,6 +13,151 @@
 - Requests and responses follow the JSON:API specification, including pagination for listings.
 - Use TypeDoc to document public functions, classes, methods, and complex code blocks.
 
+<!-- Source: .ruler/backend/notifications.md -->
+
+# Notifications
+
+Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
+
+## Usage
+
+<embedex source="packages/notifications/examples/usage.md">
+
+1. Search your service for a `NotificationJobEnqueuer` instance. If there isn't one, create and export it:
+
+   ```ts
+   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
+
+   import { BackgroundJobsService } from "./setup";
+
+   // Create and export one instance of this in your microservice.
+   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
+     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
+     adapter: new BackgroundJobsService(),
+   });
+   ```
+
+1. Implement a minimal job, calling off to a NestJS service for any business logic and to send the notification.
+
+   ```ts
+   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
+   import { type NotificationData } from "@clipboard-health/notifications";
+   import { isFailure, toError } from "@clipboard-health/util-ts";
+
+   import { type ExampleNotificationService } from "./exampleNotification.service";
+
+   export type ExampleNotificationData = NotificationData<{
+     workplaceId: string;
+   }>;
+
+   export const EXAMPLE_NOTIFICATION_JOB_NAME = "ExampleNotificationJob";
+
+   // For mongo-jobs, you'll implement HandlerInterface<ExampleNotificationData["Job"]>
+   // For background-jobs-postgres, you'll implement Handler<ExampleNotificationData["Job"]>
+   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationData["Job"]> {
+     public name = EXAMPLE_NOTIFICATION_JOB_NAME;
+
+     constructor(private readonly service: ExampleNotificationService) {}
+
+     async perform(data: ExampleNotificationData["Job"], job: { attemptsCount: number }) {
+       const result = await this.service.sendNotification({
+         ...data,
+         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
+         attempt: job.attemptsCount + 1,
+       });
+
+       if (isFailure(result)) {
+         throw toError(result.error);
+       }
+     }
+   }
+   ```
+
+1. Search your service for a constant that stores workflow keys. If there isn't one, create and export it:
+
+   ```ts
+   export const WORKFLOW_KEYS = {
+     eventStartingReminder: "event-starting-reminder",
+   } as const;
+   ```
+
+1. Enqueue your job:
+
+   ```ts
+   import {
+     EXAMPLE_NOTIFICATION_JOB_NAME,
+     type ExampleNotificationData,
+   } from "./exampleNotification.job";
+   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
+   import { WORKFLOW_KEYS } from "./workflowKeys";
+
+   async function enqueueNotificationJob() {
+     await notificationJobEnqueuer.enqueueOneOrMore<ExampleNotificationData["Enqueue"]>(
+       EXAMPLE_NOTIFICATION_JOB_NAME,
+       // Important: Read the TypeDoc documentation for additional context.
+       {
+         /**
+          * Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
+          * service instead of this manual calculation.
+          */
+         expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
+         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
+         idempotencyKey: {
+           resourceId: "event-123",
+         },
+         // Set recipients at enqueue-time so they respect our notification provider's limits.
+         recipients: ["userId-1"],
+
+         workflowKey: WORKFLOW_KEYS.eventStartingReminder,
+
+         // Any additional enqueue-time data passed to the job:
+         workplaceId: "workplaceId-123",
+       },
+     );
+   }
+
+   // eslint-disable-next-line unicorn/prefer-top-level-await
+   void enqueueNotificationJob();
+   ```
+
+1. Trigger the job in your NestJS service:
+
+   ```ts
+   import { type NotificationClient } from "@clipboard-health/notifications";
+
+   import { type ExampleNotificationData } from "./exampleNotification.job";
+
+   type ExampleNotificationDo = ExampleNotificationData["Job"] & { attempt: number };
+
+   export class ExampleNotificationService {
+     constructor(private readonly client: NotificationClient) {}
+
+     async sendNotification(params: ExampleNotificationDo) {
+       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
+
+       // Assume this comes from a database and are used as template variables...
+       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
+       const data = { favoriteColor: "blue", favoriteAt: new Date().toISOString(), secret: "2" };
+
+       // Important: Read the TypeDoc documentation for additional context.
+       return await this.client.trigger({
+         attempt,
+         body: {
+           data,
+           recipients,
+           workplaceId,
+         },
+         expiresAt: new Date(expiresAt),
+         idempotencyKey,
+         keysToRedact: ["secret"],
+         workflowKey,
+       });
+     }
+   }
+   ```
+
+</embedex>
+
 <!-- Source: .ruler/common/codeStyleAndStructure.md -->
 
 # Code style and structure

package/backend/CLAUDE.md

@@ -11,6 +11,151 @@
 - Requests and responses follow the JSON:API specification, including pagination for listings.
 - Use TypeDoc to document public functions, classes, methods, and complex code blocks.
 
+<!-- Source: .ruler/backend/notifications.md -->
+
+# Notifications
+
+Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
+
+## Usage
+
+<embedex source="packages/notifications/examples/usage.md">
+
+1. Search your service for a `NotificationJobEnqueuer` instance. If there isn't one, create and export it:
+
+   ```ts
+   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
+
+   import { BackgroundJobsService } from "./setup";
+
+   // Create and export one instance of this in your microservice.
+   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
+     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
+     adapter: new BackgroundJobsService(),
+   });
+   ```
+
+1. Implement a minimal job, calling off to a NestJS service for any business logic and to send the notification.
+
+   ```ts
+   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
+   import { type NotificationData } from "@clipboard-health/notifications";
+   import { isFailure, toError } from "@clipboard-health/util-ts";
+
+   import { type ExampleNotificationService } from "./exampleNotification.service";
+
+   export type ExampleNotificationData = NotificationData<{
+     workplaceId: string;
+   }>;
+
+   export const EXAMPLE_NOTIFICATION_JOB_NAME = "ExampleNotificationJob";
+
+   // For mongo-jobs, you'll implement HandlerInterface<ExampleNotificationData["Job"]>
+   // For background-jobs-postgres, you'll implement Handler<ExampleNotificationData["Job"]>
+   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationData["Job"]> {
+     public name = EXAMPLE_NOTIFICATION_JOB_NAME;
+
+     constructor(private readonly service: ExampleNotificationService) {}
+
+     async perform(data: ExampleNotificationData["Job"], job: { attemptsCount: number }) {
+       const result = await this.service.sendNotification({
+         ...data,
+         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
+         attempt: job.attemptsCount + 1,
+       });
+
+       if (isFailure(result)) {
+         throw toError(result.error);
+       }
+     }
+   }
+   ```
+
+1. Search your service for a constant that stores workflow keys. If there isn't one, create and export it:
+
+   ```ts
+   export const WORKFLOW_KEYS = {
+     eventStartingReminder: "event-starting-reminder",
+   } as const;
+   ```
+
+1. Enqueue your job:
+
+   ```ts
+   import {
+     EXAMPLE_NOTIFICATION_JOB_NAME,
+     type ExampleNotificationData,
+   } from "./exampleNotification.job";
+   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
+   import { WORKFLOW_KEYS } from "./workflowKeys";
+
+   async function enqueueNotificationJob() {
+     await notificationJobEnqueuer.enqueueOneOrMore<ExampleNotificationData["Enqueue"]>(
+       EXAMPLE_NOTIFICATION_JOB_NAME,
+       // Important: Read the TypeDoc documentation for additional context.
+       {
+         /**
+          * Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
+          * service instead of this manual calculation.
+          */
+         expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
+         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
+         idempotencyKey: {
+           resourceId: "event-123",
+         },
+         // Set recipients at enqueue-time so they respect our notification provider's limits.
+         recipients: ["userId-1"],
+
+         workflowKey: WORKFLOW_KEYS.eventStartingReminder,
+
+         // Any additional enqueue-time data passed to the job:
+         workplaceId: "workplaceId-123",
+       },
+     );
+   }
+
+   // eslint-disable-next-line unicorn/prefer-top-level-await
+   void enqueueNotificationJob();
+   ```
+
+1. Trigger the job in your NestJS service:
+
+   ```ts
+   import { type NotificationClient } from "@clipboard-health/notifications";
+
+   import { type ExampleNotificationData } from "./exampleNotification.job";
+
+   type ExampleNotificationDo = ExampleNotificationData["Job"] & { attempt: number };
+
+   export class ExampleNotificationService {
+     constructor(private readonly client: NotificationClient) {}
+
+     async sendNotification(params: ExampleNotificationDo) {
+       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
+
+       // Assume this comes from a database and are used as template variables...
+       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
+       const data = { favoriteColor: "blue", favoriteAt: new Date().toISOString(), secret: "2" };
+
+       // Important: Read the TypeDoc documentation for additional context.
+       return await this.client.trigger({
+         attempt,
+         body: {
+           data,
+           recipients,
+           workplaceId,
+         },
+         expiresAt: new Date(expiresAt),
+         idempotencyKey,
+         keysToRedact: ["secret"],
+         workflowKey,
+       });
+     }
+   }
+   ```
+
+</embedex>
+
 <!-- Source: .ruler/common/codeStyleAndStructure.md -->
 
 # Code style and structure

package/fullstack/AGENTS.md

@@ -13,6 +13,151 @@
 - Requests and responses follow the JSON:API specification, including pagination for listings.
 - Use TypeDoc to document public functions, classes, methods, and complex code blocks.
 
+<!-- Source: .ruler/backend/notifications.md -->
+
+# Notifications
+
+Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
+
+## Usage
+
+<embedex source="packages/notifications/examples/usage.md">
+
+1. Search your service for a `NotificationJobEnqueuer` instance. If there isn't one, create and export it:
+
+   ```ts
+   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
+
+   import { BackgroundJobsService } from "./setup";
+
+   // Create and export one instance of this in your microservice.
+   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
+     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
+     adapter: new BackgroundJobsService(),
+   });
+   ```
+
+1. Implement a minimal job, calling off to a NestJS service for any business logic and to send the notification.
+
+   ```ts
+   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
+   import { type NotificationData } from "@clipboard-health/notifications";
+   import { isFailure, toError } from "@clipboard-health/util-ts";
+
+   import { type ExampleNotificationService } from "./exampleNotification.service";
+
+   export type ExampleNotificationData = NotificationData<{
+     workplaceId: string;
+   }>;
+
+   export const EXAMPLE_NOTIFICATION_JOB_NAME = "ExampleNotificationJob";
+
+   // For mongo-jobs, you'll implement HandlerInterface<ExampleNotificationData["Job"]>
+   // For background-jobs-postgres, you'll implement Handler<ExampleNotificationData["Job"]>
+   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationData["Job"]> {
+     public name = EXAMPLE_NOTIFICATION_JOB_NAME;
+
+     constructor(private readonly service: ExampleNotificationService) {}
+
+     async perform(data: ExampleNotificationData["Job"], job: { attemptsCount: number }) {
+       const result = await this.service.sendNotification({
+         ...data,
+         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
+         attempt: job.attemptsCount + 1,
+       });
+
+       if (isFailure(result)) {
+         throw toError(result.error);
+       }
+     }
+   }
+   ```
+
+1. Search your service for a constant that stores workflow keys. If there isn't one, create and export it:
+
+   ```ts
+   export const WORKFLOW_KEYS = {
+     eventStartingReminder: "event-starting-reminder",
+   } as const;
+   ```
+
+1. Enqueue your job:
+
+   ```ts
+   import {
+     EXAMPLE_NOTIFICATION_JOB_NAME,
+     type ExampleNotificationData,
+   } from "./exampleNotification.job";
+   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
+   import { WORKFLOW_KEYS } from "./workflowKeys";
+
+   async function enqueueNotificationJob() {
+     await notificationJobEnqueuer.enqueueOneOrMore<ExampleNotificationData["Enqueue"]>(
+       EXAMPLE_NOTIFICATION_JOB_NAME,
+       // Important: Read the TypeDoc documentation for additional context.
+       {
+         /**
+          * Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
+          * service instead of this manual calculation.
+          */
+         expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
+         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
+         idempotencyKey: {
+           resourceId: "event-123",
+         },
+         // Set recipients at enqueue-time so they respect our notification provider's limits.
+         recipients: ["userId-1"],
+
+         workflowKey: WORKFLOW_KEYS.eventStartingReminder,
+
+         // Any additional enqueue-time data passed to the job:
+         workplaceId: "workplaceId-123",
+       },
+     );
+   }
+
+   // eslint-disable-next-line unicorn/prefer-top-level-await
+   void enqueueNotificationJob();
+   ```
+
+1. Trigger the job in your NestJS service:
+
+   ```ts
+   import { type NotificationClient } from "@clipboard-health/notifications";
+
+   import { type ExampleNotificationData } from "./exampleNotification.job";
+
+   type ExampleNotificationDo = ExampleNotificationData["Job"] & { attempt: number };
+
+   export class ExampleNotificationService {
+     constructor(private readonly client: NotificationClient) {}
+
+     async sendNotification(params: ExampleNotificationDo) {
+       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
+
+       // Assume this comes from a database and are used as template variables...
+       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
+       const data = { favoriteColor: "blue", favoriteAt: new Date().toISOString(), secret: "2" };
+
+       // Important: Read the TypeDoc documentation for additional context.
+       return await this.client.trigger({
+         attempt,
+         body: {
+           data,
+           recipients,
+           workplaceId,
+         },
+         expiresAt: new Date(expiresAt),
+         idempotencyKey,
+         keysToRedact: ["secret"],
+         workflowKey,
+       });
+     }
+   }
+   ```
+
+</embedex>
+
 <!-- Source: .ruler/common/codeStyleAndStructure.md -->
 
 # Code style and structure

package/fullstack/CLAUDE.md

@@ -11,6 +11,151 @@
 - Requests and responses follow the JSON:API specification, including pagination for listings.
 - Use TypeDoc to document public functions, classes, methods, and complex code blocks.
 
+<!-- Source: .ruler/backend/notifications.md -->
+
+# Notifications
+
+Send notifications through [Knock](https://docs.knock.app) using the `@clipboard-health/notifications` NPM library.
+
+## Usage
+
+<embedex source="packages/notifications/examples/usage.md">
+
+1. Search your service for a `NotificationJobEnqueuer` instance. If there isn't one, create and export it:
+
+   ```ts
+   import { NotificationJobEnqueuer } from "@clipboard-health/notifications";
+
+   import { BackgroundJobsService } from "./setup";
+
+   // Create and export one instance of this in your microservice.
+   export const notificationJobEnqueuer = new NotificationJobEnqueuer({
+     // Use your instance of `@clipboard-health/mongo-jobs` or `@clipboard-health/background-jobs-postgres` here.
+     adapter: new BackgroundJobsService(),
+   });
+   ```
+
+1. Implement a minimal job, calling off to a NestJS service for any business logic and to send the notification.
+
+   ```ts
+   import { type BaseHandler } from "@clipboard-health/background-jobs-adapter";
+   import { type NotificationData } from "@clipboard-health/notifications";
+   import { isFailure, toError } from "@clipboard-health/util-ts";
+
+   import { type ExampleNotificationService } from "./exampleNotification.service";
+
+   export type ExampleNotificationData = NotificationData<{
+     workplaceId: string;
+   }>;
+
+   export const EXAMPLE_NOTIFICATION_JOB_NAME = "ExampleNotificationJob";
+
+   // For mongo-jobs, you'll implement HandlerInterface<ExampleNotificationData["Job"]>
+   // For background-jobs-postgres, you'll implement Handler<ExampleNotificationData["Job"]>
+   export class ExampleNotificationJob implements BaseHandler<ExampleNotificationData["Job"]> {
+     public name = EXAMPLE_NOTIFICATION_JOB_NAME;
+
+     constructor(private readonly service: ExampleNotificationService) {}
+
+     async perform(data: ExampleNotificationData["Job"], job: { attemptsCount: number }) {
+       const result = await this.service.sendNotification({
+         ...data,
+         // Include the job's attempts count for debugging, this is called `retryAttempts` in `background-jobs-postgres`.
+         attempt: job.attemptsCount + 1,
+       });
+
+       if (isFailure(result)) {
+         throw toError(result.error);
+       }
+     }
+   }
+   ```
+
+1. Search your service for a constant that stores workflow keys. If there isn't one, create and export it:
+
+   ```ts
+   export const WORKFLOW_KEYS = {
+     eventStartingReminder: "event-starting-reminder",
+   } as const;
+   ```
+
+1. Enqueue your job:
+
+   ```ts
+   import {
+     EXAMPLE_NOTIFICATION_JOB_NAME,
+     type ExampleNotificationData,
+   } from "./exampleNotification.job";
+   import { notificationJobEnqueuer } from "./notificationJobEnqueuer";
+   import { WORKFLOW_KEYS } from "./workflowKeys";
+
+   async function enqueueNotificationJob() {
+     await notificationJobEnqueuer.enqueueOneOrMore<ExampleNotificationData["Enqueue"]>(
+       EXAMPLE_NOTIFICATION_JOB_NAME,
+       // Important: Read the TypeDoc documentation for additional context.
+       {
+         /**
+          * Set expiresAt at enqueue-time so it remains stable across job retries. Use date-fns in your
+          * service instead of this manual calculation.
+          */
+         expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
+         // Set idempotencyKey at enqueue-time so it remains stable across job retries.
+         idempotencyKey: {
+           resourceId: "event-123",
+         },
+         // Set recipients at enqueue-time so they respect our notification provider's limits.
+         recipients: ["userId-1"],
+
+         workflowKey: WORKFLOW_KEYS.eventStartingReminder,
+
+         // Any additional enqueue-time data passed to the job:
+         workplaceId: "workplaceId-123",
+       },
+     );
+   }
+
+   // eslint-disable-next-line unicorn/prefer-top-level-await
+   void enqueueNotificationJob();
+   ```
+
+1. Trigger the job in your NestJS service:
+
+   ```ts
+   import { type NotificationClient } from "@clipboard-health/notifications";
+
+   import { type ExampleNotificationData } from "./exampleNotification.job";
+
+   type ExampleNotificationDo = ExampleNotificationData["Job"] & { attempt: number };
+
+   export class ExampleNotificationService {
+     constructor(private readonly client: NotificationClient) {}
+
+     async sendNotification(params: ExampleNotificationDo) {
+       const { attempt, expiresAt, idempotencyKey, recipients, workflowKey, workplaceId } = params;
+
+       // Assume this comes from a database and are used as template variables...
+       // Use @clipboard-health/date-time's formatShortDateTime in your service for consistency.
+       const data = { favoriteColor: "blue", favoriteAt: new Date().toISOString(), secret: "2" };
+
+       // Important: Read the TypeDoc documentation for additional context.
+       return await this.client.trigger({
+         attempt,
+         body: {
+           data,
+           recipients,
+           workplaceId,
+         },
+         expiresAt: new Date(expiresAt),
+         idempotencyKey,
+         keysToRedact: ["secret"],
+         workflowKey,
+       });
+     }
+   }
+   ```
+
+</embedex>
+
 <!-- Source: .ruler/common/codeStyleAndStructure.md -->
 
 # Code style and structure

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/ai-rules",
   "description": "Pre-built AI agent rules for consistent coding standards.",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "devDependencies": {
     "@intellectronica/ruler": "0.3.10"