add support for event summary

Signed-off-by: Kent Rancourt <[email protected]>

Author: krancour

src/core/events.ts

@@ -102,6 +102,13 @@ export interface Event {
    * that are useful only to properly configured Workers.
    */
   payload?: string
+  /**
+   * A counterpart to payload. If payload is free-form Worker input,
+	 * then Summary is free-form Worker output. It can optionally be set by a
+	 * Worker to provide a summary of the work completed by the Worker and its
+	 * Jobs.
+   */
+  summary?: string
   /**
    * Contains details of the Worker assigned to handle the Event
    */
@@ -119,6 +126,16 @@ export interface SourceState {
   state?: { [key: string]: string }
 }
 
+/**
+ * Encapsulates an opaque, Worker-specific summary of an Event.
+ */
+export interface EventSummary {
+  /**
+   * The Event summary as (optionally) provided by a Worker.
+   */
+  text: string
+}
+
 /**
  * Useful filter criteria when selecting multiple Events for API group
  * operations like list, cancel, or delete.
@@ -281,6 +298,19 @@ export class EventsClient {
     return this.rmClient.executeRequest(req) as Promise<Event>
   }
 
+  /**
+   * Updates a Worker-specific Event summary.
+   * 
+   * @param id Identifier of the Event to update
+   * @throws An error if the specified Event is not found
+   */
+  public async updateSummary(id: string, summary: EventSummary): Promise<void> {
+    const req = new rm.Request("PUT", `v2/events/${id}/summary`)
+    req.bodyObj = summary
+    req.successCode = 200
+    return this.rmClient.executeRequest(req) as Promise<void>
+  }
+
   /**
    * Copies an Event in a terminal state, including Worker configuration and
    * creates a new Event from this information. Where possible, job results are

test/core/events.ts

@@ -1,4 +1,4 @@
-import { CancelManyEventsResult, DeleteManyEventsResult, Event, EventsClient } from "../../src/core/events" 
+import { CancelManyEventsResult, DeleteManyEventsResult, Event, EventsClient, EventSummary } from "../../src/core/events" 
 import { WorkerPhase } from "../../src/core/workers" 
 import * as meta from "../../src/meta"
 
@@ -158,6 +158,23 @@ describe("events", () => {
       })
     })
 
+    describe("#updateSummary", () => {
+      it("should send/receive properly over HTTP", async () => { 
+        const testEventID = "12345"
+        const testSummary: EventSummary = {
+          text: "This is a summary"
+        }
+        await common.testClient({
+          expectedRequestMethod: "PUT",
+          expectedRequestPath: `/v2/events/${testEventID}/summary`,
+          expectedRequestBody: testSummary,
+          clientInvocationLogic: () => {
+            return client.updateSummary(testEventID, testSummary)
+          }
+        })
+      })
+    })
+
     describe("#retry", () => {
       it("should send/receive properly over HTTP", async () => { 
         const testOriginalEventID = "tunguska"