feat: prompt() (#39)

Author: gr2m

README.md

@@ -38,6 +38,23 @@ export default handler(request, response) {
 }
 ```
 
+### Send a custom propmt
+
+```js
+import { prompt } from "@copilot-extensions/preview-sdk";
+
+try {
+  const { message } = await prompt("What is the capital of France?", {
+    model: "gpt-4",
+    token: process.env.TOKEN,
+  });
+
+  console.log(message.content);
+} catch (error) {
+  console.error(error);
+}
+```
+
 ## API
 
 ### Verification
@@ -285,6 +302,86 @@ if (userConfirmation) {
 }
 ```
 
+## Prompt (Custom Chat completion calls)
+
+#### `prompt(message, options)`
+
+Send a prompt to the chat UI and receive a response from the user. The `message` argument must be a string and may include markdown.
+
+The `options` argument is optional. It can contain a `token` to authenticate the request to GitHub's API, or a custom `request.fetch` instance to use for the request.
+
+```js
+import { prompt } from "@copilot-extensions/preview-sdk";
+
+const { message } = await prompt("What is the capital of France?", {
+  model: "gpt-4",
+  token: process.env.TOKEN,
+});
+
+console.log(message.content);
+```
+
+⚠️ Not all of the arguments below are implemented yet.
+
+```js
+await prompt({
+  model: "gpt-4o",
+  token: process.env.TOKEN,
+  system: "You are a helpful assistant.",
+  messages: [
+    { role: "user", content: "What is the capital of France?" },
+    { role: "assistant", content: "The capital of France is Paris." },
+    {
+      role: "user",
+      content: [
+        [
+          { type: "text", text: "What about this country?" },
+          {
+            type: "image_url",
+            image_url: urlToImageOfFlagOfSpain,
+          },
+        ],
+      ],
+    },
+  ],
+  // GitHub recommends using your GitHub username, the name of your application
+  // https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api?apiVersion=2022-11-28#user-agent
+  userAgent: "gr2m/my-app v1.2.3",
+  // set an alternative chat completions endpoint
+  endpoint: "https://models.inference.ai.azure.com/chat/completions",
+  // compare https://platform.openai.com/docs/guides/function-calling/configuring-function-calling-behavior-using-the-tool_choice-parameter
+  toolChoice: "auto",
+  tools: [
+    {
+      type: "function",
+      function: {
+        name: "get_weather",
+        strict: true,
+        parameters: {
+          type: "object",
+          properties: {
+            location: { type: "string" },
+            unit: { type: "string", enum: ["c", "f"] },
+          },
+          required: ["location", "unit"],
+          additionalProperties: False,
+        },
+      },
+    },
+  ],
+  // configuration related to the request transport layer
+  request: {
+    // for mocking, proxying, client certificates, etc.
+    fetch: myCustomFetch,
+    // hook into request life cycle for complex authentication strategies, retries, throttling, etc
+    // compare options.request.hook from https://github.com/octokit/request.js
+    hook: myCustomHook,
+    // Use an `AbortController` instance to cancel a request
+    signal: myAbortController.signal,
+  },
+});
+```
+
 ## Dreamcode
 
 While implementing the lower-level functionality, we also dream big: what would our dream SDK for Coplitot extensions look like? Please have a look and share your thoughts and ideas:

index.d.ts

@@ -244,6 +244,30 @@ export interface GetUserConfirmationInterface {
   (payload: CopilotRequestPayload): UserConfirmation | undefined;
 }
 
+// prompt
+
+/** model names supported by Copilot API */
+export type ModelName =
+  | "gpt-4"
+  | "gpt-3.5-turbo"
+
+export type PromptOptions = {
+  model: ModelName
+  token: string
+  request?: {
+    fetch?: Function
+  }
+}
+
+export type PromptResult = {
+  requestId: string
+  message: Message
+}
+
+interface PromptInterface {
+  (userPrompt: string, options: PromptOptions): Promise<PromptResult>;
+}
+
 // exported methods
 
 export declare const verifyRequest: VerifyRequestInterface;
@@ -261,4 +285,6 @@ export declare const parseRequestBody: ParseRequestBodyInterface;
 export declare const transformPayloadForOpenAICompatibility: TransformPayloadForOpenAICompatibilityInterface;
 export declare const verifyAndParseRequest: VerifyAndParseRequestInterface;
 export declare const getUserMessage: GetUserMessageInterface;
-export declare const getUserConfirmation: GetUserConfirmationInterface;
+export declare const getUserConfirmation: GetUserConfirmationInterface;
+
+export declare const prompt: PromptInterface;

index.js

@@ -3,3 +3,4 @@
 export * from "./lib/parse.js";
 export * from "./lib/response.js";
 export * from "./lib/verification.js";
+export * from "./lib/prompt.js";

index.test-d.ts

@@ -18,6 +18,7 @@ import {
   getUserConfirmation,
   type VerificationPublicKey,
   CopilotRequestPayload,
+  prompt,
 } from "./index.js";
 
 const token = "";
@@ -267,3 +268,31 @@ export function getUserConfirmationTest(payload: CopilotRequestPayload) {
 
   expectType<{ accepted: boolean; id?: string; metadata: Record<string, unknown> }>(result)
 }
+
+export async function promptTest() {
+  const result = await prompt("What is the capital of France?", {
+    model: "gpt-4",
+    token: "secret",
+  })
+
+  expectType<string>(result.requestId)
+  expectType<string>(result.message.content)
+
+  // with custom fetch
+  await prompt("What is the capital of France?", {
+    model: "gpt-4",
+    token: "secret",
+    request: {
+      fetch: () => { }
+    }
+  })
+
+  // @ts-expect-error - 2nd argument is required
+  prompt("What is the capital of France?")
+
+  // @ts-expect-error - model argument is required
+  prompt("What is the capital of France?", { token: "" })
+
+  // @ts-expect-error - token argument is required
+  prompt("What is the capital of France?", { model: "" })
+}

lib/prompt.js

@@ -0,0 +1,38 @@
+// @ts-check
+
+/** @type {import('..').PromptInterface} */
+export async function prompt(userPrompt, promptOptions) {
+  const promptFetch = promptOptions.request?.fetch || fetch;
+  const response = await promptFetch(
+    "https://api.githubcopilot.com/chat/completions",
+    {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json; charset=UTF-8",
+        "user-agent": "copilot-extensions/preview-sdk.js",
+        authorization: `Bearer ${promptOptions.token}`,
+      },
+      body: JSON.stringify({
+        messages: [
+          {
+            role: "system",
+            content: "You are a helpful assistant.",
+          },
+          {
+            role: "user",
+            content: userPrompt,
+          },
+        ],
+        model: promptOptions.model,
+      }),
+    }
+  );
+
+  const data = await response.json();
+
+  return {
+    requestId: response.headers.get("x-request-id"),
+    message: data.choices[0].message,
+  };
+}

test/prompt.test.js

@@ -0,0 +1,70 @@
+import { test } from "node:test";
+
+import { MockAgent } from "undici";
+
+import { prompt } from "../index.js";
+
+test("smoke", (t) => {
+  t.assert.equal(typeof prompt, "function");
+});
+
+test("minimal usage", async (t) => {
+  const mockAgent = new MockAgent();
+  function fetchMock(url, opts) {
+    opts ||= {};
+    opts.dispatcher = mockAgent;
+    return fetch(url, opts);
+  }
+
+  mockAgent.disableNetConnect();
+  const mockPool = mockAgent.get("https://api.githubcopilot.com");
+  mockPool
+    .intercept({
+      method: "post",
+      path: `/chat/completions`,
+      body: JSON.stringify({
+        messages: [
+          {
+            role: "system",
+            content: "You are a helpful assistant.",
+          },
+          {
+            role: "user",
+            content: "What is the capital of France?",
+          },
+        ],
+        model: "gpt-4o-mini",
+      }),
+    })
+    .reply(
+      200,
+      {
+        choices: [
+          {
+            message: {
+              content: "<response text>",
+            },
+          },
+        ],
+      },
+      {
+        headers: {
+          "content-type": "application/json",
+          "x-request-id": "<request-id>",
+        },
+      }
+    );
+
+  const result = await prompt("What is the capital of France?", {
+    token: "secret",
+    model: "gpt-4o-mini",
+    request: { fetch: fetchMock },
+  });
+
+  t.assert.deepEqual(result, {
+    requestId: "<request-id>",
+    message: {
+      content: "<response text>",
+    },
+  });
+});