@forge/events 1.1.0-next.0 → 2.0.0-next.2

package/src/__test__/queue.test.ts

@@ -1,6 +1,7 @@
 import {
   InternalServerError,
   InvalidQueueNameError,
+  InvalidPayloadError,
   NoEventsToPushError,
   PartialSuccessError,
   PayloadTooBigError,
@@ -30,21 +31,57 @@ describe('Queue methods', () => {
     });
   });
 
+  const PAYLOAD = { body: { page: 1 } } as const;
+
   describe('push', () => {
-    it('should call the queue/publish endpoint', async () => {
+    it.each([
+      ['single payload', PAYLOAD, [PAYLOAD]],
+      ['payload array', [PAYLOAD, PAYLOAD], [PAYLOAD, PAYLOAD]]
+    ])('should call the queue/publish endpoint when given %s', async (_, payload, expectedPayload) => {
+      const apiClientMock = getMockFetchMethod();
+      const queue = getQueue('name', apiClientMock);
+      await queue.push(payload);
+      verifyApiClientCalledPushPathWith(apiClientMock, expectedPayload, 'name');
+    });
+
+    it.each([
+      ['number', 1],
+      ['string', 'test'],
+      ['boolean', true],
+      ['array', [1, 2, 3]],
+      ['null', null],
+      ['undefined', undefined],
+      ['array with non-object', [1]],
+      ['array with an array', [[2, 3]]]
+    ])('rejects non-object (%s) event', async (_, payload) => {
+      const apiClientMock = getMockFetchMethod();
+      const queue = getQueue('name', apiClientMock);
+      // @ts-expect-error Testing invalid payload type on purpose
+      await expect(queue.push(payload)).rejects.toThrow(new InvalidPayloadError(`Event must be an object.`));
+      expect(apiClientMock).toHaveBeenCalledTimes(0);
+    });
+
+    it.each([
+      ['number', 1],
+      ['string', 'test'],
+      ['boolean', true],
+      ['array', [1, 2, 3]],
+      ['null', null],
+      ['undefined', undefined],
+      ['array with non-object', [1]],
+      ['array with an array', [[2, 3]]]
+    ])('rejects non-object (%s) event body', async (_, body) => {
       const apiClientMock = getMockFetchMethod();
       const queue = getQueue('name', apiClientMock);
-      const payload = {
-        page: 1
-      };
-      await queue.push([payload]);
-      verifyApiClientCalledPushPathWith(apiClientMock, [payload], 'name');
+      // @ts-expect-error Testing invalid payload type on purpose
+      await expect(queue.push({ body })).rejects.toThrow(new InvalidPayloadError(`Event body must be an object.`));
+      expect(apiClientMock).toHaveBeenCalledTimes(0);
     });
 
     it('should throw InvalidPushSettingsError for delay', async () => {
       const apiClientMock = getMockFetchMethod();
       const queue = getQueue('name', apiClientMock);
-      await expect(queue.push(1, { delayInSeconds: 901 })).rejects.toThrow(
+      await expect(queue.push({ ...PAYLOAD, delayInSeconds: 901 })).rejects.toThrow(
         new InvalidPushSettingsError(`The delayInSeconds setting must be between 0 and 900.`)
       );
       expect(apiClientMock).toHaveBeenCalledTimes(0);
@@ -60,7 +97,7 @@ describe('Queue methods', () => {
     it('should throw TooManyEventsError', async () => {
       const apiClientMock = getMockFetchMethod();
       const queue = getQueue('name', apiClientMock);
-      await expect(queue.push([...Array(51).keys()])).rejects.toThrow(
+      await expect(queue.push(Array(51).fill(PAYLOAD))).rejects.toThrow(
         new TooManyEventsError(`This push contains more than the 50 events allowed.`)
       );
       expect(apiClientMock).toHaveBeenCalledTimes(0);
@@ -69,7 +106,7 @@ describe('Queue methods', () => {
     it('should throw PayloadTooBigError', async () => {
       const apiClientMock = getMockFetchMethod();
       const queue = getQueue('name', apiClientMock);
-      await expect(queue.push('x'.repeat(201 * 1024))).rejects.toThrow(
+      await expect(queue.push({ body: { content: 'x'.repeat(201 * 1024) } })).rejects.toThrow(
         new PayloadTooBigError(`The maximum payload size is 200KB.`)
       );
       expect(apiClientMock).toHaveBeenCalledTimes(0);
@@ -78,19 +115,17 @@ describe('Queue methods', () => {
     it('should throw RateLimitError', async () => {
       const apiClientMock = getMockFetchMethod({}, 429);
       const queue = getQueue('name', apiClientMock);
-      const payload = [...Array(10).keys()];
-      await expect(queue.push(payload)).rejects.toThrow(new RateLimitError(`Too many requests.`));
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+      await expect(queue.push(PAYLOAD)).rejects.toThrow(new RateLimitError(`Too many requests.`));
+      verifyApiClientCalledPushPathWith(apiClientMock, [PAYLOAD], 'name');
     });
 
     it('should throw InvocationLimitReachedError', async () => {
       const apiClientMock = getMockFetchMethod({}, 405);
       const queue = getQueue('name', apiClientMock);
-      const payload = [...Array(5).keys()];
-      await expect(queue.push(payload)).rejects.toThrow(
+      await expect(queue.push(PAYLOAD)).rejects.toThrow(
         new InvocationLimitReachedError(`The limit on cyclic invocation has been reached.`)
       );
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+      verifyApiClientCalledPushPathWith(apiClientMock, [PAYLOAD], 'name');
     });
 
     it('should throw PartialSuccessError when there are failed events', async () => {
@@ -112,27 +147,37 @@ describe('Queue methods', () => {
       const queue = getQueue('name', apiClientMock);
       const payload = [
         {
-          content: 'payload-1'
+          body: {
+            content: 'payload-1'
+          }
         },
         {
-          content: 'payload-2'
+          body: {
+            content: 'payload-2'
+          }
         },
         {
-          content: 'payload-3'
+          body: {
+            content: 'payload-3'
+          }
         }
       ];
       await expect(queue.push(payload)).rejects.toThrow(
-        new PartialSuccessError(`Failed to process 2 event(s).`, [
+        new PartialSuccessError(`Failed to process 2 event(s).`, { jobId: 'some-job-id' }, [
           {
             errorMessage: 'failed-1',
-            payload: {
-              content: 'payload-1'
+            event: {
+              body: {
+                content: 'payload-1'
+              }
             }
           },
           {
             errorMessage: 'failed-3',
-            payload: {
-              content: 'payload-3'
+            event: {
+              body: {
+                content: 'payload-3'
+              }
             }
           }
         ])
@@ -150,17 +195,23 @@ describe('Queue methods', () => {
       const queue = getQueue('name', apiClientMock);
       const payload = [
         {
-          content: 'payload-1'
+          body: {
+            content: 'payload-1'
+          }
         },
         {
-          content: 'payload-2'
+          body: {
+            content: 'payload-2'
+          }
         },
         {
-          content: 'payload-3'
+          body: {
+            content: 'payload-3'
+          }
         }
       ];
       await expect(queue.push(payload)).rejects.toThrow(
-        new PartialSuccessError(`Failed to create stats for job name#12345`, [])
+        new PartialSuccessError(`Failed to create stats for job name#12345`, { jobId: 'some-job-id' }, [])
       );
       verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
     });
@@ -181,21 +232,31 @@ describe('Queue methods', () => {
       const queue = getQueue('name', apiClientMock);
       const payload = [
         {
-          content: 'payload-1'
+          body: {
+            content: 'payload-1'
+          }
         },
         {
-          content: 'payload-2'
+          body: {
+            content: 'payload-2'
+          }
         }
       ];
       await expect(queue.push(payload)).rejects.toThrow(
-        new PartialSuccessError(`Failed to process 1 event(s). Failed to create stats for job name#12345`, [
-          {
-            errorMessage: 'failed-1',
-            payload: {
-              content: 'payload-1'
+        new PartialSuccessError(
+          `Failed to process 1 event(s). Failed to create stats for job name#12345`,
+          { jobId: 'some-job-id' },
+          [
+            {
+              errorMessage: 'failed-1',
+              event: {
+                body: {
+                  content: 'payload-1'
+                }
+              }
             }
-          }
-        ])
+          ]
+        )
       );
       verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
     });
@@ -210,28 +271,26 @@ describe('Queue methods', () => {
         500
       );
       const queue = getQueue('name', apiClientMock);
-      const payload = [...Array(9).keys()];
-      await expect(queue.push(payload)).rejects.toThrow(
+      await expect(queue.push(PAYLOAD)).rejects.toThrow(
         new InternalServerError(
           `500 Status Text: AWS SQS timed out`,
           500,
           'The request processing has failed because of an unknown error, exception or failure'
         )
       );
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+      verifyApiClientCalledPushPathWith(apiClientMock, [PAYLOAD], 'name');
     });
 
     it('should throw InternalServerError for error response without response body', async () => {
       const apiClientMock = getApiClientMockWithoutResponseBody(504, 'Gateway Timeout');
       const queue = getQueue('name', apiClientMock);
-      const payload = [1];
-      await expect(queue.push(1)).rejects.toThrow(new InternalServerError(`504 Gateway Timeout`, 504));
-      verifyApiClientCalledPushPathWith(apiClientMock, payload, 'name');
+      await expect(queue.push(PAYLOAD)).rejects.toThrow(new InternalServerError(`504 Gateway Timeout`, 504));
+      verifyApiClientCalledPushPathWith(apiClientMock, [PAYLOAD], 'name');
     });
 
     it('requests stargate if no api client is provided', async () => {
       const queue = getQueue('queue');
-      await queue.push({ test: 'stargate' });
+      await queue.push({ body: { test: 'stargate' } });
       expect(__requestAtlassianAsApp).toHaveBeenCalledTimes(1);
     });
   });
@@ -241,7 +300,7 @@ describe('Queue methods', () => {
       const apiClientMock = getMockFetchMethod();
       const queue = getQueue('name', apiClientMock);
       const jobProgress = queue.getJob('test-job-id');
-      expect(jobProgress).toEqual(new JobProgress('test-job-id', apiClientMock));
+      expect(jobProgress).toEqual(new JobProgress({ key: 'name' }, 'test-job-id', apiClientMock));
     });
   });
 });

package/src/__test__/utils.ts

@@ -40,7 +40,7 @@ export const verifyApiClientCalledPushPathWith = (
 ) => {
   verifyApiClientCalledWith(apiClientMock, '/webhook/queue/publish/{contextAri}/{environmentId}/{appId}/{appVersion}', {
     queueName: name,
-    schema: 'ari:cloud:ecosystem::forge/app-event',
+    schema: 'ari:cloud:ecosystem::forge/app-event-2',
     type: 'avi:forge:app:event',
     payload: payloads
   });

package/src/errors.ts

@@ -1,51 +1,36 @@
-import { FailedEvent } from './types';
+import { FailedEvent, PushResult } from './types';
 
-export class InvalidPushSettingsError extends Error {
+export class EventsError extends Error {
   constructor(message: string) {
     super(message);
   }
 }
 
-export class InvalidQueueNameError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class InvalidPushSettingsError extends EventsError {}
 
-export class TooManyEventsError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class InvalidQueueNameError extends EventsError {}
 
-export class PayloadTooBigError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class InvalidPayloadError extends EventsError {}
 
-export class NoEventsToPushError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class TooManyEventsError extends EventsError {}
 
-export class RateLimitError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class PayloadTooBigError extends EventsError {}
 
-export class PartialSuccessError extends Error {
-  constructor(message: string, failedEvents: FailedEvent[]) {
+export class NoEventsToPushError extends EventsError {}
+
+export class RateLimitError extends EventsError {}
+
+export class PartialSuccessError extends EventsError {
+  constructor(
+    message: string,
+    public result: PushResult,
+    public failedEvents: FailedEvent[]
+  ) {
     super(message);
-    this.failedEvents = failedEvents;
   }
-
-  failedEvents: FailedEvent[];
 }
 
-export class InternalServerError extends Error {
+export class InternalServerError extends EventsError {
   constructor(message: string, errorCode?: number, details?: string) {
     super(message);
     this.errorCode = errorCode;
@@ -56,14 +41,6 @@ export class InternalServerError extends Error {
   details?: string;
 }
 
-export class JobDoesNotExistError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class JobDoesNotExistError extends EventsError {}
 
-export class InvocationLimitReachedError extends Error {
-  constructor(message: string) {
-    super(message);
-  }
-}
+export class InvocationLimitReachedError extends EventsError {}

package/src/index.ts

@@ -11,11 +11,12 @@ export {
   InvalidPushSettingsError,
   InvocationLimitReachedError
 } from './errors';
-export { JobProgress } from './jobProgress';
+export { JobProgress, JobStats } from './jobProgress';
 export { QueueResponse } from './queueResponse';
 export { InvocationError } from './invocationError';
 export { InvocationErrorCode } from './invocationErrorCode';
 export { RetryOptions } from './retryOptions';
+export { AsyncEvent, PushEvent, PushResult } from './types';
 export {
   appEvents,
   AppEvent,

package/src/jobProgress.ts

@@ -1,4 +1,4 @@
-import { __requestAtlassianAsApp, FetchMethod, APIResponse } from '@forge/api';
+import { __requestAtlassianAsApp, FetchMethod } from '@forge/api';
 import { CANCEL_JOB_PATH, GET_STATS_PATH, post } from './queries';
 import {
   validateCancelJobAPIResponse,
@@ -6,19 +6,25 @@ import {
   validateGetStatsAPIResponse,
   validateGetStatsPayload
 } from './validators';
-import { CancelJobRequest, GetStatsRequest } from './types';
+import { CancelJobRequest, GetStatsRequest, QueueParams } from './types';
+
+export type JobStats = {
+  success: number;
+  inProgress: number;
+  failed: number;
+};
 
 export class JobProgress {
   constructor(
+    private readonly queueParams: QueueParams,
     private readonly id: string,
     private readonly apiClient: FetchMethod = __requestAtlassianAsApp
   ) {}
 
-  async getStats(): Promise<APIResponse> {
-    const [queueName, jobId] = this.id.split('#');
+  async getStats(): Promise<JobStats> {
     const getStatsRequest: GetStatsRequest = {
-      queueName: queueName,
-      jobId: jobId,
+      queueName: this.queueParams.key,
+      jobId: this.id,
       time: new Date().toISOString()
     };
 
@@ -26,14 +32,14 @@ export class JobProgress {
 
     const response = await post(GET_STATS_PATH, getStatsRequest, this.apiClient);
     await validateGetStatsAPIResponse(response, getStatsRequest);
-    return response;
+    const { success, inProgress, failed } = await response.json();
+    return { success, inProgress, failed };
   }
 
-  async cancel(): Promise<APIResponse> {
-    const [queueName, jobId] = this.id.split('#');
+  async cancel(): Promise<void> {
     const cancelJobRequest: CancelJobRequest = {
-      queueName: queueName,
-      jobId: jobId,
+      queueName: this.queueParams.key,
+      jobId: this.id,
       time: new Date().toISOString()
     };
 
@@ -41,6 +47,5 @@ export class JobProgress {
 
     const response = await post(CANCEL_JOB_PATH, cancelJobRequest, this.apiClient);
     await validateCancelJobAPIResponse(response, cancelJobRequest);
-    return response;
   }
 }

package/src/queue.ts

@@ -1,7 +1,7 @@
 import { FetchMethod, __requestAtlassianAsApp } from '@forge/api';
 import { PUSH_PATH, post } from './queries';
-import { validatePushAPIResponse, validatePushPayloads, validateQueueKey, validatePushSettings } from './validators';
-import { Payload, QueueParams, PushSettings, PushRequest } from './types';
+import { validatePushAPIResponse, validatePushEvents, validateQueueKey } from './validators';
+import { QueueParams, PushEvent, PushRequest, PushResult } from './types';
 import { v4 as uuid } from 'uuid';
 import { JobProgress } from './jobProgress';
 
@@ -13,8 +13,8 @@ export class Queue {
     validateQueueKey(this.queueParams.key);
   }
 
-  async push(payloads: Payload | Payload[], pushSettings?: PushSettings): Promise<string> {
-    validatePushPayloads(payloads);
+  async push(events: PushEvent | PushEvent[]): Promise<PushResult> {
+    const validEvents = validatePushEvents(events);
     const queueName = this.queueParams.key;
     const jobId = uuid();
 
@@ -22,24 +22,18 @@ export class Queue {
       queueName: queueName,
       jobId: jobId,
       type: 'avi:forge:app:event',
-      schema: 'ari:cloud:ecosystem::forge/app-event',
-      payload: Array.isArray(payloads) ? payloads : [payloads],
+      schema: 'ari:cloud:ecosystem::forge/app-event-2',
+      payload: validEvents,
       time: new Date().toISOString()
     };
 
-    if (pushSettings) {
-      validatePushSettings(pushSettings);
-      if (pushSettings.delayInSeconds) {
-        pushRequest.delayInSeconds = pushSettings.delayInSeconds;
-      }
-    }
-
     const response = await post(PUSH_PATH, pushRequest, this.apiClient);
-    await validatePushAPIResponse(response, pushRequest);
-    return `${queueName}#${jobId}`;
+    const result = { jobId };
+    await validatePushAPIResponse(pushRequest, response, result);
+    return result;
   }
 
   getJob(jobId: string): JobProgress {
-    return new JobProgress(jobId, this.apiClient);
+    return new JobProgress(this.queueParams, jobId, this.apiClient);
   }
 }

package/src/text.ts

@@ -1,6 +1,8 @@
 export const Text = {
   error: {
     invalidQueueName: `Queue names can only contain alphanumeric characters, dashes and underscores.`,
+    invalidEvent: `Event must be an object.`,
+    invalidEventBody: `Event body must be an object.`,
     invalidDelayInSecondsSetting: `The delayInSeconds setting must be between 0 and 900.`,
     maxEventsAllowed: (maxEventsCount: number): string =>
       `This push contains more than the ${maxEventsCount} events allowed.`,

package/src/types.ts

@@ -1,17 +1,16 @@
-export type Payload = string | number | boolean | { [key: string]: Payload };
+import { InvocationErrorCode } from './invocationErrorCode';
+
+export type Payload = Record<string, unknown>;
 
-export interface PushSettings {
-  delayInSeconds: number;
-}
 export interface QueueParams {
   key: string;
 }
 
 export interface PushRequest extends APIRequest {
-  payload: Payload[];
+  payload: PushEvent[];
   schema: string;
   type: string;
-  delayInSeconds?: number;
+  jobId: string;
 }
 
 export interface APIRequest {
@@ -20,9 +19,33 @@ export interface APIRequest {
   time: string;
 }
 
+export interface PushEvent {
+  body: Body;
+  delayInSeconds?: number;
+}
+
+export type Body = Record<string, unknown>;
+
+export interface PushResult {
+  jobId: string;
+}
+
 export interface FailedEvent {
   errorMessage: string;
-  payload: Payload;
+  event: PushEvent;
+}
+
+export interface AsyncEvent extends PushEvent {
+  queueName: string;
+  jobId: string;
+  eventId: string;
+  retryContext?: RetryContext;
+}
+
+export interface RetryContext {
+  retryCount: number;
+  retryReason: InvocationErrorCode;
+  retryData: any;
 }
 
 export type GetStatsRequest = APIRequest;

package/src/validators.ts

@@ -3,6 +3,7 @@ import {
   InternalServerError,
   InvalidQueueNameError,
   JobDoesNotExistError,
+  InvalidPayloadError,
   NoEventsToPushError,
   PartialSuccessError,
   PayloadTooBigError,
@@ -12,7 +13,7 @@ import {
   InvocationLimitReachedError
 } from './errors';
 import { Text } from './text';
-import { CancelJobRequest, GetStatsRequest, Payload, PushRequest, PushSettings } from './types';
+import { CancelJobRequest, GetStatsRequest, PushEvent, PushRequest, PushResult } from './types';
 
 const VALID_QUEUE_NAME_PATTERN = /^[a-zA-Z0-9-_]+$/;
 const MAXIMUM_EVENTS = 50;
@@ -24,26 +25,42 @@ export const validateQueueKey = (queueName: string) => {
   }
 };
 
-export const validatePushSettings = (settings: PushSettings) => {
-  if ((settings.delayInSeconds && settings.delayInSeconds > 900) || settings.delayInSeconds < 0) {
+export const validatePushSettings = (event: PushEvent) => {
+  if ((event.delayInSeconds && event.delayInSeconds > 900) || (event.delayInSeconds && event.delayInSeconds < 0)) {
     throw new InvalidPushSettingsError(Text.error.invalidDelayInSecondsSetting);
   }
 };
 
-export const validatePushPayloads = (payloads: Payload | Payload[]) => {
-  if (!payloads || (Array.isArray(payloads) && payloads.length === 0)) {
+export function validatePushEvents(arg: PushEvent | PushEvent[]): PushEvent[] {
+  const events = Array.isArray(arg) ? arg : [arg];
+
+  if (events.length === 0) {
     throw new NoEventsToPushError(Text.error.noEventsPushed);
   }
 
-  if (Array.isArray(payloads) && payloads.length > MAXIMUM_EVENTS) {
+  if (events.length > MAXIMUM_EVENTS) {
     throw new TooManyEventsError(Text.error.maxEventsAllowed(MAXIMUM_EVENTS));
   }
 
-  const payloadSizeKB = Buffer.byteLength(JSON.stringify(payloads)) / 1024;
+  for (const event of events) {
+    if (typeof event !== 'object' || Array.isArray(event) || event === null) {
+      throw new InvalidPayloadError(Text.error.invalidEvent);
+    }
+
+    if (typeof event.body !== 'object' || Array.isArray(event.body) || event.body === null) {
+      throw new InvalidPayloadError(Text.error.invalidEventBody);
+    }
+
+    validatePushSettings(event);
+  }
+
+  const payloadSizeKB = Buffer.byteLength(JSON.stringify(events)) / 1024;
   if (payloadSizeKB > MAXIMUM_PAYLOAD_SIZE_KB) {
     throw new PayloadTooBigError(Text.error.maxPayloadAllowed(MAXIMUM_PAYLOAD_SIZE_KB));
   }
-};
+
+  return events;
+}
 
 export const validateGetStatsPayload = (getStatsRequest: GetStatsRequest) => {
   if (!getStatsRequest.jobId) {
@@ -90,7 +107,7 @@ export const validateAPIResponse = async (response: APIResponse, expectedSuccess
   }
 };
 
-export const validatePushAPIResponse = async (response: APIResponse, requestBody: PushRequest) => {
+export const validatePushAPIResponse = async (requestBody: PushRequest, response: APIResponse, result: PushResult) => {
   if (response.status === 413) {
     //Server can return this error response if it has a different max payload size and max number of events limits
     const responseBody = await response.json();
@@ -100,7 +117,7 @@ export const validatePushAPIResponse = async (response: APIResponse, requestBody
   if (response.status === 202) {
     const responseBody = await response.json();
     const defaultErrorMessage = 'Failed to process some events.';
-    const partialSuccessError = new PartialSuccessError(defaultErrorMessage, []);
+    const partialSuccessError = new PartialSuccessError(defaultErrorMessage, result, []);
 
     if (responseBody.failedEvents && responseBody.failedEvents.length > 0) {
       partialSuccessError.message = `Failed to process ${responseBody.failedEvents.length} event(s).`;