Merge pull request #31 from nlxai/generate-api-docs

generate api docs from tsdoc
nlxai · Mar 26, 2024 · 900db39 · 900db39
2 parents 2e91693 + b1ab8c7
commit 900db39
Show file tree

Hide file tree

Showing 11 changed files with 369 additions and 43 deletions.
diff --git a/packages/voice-compass/.gitignore b/packages/voice-compass/.gitignore
@@ -0,0 +1 @@
+docs
diff --git a/packages/voice-compass/README.md b/packages/voice-compass/README.md
@@ -0,0 +1,11 @@
+# VoiceCompass SDK
+
+The API for creating multi-modal integrations with a voice assistant.
+
+## Installation
+
+`npm install --save @nlxai/voice-compass`
+
+## Usage
+
+see: https://developers.nlx.ai/#/multimodal-getting-started
diff --git a/packages/voice-compass/package.json b/packages/voice-compass/package.json
@@ -10,6 +10,8 @@
   "types": "lib/index.d.ts",
   "scripts": {
     "build": "rm -rf lib && rollup -c",
+    "docs": "typedoc",
+    "publish-docs": "npm run docs && concat-md --decrease-title-levels --dir-name-as-title docs/ > ../website/src/content/06-03-multimodal-api-reference.md",
     "prepublish": "npm run build",
     "test": "jest"
   },
@@ -26,13 +28,15 @@
     "@types/jest": "^29.5.12",
     "@types/node": "^11.15.11",
     "@types/ramda": "0.29.1",
+    "concat-md": "^0.5.1",
     "fast-check": "^3.16.0",
     "jest": "^29.7.0",
     "prettier": "^3.0.3",
     "rollup": "^4.3.0",
     "rollup-plugin-node-polyfills": "^0.2.1",
     "ts-jest": "^29.1.2",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.25.12",
     "typescript": "^5.2.2"
   },
   "dependencies": {

diff --git a/packages/voice-compass/src/index.ts b/packages/voice-compass/src/index.ts
@@ -1,26 +1,29 @@
 import fetch from "isomorphic-fetch";
 
-// Initial configuration used when creating a journey manager
-export interface Config {
-  apiKey: string;
-  workspaceId: string;
-  conversationId: string;
-  journeyId: string;
-  languageCode: string;
-  debug?: boolean;
-  dev?: boolean;
-}
-
-export type Context = Record<string, any>;
-
-// The journey manager object
-export interface VoiceCompass {
-  sendStep: (stepId: string, context?: Context) => Promise<void>;
-}
-
-export const stepIdRegex =
-  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
-
+/**
+ * The starting point of the package. Call create to create a `VoiceCompass` client.
+ *
+ * @example
+ * ```typescript
+ *  const client = nlxai.voiceCompass.create({
+ *  // hard-coded params
+ *  apiKey: "REPLACE_WITH_API_KEY",
+ *  workspaceId: "REPLACE_WITH_WORKSPACE_ID",
+ *  journeyId: "REPLACE_WITH_JOURNEY_ID",
+ *  // dynamic params
+ *  conversationId: "REPLACE_WITH_CONVERSATION_ID",
+ *  languageCode: "en-US",
+ * });
+ *
+ * client.sendStep("REPLACE_WITH_STEP_ID");
+ * ```
+ *
+ * @category Setup
+ *
+ * @param options - the configuration object
+ *
+ * @returns a Voice Compass client
+ */
 export const create = ({
   apiKey,
   workspaceId,
@@ -29,7 +32,7 @@ export const create = ({
   languageCode,
   debug = false,
   dev = false,
-}: Config): VoiceCompass => {
+}: Config): Client => {
   if (!conversationId) {
     console.warn(
       'No conversation ID provided. Please call the Voice Compass client `create` method with a `conversationId` field extracted from the URL. Example code: `new URLSearchParams(window.location.search).get("cid")`',
@@ -72,3 +75,80 @@ export const create = ({
 
   return { sendStep };
 };
+
+/**
+ * The VoiceCompass client
+ * @category Client
+ */
+export interface Client {
+  /**
+   *
+   * * @example
+   * ```typescript
+   *  const client = nlxai.voiceCompass.create({
+   *  // hard-coded params
+   *  apiKey: "REPLACE_WITH_API_KEY",
+   *  workspaceId: "REPLACE_WITH_WORKSPACE_ID",
+   *  journeyId: "REPLACE_WITH_JOURNEY_ID",
+   *  // dynamic params
+   *  conversationId: "REPLACE_WITH_CONVERSATION_ID",
+   *  languageCode: "en-US",
+   * });
+   *
+   * client.sendStep("REPLACE_WITH_STEP_ID", {selectedSeat: "4a"});
+   * ```
+   * sends a step to the voice bot
+   * @param stepId - the next step to transition to.
+   *
+   *
+   *   _Note: Must be a valid UUID_
+   *
+   * @param context -  context to send back to the voice bot, for usage later in the intent.
+   */
+  sendStep: (stepId: string, context?: Context) => Promise<void>;
+}
+
+/**
+ * context to send back to the voice bot, for usage later in the intent.
+ * @category Client
+ */
+export type Context = Record<string, any>;
+
+/**
+ * Initial configuration used when creating a journey manager
+ * @category Setup
+ */
+export interface Config {
+  /** * the API key generated for the journey.  **/
+  apiKey: string;
+  /** the ID of the journey.  */
+  journeyId: string;
+
+  /** your workspace id */
+  workspaceId: string;
+
+  /** the conversation id, passed from the active voice bot.
+   *
+   * _Note: This must be dynamically set by the voice bot._
+   * */
+  conversationId: string;
+
+  /** the user's language code.
+   *
+   * In the browser may be fetched from `navigator.language`, or if the journey doesn't support multiple languages, can be hardcoded.
+   * */
+  languageCode: string;
+
+  /** set to true to help debug issues or errors. Defaults to false */
+  debug?: boolean;
+
+  /** used for library testing @internal @hidden */
+  dev?: boolean;
+}
+
+/**
+ * @internal @hidden
+ * this is exported so we can test it. Should be equivalent to a UUID v4 regex.
+ */
+export const stepIdRegex =
+  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
diff --git a/packages/voice-compass/tsconfig.json b/packages/voice-compass/tsconfig.json
@@ -5,7 +5,6 @@
     "moduleResolution": "bundler",
     "declaration": true,
     "outDir": "./lib",
-    "rootDir": "./src",
     "strict": true,
     "strictNullChecks": true,
     "esModuleInterop": true,

diff --git a/packages/voice-compass/typedoc.cjs b/packages/voice-compass/typedoc.cjs
@@ -0,0 +1,12 @@
+/** @type {import('typedoc').TypeDocOptions} */
+module.exports = {
+  sort: ["source-order", "kind", "instance-first", "alphabetical"],
+  entryPoints: ["./src/index.ts"],
+  out: "docs",
+  validation: { notExported: true, invalidLink: true, notDocumented: true },
+  treatWarningsAsErrors: true,
+  treatValidationWarningsAsErrors: true,
+  categoryOrder: ["Setup", "Client"],
+  plugin: ["typedoc-plugin-markdown"],
+  readme: "none",
+};
diff --git a/packages/website/package.json b/packages/website/package.json
@@ -19,6 +19,8 @@
     "react-dom": "^18.2.0",
     "react-markdown": "^9.0.0",
     "react-router-dom": "^6.17.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.0",
     "tinycolor2": "^1.4.1"
   },

diff --git a/packages/website/src/components/PageContent.tsx b/packages/website/src/components/PageContent.tsx
@@ -3,6 +3,8 @@ import Markdown from "react-markdown";
 import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { CheckIcon, ContentCopyIcon } from "./Icons";
 import remarkGfm from "remark-gfm";
+import rehypeRaw from "rehype-raw";
+import rehypeSlug from "rehype-slug";
 
 const CopyToClipboardButton: FC<{ text: string; className?: string }> = ({
   text,
@@ -45,6 +47,7 @@ export const PageContent: FC<{ md: string }> = ({ md }) => (
   <Prose>
     <Markdown
       remarkPlugins={[remarkGfm]}
+      rehypePlugins={[rehypeRaw, rehypeSlug]}
       components={{
         pre(props) {
           return (