chore: enhance OpenAI API integration with detailed documentation and update CI/CD workflow for NPM publishing

Author: Almaju

.github/scripts/publish-npm.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+cargo component build -p $1 --release
+safe_component=$(echo $1 | tr '-' '_')
+path="target/wasm32-wasip1/release/$safe_component.wasm"
+
+# Extract version from Cargo.toml
+version=$(grep "^version = " "crates/$1/Cargo.toml" | cut -d'"' -f2)
+
+rm -rf npm/$1
+mkdir -p npm/$1
+cd npm/$1
+npm init --init-version $version --scope=@wassemble -y
+cd ../..
+wit-bindgen markdown crates/$1/wit/world.wit --html-in-md
+mv $1.md npm/$1/README.md
+npx jco transpile $path -o npm/$1
+cd npm/$1
+npm publish --access public --provenance

.github/workflows/cd.yml

@@ -12,6 +12,7 @@ permissions:
   contents: read
   packages: write
   id-token: write
+  actions: read
 
 jobs:
   detect-changes:
@@ -32,6 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       GH_TOKEN: ${{ github.token }}
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
     strategy:
       matrix:
         component: ${{ fromJson(needs.detect-changes.outputs.matrix).component }}
@@ -55,3 +57,12 @@ jobs:
       # Publish
       - run: |
           cargo component publish -p ${{ matrix.component }} --config config.toml
+
+      # NPM package
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: .github/scripts/publish-npm.sh ${{ matrix.component }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

crates/openai/src/bindings.rs

@@ -1,9 +1,13 @@
 // Generated by `wit-bindgen` 0.41.0. DO NOT EDIT!
 // Options used:
 //   * runtime_path: "wit_bindgen_rt"
+/// Represents a single message in a chat conversation
+/// Used for both user input and assistant responses
 #[derive(Clone)]
 pub struct ChatMessage {
+    /// The role of the message sender: "user", "assistant", or "system"
     pub role: _rt::String,
+    /// The content/body of the message
     pub content: _rt::String,
 }
 impl ::core::fmt::Debug for ChatMessage {
@@ -14,12 +18,21 @@ impl ::core::fmt::Debug for ChatMessage {
             .finish()
     }
 }
+/// Configuration for a chat completion request to OpenAI
+/// Contains the conversation history and generation parameters
 #[derive(Clone)]
 pub struct ChatCompletion {
+    /// Unique identifier for this completion request
     pub id: _rt::String,
+    /// The OpenAI model to use (e.g., "gpt-3.5-turbo", "gpt-4")
     pub model: _rt::String,
+    /// List of messages in the conversation history
     pub messages: _rt::Vec<ChatMessage>,
+    /// Controls randomness in the response (0.0 = deterministic, 2.0 = very random)
+    /// Optional parameter - if not provided, uses model default
     pub temperature: Option<f64>,
+    /// Maximum number of tokens to generate in the response
+    /// Optional parameter - if not provided, uses model default
     pub max_tokens: Option<u32>,
 }
 impl ::core::fmt::Debug for ChatCompletion {
@@ -33,11 +46,17 @@ impl ::core::fmt::Debug for ChatCompletion {
             .finish()
     }
 }
+/// Response from OpenAI's chat completion API
+/// Contains the generated text and metadata about the completion
 #[derive(Clone)]
 pub struct ChatResponse {
+    /// Unique identifier for this completion response
     pub id: _rt::String,
+    /// The model that was used to generate the response
     pub model: _rt::String,
+    /// The generated text content from the assistant
     pub content: _rt::String,
+    /// Reason why the generation stopped: "stop", "length", "content_filter", etc.
     pub finish_reason: _rt::String,
 }
 impl ::core::fmt::Debug for ChatResponse {
@@ -50,9 +69,13 @@ impl ::core::fmt::Debug for ChatResponse {
             .finish()
     }
 }
+/// Configuration for an embedding request to OpenAI
+/// Used to convert text into numerical vector representations
 #[derive(Clone)]
 pub struct Embedding {
+    /// The OpenAI embedding model to use (e.g., "text-embedding-ada-002")
     pub model: _rt::String,
+    /// The text input to convert into an embedding vector
     pub input: _rt::String,
 }
 impl ::core::fmt::Debug for Embedding {
@@ -63,9 +86,14 @@ impl ::core::fmt::Debug for Embedding {
             .finish()
     }
 }
+/// Response from OpenAI's embedding API
+/// Contains the numerical vector representation of the input text
 #[derive(Clone)]
 pub struct EmbeddingResponse {
+    /// The model that was used to generate the embedding
     pub model: _rt::String,
+    /// The numerical vector representation of the input text
+    /// Each number represents a dimension in the embedding space
     pub embedding: _rt::Vec<f64>,
 }
 impl ::core::fmt::Debug for EmbeddingResponse {
@@ -302,7 +330,23 @@ pub unsafe fn __post_return_create_embedding<T: Guest>(arg0: *mut u8) {
     _rt::cabi_dealloc(base4, len4 * 8, 8);
 }
 pub trait Guest {
+    /// Creates a chat completion using OpenAI's API
+    /// Sends a conversation to OpenAI and returns the assistant's response
+    ///
+    /// Parameters:
+    /// - api-key: Your OpenAI API key for authentication
+    /// - completion: The chat completion configuration and conversation
+    ///
+    /// Returns: The generated response from the assistant
     fn create_chat_completion(api_key: _rt::String, completion: ChatCompletion) -> ChatResponse;
+    /// Creates an embedding vector using OpenAI's API
+    /// Converts text into a numerical representation for semantic analysis
+    ///
+    /// Parameters:
+    /// - api-key: Your OpenAI API key for authentication
+    /// - embedding: The embedding configuration and input text
+    ///
+    /// Returns: The numerical vector representation of the input text
     fn create_embedding(api_key: _rt::String, embedding: Embedding) -> EmbeddingResponse;
 }
 #[doc(hidden)]

crates/openai/wit/world.wit

@@ -1,36 +1,82 @@
 package wassemble:openai@0.1.0;
 
+/// OpenAI API integration world for chat completions and embeddings
 world openai {
+    /// Represents a single message in a chat conversation
+    /// Used for both user input and assistant responses
     record chat-message {
+        /// The role of the message sender: "user", "assistant", or "system"
         role: string,
+        /// The content/body of the message
         content: string,
     }
 
+    /// Configuration for a chat completion request to OpenAI
+    /// Contains the conversation history and generation parameters
     record chat-completion {
+        /// Unique identifier for this completion request
         id: string,
+        /// The OpenAI model to use (e.g., "gpt-3.5-turbo", "gpt-4")
         model: string,
+        /// List of messages in the conversation history
         messages: list<chat-message>,
+        /// Controls randomness in the response (0.0 = deterministic, 2.0 = very random)
+        /// Optional parameter - if not provided, uses model default
         temperature: option<f64>,
+        /// Maximum number of tokens to generate in the response
+        /// Optional parameter - if not provided, uses model default
         max-tokens: option<u32>,
     }
 
+    /// Response from OpenAI's chat completion API
+    /// Contains the generated text and metadata about the completion
     record chat-response {
+        /// Unique identifier for this completion response
         id: string,
+        /// The model that was used to generate the response
         model: string,
+        /// The generated text content from the assistant
         content: string,
+        /// Reason why the generation stopped: "stop", "length", "content_filter", etc.
         finish-reason: string,
     }
 
+    /// Configuration for an embedding request to OpenAI
+    /// Used to convert text into numerical vector representations
     record embedding {
+        /// The OpenAI embedding model to use (e.g., "text-embedding-ada-002")
         model: string,
+        /// The text input to convert into an embedding vector
         input: string,
     }
 
+    /// Response from OpenAI's embedding API
+    /// Contains the numerical vector representation of the input text
     record embedding-response {
+        /// The model that was used to generate the embedding
         model: string,
+        /// The numerical vector representation of the input text
+        /// Each number represents a dimension in the embedding space
         embedding: list<f64>,
     }
 
+    /// Creates a chat completion using OpenAI's API
+    /// Sends a conversation to OpenAI and returns the assistant's response
+    /// 
+    /// Parameters:
+    /// - api-key: Your OpenAI API key for authentication
+    /// - completion: The chat completion configuration and conversation
+    /// 
+    /// Returns: The generated response from the assistant
     export create-chat-completion: func(api-key: string, completion: chat-completion) -> chat-response;
+
+    /// Creates an embedding vector using OpenAI's API
+    /// Converts text into a numerical representation for semantic analysis
+    /// 
+    /// Parameters:
+    /// - api-key: Your OpenAI API key for authentication
+    /// - embedding: The embedding configuration and input text
+    /// 
+    /// Returns: The numerical vector representation of the input text
     export create-embedding: func(api-key: string, embedding: embedding) -> embedding-response;
 }