@dismissible/nestjs-dismissible 0.0.2-canary.738340d.0 → 0.0.2-canary.c91edbc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dismissible/nestjs-dismissible",
-  "version": "0.0.2-canary.738340d.0",
+  "version": "0.0.2-canary.c91edbc.0",
   "description": "Dismissible state management library for NestJS applications",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -19,8 +19,8 @@
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/swagger": "^11.0.0",
-    "@dismissible/nestjs-dismissible-item": "^0.0.2-canary.738340d.0",
-    "@dismissible/nestjs-storage": "^0.0.2-canary.738340d.0",
+    "@dismissible/nestjs-dismissible-item": "^0.0.2-canary.c91edbc.0",
+    "@dismissible/nestjs-storage": "^0.0.2-canary.c91edbc.0",
     "class-validator": "^0.14.0",
     "class-transformer": "^0.5.0"
   },
@@ -34,7 +34,7 @@
     "@nestjs/swagger": {
       "optional": false
     },
-    "dismissible/nestjs-dismissible-item": {
+    "@dismissible/nestjs-dismissible-item": {
       "optional": false
     },
     "@dismissible/nestjs-storage": {
@@ -58,6 +58,9 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": ""
+    "url": "https://github.com/DismissibleIo/dismissible-api"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/core/dismissible-core.service.spec.ts

@@ -51,6 +51,94 @@ describe('DismissibleCoreService', () => {
     jest.clearAllMocks();
   });
 
+  describe('get', () => {
+    it('should return item when it exists', async () => {
+      const userId = 'user-123';
+      const existingItem = createTestItem({ id: 'existing-item', userId });
+      storage.get.mockResolvedValue(existingItem);
+
+      const result = await service.get('existing-item', userId);
+
+      expect(result).toEqual(existingItem);
+      expect(storage.get).toHaveBeenCalledWith(userId, 'existing-item');
+    });
+
+    it('should return null when item does not exist', async () => {
+      const userId = 'user-123';
+      storage.get.mockResolvedValue(null);
+
+      const result = await service.get('non-existent', userId);
+
+      expect(result).toBeNull();
+      expect(storage.get).toHaveBeenCalledWith(userId, 'non-existent');
+    });
+  });
+
+  describe('create', () => {
+    it('should create a new item', async () => {
+      const testDate = new Date('2024-01-15T10:00:00.000Z');
+      const userId = 'user-123';
+      const newItem = createTestItem({ id: 'new-item', userId, createdAt: testDate });
+
+      storage.create.mockResolvedValue(newItem);
+      mockDateService.getNow.mockReturnValue(testDate);
+      itemFactory.create.mockReturnValue(newItem);
+
+      const result = await service.create('new-item', userId);
+
+      expect(result.id).toBe('new-item');
+      expect(result.userId).toBe(userId);
+      expect(result.createdAt).toBeInstanceOf(Date);
+      expect(result.dismissedAt).toBeUndefined();
+      expect(storage.create).toHaveBeenCalledWith(newItem);
+    });
+
+    it('should create item with metadata when provided', async () => {
+      const userId = 'user-123';
+      const metadata = { version: 2, category: 'test' };
+      const testDate = new Date('2024-01-15T10:00:00.000Z');
+      const newItem = createTestItem({ id: 'new-item', userId, metadata, createdAt: testDate });
+
+      storage.create.mockResolvedValue(newItem);
+      mockDateService.getNow.mockReturnValue(testDate);
+      itemFactory.create.mockReturnValue(newItem);
+
+      const result = await service.create('new-item', userId, { metadata });
+
+      expect(result.metadata).toEqual(metadata);
+      expect(storage.create).toHaveBeenCalledWith(newItem);
+    });
+
+    it('should validate item before storage', async () => {
+      const userId = 'user-123';
+      const testDate = new Date('2024-01-15T10:00:00.000Z');
+      const newItem = createTestItem({ id: 'new-item', userId, createdAt: testDate });
+
+      storage.create.mockResolvedValue(newItem);
+      mockDateService.getNow.mockReturnValue(testDate);
+      itemFactory.create.mockReturnValue(newItem);
+
+      await service.create('new-item', userId);
+
+      expect(validationService.validateInstance).toHaveBeenCalledWith(newItem);
+    });
+
+    it('should throw BadRequestException when validation fails', async () => {
+      const userId = 'user-123';
+      const testDate = new Date('2024-01-15T10:00:00.000Z');
+      const newItem = createTestItem({ id: 'new-item', userId, createdAt: testDate });
+
+      mockDateService.getNow.mockReturnValue(testDate);
+      itemFactory.create.mockReturnValue(newItem);
+      validationService.validateInstance.mockRejectedValue(
+        new BadRequestException('id must be a string'),
+      );
+
+      await expect(service.create('new-item', userId)).rejects.toThrow(BadRequestException);
+      expect(storage.create).not.toHaveBeenCalled();
+    });
+  });
+
   describe('getOrCreate', () => {
     it('should create a new item when it does not exist', async () => {
       const testDate = new Date('2024-01-15T10:00:00.000Z');

package/src/core/dismissible-core.service.ts

@@ -14,7 +14,11 @@ import {
   ItemNotDismissedException,
 } from '../exceptions';
 import { ValidationService } from '@dismissible/nestjs-validation';
-import { BaseMetadata, DismissibleItemFactory } from '@dismissible/nestjs-dismissible-item';
+import {
+  BaseMetadata,
+  DismissibleItemDto,
+  DismissibleItemFactory,
+} from '@dismissible/nestjs-dismissible-item';
 import { ICreateItemOptions } from './create-options';
 
 /**
@@ -33,28 +37,32 @@ export class DismissibleCoreService<TMetadata extends BaseMetadata = BaseMetadat
   ) {}
 
   /**
-   * Get an existing item or create a new one.
+   * Get an existing item by user ID and item ID.
    * @param itemId The item identifier
    * @param userId The user identifier (required)
-   * @param options Optional creation options (metadata)
+   * @returns The item or null if not found
    */
-  async getOrCreate(
-    itemId: string,
-    userId: string,
-    options?: ICreateItemOptions<TMetadata>,
-  ): Promise<IGetOrCreateServiceResponse<TMetadata>> {
+  async get(itemId: string, userId: string): Promise<DismissibleItemDto<TMetadata> | null> {
     this.logger.debug(`Looking up item in storage`, { itemId, userId });
-
-    const existingItem = await this.storage.get(userId, itemId);
-
-    if (existingItem) {
+    const item = await this.storage.get(userId, itemId);
+    if (item) {
       this.logger.debug(`Found existing item`, { itemId, userId });
-      return {
-        item: existingItem,
-        created: false,
-      };
     }
+    return item;
+  }
 
+  /**
+   * Create a new item.
+   * @param itemId The item identifier
+   * @param userId The user identifier (required)
+   * @param options Optional creation options (metadata)
+   * @returns The created item
+   */
+  async create(
+    itemId: string,
+    userId: string,
+    options?: ICreateItemOptions<TMetadata>,
+  ): Promise<DismissibleItemDto<TMetadata>> {
     this.logger.debug(`Creating new item`, {
       itemId,
       userId,
@@ -77,6 +85,31 @@ export class DismissibleCoreService<TMetadata extends BaseMetadata = BaseMetadat
 
     this.logger.info(`Created new dismissible item`, { itemId, userId });
 
+    return createdItem;
+  }
+
+  /**
+   * Get an existing item or create a new one.
+   * @param itemId The item identifier
+   * @param userId The user identifier (required)
+   * @param options Optional creation options (metadata)
+   */
+  async getOrCreate(
+    itemId: string,
+    userId: string,
+    options?: ICreateItemOptions<TMetadata>,
+  ): Promise<IGetOrCreateServiceResponse<TMetadata>> {
+    const existingItem = await this.get(itemId, userId);
+
+    if (existingItem) {
+      return {
+        item: existingItem,
+        created: false,
+      };
+    }
+
+    const createdItem = await this.create(itemId, userId, options);
+
     return {
       item: createdItem,
       created: true,

package/src/core/dismissible.service.spec.ts

@@ -34,22 +34,28 @@ describe('DismissibleService', () => {
   });
 
   describe('getOrCreate', () => {
-    it('should run hooks, call core service, and emit ITEM_RETRIEVED event for existing item', async () => {
+    it('should run request and get hooks for existing item', async () => {
       const item = createTestItem({ id: 'existing-item' });
       const context = createTestContext();
 
-      mockHookRunner.runPreGetOrCreate.mockResolvedValue(createHookResult('existing-item'));
-      mockCoreService.getOrCreate.mockResolvedValue({ item, created: false });
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('existing-item'));
+      mockHookRunner.runPreGet.mockResolvedValue(createHookResult('existing-item'));
+      mockCoreService.get.mockResolvedValue(item);
 
       const result = await service.getOrCreate('existing-item', testUserId, undefined, context);
 
-      expect(mockHookRunner.runPreGetOrCreate).toHaveBeenCalled();
-      expect(mockCoreService.getOrCreate).toHaveBeenCalledWith(
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
+      expect(mockCoreService.get).toHaveBeenCalledWith('existing-item', testUserId);
+      expect(mockHookRunner.runPreGet).toHaveBeenCalledWith(
         'existing-item',
+        item,
         testUserId,
-        undefined,
+        expect.anything(),
       );
-      expect(mockHookRunner.runPostGetOrCreate).toHaveBeenCalled();
+      expect(mockHookRunner.runPostGet).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
+      expect(mockCoreService.create).not.toHaveBeenCalled();
+      expect(mockHookRunner.runPreCreate).not.toHaveBeenCalled();
       expect(mockEventEmitter.emit).toHaveBeenCalledWith(
         DismissibleEvents.ITEM_RETRIEVED,
         expect.anything(),
@@ -57,24 +63,90 @@ describe('DismissibleService', () => {
       expect(result.created).toBe(false);
     });
 
-    it('should run create hooks and emit ITEM_CREATED event for new item', async () => {
+    it('should run pre-create hooks BEFORE creating for new item', async () => {
       const item = createTestItem({ id: 'new-item' });
       const context = createTestContext();
-
-      mockHookRunner.runPreGetOrCreate.mockResolvedValue(createHookResult('new-item'));
-      mockHookRunner.runPreCreate.mockResolvedValue(createHookResult('new-item'));
-      mockCoreService.getOrCreate.mockResolvedValue({ item, created: true });
+      const callOrder: string[] = [];
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('new-item'));
+      mockCoreService.get.mockResolvedValue(null);
+      mockHookRunner.runPreCreate.mockImplementation(async () => {
+        callOrder.push('runPreCreate');
+        return createHookResult('new-item');
+      });
+      mockCoreService.create.mockImplementation(async () => {
+        callOrder.push('create');
+        return item;
+      });
 
       const result = await service.getOrCreate('new-item', testUserId, undefined, context);
 
+      // Verify pre-create hooks run BEFORE create
+      expect(callOrder).toEqual(['runPreCreate', 'create']);
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
       expect(mockHookRunner.runPreCreate).toHaveBeenCalled();
+      expect(mockCoreService.create).toHaveBeenCalledWith('new-item', testUserId, undefined);
       expect(mockHookRunner.runPostCreate).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
       expect(mockEventEmitter.emit).toHaveBeenCalledWith(
         DismissibleEvents.ITEM_CREATED,
         expect.anything(),
       );
       expect(result.created).toBe(true);
     });
+
+    it('should NOT create item when pre-create hook blocks the operation', async () => {
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('new-item'));
+      mockCoreService.get.mockResolvedValue(null);
+      mockHookRunner.runPreCreate.mockResolvedValue({
+        proceed: false,
+        reason: 'Plan limit reached',
+        id: 'new-item',
+        userId: testUserId,
+        context: createTestContext(),
+      });
+
+      await expect(
+        service.getOrCreate('new-item', testUserId, undefined, context),
+      ).rejects.toThrow();
+
+      // Verify create was NOT called because pre-create hook blocked it
+      expect(mockCoreService.create).not.toHaveBeenCalled();
+      expect(mockHookRunner.runPostCreate).not.toHaveBeenCalled();
+      expect(mockEventEmitter.emit).not.toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_CREATED,
+        expect.anything(),
+      );
+    });
+
+    it('should NOT return existing item when pre-get hook blocks the operation', async () => {
+      const item = createTestItem({ id: 'existing-item' });
+      const context = createTestContext();
+
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('existing-item'));
+      mockCoreService.get.mockResolvedValue(item);
+      mockHookRunner.runPreGet.mockResolvedValue({
+        proceed: false,
+        reason: 'Item access denied',
+        id: 'existing-item',
+        userId: testUserId,
+        context: createTestContext(),
+      });
+
+      await expect(
+        service.getOrCreate('existing-item', testUserId, undefined, context),
+      ).rejects.toThrow();
+
+      // Verify post-get hooks were NOT called because pre-get hook blocked
+      expect(mockHookRunner.runPostGet).not.toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).not.toHaveBeenCalled();
+      expect(mockEventEmitter.emit).not.toHaveBeenCalledWith(
+        DismissibleEvents.ITEM_RETRIEVED,
+        expect.anything(),
+      );
+    });
   });
 
   describe('dismiss', () => {
@@ -83,14 +155,17 @@ describe('DismissibleService', () => {
       const previousItem = createTestItem({ id: 'test-item' });
       const context = createTestContext();
 
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('test-item'));
       mockHookRunner.runPreDismiss.mockResolvedValue(createHookResult('test-item'));
       mockCoreService.dismiss.mockResolvedValue({ item, previousItem });
 
       const result = await service.dismiss('test-item', testUserId, context);
 
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
       expect(mockHookRunner.runPreDismiss).toHaveBeenCalled();
       expect(mockCoreService.dismiss).toHaveBeenCalledWith('test-item', testUserId);
       expect(mockHookRunner.runPostDismiss).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
       expect(mockEventEmitter.emit).toHaveBeenCalledWith(
         DismissibleEvents.ITEM_DISMISSED,
         expect.anything(),
@@ -105,14 +180,17 @@ describe('DismissibleService', () => {
       const previousItem = createTestItem({ id: 'test-item' });
       const context = createTestContext();
 
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('test-item'));
       mockHookRunner.runPreRestore.mockResolvedValue(createHookResult('test-item'));
       mockCoreService.restore.mockResolvedValue({ item, previousItem });
 
       const result = await service.restore('test-item', testUserId, context);
 
+      expect(mockHookRunner.runPreRequest).toHaveBeenCalled();
       expect(mockHookRunner.runPreRestore).toHaveBeenCalled();
       expect(mockCoreService.restore).toHaveBeenCalledWith('test-item', testUserId);
       expect(mockHookRunner.runPostRestore).toHaveBeenCalled();
+      expect(mockHookRunner.runPostRequest).toHaveBeenCalled();
       expect(mockEventEmitter.emit).toHaveBeenCalledWith(
         DismissibleEvents.ITEM_RESTORED,
         expect.anything(),
@@ -126,8 +204,9 @@ describe('DismissibleService', () => {
       const item = createTestItem({ id: 'test-item' });
       const context = createTestContext();
 
-      mockHookRunner.runPreGetOrCreate.mockResolvedValue(createHookResult('test-item'));
-      mockCoreService.getOrCreate.mockResolvedValue({ item, created: false });
+      mockHookRunner.runPreRequest.mockResolvedValue(createHookResult('test-item'));
+      mockHookRunner.runPreGet.mockResolvedValue(createHookResult('test-item'));
+      mockCoreService.get.mockResolvedValue(item);
 
       await service.getOrCreate('test-item', testUserId, undefined, context);
 

package/src/core/dismissible.service.ts

@@ -48,54 +48,81 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
   ): Promise<IGetOrCreateServiceResponse<TMetadata>> {
     this.logger.debug(`getOrCreate called`, { itemId, userId });
 
-    // Run pre-getOrCreate hooks
-    const preResult = await this.hookRunner.runPreGetOrCreate(itemId, userId, context);
+    // Run global pre-request hooks (auth, rate limiting, validation)
+    const preResult = await this.hookRunner.runPreRequest(itemId, userId, context);
     HookRunner.throwIfBlocked(preResult);
 
     const resolvedId = preResult.id;
     const resolvedUserId = preResult.userId;
     const resolvedContext = preResult.context;
 
-    // Check if we need to run create hooks (for potential new item)
-    const result = await this.coreService.getOrCreate(resolvedId, resolvedUserId, options);
+    // Check if item already exists
+    const existingItem = await this.coreService.get(resolvedId, resolvedUserId);
 
-    // If item was created, run create-specific hooks
-    if (result.created) {
-      // Run pre-create hooks
-      const preCreateResult = await this.hookRunner.runPreCreate(
+    if (existingItem) {
+      // Item exists - run pre-get hooks (access control based on item state)
+      const preGetResult = await this.hookRunner.runPreGet(
         resolvedId,
+        existingItem,
         resolvedUserId,
         resolvedContext,
       );
-      HookRunner.throwIfBlocked(preCreateResult);
+      HookRunner.throwIfBlocked(preGetResult);
 
-      // Run post-create hooks
-      await this.hookRunner.runPostCreate(resolvedId, result.item, resolvedUserId, resolvedContext);
-
-      // Emit created event (async)
-      this.eventEmitter.emit(
-        DismissibleEvents.ITEM_CREATED,
-        new ItemCreatedEvent(resolvedId, result.item, resolvedUserId, resolvedContext),
-      );
-    } else {
-      // Emit retrieved event (async)
+      // Emit retrieved event
       this.eventEmitter.emit(
         DismissibleEvents.ITEM_RETRIEVED,
-        new ItemRetrievedEvent(resolvedId, result.item, resolvedUserId, resolvedContext),
+        new ItemRetrievedEvent(resolvedId, existingItem, resolvedUserId, resolvedContext),
       );
+
+      // Run post-get hooks
+      await this.hookRunner.runPostGet(resolvedId, existingItem, resolvedUserId, resolvedContext);
+
+      // Run global post-request hooks
+      await this.hookRunner.runPostRequest(
+        resolvedId,
+        existingItem,
+        resolvedUserId,
+        resolvedContext,
+      );
+
+      this.logger.debug(`getOrCreate completed`, { itemId, created: false });
+
+      return {
+        item: existingItem,
+        created: false,
+      };
     }
 
-    // Run post-getOrCreate hooks
-    await this.hookRunner.runPostGetOrCreate(
+    // Item doesn't exist - run pre-create hooks BEFORE creating
+    const preCreateResult = await this.hookRunner.runPreCreate(
       resolvedId,
-      result.item,
       resolvedUserId,
       resolvedContext,
     );
+    HookRunner.throwIfBlocked(preCreateResult);
 
-    this.logger.debug(`getOrCreate completed`, { itemId, created: result.created });
+    // Now create the item
+    const createdItem = await this.coreService.create(resolvedId, resolvedUserId, options);
 
-    return result;
+    // Run post-create hooks
+    await this.hookRunner.runPostCreate(resolvedId, createdItem, resolvedUserId, resolvedContext);
+
+    // Emit created event
+    this.eventEmitter.emit(
+      DismissibleEvents.ITEM_CREATED,
+      new ItemCreatedEvent(resolvedId, createdItem, resolvedUserId, resolvedContext),
+    );
+
+    // Run global post-request hooks
+    await this.hookRunner.runPostRequest(resolvedId, createdItem, resolvedUserId, resolvedContext);
+
+    this.logger.debug(`getOrCreate completed`, { itemId, created: true });
+
+    return {
+      item: createdItem,
+      created: true,
+    };
   }
 
   /**
@@ -111,13 +138,21 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
   ): Promise<IDismissServiceResponse<TMetadata>> {
     this.logger.debug(`dismiss called`, { itemId, userId });
 
-    // Run pre-dismiss hooks
-    const preResult = await this.hookRunner.runPreDismiss(itemId, userId, context);
-    HookRunner.throwIfBlocked(preResult);
+    // Run global pre-request hooks (auth, rate limiting, validation)
+    const preRequestResult = await this.hookRunner.runPreRequest(itemId, userId, context);
+    HookRunner.throwIfBlocked(preRequestResult);
 
-    const resolvedId = preResult.id;
-    const resolvedUserId = preResult.userId;
-    const resolvedContext = preResult.context;
+    const resolvedId = preRequestResult.id;
+    const resolvedUserId = preRequestResult.userId;
+    const resolvedContext = preRequestResult.context;
+
+    // Run pre-dismiss hooks
+    const preDismissResult = await this.hookRunner.runPreDismiss(
+      resolvedId,
+      resolvedUserId,
+      resolvedContext,
+    );
+    HookRunner.throwIfBlocked(preDismissResult);
 
     // Execute core dismiss operation
     const result = await this.coreService.dismiss(resolvedId, resolvedUserId);
@@ -125,7 +160,7 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
     // Run post-dismiss hooks
     await this.hookRunner.runPostDismiss(resolvedId, result.item, resolvedUserId, resolvedContext);
 
-    // Emit dismissed event (async)
+    // Emit dismissed event
     this.eventEmitter.emit(
       DismissibleEvents.ITEM_DISMISSED,
       new ItemDismissedEvent(
@@ -137,6 +172,9 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
       ),
     );
 
+    // Run global post-request hooks
+    await this.hookRunner.runPostRequest(resolvedId, result.item, resolvedUserId, resolvedContext);
+
     this.logger.debug(`dismiss completed`, { itemId });
 
     return result;
@@ -155,13 +193,21 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
   ): Promise<IRestoreServiceResponse<TMetadata>> {
     this.logger.debug(`restore called`, { itemId, userId });
 
-    // Run pre-restore hooks
-    const preResult = await this.hookRunner.runPreRestore(itemId, userId, context);
-    HookRunner.throwIfBlocked(preResult);
+    // Run global pre-request hooks (auth, rate limiting, validation)
+    const preRequestResult = await this.hookRunner.runPreRequest(itemId, userId, context);
+    HookRunner.throwIfBlocked(preRequestResult);
 
-    const resolvedId = preResult.id;
-    const resolvedUserId = preResult.userId;
-    const resolvedContext = preResult.context;
+    const resolvedId = preRequestResult.id;
+    const resolvedUserId = preRequestResult.userId;
+    const resolvedContext = preRequestResult.context;
+
+    // Run pre-restore hooks
+    const preRestoreResult = await this.hookRunner.runPreRestore(
+      resolvedId,
+      resolvedUserId,
+      resolvedContext,
+    );
+    HookRunner.throwIfBlocked(preRestoreResult);
 
     // Execute core restore operation
     const result = await this.coreService.restore(resolvedId, resolvedUserId);
@@ -169,7 +215,7 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
     // Run post-restore hooks
     await this.hookRunner.runPostRestore(resolvedId, result.item, resolvedUserId, resolvedContext);
 
-    // Emit restored event (async)
+    // Emit restored event
     this.eventEmitter.emit(
       DismissibleEvents.ITEM_RESTORED,
       new ItemRestoredEvent(
@@ -181,6 +227,9 @@ export class DismissibleService<TMetadata extends BaseMetadata = BaseMetadata> {
       ),
     );
 
+    // Run global post-request hooks
+    await this.hookRunner.runPostRequest(resolvedId, result.item, resolvedUserId, resolvedContext);
+
     this.logger.debug(`restore completed`, { itemId });
 
     return result;

package/src/core/hook-runner.service.spec.ts

@@ -21,9 +21,9 @@ describe('HookRunner', () => {
       hookRunner = new HookRunner([], mockLogger);
     });
 
-    it('should return proceed: true for pre-getOrCreate', async () => {
+    it('should return proceed: true for pre-request', async () => {
       const context = createTestContext();
-      const result = await hookRunner.runPreGetOrCreate('test-id', testUserId, context);
+      const result = await hookRunner.runPreRequest('test-id', testUserId, context);
 
       expect(result.proceed).toBe(true);
       expect(result.id).toBe('test-id');
@@ -31,12 +31,12 @@ describe('HookRunner', () => {
       expect(result.context).toEqual(context);
     });
 
-    it('should complete post-getOrCreate without error', async () => {
+    it('should complete post-request without error', async () => {
       const item = createTestItem();
       const context = createTestContext();
 
       await expect(
-        hookRunner.runPostGetOrCreate('test-id', item, testUserId, context),
+        hookRunner.runPostRequest('test-id', item, testUserId, context),
       ).resolves.not.toThrow();
     });
   });
@@ -47,7 +47,7 @@ describe('HookRunner', () => {
 
       const hook1: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 10,
-        onBeforeGetOrCreate: jest.fn(async () => {
+        onBeforeRequest: jest.fn(async () => {
           executionOrder.push(10);
           return { proceed: true };
         }),
@@ -55,7 +55,7 @@ describe('HookRunner', () => {
 
       const hook2: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 5,
-        onBeforeGetOrCreate: jest.fn(async () => {
+        onBeforeRequest: jest.fn(async () => {
           executionOrder.push(5);
           return { proceed: true };
         }),
@@ -63,14 +63,14 @@ describe('HookRunner', () => {
 
       const hook3: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 15,
-        onBeforeGetOrCreate: jest.fn(async () => {
+        onBeforeRequest: jest.fn(async () => {
           executionOrder.push(15);
           return { proceed: true };
         }),
       };
 
       hookRunner = new HookRunner([hook1, hook2, hook3], mockLogger);
-      await hookRunner.runPreGetOrCreate('test-id', testUserId, createTestContext());
+      await hookRunner.runPreRequest('test-id', testUserId, createTestContext());
 
       expect(executionOrder).toEqual([5, 10, 15]);
     });
@@ -80,46 +80,41 @@ describe('HookRunner', () => {
 
       const hook1: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 10,
-        onAfterGetOrCreate: jest.fn(async () => {
+        onAfterRequest: jest.fn(async () => {
           executionOrder.push(10);
         }),
       };
 
       const hook2: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 5,
-        onAfterGetOrCreate: jest.fn(async () => {
+        onAfterRequest: jest.fn(async () => {
           executionOrder.push(5);
         }),
       };
 
       const hook3: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 15,
-        onAfterGetOrCreate: jest.fn(async () => {
+        onAfterRequest: jest.fn(async () => {
           executionOrder.push(15);
         }),
       };
 
       hookRunner = new HookRunner([hook1, hook2, hook3], mockLogger);
-      await hookRunner.runPostGetOrCreate(
-        'test-id',
-        createTestItem(),
-        testUserId,
-        createTestContext(),
-      );
+      await hookRunner.runPostRequest('test-id', createTestItem(), testUserId, createTestContext());
 
       expect(executionOrder).toEqual([15, 10, 5]);
     });
 
     it('should block operation when pre-hook returns proceed: false', async () => {
       const blockingHook: IDismissibleLifecycleHook<BaseMetadata> = {
-        onBeforeGetOrCreate: jest.fn(async () => ({
+        onBeforeRequest: jest.fn(async () => ({
           proceed: false,
           reason: 'Rate limit exceeded',
         })),
       };
 
       hookRunner = new HookRunner([blockingHook], mockLogger);
-      const result = await hookRunner.runPreGetOrCreate('test-id', testUserId, createTestContext());
+      const result = await hookRunner.runPreRequest('test-id', testUserId, createTestContext());
 
       expect(result.proceed).toBe(false);
       expect(result.reason).toBe('Rate limit exceeded');
@@ -127,7 +122,7 @@ describe('HookRunner', () => {
 
     it('should apply mutations from pre-hooks', async () => {
       const mutatingHook: IDismissibleLifecycleHook<BaseMetadata> = {
-        onBeforeGetOrCreate: jest.fn(async () => ({
+        onBeforeRequest: jest.fn(async () => ({
           proceed: true,
           mutations: {
             id: 'mutated-id',
@@ -137,11 +132,7 @@ describe('HookRunner', () => {
       };
 
       hookRunner = new HookRunner([mutatingHook], mockLogger);
-      const result = await hookRunner.runPreGetOrCreate(
-        'original-id',
-        testUserId,
-        createTestContext(),
-      );
+      const result = await hookRunner.runPreRequest('original-id', testUserId, createTestContext());
 
       expect(result.id).toBe('mutated-id');
       expect(result.userId).toBe('mutated-user');
@@ -150,7 +141,7 @@ describe('HookRunner', () => {
     it('should pass mutations through multiple hooks', async () => {
       const hook1: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 1,
-        onBeforeGetOrCreate: jest.fn(async (itemId) => ({
+        onBeforeRequest: jest.fn(async (itemId) => ({
           proceed: true,
           mutations: { id: `${itemId}-hook1` },
         })),
@@ -158,18 +149,14 @@ describe('HookRunner', () => {
 
       const hook2: IDismissibleLifecycleHook<BaseMetadata> = {
         priority: 2,
-        onBeforeGetOrCreate: jest.fn(async (itemId) => ({
+        onBeforeRequest: jest.fn(async (itemId) => ({
           proceed: true,
           mutations: { id: `${itemId}-hook2` },
         })),
       };
 
       hookRunner = new HookRunner([hook1, hook2], mockLogger);
-      const result = await hookRunner.runPreGetOrCreate(
-        'original',
-        testUserId,
-        createTestContext(),
-      );
+      const result = await hookRunner.runPreRequest('original', testUserId, createTestContext());
 
       expect(result.id).toBe('original-hook1-hook2');
     });
@@ -178,7 +165,7 @@ describe('HookRunner', () => {
   describe('error handling', () => {
     it('should throw error from pre-hook', async () => {
       const errorHook: IDismissibleLifecycleHook<BaseMetadata> = {
-        onBeforeGetOrCreate: jest.fn(async () => {
+        onBeforeRequest: jest.fn(async () => {
           throw new Error('Hook error');
         }),
       };
@@ -186,7 +173,7 @@ describe('HookRunner', () => {
       hookRunner = new HookRunner([errorHook], mockLogger);
 
       await expect(
-        hookRunner.runPreGetOrCreate('test-id', testUserId, createTestContext()),
+        hookRunner.runPreRequest('test-id', testUserId, createTestContext()),
       ).rejects.toThrow('Hook error');
 
       expect(mockLogger.error).toHaveBeenCalled();
@@ -194,7 +181,7 @@ describe('HookRunner', () => {
 
     it('should log but not throw errors from post-hooks', async () => {
       const errorHook: IDismissibleLifecycleHook<BaseMetadata> = {
-        onAfterGetOrCreate: jest.fn(async () => {
+        onAfterRequest: jest.fn(async () => {
           throw new Error('Post-hook error');
         }),
       };
@@ -202,7 +189,7 @@ describe('HookRunner', () => {
       hookRunner = new HookRunner([errorHook], mockLogger);
 
       await expect(
-        hookRunner.runPostGetOrCreate('test-id', createTestItem(), testUserId, createTestContext()),
+        hookRunner.runPostRequest('test-id', createTestItem(), testUserId, createTestContext()),
       ).resolves.not.toThrow();
 
       expect(mockLogger.error).toHaveBeenCalled();
@@ -234,14 +221,83 @@ describe('HookRunner', () => {
     });
   });
 
+  describe('runPreGet and runPostGet', () => {
+    it('should pass item to onBeforeGet hook', async () => {
+      const item = createTestItem();
+      const context = createTestContext();
+
+      const hook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onBeforeGet: jest.fn().mockResolvedValue({ proceed: true }),
+      };
+
+      hookRunner = new HookRunner([hook], mockLogger);
+      await hookRunner.runPreGet('test-id', item, testUserId, context);
+
+      expect(hook.onBeforeGet).toHaveBeenCalledWith('test-id', item, testUserId, context);
+    });
+
+    it('should block operation when onBeforeGet returns proceed: false', async () => {
+      const item = createTestItem();
+      const context = createTestContext();
+
+      const blockingHook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onBeforeGet: jest.fn().mockResolvedValue({
+          proceed: false,
+          reason: 'Item is in invalid state',
+        }),
+      };
+
+      hookRunner = new HookRunner([blockingHook], mockLogger);
+      const result = await hookRunner.runPreGet('test-id', item, testUserId, context);
+
+      expect(result.proceed).toBe(false);
+      expect(result.reason).toBe('Item is in invalid state');
+    });
+
+    it('should run onAfterGet hook', async () => {
+      const item = createTestItem();
+      const context = createTestContext();
+
+      const hook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onAfterGet: jest.fn(),
+      };
+
+      hookRunner = new HookRunner([hook], mockLogger);
+      await hookRunner.runPostGet('test-id', item, testUserId, context);
+
+      expect(hook.onAfterGet).toHaveBeenCalledWith('test-id', item, testUserId, context);
+    });
+
+    it('should apply mutations from onBeforeGet hook', async () => {
+      const item = createTestItem();
+      const context = createTestContext();
+
+      const mutatingHook: IDismissibleLifecycleHook<BaseMetadata> = {
+        onBeforeGet: jest.fn().mockResolvedValue({
+          proceed: true,
+          mutations: {
+            id: 'mutated-id',
+          },
+        }),
+      };
+
+      hookRunner = new HookRunner([mutatingHook], mockLogger);
+      const result = await hookRunner.runPreGet('original-id', item, testUserId, context);
+
+      expect(result.id).toBe('mutated-id');
+    });
+  });
+
   describe('all hook methods', () => {
     let allMethodsHook: IDismissibleLifecycleHook<BaseMetadata>;
 
     beforeEach(() => {
       allMethodsHook = {
         priority: 0,
-        onBeforeGetOrCreate: jest.fn().mockResolvedValue({ proceed: true }),
-        onAfterGetOrCreate: jest.fn(),
+        onBeforeRequest: jest.fn().mockResolvedValue({ proceed: true }),
+        onAfterRequest: jest.fn(),
+        onBeforeGet: jest.fn().mockResolvedValue({ proceed: true }),
+        onAfterGet: jest.fn(),
         onBeforeCreate: jest.fn().mockResolvedValue({ proceed: true }),
         onAfterCreate: jest.fn(),
         onBeforeDismiss: jest.fn().mockResolvedValue({ proceed: true }),
@@ -253,6 +309,33 @@ describe('HookRunner', () => {
       hookRunner = new HookRunner([allMethodsHook], mockLogger);
     });
 
+    it('should run pre and post request hooks', async () => {
+      const context = createTestContext();
+      const item = createTestItem();
+
+      await hookRunner.runPreRequest('test-id', testUserId, context);
+      await hookRunner.runPostRequest('test-id', item, testUserId, context);
+
+      expect(allMethodsHook.onBeforeRequest).toHaveBeenCalledWith('test-id', testUserId, context);
+      expect(allMethodsHook.onAfterRequest).toHaveBeenCalledWith(
+        'test-id',
+        item,
+        testUserId,
+        context,
+      );
+    });
+
+    it('should run pre and post get hooks', async () => {
+      const context = createTestContext();
+      const item = createTestItem();
+
+      await hookRunner.runPreGet('test-id', item, testUserId, context);
+      await hookRunner.runPostGet('test-id', item, testUserId, context);
+
+      expect(allMethodsHook.onBeforeGet).toHaveBeenCalledWith('test-id', item, testUserId, context);
+      expect(allMethodsHook.onAfterGet).toHaveBeenCalledWith('test-id', item, testUserId, context);
+    });
+
     it('should run pre and post create hooks', async () => {
       const context = createTestContext();
       const item = createTestItem();

package/src/core/hook-runner.service.ts

@@ -46,29 +46,68 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
     this.sortedHooks = [...hooks].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Global Request Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
-   * Run pre-getOrCreate hooks.
+   * Run pre-request hooks (global - runs at start of any operation).
+   * Use for authentication, rate limiting, request validation.
    */
-  async runPreGetOrCreate(
+  async runPreRequest(
     itemId: string,
     userId: string,
     context?: IRequestContext,
   ): Promise<IHookRunResult> {
-    return this.runPreHooks('onBeforeGetOrCreate', itemId, userId, context);
+    return this.runPreHooks('onBeforeRequest', itemId, userId, context);
   }
 
   /**
-   * Run post-getOrCreate hooks.
+   * Run post-request hooks (global - runs at end of any operation).
+   * Use for audit logging, metrics, cleanup.
    */
-  async runPostGetOrCreate(
+  async runPostRequest(
     itemId: string,
     item: DismissibleItemDto<TMetadata>,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> {
-    await this.runPostHooks('onAfterGetOrCreate', itemId, item, userId, context);
+    await this.runPostHooks('onAfterRequest', itemId, item, userId, context);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Get Hooks
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Run pre-get hooks (when item exists and is about to be returned).
+   * Receives the item for access control based on item state.
+   */
+  async runPreGet(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    return this.runPreHooksWithItem('onBeforeGet', itemId, item, userId, context);
+  }
+
+  /**
+   * Run post-get hooks (after item is returned).
+   */
+  async runPostGet(
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> {
+    await this.runPostHooks('onAfterGet', itemId, item, userId, context);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Create Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Run pre-create hooks.
    */
@@ -92,6 +131,10 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
     await this.runPostHooks('onAfterCreate', itemId, item, userId, context);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Dismiss Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Run pre-dismiss hooks.
    */
@@ -115,6 +158,10 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
     await this.runPostHooks('onAfterDismiss', itemId, item, userId, context);
   }
 
+  // ─────────────────────────────────────────────────────────────────
+  // Restore Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Run pre-restore hooks.
    */
@@ -214,6 +261,85 @@ export class HookRunner<TMetadata extends BaseMetadata = BaseMetadata> {
     };
   }
 
+  /**
+   * Internal method to run pre-hooks that receive the item (e.g., onBeforeGet).
+   * Unlike standard pre-hooks, these receive the item for inspection/access control.
+   */
+  private async runPreHooksWithItem(
+    hookName: keyof IDismissibleLifecycleHook<TMetadata>,
+    itemId: string,
+    item: DismissibleItemDto<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookRunResult> {
+    let currentId = itemId;
+    let currentUserId = userId;
+    let currentContext = context ? { ...context } : undefined;
+
+    for (const hook of this.sortedHooks) {
+      const hookFn = hook[hookName] as
+        | ((
+            itemId: string,
+            item: DismissibleItemDto<TMetadata>,
+            userId: string,
+            context?: IRequestContext,
+          ) => Promise<IHookResult> | IHookResult)
+        | undefined;
+
+      if (hookFn) {
+        try {
+          const result = await hookFn.call(hook, currentId, item, currentUserId, currentContext);
+
+          if (!result.proceed) {
+            this.logger.debug(`Hook ${hook.constructor.name}.${hookName} blocked operation`, {
+              itemId: currentId,
+              userId: currentUserId,
+              reason: result.reason,
+            });
+
+            return {
+              proceed: false,
+              id: currentId,
+              userId: currentUserId,
+              context: currentContext,
+              reason: result.reason,
+            };
+          }
+
+          // Apply mutations if present
+          if (result.mutations) {
+            if (result.mutations.id !== undefined) {
+              currentId = result.mutations.id;
+            }
+            if (result.mutations.userId !== undefined) {
+              currentUserId = result.mutations.userId;
+            }
+            if (result.mutations.context && currentContext) {
+              currentContext = { ...currentContext, ...result.mutations.context };
+            }
+          }
+        } catch (error) {
+          this.logger.error(
+            `Error in hook ${hook.constructor.name}.${hookName}`,
+            error instanceof Error ? error : new Error(String(error)),
+            {
+              itemId: currentId,
+              userId: currentUserId,
+            },
+          );
+          throw error;
+        }
+      }
+    }
+
+    return {
+      proceed: true,
+      id: currentId,
+      userId: currentUserId,
+      context: currentContext,
+    };
+  }
+
   /**
    * Internal method to run post-hooks.
    * Post-hooks run in reverse priority order.

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

@@ -44,27 +44,65 @@ export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = Base
    */
   readonly priority?: number;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Global Request Hooks (run on ALL operations)
+  // ─────────────────────────────────────────────────────────────────
+
   /**
-   * Called before getOrCreate operation.
+   * Called at the start of any operation (getOrCreate, dismiss, restore).
+   * Use for global concerns like authentication, rate limiting, request validation.
    */
-  onBeforeGetOrCreate?(
+  onBeforeRequest?(
     itemId: string,
     userId: string,
     context?: IRequestContext,
   ): Promise<IHookResult> | IHookResult;
 
   /**
-   * Called after getOrCreate operation.
+   * Called at the end of any operation (getOrCreate, dismiss, restore).
+   * Use for global concerns like audit logging, metrics, cleanup.
    */
-  onAfterGetOrCreate?(
+  onAfterRequest?(
     itemId: string,
     item: DismissibleItemDto<TMetadata>,
     userId: string,
     context?: IRequestContext,
   ): Promise<void> | void;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Get Hooks (when retrieving existing item)
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * 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<TMetadata>,
+    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<TMetadata>,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<void> | void;
+
+  // ─────────────────────────────────────────────────────────────────
+  // Create Hooks (when creating new item)
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Called before creating a new item.
+   * Use for plan limits, quota checks, etc.
    */
   onBeforeCreate?(
     itemId: string,
@@ -82,6 +120,10 @@ export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = Base
     context?: IRequestContext,
   ): Promise<void> | void;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Dismiss Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Called before dismissing an item.
    */
@@ -101,6 +143,10 @@ export interface IDismissibleLifecycleHook<TMetadata extends BaseMetadata = Base
     context?: IRequestContext,
   ): Promise<void> | void;
 
+  // ─────────────────────────────────────────────────────────────────
+  // Restore Hooks
+  // ─────────────────────────────────────────────────────────────────
+
   /**
    * Called before restoring an item.
    */

package/src/response/http-exception-filter.ts

@@ -1,12 +1,12 @@
 import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
-import { Response } from 'express';
+import { FastifyReply } from 'fastify';
 import { IErrorResponseDto } from './dtos';
 
 @Catch(HttpException)
 export class HttpExceptionFilter implements ExceptionFilter {
   catch(exception: HttpException, host: ArgumentsHost) {
     const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
+    const response = ctx.getResponse<FastifyReply>();
     const status = exception.getStatus();
 
     const errorResponse: IErrorResponseDto = {
@@ -16,6 +16,6 @@ export class HttpExceptionFilter implements ExceptionFilter {
       },
     };
 
-    response.status(status).json(errorResponse);
+    response.status(status).send(errorResponse);
   }
 }