docs(examples): hello world, prompt

.gitignore

@@ -1,2 +1,3 @@
-node_modules
 coverage
+examples/**/package-lock.json
+node_modules

examples/1-hello-world/index.js

@@ -0,0 +1,21 @@
+import { createServer } from "node:http";
+
+import {
+  createTextEvent,
+  createDoneEvent,
+} from "@copilot-extensions/preview-sdk";
+
+const server = createServer((request, ressponse) => {
+  console.log(`Received [${request.method}] to [${request.url}]`);
+  if (request.method === "GET") {
+    return ressponse.end("ok");
+  }
+
+  ressponse.write(createTextEvent("Hello, world!"));
+  ressponse.end(createDoneEvent());
+});
+
+const PORT = process.env.PORT || 3000;
+server.listen(PORT, () => {
+  console.log(`Server is running on port ${PORT}`);
+});

examples/1-hello-world/package.json

@@ -0,0 +1,11 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "watch": "node --watch index.js"
+  },
+  "dependencies": {
+    "@copilot-extensions/preview-sdk": "latest"
+  }
+}

examples/2-handle-prompt/index.js

@@ -0,0 +1,111 @@
+import { createServer } from 'node:http';
+import { Octokit } from "@octokit";
+import { 
+    createAckEvent, 
+    createDoneEvent, 
+    createTextEvent, 
+    parseRequestBody, 
+    prompt,
+    verifyRequestByKeyId
+ } from "@copilot-extensions/preview-sdk";
+
+
+// Define the handler function
+const handler = async (request, response) => {
+
+    if (request.method !== 'POST') {
+        // Handle other request methods if necessary
+        response.writeHead(405, { 'Content-Type': 'text/plain' });
+        console.log(`Method ${request.method} not allowed`);
+
+        response.end('Method Not Allowed');
+    }
+
+    console.log('Received POST request');
+
+    // get a token to use
+    const tokenForUser = request.headers['x-github-token'];
+
+    // get the user information with the token        
+    const octokit = new Octokit({ auth: tokenForUser });
+    const user = await octokit.request("GET /user");
+    const userHandle = user.data.login
+
+    // Collect incoming data chunks to use in the `on("end")` event
+    let body = '';
+    request.on('data', chunk => {
+        body += chunk.toString();
+    });
+
+    // Parse the collected data once the request ends
+    request.on('end', async () => {
+        try {
+            const payloadIsVerified = await verifyRequestByKeyId(
+                request.body,
+                signature,
+                keyId,
+                {
+                  token: process.env.GITHUB_TOKEN,
+                },
+            );
+
+            if (!payloadIsVerified) {
+                console.error('Request verification failed');
+                response.writeHead(401, { 'Content-Type': 'text/plain' });
+                response.end('Request could not be verified');
+                return;
+            }
+
+            // start sending the response back to Copilot
+            console.log('Handling response');
+            // write the acknowledge event to let Copilot know we are handling the request
+            // this will also show the message "Copilot is responding" in the chat
+            response.write(createAckEvent());
+
+            // parse the incoming body as that has the information we need to handle the request / user prompt
+            const payload = parseRequestBody(body);
+
+            // start writing text in the response
+            const textEvent = createTextEvent(`Hello ${userHandle}, \n\n`);
+            response.write(textEvent);
+            // add new lines to mark the difference between the fixed text and the dynamic text
+            response.write("\n\n");
+
+            // get an authentication token to use
+            const tokenForUser = request.headers['x-github-token'];
+
+            console.log('Calling the GitHub Copilot API with the user prompt');
+            // the prompt to forward to the Copilot API is the last message in the payload
+            const payload_message = payload.messages[payload.messages.length - 1];
+            const result = await prompt(payload_message.content, {
+                system: "you talk like a pirate", // extra instructions for the prompt, the "you are a helpful assistant" is already set in the SDK
+                messages: payload.messages, // we are giving the prompt the existing messages in this chat conversation
+                token: tokenForUser         
+            });
+
+            // write the prompt response back to Copilot
+            // note that this is only send when the entire response from the Copilot API is ready
+            response.write(createTextEvent(result.message.content));
+
+            // write the done event to let Copilot know we are done handling the request
+            response.end(createDoneEvent());
+            console.log('Response sent');
+        }
+        catch (error) {
+            console.error('Error:', error);
+            response.writeHead(500, { 'Content-Type': 'text/plain' });
+            response.end('Internal Server Error');
+        }
+    });
+};
+
+// Create an HTTP server
+const server = http.createServer(handler);
+
+// Define the port to listen on
+const PORT = 3000;
+
+// Start the server
+server.listen(PORT, () => {
+    console.log(`Server is listening on port ${PORT}`);
+});

examples/2-handle-prompt/package.json

@@ -0,0 +1,12 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "watch": "node --watch index.js"
+  },
+  "dependencies": {
+    "@copilot-extensions/preview-sdk": "latest",
+    "@octokit": "latest"
+  }
+}

examples/README.md

@@ -0,0 +1,28 @@
+This folder contains examples to show how you can use the Copilot Agent SDK in your own projects.
+Keep in mind that the SDK is in preview, so things might be changed already!
+
+If you find any issues or have any questions, please let us know by opening an issue, pull requests welcome (please read the (contribution guidelines)[../CONTRIBUTING.md] first).
+
+# Examples
+Here's an overview of the examples in this folder:
+- 1-hello-world: A simple example that responds to all prompts with a message: "Hello, world!"
+- 2-handle-prompt: An example that responds to prompts with a message: "Hello, world!" and then forwards the prompt to the Copilot API. The response from the Copilot API is then sent back to the user.
+
+## Running the examples
+These examples are setup so that you can run them inside a GitHub Codespace. To do so, follow these steps:
+1. Open the GitHub Codespace by clicking the "Code" button in the top right of the repository and selecting "Open with Codespaces".
+2. Once the Codespace is open, you can run the examples by running the following command in the terminal:
+```sh
+# go to the correct folder
+cd examples/<example-name>
+# install dependencies
+npm install
+# run the example
+npm run start
+```
+
+> [!IMPORTANT]  
+> By default, the examples will run on port 3000 and ports in Codespaces are private by default. If you want to access the examples from your browser, you'll need to make the port public. To do so, click on the "Ports" tab in the Codespace and right click, Go to "Port Visibility" next to port 3000 and set it to `public`. Do be aware that this will make the port accessible to anyone with the link to your Codespace. The port visibility setting is not saved when the Codespace is stopped, so you'll need to set it again if you restart the Codespace or node. The url does stay the same as long as the Codespace is not deleted.
+
+> [!TIP]  
+> Don't forget to set the Codespace url (with the port) in your GitHub App that you are using. The Copilot backend needs to be able to reach your Codespace to send messages to your extension. If your app is not running, the port is not public, or the codespace is stopped, the extension will not work.