@forge/events 1.0.3 → 2.0.0-next.1

package/src/__test__/jobProgress.test.ts

@@ -4,7 +4,7 @@ import { JobProgress } from '../jobProgress';
 import { __requestAtlassianAsApp } from '@forge/api';
 
 jest.mock('@forge/api', () => ({
-  __requestAtlassianAsApp: getMockFetchMethod('done', 200)
+  __requestAtlassianAsApp: getMockFetchMethod({ done: true }, 200)
 }));
 
 const getJobProgress = (jobId: string, apiClientMock?: any) => new JobProgress(jobId, apiClientMock);
@@ -21,8 +21,7 @@ describe('JobProgress methods', () => {
         200
       );
       const jobProgress = getJobProgress('test-queue-name#test-job-id', apiClientMock);
-      const response = await jobProgress.getStats();
-      const { success, inProgress, failed } = await response.json();
+      const { success, inProgress, failed } = await jobProgress.getStats();
       verifyApiClientCalledWith(
         apiClientMock,
         '/webhook/queue/stats/{contextAri}/{environmentId}/{appId}/{appVersion}',
@@ -100,7 +99,7 @@ describe('JobProgress methods', () => {
     it('should call the queue/cancel endpoint', async () => {
       const apiClientMock = getMockFetchMethod({}, 204);
       const jobProgress = getJobProgress('test-queue-name#test-job-id', apiClientMock);
-      const response = await jobProgress.cancel();
+      await jobProgress.cancel();
       verifyApiClientCalledWith(
         apiClientMock,
         '/webhook/queue/cancel/{contextAri}/{environmentId}/{appId}/{appVersion}',
@@ -109,7 +108,6 @@ describe('JobProgress methods', () => {
           jobId: 'test-job-id'
         }
       );
-      expect(response.status).toEqual(204);
     });
 
     it('should throw JobDoesNotExistError', async () => {

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);
     });
   });

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/appEvents.ts

@@ -0,0 +1,107 @@
+import { post } from './queries';
+import { __requestAtlassianAsApp } from '@forge/api';
+
+export interface AppEvent {
+  key: string;
+}
+
+export type AppEventPublishResult = AppEventPublishSuccess | AppEventPublishError;
+
+/**
+ * Represents the successful result of the publishing operation.
+ *
+ * It may happen that publishing some of the events fails even though the request was generally successful.
+ * Inspect the `failedEvents` field to see which events failed to be published and why
+ * (if the list is empty then the operation was fully successful).
+ */
+export type AppEventPublishSuccess = {
+  type: 'success';
+  /** A list of events that failed to be published along with error messages. */
+  failedEvents: AppEventPublishFailure[];
+};
+
+/**
+ * A publishing failure of a specific event.
+ */
+export interface AppEventPublishFailure {
+  event: AppEvent;
+  errorMessage: string;
+}
+
+/**
+ * A general error of the event publishing operation.
+ * No events were published if this is returned.
+ */
+export interface AppEventPublishError {
+  type: 'error';
+  errorType: AppEventErrorType;
+  errorMessage: string;
+}
+
+export type AppEventErrorType =
+  | 'VALIDATION_ERROR'
+  | 'AUTHENTICATION_ERROR'
+  | 'AUTHORIZATION_ERROR'
+  | 'RATE_LIMIT'
+  | 'SERVICE_ERROR'
+  | 'SERVICE_UNAVAILABLE'
+  | `OTHER`;
+
+interface AppEventErrorResponse {
+  errorMessages: string[];
+  errors: Map<string, string>;
+}
+
+interface AppEventSuccessResponse {
+  failedEvents: AppEventPublishFailure[];
+}
+
+const errorTypes: Record<number, AppEventErrorType> = {
+  400: 'VALIDATION_ERROR',
+  401: 'AUTHENTICATION_ERROR',
+  403: 'AUTHORIZATION_ERROR',
+  429: 'RATE_LIMIT',
+  500: 'SERVICE_ERROR',
+  503: 'SERVICE_UNAVAILABLE'
+};
+
+const endpoint = '/forge/events/v1/app-events';
+
+export const appEvents = {
+  async publish(events: AppEvent | AppEvent[]): Promise<AppEventPublishResult> {
+    const eventsArray = Array.isArray(events) ? events : [events];
+    const body = {
+      events: eventsArray.map((e) => ({
+        key: e.key
+      }))
+    };
+
+    const response = await post(endpoint, body, __requestAtlassianAsApp);
+    const responseBody = await response.json();
+
+    if (!response.ok) {
+      return {
+        type: 'error',
+        errorType: errorTypes[response.status] ?? 'OTHER',
+        errorMessage: getErrorMessage(responseBody)
+      };
+    }
+
+    return {
+      type: 'success',
+      failedEvents: (responseBody as AppEventSuccessResponse).failedEvents ?? []
+    };
+  }
+};
+
+function getErrorMessage(responseBody: AppEventErrorResponse) {
+  if (responseBody.errorMessages && responseBody.errorMessages.length > 0) {
+    return responseBody.errorMessages.join(', ');
+  } else if (responseBody.errors) {
+    return Object.entries(responseBody.errors)
+      .map(([key, value]) => `${key}: ${value}`)
+      .join(', ');
+  } else {
+    return JSON.stringify(responseBody);
+  }
+}

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,8 +11,18 @@ 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,
+  AppEventPublishResult,
+  AppEventPublishSuccess,
+  AppEventPublishFailure,
+  AppEventPublishError,
+  AppEventErrorType
+} from './appEvents';

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,
@@ -8,13 +8,19 @@ import {
 } from './validators';
 import { CancelJobRequest, GetStatsRequest } from './types';
 
+export type JobStats = {
+  success: number;
+  inProgress: number;
+  failed: number;
+};
+
 export class JobProgress {
   constructor(
     private readonly id: string,
     private readonly apiClient: FetchMethod = __requestAtlassianAsApp
   ) {}
 
-  async getStats(): Promise<APIResponse> {
+  async getStats(): Promise<JobStats> {
     const [queueName, jobId] = this.id.split('#');
     const getStatsRequest: GetStatsRequest = {
       queueName: queueName,
@@ -26,10 +32,11 @@ 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> {
+  async cancel(): Promise<void> {
     const [queueName, jobId] = this.id.split('#');
     const cancelJobRequest: CancelJobRequest = {
       queueName: queueName,
@@ -41,6 +48,5 @@ export class JobProgress {
 
     const response = await post(CANCEL_JOB_PATH, cancelJobRequest, this.apiClient);
     await validateCancelJobAPIResponse(response, cancelJobRequest);
-    return response;
   }
 }

package/src/queries.ts

@@ -1,10 +1,10 @@
 import { APIResponse, FetchMethod } from '@forge/api';
-import { APIRequest } from './types';
+
 export const PUSH_PATH = '/webhook/queue/publish/{contextAri}/{environmentId}/{appId}/{appVersion}';
 export const GET_STATS_PATH = '/webhook/queue/stats/{contextAri}/{environmentId}/{appId}/{appVersion}';
 export const CANCEL_JOB_PATH = '/webhook/queue/cancel/{contextAri}/{environmentId}/{appId}/{appVersion}';
 
-export const post = async (endpoint: string, body: APIRequest, apiClient: FetchMethod): Promise<APIResponse> => {
+export const post = async (endpoint: string, body: unknown, apiClient: FetchMethod): Promise<APIResponse> => {
   const request = {
     method: 'POST',
     body: JSON.stringify(body),

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,21 +22,15 @@ 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 {

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.`,