Update docs for workflow context (#29)

Update docs based on our latest changes in
dbos-inc/dbos-transact-ts#149, where we added `getEvent()`
and `retrieveWorkflow()` methods in workflow context.

Question: should we merge this into main, or do we want to create a
branch for the next release?

Author: qianl15

.github/workflows/deploy.yml

@@ -1,11 +1,12 @@
 name: Deploy to GitHub Pages
 
 on:
-  push:
-    branches:
-      - main
+  # push:  ### Temporarily disable auto deployment on push to main.
+  #   branches:
+  #     - main
     # Review gh actions docs if you want to further define triggers, paths, etc
     # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+  workflow_dispatch:
 
 jobs:
   deploy:

.github/workflows/test-deploy.yml

@@ -1,6 +1,9 @@
 name: Test deployment
 
 on:
+  push:  ### Temporarily enable test on main.
+    branches:
+      - main
   pull_request:
     branches:
       - main

docs/api-reference/contexts.md

@@ -198,7 +198,7 @@ getEvent<T extends NonNullable<any>>(workflowUUID: string, key: string, timeoutS
 ```
 
 Retrieves an event published by _workflowUUID_ for a given key using the [events API](../tutorials/workflow-communication-tutorial#events-api).
-A call to `getEvent` waits for the workflow to publish the key, returning `null` if the wait times out:
+Awaiting on the promise returned by `getEvent()` waits for the workflow to publish the key, returning `null` if the wait times out.
 
 ---
 
@@ -213,6 +213,8 @@ Workflows use `WorkflowContext` to invoke other functions and interact with othe
 - [send(destinationUUID, message, \[topic\])](#workflowctxtsenddestinationuuid-message-topic)
 - [recv(\[topic, timeoutSeconds\])](#workflowctxtrecvtopic-timeoutseconds)
 - [setEvent(key, value)](#workflowctxtseteventkey-value)
+- [getEvent()](#workflowctxtgeteventworkflowuuid-key-timeoutseconds)
+- [retrieveWorkflow(workflowUUID)](#workflowctxtretrieveworkflowworkflowuuid)
 
 ### workflowCtxt.invoke(targetClass)
 
@@ -279,6 +281,25 @@ HTTP handlers can read events by calling [`getEvent`](#handlerctxtgeteventworkfl
 Events are immutable and attempting to emit an event twice from a given workflow instance will result in an error.
 For more information, see our [events API tutorial](../tutorials/workflow-communication-tutorial#events-api).
 
+### workflowCtxt.getEvent(workflowUUID, key, \[timeoutSeconds\])
+
+```typescript
+getEvent<T extends NonNullable<any>>(workflowUUID: string, key: string, timeoutSeconds?: number): Promise<T | null>
+```
+
+Retrieves an event published by _workflowUUID_ for a given key using the [events API](../tutorials/workflow-communication-tutorial#events-api).
+Awaiting on the promise returned by `getEvent()` waits for the workflow to publish the key, returning `null` if the wait times out.
+
+### workflowCtxt.retrieveWorkflow(workflowUUID)
+
+```typescript
+retrieveWorkflow<R>(workflowUUID: string): WorkflowHandle<R>
+```
+
+Returns a [workflow handle](./workflow-handles.md) to the workflow with [identity](../tutorials/workflow-tutorial#workflow-identity) _workflowUUID_.
+`R` is the return type of the target workflow.
+
+
 ---
 
 ## `TransactionContext<T>`