Release v1.1.0 — async hooks in forward mode

Author: cgenuity

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "posthook",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Posthook CLI - Manage projects and receive webhook deliveries locally",
   "type": "module",
   "bin": {

package.json

@@ -109,7 +109,7 @@ describe('createForwardHandler', () => {
 
   it('sends positive ack on successful forward', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: true,
+      kind: 'sync_success',
       statusCode: 200,
       duration: 50,
     });
@@ -126,9 +126,51 @@ describe('createForwardHandler', () => {
     expect(mockClient.sendAck).toHaveBeenCalledWith('hook-123', true);
   });
 
+  it('sends async ack when forward target returns 202', async () => {
+    mockForwarder.forward.mockResolvedValue({
+      kind: 'async_accepted',
+      asyncTimeout: 600,
+      duration: 50,
+    });
+
+    const handler = createForwardHandler(
+      () => mockClient as any,
+      mockForwarder as any,
+      false
+    );
+
+    await handler(createHook({ ackUrl: 'https://api.posthook.io/ack', nackUrl: 'https://api.posthook.io/nack' }), emptyQueue);
+
+    expect(mockClient.sendAck).toHaveBeenCalledWith('hook-123', true, null, {
+      async: true,
+      timeout: 600,
+    });
+  });
+
+  it('rejects 202 when callback URLs are unavailable', async () => {
+    mockForwarder.forward.mockResolvedValue({
+      kind: 'async_accepted',
+      duration: 50,
+    });
+
+    const handler = createForwardHandler(
+      () => mockClient as any,
+      mockForwarder as any,
+      false
+    );
+
+    await handler(createHook({ ackUrl: undefined, nackUrl: undefined }), emptyQueue);
+
+    expect(mockClient.sendAck).toHaveBeenCalledWith(
+      'hook-123',
+      false,
+      'Forward target returned 202 but async callback URLs are unavailable'
+    );
+  });
+
   it('sends negative ack on failed forward', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: false,
+      kind: 'failure',
       statusCode: 500,
       error: 'Internal Server Error',
       duration: 100,
@@ -147,8 +189,7 @@ describe('createForwardHandler', () => {
 
   it('does not send ack when request was aborted', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: false,
-      aborted: true,
+      kind: 'aborted',
       error: 'Request aborted',
       duration: 5000,
     });
@@ -164,11 +205,11 @@ describe('createForwardHandler', () => {
     expect(mockClient.sendAck).not.toHaveBeenCalled();
   });
 
-  it('sends negative ack with default message when error is undefined', async () => {
+  it('sends negative ack with returned error message', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: false,
+      kind: 'failure',
       statusCode: 502,
-      error: undefined,
+      error: 'Forward failed',
       duration: 100,
     });
 
@@ -185,7 +226,7 @@ describe('createForwardHandler', () => {
 
   it('logs verbose output when verbose flag is true', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: true,
+      kind: 'sync_success',
       statusCode: 200,
       duration: 50,
     });
@@ -210,7 +251,7 @@ describe('createForwardHandler', () => {
 
   it('logs Posthook-* headers in verbose mode when present', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: true,
+      kind: 'sync_success',
       statusCode: 200,
       duration: 50,
     });
@@ -245,7 +286,7 @@ describe('createForwardHandler', () => {
 
   it('omits Posthook-* headers in verbose mode when absent', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: true,
+      kind: 'sync_success',
       statusCode: 200,
       duration: 50,
     });
@@ -271,7 +312,7 @@ describe('createForwardHandler', () => {
 
   it('handles hook without forwardRequest in verbose mode gracefully', async () => {
     mockForwarder.forward.mockResolvedValue({
-      success: true,
+      kind: 'sync_success',
       statusCode: 200,
       duration: 50,
     });

src/commands/__tests__/listen.test.ts

@@ -202,22 +202,35 @@ export function createForwardHandler(
     // Forward to the local endpoint
     const result = await forwarder.forward(hook);
 
-    // If request was aborted (server timeout), don't send ack - server already moved on
-    if (result.aborted) {
-      console.log(`    ${chalk.yellow('⏱')} ${result.error} (${result.duration}ms)`);
-      return;
-    }
-
     const client = getClient();
-    if (result.success) {
-      // Success - send positive ack
-      client.sendAck(hook.id, true);
-      console.log(`    ${chalk.green('✓')} ${result.statusCode} (${result.duration}ms)`);
-    } else {
-      // Failed - send negative ack so it will retry
-      client.sendAck(hook.id, false, result.error || 'Forward failed');
-      const statusInfo = result.statusCode ? `${result.statusCode} ` : '';
-      console.log(`    ${chalk.red('✗')} ${statusInfo}${result.error} (${result.duration}ms)`);
+    switch (result.kind) {
+      case 'aborted':
+        console.log(`    ${chalk.yellow('⏱')} ${result.error} (${result.duration}ms)`);
+        return;
+
+      case 'async_accepted':
+        if (!hook.ackUrl || !hook.nackUrl) {
+          client.sendAck(hook.id, false, 'Forward target returned 202 but async callback URLs are unavailable');
+          console.log(`    ${chalk.red('✗')} 202 Async callbacks unavailable (${result.duration}ms)`);
+          return;
+        }
+
+        client.sendAck(hook.id, true, null, {
+          async: true,
+          timeout: result.asyncTimeout,
+        });
+        console.log(`    ${chalk.cyan('↻')} 202 accepted for async processing (${result.duration}ms)`);
+        return;
+
+      case 'sync_success':
+        client.sendAck(hook.id, true);
+        console.log(`    ${chalk.green('✓')} ${result.statusCode} (${result.duration}ms)`);
+        return;
+
+      case 'failure':
+        client.sendAck(hook.id, false, result.error);
+        console.log(`    ${chalk.red('✗')} ${result.statusCode ? `${result.statusCode} ` : ''}${result.error} (${result.duration}ms)`);
+        return;
     }
   };
 }

src/commands/listen.ts

@@ -26,6 +26,8 @@ describe('api', () => {
 
       mockFetch.mockResolvedValue({
         ok: true,
+        status: 200,
+        statusText: 'OK',
         json: () => Promise.resolve(ticketResponse),
       });
 
@@ -86,6 +88,19 @@ describe('api', () => {
       await expect(getTicket('https://api.test.io', 'key')).rejects.not.toThrow(AuthenticationError);
     });
 
+    it('rejects unexpected 201 ticket responses', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 201,
+        statusText: 'Created',
+        text: () => Promise.resolve('created unexpectedly'),
+      });
+
+      const { getTicket } = await import('../api.js');
+
+      await expect(getTicket('https://api.test.io', 'key')).rejects.toThrow(/API error: 201 Created/);
+    });
+
     it('throws timeout error when request aborted', async () => {
       const abortError = new Error('Aborted');
       abortError.name = 'AbortError';
@@ -120,6 +135,8 @@ describe('api', () => {
       const ticketResponse = { data: { ticket: 'test', url: 'wss://test', expiresAt: '' } };
       mockFetch.mockResolvedValue({
         ok: true,
+        status: 200,
+        statusText: 'OK',
         json: () => Promise.resolve(ticketResponse),
       });
 
@@ -145,6 +162,8 @@ describe('api', () => {
       };
       mockFetch.mockResolvedValue({
         ok: true,
+        status: 200,
+        statusText: 'OK',
         json: () => Promise.resolve(ticketResponse),
       });