Improve example providers

provider/hello-world/README.md

@@ -22,3 +22,11 @@ This sample provider is not configurable.
 - [Source code](https://sourcegraph.com/github.com/sourcegraph/openctx/-/tree/provider/hello-world)
 - [Docs](https://openctx.org/docs/providers/hello-world)
 - License: Apache 2.0
+
+### Local Testing
+
+1. Clone the repo
+1. `pnpm install`
+1. `pnpm -C provider/hello-world bundle --watch` to automatically recompile on changes
+1. Run `echo file://$(pwd)/provider/hello-world/dist/bundle.js` and use that URL in your OpenCtx instead of `"https://openctx.org/npm/@openctx/provider-hello-world"`
+1. Reload your OpenCtx client

provider/hello-world/index.ts

@@ -4,31 +4,60 @@ import type {
     AnnotationsResult,
     ItemsParams,
     ItemsResult,
+    MentionsParams,
+    MentionsResult,
     MetaParams,
     MetaResult,
     Provider,
     ProviderSettings,
 } from '@openctx/provider'
 
 /**
- * A demo [OpenCtx](https://openctx.org) provider that annotates every 10th line in every
- * file with "✨ Hello, world!".
+ * A demo [OpenCtx](https://openctx.org) provider that provides some sample
+ * @-mentions, and annotates every 10th line in every file with "✨ Hello,
+ * world!".
  */
-const helloWorld: Provider = {
+const provider: Provider = {
     meta(params: MetaParams, settings: ProviderSettings): MetaResult {
-        return { name: '✨ Hello World!', annotations: {} }
+        return { name: 'Hello World', mentions: {}, annotations: {} }
+    },
+
+    mentions(params: MentionsParams, settings: ProviderSettings): MentionsResult {
+        // Initial state
+        if (!params.query) {
+            return [
+                {
+                    title: '✨ Hello World!',
+                    description: 'This is a sample @-mention',
+                    uri: 'https://openctx.org/',
+                    data: { key: 'hello-world-1' },
+                },
+            ]
+        }
+
+        // Typed a query/search
+        return [
+            {
+                title: '🎉 Foo Bar Baz',
+                description: `Item matching "${params.query}"`,
+                uri: 'https://openctx.org/',
+                data: { key: 'hello-world-2' },
+            },
+        ]
     },
 
     items(params: ItemsParams, settings: ProviderSettings): ItemsResult {
+        const mentionKey = params.mention?.data?.key as string
+
         return [
             {
-                title: '✨ Hello, world!',
+                title: `Hello World (${mentionKey})`,
                 url: 'https://openctx.org',
                 ui: {
                     hover: { text: 'From OpenCtx' },
                 },
                 ai: {
-                    content: 'Hello, world!',
+                    content: `This is the content of this item: 'Hello world context data (${mentionKey})'`,
                 },
             },
         ]
@@ -61,4 +90,4 @@ const helloWorld: Provider = {
     },
 }
 
-export default helloWorld
+export default provider

provider/hello-world/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openctx/provider-hello-world",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Hello World (OpenCtx provider)",
   "license": "Apache-2.0",
   "homepage": "https://openctx.org/docs/providers/hello-world",
@@ -12,14 +12,11 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist/index.js",
-    "dist/index.d.ts"
-  ],
+  "files": ["dist/index.js", "dist/index.d.ts"],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc --build",
-    "prepublishOnly": "tsc --build --clean && pnpm run --silent build",
+    "bundle": "tsc --build && esbuild --log-level=error --bundle --format=esm --outfile=dist/bundle.js index.ts",
+    "prepublishOnly": "tsc --build --clean && npm run --silent bundle",
     "test": "vitest"
   },
   "dependencies": {

provider/json-api-example/README.md

@@ -0,0 +1,35 @@
+# JSON API Example Provider for OpenCtx
+
+[OpenCtx](https://openctx.org) context provider example that calls a JSON API to fetch context.
+
+## Usage
+
+```json
+"openctx.providers": {
+    // ...other providers...
+    "https://openctx.org/npm/@openctx/provider-json-api-example": true
+},
+```
+
+## Mention support
+
+- Vehicle list
+- Vehicle search
+
+## Context included
+
+- Vehicle data
+
+## Development
+
+- [Source code](https://sourcegraph.com/github.com/sourcegraph/openctx/-/tree/provider/json-api-example)
+- [Docs](https://openctx.org/docs/providers/json-api-example)
+- License: Apache 2.0
+
+### Local Testing
+
+1. Clone the repo
+1. `pnpm install`
+1. `pnpm -C provider/json-api-example bundle --watch` to automatically recompile on changes
+1. Run `echo file://$(pwd)/provider/json-api-example/dist/bundle.js` and use that URL in your OpenCtx instead of `"https://openctx.org/npm/@openctx/provider-json-api-example"`
+1. Reload your OpenCtx client

provider/json-api-example/index.ts

@@ -0,0 +1,68 @@
+import type {
+    ItemsParams,
+    ItemsResult,
+    MentionsParams,
+    MentionsResult,
+    MetaParams,
+    MetaResult,
+    Provider,
+    ProviderSettings,
+} from '@openctx/provider'
+
+// https://swapi.dev/documentation#vehicles
+type Vehicle = {
+    name: string
+    model: string
+    manufacturer: string
+    url: string
+}
+
+const provider: Provider = {
+    meta(params: MetaParams, settings: ProviderSettings): MetaResult {
+        return {
+            name: 'JSON API Example',
+            mentions: {},
+        }
+    },
+
+    async mentions(params: MentionsParams, settings: ProviderSettings): Promise<MentionsResult> {
+        const endpoint = 'https://swapi.dev/api/vehicles'
+        const url = params.query ? `${endpoint}?search=${encodeURIComponent(params.query)}` : endpoint
+
+        return fetch(url)
+            .then(response => response.json() as Promise<{ results: Vehicle[] }>)
+            .then(data => {
+                return data.results.map(vehicle => ({
+                    title: `${vehicle.name} (${vehicle.model})`,
+                    description: vehicle.manufacturer,
+                    uri: vehicle.url,
+                    data: {
+                        // Only minimal data should used here (e.g. an id or key)
+                        id: vehicle.url.split('/').pop(),
+                    },
+                }))
+            })
+    },
+
+    async items(params: ItemsParams, settings: ProviderSettings): Promise<ItemsResult> {
+        // We just use the `mention.data`, but you can also make use of `params.message`
+        const data = params.mention?.data as { id: string }
+
+        const vehicle = await fetch(`https://swapi.dev/api/vehicles/${data.id}`).then(
+            response => response.json() as Promise<Vehicle>
+        )
+
+        // We return one item, but you can return more to provide more context
+        return [
+            {
+                title: vehicle.name,
+                url: vehicle.url,
+                ai: {
+                    content: `Star wars vehicle named @${vehicle.name}: ${JSON.stringify(vehicle)}`,
+                },
+            },
+        ]
+    },
+}
+
+export default provider

provider/json-api-example/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@openctx/provider-json-api-example",
+  "version": "0.0.1",
+  "description": "JSON API Example (OpenCtx provider)",
+  "license": "Apache-2.0",
+  "homepage": "https://openctx.org/docs/providers/json-api-example",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sourcegraph/json-api-example",
+    "directory": "provider/json-api-example"
+  },
+  "type": "module",
+  "main": "dist/bundle.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist/bundle.js", "dist/index.d.ts"],
+  "sideEffects": false,
+  "scripts": {
+    "bundle": "tsc --build && esbuild --log-level=error --bundle --format=esm --outfile=dist/bundle.js index.ts",
+    "prepublishOnly": "tsc --build --clean && npm run --silent bundle",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@openctx/provider": "workspace:*"
+  }
+}
+

provider/json-api-example/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"extends": "../../.config/tsconfig.base.json",
+	"compilerOptions": {
+	  "rootDir": ".",
+	  "outDir": "dist",
+	  "lib": ["ESNext"],
+	},
+	"include": ["*.ts"],
+	"exclude": ["dist", "vitest.config.ts"],
+	"references": [{ "path": "../../lib/provider" }],
+  }
+