docs(examples): hello world, prompt

.gitignore

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

examples/README.md

@@ -0,0 +1,27 @@
+# Examples
+
+This folder contains examples to show how you can use the Copilot Agent SDK in your own projects.
+
+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).
+
+## 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.

examples/hello-world/index.js

@@ -0,0 +1,22 @@
+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/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": "../../"
+  }
+}

examples/prompt/index.js

@@ -0,0 +1,108 @@
+import { createServer } from "node:http";
+import { Octokit } from "octokit";
+import {
+  createAckEvent,
+  createDoneEvent,
+  prompt,
+  verifyAndParseRequest,
+} from "@copilot-extensions/preview-sdk";
+
+// Define the port to listen on
+const PORT = 3000;
+
+// Define the handler function
+async function handler(request, response) {
+  console.log(`Received [${request.method}] to [${request.url}]`);
+
+  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");
+    return;
+  }
+
+  // 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");
+
+  // Collect incoming data chunks to use in the `on("end")` event
+  const body = await getBody(request);
+  const signature = String(request.headers["github-public-key-signature"]);
+  const keyID = String(request.headers["github-public-key-identifier"]);
+
+  try {
+    const { isValidRequest, payload } = await verifyAndParseRequest(
+      body,
+      signature,
+      keyID,
+      {
+        token: tokenForUser,
+      },
+    );
+
+    if (!isValidRequest) {
+      console.error("Request verification failed");
+      response.writeHead(401, { "Content-Type": "text/plain" });
+      response.end("Request could not be verified");
+      return;
+    }
+
+    // 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());
+
+    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 { stream } = await prompt.stream(payload_message.content, {
+      system: `You are a helpful assistant that replies to user messages as if you were the Blackbeard Pirate. Start every response with the user's name, which is @${user.data.login}`, // extra instructions for the prompt
+      messages: payload.messages, // we are giving the prompt the existing messages in this chat conversation for context
+      token: tokenForUser,
+    });
+
+    // stream the prompt response back to Copilot
+    for await (const chunk of stream) {
+      response.write(new TextDecoder().decode(chunk));
+    }
+
+    // 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 = createServer(handler);
+
+// Start the server
+server.listen(PORT);
+console.log(`Server started at http://localhost:${PORT}`);
+
+/**
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @returns
+ */
+function getBody(request) {
+  return new Promise((resolve) => {
+    const bodyParts = [];
+    let body;
+    request
+      .on("data", (chunk) => {
+        bodyParts.push(chunk);
+      })
+      .on("end", () => {
+        body = Buffer.concat(bodyParts).toString();
+        resolve(body);
+      });
+  });
+}

examples/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": "../../",
+    "octokit": "^4.0.2"
+  }
+}