From c19b2f320ae4e5bc388e55120dcde133643f377d Mon Sep 17 00:00:00 2001
From: Ivan Artemiev <29709626+iartemiev@users.noreply.github.com>
Date: Mon, 28 Oct 2024 11:36:08 -0400
Subject: [PATCH] chore(api-graphql): events client docstrings (#13967)

---
 .../api-graphql/src/internals/events/index.ts | 53 +++++++++++++------
 .../api-graphql/src/internals/events/types.ts | 36 +++++++++++++
 2 files changed, 74 insertions(+), 15 deletions(-)

diff --git a/packages/api-graphql/src/internals/events/index.ts b/packages/api-graphql/src/internals/events/index.ts
index 02f003c4d7c..49860a92049 100644
--- a/packages/api-graphql/src/internals/events/index.ts
+++ b/packages/api-graphql/src/internals/events/index.ts
@@ -18,11 +18,27 @@ import type {
 } from './types';
 
 /**
+ * @experimental API may change in future versions
+ *
  * Establish a WebSocket connection to an Events channel
  *
+ * @example
+ * const channel = await events.connect("default/channel")
+ *
+ * channel.subscribe({
+ *   next: (data) => { console.log(data) },
+ *   error: (err) => { console.error(err) },
+ * })
+ *
+ * @example // authMode override
+ * const channel = await events.connect("default/channel", { authMode: "userPool" })
+ *
+ * @param channel - channel path; `<namespace>/<channel>`
+ * @param options - request overrides: `authMode`, `authToken`
+ *
  */
 async function connect(
-	channelName: string,
+	channel: string,
 	options?: EventsOptions,
 ): Promise<EventsChannel> {
 	const providerOptions = configure();
@@ -40,7 +56,7 @@ async function connect(
 		observer: SubscriptionObserver<any>,
 		subOptions?: EventsOptions,
 	): Subscription => {
-		const subscribeOptions = { ...providerOptions, query: channelName };
+		const subscribeOptions = { ...providerOptions, query: channel };
 		subscribeOptions.authenticationType = normalizeAuth(
 			subOptions?.authMode,
 			subscribeOptions.authenticationType,
@@ -60,7 +76,7 @@ async function connect(
 	): Promise<any> => {
 		const publishOptions = {
 			...providerOptions,
-			query: channelName,
+			query: channel,
 			variables: event,
 		};
 		publishOptions.authenticationType = normalizeAuth(
@@ -76,27 +92,35 @@ async function connect(
 	};
 
 	return {
-		/**
-		 * Subscribe to incoming events
-		 */
 		subscribe: sub,
-		/**
-		 * Close channel and any active subscriptions
-		 */
 		close,
 		// publish: pub,
 	};
 }
 
 /**
- * Publish events to a channel via REST request
+ * @experimental API may change in future versions
  *
- * @param channelName - publish destination
+ * Publish events to a channel via HTTP request
+ *
+ * @example
+ * await events.post("default/channel", { some: "event" })
+ *
+ * @example // event batching
+ * await events.post("default/channel", [{ some: "event" }, { some: "event2" }])
+ *
+ * @example // authMode override
+ * await events.post("default/channel", { some: "event" }, { authMode: "userPool" })
+ *
+ * @param channel - channel path; `<namespace>/<channel>`
  * @param event - JSON-serializable value or an array of values
- * @param options
+ * @param options - request overrides: `authMode`, `authToken`
+ *
+ * @returns void on success
+ * @throws on error
  */
 async function post(
-	channelName: string,
+	channel: string,
 	event: DocumentType | DocumentType[],
 	options?: EventsOptions,
 ): Promise<void | PublishedEvent[]> {
@@ -107,8 +131,7 @@ async function post(
 	);
 
 	// trailing slash required in publish
-	const normalizedChannelName =
-		channelName[0] === '/' ? channelName : `/${channelName}`;
+	const normalizedChannelName = channel[0] === '/' ? channel : `/${channel}`;
 
 	const publishOptions = {
 		...providerOptions,
diff --git a/packages/api-graphql/src/internals/events/types.ts b/packages/api-graphql/src/internals/events/types.ts
index c0b7ed50be2..f9f52c538c1 100644
--- a/packages/api-graphql/src/internals/events/types.ts
+++ b/packages/api-graphql/src/internals/events/types.ts
@@ -10,10 +10,46 @@ export interface SubscriptionObserver<T> {
 }
 
 export interface EventsChannel {
+	/**
+	 * @experimental API may change in future versions
+	 *
+	 * Subscribe to Events
+	 *
+	 * @example
+	 * const channel = await events.connect("default/channel")
+	 *
+	 * channel.subscribe({
+	 *   next: (data) => { console.log(data) },
+	 *   error: (err) => { console.error(err) },
+	 * })
+	 *
+	 * @example // authMode override
+	 * channel.subscribe({
+	 *   next: (data) => { console.log(data) },
+	 *   error: (err) => { console.error(err) },
+	 * }, { authMode: 'userPool' })
+	 *
+	 * @param observer - observer callback handlers
+	 * `{ next: () => {}, error: () => {}}`
+	 *
+	 * @param options - subscribe overrides: `authMode`, `authToken`
+	 *
+	 */
 	subscribe(
 		observer: SubscriptionObserver<any>,
 		subOptions?: EventsOptions,
 	): Subscription;
+	/**
+	 * @experimental API may change in future versions
+	 *
+	 * Close channel and any active subscriptions
+	 *
+	 * @example
+	 * const channel = await events.connect("default/channel")
+	 *
+	 * channel.close()
+	 *
+	 */
 	close(): void;
 }