@dismissible/nestjs-dismissible-hooks 0.0.1

package/README.md

@@ -0,0 +1,116 @@
+# @dismissible/nestjs-dismissible-hooks
+
+Lifecycle hooks interfaces for Dismissible applications.
+
+> **Part of the Dismissible API** - This library is part of the [Dismissible API](https://dismissible.io) ecosystem. Visit [dismissible.io](https://dismissible.io) for more information and documentation.
+
+## Overview
+
+This library provides the core interfaces for implementing lifecycle hooks in the Dismissible system:
+
+- `IDismissibleLifecycleHook` - Interface for lifecycle hooks
+- `IHookResult` - Result returned by pre-hooks
+- `IHookMutations` - Mutations that can be applied by pre-hooks
+- `IRequestContext` - Request context passed through dismissible operations
+- `DISMISSIBLE_HOOKS` - Injection token for lifecycle hooks
+
+## Installation
+
+```bash
+npm install @dismissible/nestjs-dismissible-hooks
+```
+
+## Getting Started
+
+### Basic Usage
+
+Implement the `IDismissibleLifecycleHook` interface to create custom lifecycle hooks:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import {
+  IDismissibleLifecycleHook,
+  IHookResult,
+  IRequestContext,
+} from '@dismissible/nestjs-dismissible-hooks';
+
+@Injectable()
+export class MyLifecycleHook implements IDismissibleLifecycleHook {
+  readonly priority = 0;
+
+  async onBeforeRequest(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> {
+    // Your logic here
+    return { proceed: true };
+  }
+}
+```
+
+## API Reference
+
+### IDismissibleLifecycleHook
+
+Interface for lifecycle hooks that can intercept dismissible operations.
+
+#### Methods
+
+- `onBeforeRequest(itemId, userId, context?)` - Called at the start of any operation
+- `onAfterRequest(itemId, item, userId, context?)` - Called at the end of any operation
+- `onBeforeGet(itemId, item, userId, context?)` - Called before returning an existing item
+- `onAfterGet(itemId, item, userId, context?)` - Called after returning an existing item
+- `onBeforeCreate(itemId, userId, context?)` - Called before creating a new item
+- `onAfterCreate(itemId, item, userId, context?)` - Called after creating a new item
+- `onBeforeDismiss(itemId, userId, context?)` - Called before dismissing an item
+- `onAfterDismiss(itemId, item, userId, context?)` - Called after dismissing an item
+- `onBeforeRestore(itemId, userId, context?)` - Called before restoring an item
+- `onAfterRestore(itemId, item, userId, context?)` - Called after restoring an item
+
+### IHookResult
+
+Result returned by pre-hooks.
+
+```typescript
+interface IHookResult {
+  proceed: boolean;
+  reason?: string;
+  mutations?: IHookMutations;
+}
+```
+
+### IHookMutations
+
+Mutations that can be applied by pre-hooks.
+
+```typescript
+interface IHookMutations {
+  id?: string;
+  userId?: string;
+  context?: Partial<IRequestContext>;
+}
+```
+
+### IRequestContext
+
+Request context passed through dismissible operations.
+
+```typescript
+interface IRequestContext {
+  requestId: string;
+  authorizationHeader?: string;
+}
+```
+
+## Related Packages
+
+This library is typically used alongside other Dismissible packages:
+
+- `@dismissible/nestjs-dismissible` - Main dismissible service and module
+- `@dismissible/nestjs-dismissible-item` - Core data models
+- `@dismissible/nestjs-jwt-auth-hook` - JWT authentication hook implementation
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dismissible/nestjs-dismissible-hooks",
+  "version": "0.0.1",
+  "description": "Lifecycle hooks interfaces for Dismissible applications",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dismissible/nestjs-dismissible-item": "^0.0.1",
+    "@dismissible/nestjs-dismissible-request": "^0.0.1"
+  },
+  "keywords": [
+    "nestjs",
+    "dismissible",
+    "hooks",
+    "lifecycle"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DismissibleIo/dismissible-api"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs"
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lifecycle-hook.interface';

package/src/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lifecycle-hook.interface"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/dismissible-hooks/src/index.ts"],"names":[],"mappings":";;;AAAA,qEAA2C"}

package/src/lifecycle-hook.interface.d.ts

@@ -0,0 +1,84 @@
+import { DismissibleItemDto } from '@dismissible/nestjs-dismissible-item';
+import { IRequestContext } from '@dismissible/nestjs-dismissible-request';
+/**
+ * Injection token for lifecycle hooks.
+ */
+export declare const DISMISSIBLE_HOOKS: unique symbol;
+/**
+ * Mutations that can be applied by pre-hooks.
+ */
+export interface IHookMutations {
+    /** Mutated item ID */
+    id?: string;
+    /** Mutated user ID */
+    userId?: string;
+    /** Mutated request context */
+    context?: Partial<IRequestContext>;
+}
+/**
+ * Result returned by pre-hooks.
+ */
+export interface IHookResult {
+    /** Whether the operation should proceed */
+    proceed: boolean;
+    /** Optional reason if the operation is blocked */
+    reason?: string;
+    /** Optional mutations to apply */
+    mutations?: IHookMutations;
+}
+/**
+ * Interface for lifecycle hooks that can intercept dismissible operations.
+ */
+export interface IDismissibleLifecycleHook {
+    /**
+     * Priority for hook execution (lower numbers run first).
+     * Default is 0.
+     */
+    readonly priority?: number;
+    /**
+     * Called at the start of any operation (getOrCreate, dismiss, restore).
+     * Use for global concerns like authentication, rate limiting, request validation.
+     */
+    onBeforeRequest?(itemId: string, userId: string, context?: IRequestContext): Promise<IHookResult> | IHookResult;
+    /**
+     * Called at the end of any operation (getOrCreate, dismiss, restore).
+     * Use for global concerns like audit logging, metrics, cleanup.
+     */
+    onAfterRequest?(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext): Promise<void> | void;
+    /**
+     * Called before returning an existing item.
+     * Only called when item exists in storage.
+     * Use for access control based on item state (e.g., block dismissed items).
+     */
+    onBeforeGet?(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext): Promise<IHookResult> | IHookResult;
+    /**
+     * Called after returning an existing item.
+     * Only called when item exists in storage.
+     */
+    onAfterGet?(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext): Promise<void> | void;
+    /**
+     * Called before creating a new item.
+     * Use for plan limits, quota checks, etc.
+     */
+    onBeforeCreate?(itemId: string, userId: string, context?: IRequestContext): Promise<IHookResult> | IHookResult;
+    /**
+     * Called after creating a new item.
+     */
+    onAfterCreate?(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext): Promise<void> | void;
+    /**
+     * Called before dismissing an item.
+     */
+    onBeforeDismiss?(itemId: string, userId: string, context?: IRequestContext): Promise<IHookResult> | IHookResult;
+    /**
+     * Called after dismissing an item.
+     */
+    onAfterDismiss?(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext): Promise<void> | void;
+    /**
+     * Called before restoring an item.
+     */
+    onBeforeRestore?(itemId: string, userId: string, context?: IRequestContext): Promise<IHookResult> | IHookResult;
+    /**
+     * Called after restoring an item.
+     */
+    onAfterRestore?(itemId: string, item: DismissibleItemDto, userId: string, context?: IRequestContext): Promise<void> | void;
+}

package/src/lifecycle-hook.interface.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISMISSIBLE_HOOKS = void 0;
+/**
+ * Injection token for lifecycle hooks.
+ */
+exports.DISMISSIBLE_HOOKS = Symbol('DISMISSIBLE_HOOKS');
+//# sourceMappingURL=lifecycle-hook.interface.js.map

package/src/lifecycle-hook.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-hook.interface.js","sourceRoot":"","sources":["../../../../libs/dismissible-hooks/src/lifecycle-hook.interface.ts"],"names":[],"mappings":";;;AAGA;;GAEG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC"}