@qikbar/qikbar 0.0.25 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +121 -0
  3. package/bin/qikbar.mjs +203 -0
  4. package/dist/ai/agent.d.ts +42 -0
  5. package/dist/ai/byok.d.ts +29 -0
  6. package/dist/ai/embeddings.d.ts +51 -0
  7. package/dist/ai/index.d.ts +12 -0
  8. package/dist/ai/mcp.d.ts +84 -0
  9. package/dist/ai/providers.d.ts +82 -0
  10. package/dist/ai/sse.d.ts +9 -0
  11. package/dist/ai.js +54 -0
  12. package/dist/ai.js.map +7 -0
  13. package/dist/chunks/bar-P3SCR4SJ.js +2555 -0
  14. package/dist/chunks/bar-P3SCR4SJ.js.map +7 -0
  15. package/dist/chunks/chunk-5FI7DNG7.js +271 -0
  16. package/dist/chunks/chunk-5FI7DNG7.js.map +7 -0
  17. package/dist/chunks/chunk-INTEVQYK.js +108 -0
  18. package/dist/chunks/chunk-INTEVQYK.js.map +7 -0
  19. package/dist/chunks/chunk-JHQAIXM7.js +458 -0
  20. package/dist/chunks/chunk-JHQAIXM7.js.map +7 -0
  21. package/dist/chunks/chunk-MPTP2EWW.js +8 -0
  22. package/dist/chunks/chunk-MPTP2EWW.js.map +7 -0
  23. package/dist/chunks/chunk-MRHKJ2FZ.js +419 -0
  24. package/dist/chunks/chunk-MRHKJ2FZ.js.map +7 -0
  25. package/dist/chunks/chunk-N4Y2Z6YD.js +69 -0
  26. package/dist/chunks/chunk-N4Y2Z6YD.js.map +7 -0
  27. package/dist/chunks/chunk-OLXZNYZ4.js +193 -0
  28. package/dist/chunks/chunk-OLXZNYZ4.js.map +7 -0
  29. package/dist/chunks/chunk-PQEHV3D4.js +124 -0
  30. package/dist/chunks/chunk-PQEHV3D4.js.map +7 -0
  31. package/dist/chunks/chunk-R2AY6LRL.js +575 -0
  32. package/dist/chunks/chunk-R2AY6LRL.js.map +7 -0
  33. package/dist/chunks/chunk-TIM4VBM4.js +98 -0
  34. package/dist/chunks/chunk-TIM4VBM4.js.map +7 -0
  35. package/dist/chunks/chunk-YCVJQ7U3.js +52 -0
  36. package/dist/chunks/chunk-YCVJQ7U3.js.map +7 -0
  37. package/dist/chunks/launcher-B5MGOPEQ.js +37 -0
  38. package/dist/chunks/launcher-B5MGOPEQ.js.map +7 -0
  39. package/dist/core/define.d.ts +40 -0
  40. package/dist/core/frecency.d.ts +16 -0
  41. package/dist/core/hotkeys.d.ts +39 -0
  42. package/dist/core/labels.d.ts +98 -0
  43. package/dist/core/launcher.d.ts +8 -0
  44. package/dist/core/lazy.d.ts +60 -0
  45. package/dist/core/search.d.ts +42 -0
  46. package/dist/core/storage.d.ts +5 -0
  47. package/dist/core/types.d.ts +737 -0
  48. package/dist/element/index.d.ts +56 -0
  49. package/dist/element.js +146 -0
  50. package/dist/element.js.map +7 -0
  51. package/dist/extensions/index.d.ts +30 -0
  52. package/dist/extensions/math.d.ts +14 -0
  53. package/dist/extensions.js +476 -0
  54. package/dist/extensions.js.map +7 -0
  55. package/dist/index.d.ts +31 -0
  56. package/dist/index.js +85 -0
  57. package/dist/index.js.map +7 -0
  58. package/dist/locales/index.d.ts +24 -0
  59. package/dist/locales.js +810 -0
  60. package/dist/locales.js.map +7 -0
  61. package/dist/qikbar.global.js +302 -0
  62. package/dist/qikbar.global.js.map +7 -0
  63. package/dist/react/index.d.ts +66 -0
  64. package/dist/react.js +121 -0
  65. package/dist/react.js.map +7 -0
  66. package/dist/server/index.d.ts +66 -0
  67. package/dist/server.js +129 -0
  68. package/dist/server.js.map +7 -0
  69. package/dist/solid/index.d.ts +42 -0
  70. package/dist/solid.js +93 -0
  71. package/dist/solid.js.map +7 -0
  72. package/dist/styles.css +253 -0
  73. package/dist/svelte/index.d.ts +58 -0
  74. package/dist/svelte.js +55 -0
  75. package/dist/svelte.js.map +7 -0
  76. package/dist/theme.d.ts +5 -0
  77. package/dist/theme.js +20 -0
  78. package/dist/theme.js.map +7 -0
  79. package/dist/ui/bar.d.ts +338 -0
  80. package/dist/ui/dom.d.ts +21 -0
  81. package/dist/ui/icons.d.ts +93 -0
  82. package/dist/ui/markdown.d.ts +10 -0
  83. package/dist/ui/nav.d.ts +8 -0
  84. package/dist/ui/styles.d.ts +6 -0
  85. package/dist/ui/themes.d.ts +27 -0
  86. package/dist/ui/views.d.ts +156 -0
  87. package/dist/ui/webmcp.d.ts +33 -0
  88. package/dist/utils.d.ts +10 -0
  89. package/dist/utils.js +50 -0
  90. package/dist/utils.js.map +7 -0
  91. package/dist/vue/index.d.ts +74 -0
  92. package/dist/vue.js +122 -0
  93. package/dist/vue.js.map +7 -0
  94. package/package.json +129 -43
  95. package/dist/qikbar.es.js +0 -8748
  96. package/dist/qikbar.umd.js +0 -113
  97. package/dist/types/boot.d.ts +0 -72
  98. package/dist/types/index.d.ts +0 -1
  99. package/dist/types/init.d.ts +0 -2
  100. package/dist/types/main.d.ts +0 -4
  101. package/dist/types/shared/AsyncRoot.d.ts +0 -5
  102. package/dist/types/shared/CommandFooter.d.ts +0 -5
  103. package/dist/types/shared/Crumbs.d.ts +0 -6
  104. package/dist/types/shared/Details.d.ts +0 -3
  105. package/dist/types/shared/ErrorBoundary.d.ts +0 -15
  106. package/dist/types/shared/Icon.d.ts +0 -4
  107. package/dist/types/shared/List.d.ts +0 -30
  108. package/dist/types/shared/Qikbar.d.ts +0 -5
  109. package/dist/types/shared/Root.d.ts +0 -4
  110. package/dist/types/shared/Search.d.ts +0 -1
  111. package/dist/types/shared/commandContext.d.ts +0 -8
  112. package/dist/types/shared/useDebounce.d.ts +0 -1
  113. package/dist/types/utils/liquid.d.ts +0 -4
  114. package/dist/types/vite-env.d.ts +0 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Qikbar contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,121 @@
1
+ <p>
2
+ <img src="https://raw.githubusercontent.com/nearbycoder/qikbar-next/main/assets/logo-wordmark-light.png" width="240" alt="Qikbar">
3
+ </p>
4
+
5
+ # qikbar
6
+
7
+ **The open-source command bar for any web app.** Raycast-style search, routing, actions, extensions and AI in one tiny, themeable package with zero dependencies.
8
+
9
+ 📖 **Docs:** [qikbar.com/docs](https://qikbar.com/docs) · 🤖 **For AI agents:** [qikbar.com/llms-full.txt](https://qikbar.com/llms-full.txt)
10
+
11
+ ```bash
12
+ npm install @qikbar/qikbar
13
+ ```
14
+
15
+ ## Vanilla
16
+
17
+ ```ts
18
+ import { createQikbar, form } from '@qikbar/qikbar'
19
+ import { calculator, themeSwitcher } from '@qikbar/qikbar/extensions'
20
+
21
+ const bar = createQikbar({
22
+ navigate: (href) => router.push(href),
23
+ routes: [
24
+ { path: '/', title: 'Dashboard', icon: 'home' },
25
+ { path: '/settings', title: 'Settings', icon: 'settings' },
26
+ ],
27
+ commands: [
28
+ { title: 'Toggle sidebar', icon: 'layout-dashboard', shortcut: 'mod+b', run: () => toggleSidebar() },
29
+ {
30
+ title: 'Invite teammate',
31
+ icon: 'users',
32
+ view: form({
33
+ title: 'Invite teammate',
34
+ fields: [{ name: 'email', label: 'Email', type: 'email', required: true }],
35
+ onSubmit: async (values, ctx) => {
36
+ await api.invite(values.email)
37
+ ctx.toast({ title: 'Invite sent', style: 'success' })
38
+ },
39
+ }),
40
+ },
41
+ ],
42
+ sources: [
43
+ {
44
+ id: 'projects',
45
+ title: 'Projects',
46
+ search: async ({ query, signal }) =>
47
+ (await fetch(`/api/projects?q=${query}`, { signal }).then((r) => r.json())).map((p) => ({
48
+ title: p.name,
49
+ icon: 'folder',
50
+ href: `/projects/${p.id}`,
51
+ })),
52
+ },
53
+ ],
54
+ extensions: [calculator(), themeSwitcher()],
55
+ theme: 'linear',
56
+ })
57
+ ```
58
+
59
+ ## React
60
+
61
+ ```tsx
62
+ import { Qikbar, useCommands } from '@qikbar/qikbar/react'
63
+
64
+ <Qikbar routes={routes} commands={commands} navigate={(href) => router.push(href)} />
65
+
66
+ // Page-specific commands, anywhere in the tree
67
+ useCommands([{ title: 'Archive project', icon: 'trash', run: archive }], [archive])
68
+ ```
69
+
70
+ ## Vue, Svelte, Solid and web components
71
+
72
+ ```ts
73
+ import { Qikbar, useCommands } from '@qikbar/qikbar/vue' // <Qikbar :config="…" />
74
+ import { qikbarStore } from '@qikbar/qikbar/svelte' // $bar is the state
75
+ import { QikbarProvider, useCommands } from '@qikbar/qikbar/solid'
76
+ import '@qikbar/qikbar/element' // <qik-bar><qik-command href="/settings">Settings</qik-command></qik-bar>
77
+ ```
78
+
79
+ ## Mobile, personalization and more
80
+
81
+ ```ts
82
+ createQikbar({
83
+ launcher: 'touch', // a floating search button on phones
84
+ labels: de, // from '@qikbar/qikbar/locales'
85
+ semantic: { embed: proxyEmbeddings({ url: '/api/embed' }) }, // search by meaning
86
+ webmcp: true, // let browser AI agents use your commands
87
+ onEvent: (e) => posthog.capture(`command_bar_${e.type}`, e), // analytics
88
+ })
89
+ ```
90
+
91
+ Users can pin commands (⌘⇧P) and give them aliases, lists can be `multiSelect` with bulk `runMany` actions, and `ctx.toast({ title, undo })` adds Undo with ⌘Z.
92
+
93
+ ## Extensions from the registry
94
+
95
+ ```bash
96
+ npx @qikbar/qikbar add weather currency
97
+ ```
98
+
99
+ ## AI
100
+
101
+ ```ts
102
+ import { createQikbar, proxy } from '@qikbar/qikbar'
103
+ createQikbar({ routes, commands, ai: proxy('/api/qikbar') })
104
+
105
+ // app/api/qikbar/route.ts
106
+ import { createHandler, anthropic } from '@qikbar/qikbar/server'
107
+ export const POST = createHandler({ provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }) })
108
+ ```
109
+
110
+ Press <kbd>Tab</kbd> in the bar to ask AI. The model can search and run your commands. Providers: `anthropic`, `openai`, `gemini`, `openaiCompatible`, `ollama`, `browserAI`, `proxy`, `byok`. Add MCP servers' tools with `ai: { provider, mcp: [mcp({ url: '/api/mcp' })] }`.
111
+
112
+ ## Script tag
113
+
114
+ ```html
115
+ <script src="https://unpkg.com/@qikbar/qikbar/dist/qikbar.global.js"></script>
116
+ <script>Qikbar.createQikbar({ autoIndex: true })</script>
117
+ ```
118
+
119
+ ## License
120
+
121
+ MIT
package/bin/qikbar.mjs ADDED
@@ -0,0 +1,203 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * qikbar CLI — add extensions from the registry to your project.
4
+ *
5
+ * npx @qikbar/qikbar add weather currency
6
+ * npx @qikbar/qikbar list
7
+ * npx @qikbar/qikbar info weather
8
+ *
9
+ * Extensions are copied into your codebase as source (like shadcn/ui), so you
10
+ * own them: read them, change them, delete what you don't need.
11
+ */
12
+
13
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
14
+ import { dirname, join, relative, resolve } from 'node:path'
15
+ import { fileURLToPath } from 'node:url'
16
+
17
+ const REGISTRY = (process.env.QIKBAR_REGISTRY || 'https://qikbar.com/registry').replace(/\/$/, '')
18
+ const color = process.stdout.isTTY && !process.env.NO_COLOR
19
+ const paint = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : String(s))
20
+ const bold = paint(1)
21
+ const dim = paint(2)
22
+ const green = paint(32)
23
+ const red = paint(31)
24
+ const cyan = paint(36)
25
+
26
+ function version() {
27
+ try {
28
+ const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'))
29
+ return pkg.version
30
+ } catch {
31
+ return 'unknown'
32
+ }
33
+ }
34
+
35
+ function parseArgs(argv) {
36
+ const args = { _: [], flags: {} }
37
+ for (let i = 0; i < argv.length; i++) {
38
+ const a = argv[i]
39
+ if (a === '--') {
40
+ args._.push(...argv.slice(i + 1))
41
+ break
42
+ }
43
+ if (a.startsWith('--')) {
44
+ const [key, inline] = a.slice(2).split('=', 2)
45
+ if (inline !== undefined) args.flags[key] = inline
46
+ else if (['dir', 'registry', 'cwd'].includes(key)) args.flags[key] = argv[++i]
47
+ else args.flags[key] = true
48
+ } else if (a.startsWith('-') && a.length > 1) {
49
+ for (const c of a.slice(1)) args.flags[{ f: 'force', h: 'help', v: 'version', d: 'dir', y: 'yes' }[c] ?? c] = c === 'd' ? argv[++i] : true
50
+ } else args._.push(a)
51
+ }
52
+ return args
53
+ }
54
+
55
+ async function get(path, registry) {
56
+ const url = `${registry}/${path}`
57
+ let res
58
+ try {
59
+ res = await fetch(url, { headers: { 'user-agent': `qikbar-cli/${version()}` } })
60
+ } catch (err) {
61
+ throw new Error(`Couldn't reach ${url} (${err.cause?.code ?? err.message})`)
62
+ }
63
+ if (!res.ok) throw new Error(`${url} responded ${res.status}`)
64
+ return res
65
+ }
66
+
67
+ async function loadIndex(registry) {
68
+ const data = await (await get('index.json', registry)).json()
69
+ if (!data || !Array.isArray(data.extensions)) throw new Error('The registry index is malformed.')
70
+ return data
71
+ }
72
+
73
+ /** Levenshtein distance, for "did you mean". */
74
+ function distance(a, b) {
75
+ const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)])
76
+ for (let j = 1; j <= b.length; j++) dp[0][j] = j
77
+ for (let i = 1; i <= a.length; i++)
78
+ for (let j = 1; j <= b.length; j++) dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
79
+ return dp[a.length][b.length]
80
+ }
81
+
82
+ function suggest(name, names) {
83
+ const best = names.map((n) => [n, distance(name, n)]).sort((x, y) => x[1] - y[1])[0]
84
+ return best && best[1] <= Math.max(2, Math.floor(name.length / 3)) ? best[0] : undefined
85
+ }
86
+
87
+ function defaultDir(cwd) {
88
+ try {
89
+ const cfg = JSON.parse(readFileSync(join(cwd, 'qikbar.json'), 'utf8'))
90
+ if (cfg.extensionsDir) return cfg.extensionsDir
91
+ } catch {
92
+ // no config
93
+ }
94
+ return existsSync(join(cwd, 'src')) ? 'src/qikbar/extensions' : 'qikbar/extensions'
95
+ }
96
+
97
+ function identifier(name) {
98
+ return name.replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase()).replace(/^[^a-zA-Z_$]/, '_$&')
99
+ }
100
+
101
+ function hasPackage(cwd) {
102
+ try {
103
+ const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'))
104
+ return !!({ ...pkg.dependencies, ...pkg.devDependencies }['@qikbar/qikbar'])
105
+ } catch {
106
+ return true // not a node project — don't nag
107
+ }
108
+ }
109
+
110
+ async function cmdList(flags, registry) {
111
+ const index = await loadIndex(registry)
112
+ if (flags.json) return console.log(JSON.stringify(index.extensions, null, 2))
113
+ const width = Math.max(...index.extensions.map((e) => e.name.length))
114
+ console.log(bold(`${index.extensions.length} extensions`) + dim(` ${registry}`))
115
+ for (const e of index.extensions) console.log(` ${cyan(e.name.padEnd(width))} ${e.description ?? e.title}`)
116
+ console.log(dim(`\nAdd one with: npx @qikbar/qikbar add <name>`))
117
+ }
118
+
119
+ async function cmdInfo(names, registry) {
120
+ const index = await loadIndex(registry)
121
+ for (const name of names) {
122
+ const e = index.extensions.find((x) => x.name === name)
123
+ if (!e) throw new Error(`Unknown extension "${name}".`)
124
+ console.log(`${bold(e.title)} ${dim(`(${e.name}${e.version ? `@${e.version}` : ''})`)}`)
125
+ if (e.description) console.log(e.description)
126
+ if (e.author) console.log(dim(`by ${e.author}`))
127
+ if (e.uses) console.log(dim(`Uses: ${e.uses}`))
128
+ if (e.tags?.length) console.log(dim(`Shows off: ${e.tags.join(', ')}`))
129
+ if (e.try) console.log(dim(`Try: “${e.try}”`))
130
+ console.log(dim(`Source: ${registry}/${e.file ?? `${e.name}.ts`}`))
131
+ }
132
+ }
133
+
134
+ async function cmdAdd(names, flags, registry) {
135
+ if (!names.length) throw new Error('Name at least one extension, e.g. `qikbar add weather`. Run `qikbar list` to see them all.')
136
+ const cwd = resolve(flags.cwd ?? process.cwd())
137
+ const dir = resolve(cwd, flags.dir ?? defaultDir(cwd))
138
+ const index = await loadIndex(registry)
139
+ const known = index.extensions.map((e) => e.name)
140
+ const wanted = names.includes('all') ? known : names
141
+ const unknown = wanted.filter((n) => !known.includes(n))
142
+ if (unknown.length) {
143
+ throw new Error(
144
+ unknown.map((n) => `Unknown extension "${n}".${suggest(n, known) ? ` Did you mean "${suggest(n, known)}"?` : ''}`).join('\n') +
145
+ '\nRun `qikbar list` to see them all.',
146
+ )
147
+ }
148
+ mkdirSync(dir, { recursive: true })
149
+ const added = []
150
+ for (const name of wanted) {
151
+ const entry = index.extensions.find((e) => e.name === name)
152
+ const file = join(dir, `${name}.ts`)
153
+ if (existsSync(file) && !flags.force) {
154
+ console.log(`${dim('skip')} ${relative(cwd, file)} ${dim('(exists — use --force to overwrite)')}`)
155
+ continue
156
+ }
157
+ const source = await (await get(entry.file ?? `${name}.ts`, registry)).text()
158
+ writeFileSync(file, source.startsWith('//') ? source : `// ${entry.title} — from ${registry}/${entry.file ?? `${name}.ts`}\n${source}`)
159
+ console.log(`${green('add')} ${relative(cwd, file)}`)
160
+ added.push({ name, file })
161
+ }
162
+ if (!added.length) return
163
+ const rel = relative(cwd, dir).replace(/\\/g, '/')
164
+ const prefix = rel.startsWith('.') ? rel : `./${rel}`
165
+ console.log(`\n${bold('Use it:')}\n`)
166
+ for (const { name } of added) console.log(` ${cyan(`import ${identifier(name)} from '${prefix}/${name}'`)}`)
167
+ console.log(`\n createQikbar({ extensions: [${added.map((a) => identifier(a.name)).join(', ')}] })`)
168
+ if (!hasPackage(cwd)) console.log(`\n${dim('Extensions import from @qikbar/qikbar — install it with')} npm install @qikbar/qikbar`)
169
+ }
170
+
171
+ const HELP = `${bold('qikbar')} ${dim(version())} — add Qikbar extensions to your project
172
+
173
+ ${bold('Usage')}
174
+ npx @qikbar/qikbar add <name...> Copy extensions into your project (or "all")
175
+ npx @qikbar/qikbar list List available extensions
176
+ npx @qikbar/qikbar info <name> Show details about an extension
177
+
178
+ ${bold('Options')}
179
+ -d, --dir <path> Where to put extensions (default: src/qikbar/extensions,
180
+ or "extensionsDir" in qikbar.json)
181
+ -f, --force Overwrite existing files
182
+ --registry <url> Use another registry (or set QIKBAR_REGISTRY)
183
+ --json Machine-readable output for list
184
+ -h, --help Show this help
185
+ -v, --version Show the version
186
+
187
+ ${dim('Registry: https://qikbar.com/extensions')}`
188
+
189
+ async function main() {
190
+ const { _: [command, ...rest], flags } = parseArgs(process.argv.slice(2))
191
+ const registry = (flags.registry ?? REGISTRY).replace(/\/$/, '')
192
+ if (flags.version) return console.log(version())
193
+ if (flags.help || !command || command === 'help') return console.log(HELP)
194
+ if (command === 'add' || command === 'install') return cmdAdd(rest, flags, registry)
195
+ if (command === 'list' || command === 'ls') return cmdList(flags, registry)
196
+ if (command === 'info' || command === 'show') return cmdInfo(rest, registry)
197
+ throw new Error(`Unknown command "${command}". Run \`qikbar --help\`.`)
198
+ }
199
+
200
+ main().catch((err) => {
201
+ console.error(red('error'), err.message)
202
+ process.exit(1)
203
+ })
@@ -0,0 +1,42 @@
1
+ import type { AIClient, AIMessage, AIProvider, AIToolCall, AIToolDefinition } from '../core/types.js';
2
+ /** Create the simple `ask` / `stream` client exposed as `ctx.ai`. */
3
+ export declare function createAIClient(provider: AIProvider, defaultSystem?: string): AIClient;
4
+ export interface RuntimeTool {
5
+ definition: AIToolDefinition;
6
+ /** Human-readable label for the UI ("Opening Billing…"). */
7
+ label?: (args: Record<string, unknown>) => string;
8
+ run: (args: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
9
+ }
10
+ export type AgentEvent = {
11
+ type: 'text';
12
+ text: string;
13
+ } | {
14
+ type: 'tool_start';
15
+ call: AIToolCall;
16
+ label: string;
17
+ } | {
18
+ type: 'tool_end';
19
+ call: AIToolCall;
20
+ ok: boolean;
21
+ result: string;
22
+ } | {
23
+ type: 'message';
24
+ message: AIMessage;
25
+ } | {
26
+ type: 'error';
27
+ error: string;
28
+ };
29
+ export interface RunAgentOptions {
30
+ provider: AIProvider;
31
+ /** Conversation so far (not mutated). */
32
+ messages: AIMessage[];
33
+ system?: string;
34
+ tools?: RuntimeTool[];
35
+ maxSteps?: number;
36
+ signal: AbortSignal;
37
+ }
38
+ /**
39
+ * Run a tool-calling loop: stream the model's answer, execute requested
40
+ * tools, feed results back, repeat until the model stops calling tools.
41
+ */
42
+ export declare function runAgent(options: RunAgentOptions): AsyncIterable<AgentEvent>;
@@ -0,0 +1,29 @@
1
+ import type { AIProvider, Extension, StorageAdapter } from '../core/types.js';
2
+ export type ByokVendor = 'anthropic' | 'openai' | 'gemini' | 'openai-compatible';
3
+ export interface ByokSettings {
4
+ vendor: ByokVendor;
5
+ apiKey: string;
6
+ model?: string;
7
+ baseURL?: string;
8
+ }
9
+ export interface ByokOptions {
10
+ /** Vendors offered in settings. Default: all. */
11
+ vendors?: ByokVendor[];
12
+ /** Storage key. Default `"qikbar:byok"`. */
13
+ key?: string;
14
+ storage?: StorageAdapter;
15
+ }
16
+ /**
17
+ * "Bring your own key": your users paste their own API key, stored only in their
18
+ * browser. Pair with `byok.settings()` so they can configure it from the bar.
19
+ *
20
+ * ```ts
21
+ * createQikbar({ ai: byok(), extensions: [byok.settings()] })
22
+ * ```
23
+ */
24
+ export declare const byok: ((options?: ByokOptions) => AIProvider) & {
25
+ /** An extension with an "AI Settings" command where users enter their own key. */
26
+ settings: typeof settingsExtension;
27
+ };
28
+ declare function settingsExtension(options?: ByokOptions): Extension;
29
+ export {};
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Embedding functions for `semantic` search. Each returns an `embed(texts)`
3
+ * function you pass as `semantic: { embed }`.
4
+ *
5
+ * Calling a provider straight from the browser exposes its key. In production,
6
+ * use `proxyEmbeddings()` with `createEmbeddingsHandler()` from `@qikbar/qikbar/server`.
7
+ */
8
+ import type { SemanticOptions } from '../core/types.js';
9
+ export type Embed = SemanticOptions['embed'];
10
+ export interface OpenAIEmbeddingsOptions {
11
+ apiKey?: string;
12
+ /** Default `"text-embedding-3-small"`. */
13
+ model?: string;
14
+ /** For OpenAI-compatible APIs (Together, Mistral, LM Studio, …). Default `"https://api.openai.com/v1"`. */
15
+ baseURL?: string;
16
+ /** Shorter vectors are faster to compare. Default 256. */
17
+ dimensions?: number | null;
18
+ headers?: Record<string, string>;
19
+ fetch?: typeof fetch;
20
+ }
21
+ /** OpenAI (or any OpenAI-compatible) embeddings. */
22
+ export declare function openaiEmbeddings(options?: OpenAIEmbeddingsOptions): Embed;
23
+ export interface OllamaEmbeddingsOptions {
24
+ /** Default `"nomic-embed-text"`. */
25
+ model?: string;
26
+ /** Default `"http://localhost:11434"`. */
27
+ host?: string;
28
+ fetch?: typeof fetch;
29
+ }
30
+ /** Local embeddings with Ollama. */
31
+ export declare function ollamaEmbeddings(options?: OllamaEmbeddingsOptions): Embed;
32
+ export interface GeminiEmbeddingsOptions {
33
+ apiKey: string;
34
+ /** Default `"gemini-embedding-001"`. */
35
+ model?: string;
36
+ /** Default 256. */
37
+ dimensions?: number;
38
+ fetch?: typeof fetch;
39
+ }
40
+ /** Google Gemini embeddings. */
41
+ export declare function geminiEmbeddings(options: GeminiEmbeddingsOptions): Embed;
42
+ export interface ProxyEmbeddingsOptions {
43
+ /** Your endpoint made with `createEmbeddingsHandler()`. */
44
+ url: string;
45
+ headers?: Record<string, string>;
46
+ fetch?: typeof fetch;
47
+ }
48
+ /** Embeddings through your own server, so API keys never reach the browser. */
49
+ export declare function proxyEmbeddings(options: ProxyEmbeddingsOptions): Embed;
50
+ /** Wrap an embed function with a cache, so repeated texts aren't re-embedded. */
51
+ export declare function cachedEmbeddings(embed: Embed, maxEntries?: number): Embed;
@@ -0,0 +1,12 @@
1
+ export { anthropic, browserAI, gemini, ollama, openai, openaiCompatible, proxy } from './providers.js';
2
+ export type { AnthropicOptions, GeminiOptions, OpenAIOptions, ProxyOptions } from './providers.js';
3
+ export { byok } from './byok.js';
4
+ export type { ByokOptions, ByokSettings, ByokVendor } from './byok.js';
5
+ export { createAIClient, runAgent } from './agent.js';
6
+ export type { AgentEvent, RunAgentOptions, RuntimeTool } from './agent.js';
7
+ export { parseNDJSON, parseSSE } from './sse.js';
8
+ export type { AIClient, AIEvent, AIMessage, AIProvider, AIRequest, AIToolCall, AIToolDefinition } from '../core/types.js';
9
+ export { MCPClient, MCPError, mcp, MCP_PROTOCOL_VERSION } from './mcp.js';
10
+ export type { MCPOptions, MCPToolInfo } from './mcp.js';
11
+ export { cachedEmbeddings, geminiEmbeddings, ollamaEmbeddings, openaiEmbeddings, proxyEmbeddings } from './embeddings.js';
12
+ export type { Embed, GeminiEmbeddingsOptions, OllamaEmbeddingsOptions, OpenAIEmbeddingsOptions, ProxyEmbeddingsOptions } from './embeddings.js';
@@ -0,0 +1,84 @@
1
+ /**
2
+ * A minimal MCP client (Streamable HTTP transport) that turns a remote MCP
3
+ * server's tools into tools the bar's AI can call.
4
+ *
5
+ * ```ts
6
+ * import { mcp } from '@qikbar/qikbar/ai'
7
+ * createQikbar({ ai: { provider, mcp: [mcp({ url: '/api/mcp' })] } })
8
+ * ```
9
+ *
10
+ * Browsers can only reach servers that allow CORS. For third-party servers,
11
+ * proxy them through your backend (which also keeps tokens server-side).
12
+ */
13
+ import type { JSONSchema, ToolProvider } from '../core/types.js';
14
+ export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
15
+ export interface MCPOptions {
16
+ /** The server's Streamable HTTP endpoint. */
17
+ url: string;
18
+ /** Prefix for tool names and the label shown in errors. Default derived from the URL. */
19
+ name?: string;
20
+ /** Extra headers, e.g. `{ Authorization: 'Bearer …' }`. A function is called per request. */
21
+ headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
22
+ /** Only expose these tools (by name). */
23
+ include?: string[];
24
+ /** Hide these tools (by name). */
25
+ exclude?: string[];
26
+ /**
27
+ * Ask the user before running a tool. Default: ask unless the server marks the tool
28
+ * `readOnlyHint: true`. Pass `true`/`false` to always/never ask, or a function per tool.
29
+ */
30
+ confirm?: boolean | ((tool: MCPToolInfo) => boolean);
31
+ /** Re-list tools after this many ms. Default 5 minutes. */
32
+ ttl?: number;
33
+ /** Custom fetch (for tests or proxies). */
34
+ fetch?: typeof fetch;
35
+ /** Send cookies to the server (same-origin proxies). Default `"same-origin"`. */
36
+ credentials?: RequestCredentials;
37
+ }
38
+ export interface MCPToolInfo {
39
+ name: string;
40
+ title?: string;
41
+ description?: string;
42
+ inputSchema?: JSONSchema;
43
+ annotations?: {
44
+ title?: string;
45
+ readOnlyHint?: boolean;
46
+ destructiveHint?: boolean;
47
+ idempotentHint?: boolean;
48
+ openWorldHint?: boolean;
49
+ };
50
+ }
51
+ export declare class MCPError extends Error {
52
+ readonly code?: number | undefined;
53
+ constructor(message: string, code?: number | undefined);
54
+ }
55
+ /** A low-level MCP client. Most apps only need `mcp()`. */
56
+ export declare class MCPClient {
57
+ private options;
58
+ private session?;
59
+ private protocol;
60
+ private ready?;
61
+ private negotiated;
62
+ private nextId;
63
+ serverInfo?: {
64
+ name?: string;
65
+ version?: string;
66
+ };
67
+ constructor(options: MCPOptions);
68
+ private headers;
69
+ private post;
70
+ private request;
71
+ /** Initialize the session (once). */
72
+ connect(signal?: AbortSignal): Promise<void>;
73
+ /** List every tool, following pagination. */
74
+ listTools(signal?: AbortSignal): Promise<MCPToolInfo[]>;
75
+ /** Call a tool and return its result as text for the model. */
76
+ callTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<string>;
77
+ /** End the session (best effort). */
78
+ close(): Promise<void>;
79
+ }
80
+ /** Use an MCP server's tools in the bar's AI chat. */
81
+ export declare function mcp(options: MCPOptions): ToolProvider & {
82
+ client: MCPClient;
83
+ refresh(): void;
84
+ };
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Zero-dependency AI providers. Each one streams text and tool calls through
3
+ * the same `AIProvider` interface, so the bar works with any model.
4
+ *
5
+ * Security: providers that take an `apiKey` call the vendor directly from the
6
+ * browser. That's fine for prototypes, internal tools, and "bring your own key"
7
+ * setups where users paste their own key. For production apps with a shared
8
+ * key, use `proxy()` on the client and `createHandler()` from `@qikbar/qikbar/server`.
9
+ */
10
+ import type { AIProvider } from '../core/types.js';
11
+ export interface AnthropicOptions {
12
+ apiKey?: string;
13
+ /** Default `"claude-opus-5-5"`. Use `"claude-haiku-5-5"` for the lowest latency and cost. */
14
+ model?: string;
15
+ baseURL?: string;
16
+ maxTokens?: number;
17
+ /** Reasoning effort. Default `"low"` — a command bar should feel instant. */
18
+ effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | false;
19
+ /**
20
+ * Server-side refusal fallbacks (Claude API only). When a safety classifier
21
+ * declines a request, the API re-runs it on a fallback model. Default `true`
22
+ * on models that support it.
23
+ */
24
+ fallbacks?: boolean;
25
+ headers?: Record<string, string>;
26
+ /** Custom fetch (e.g. for proxies or tests). */
27
+ fetch?: typeof fetch;
28
+ }
29
+ export declare function anthropic(options?: AnthropicOptions): AIProvider;
30
+ export interface OpenAIOptions {
31
+ apiKey?: string;
32
+ /** Default `"gpt-6-luna"`. */
33
+ model?: string;
34
+ /** Point at any OpenAI-compatible API: Groq, OpenRouter, Together, Mistral, Ollama (`http://localhost:11434/v1`), LM Studio, vLLM… */
35
+ baseURL?: string;
36
+ maxTokens?: number;
37
+ headers?: Record<string, string>;
38
+ /** Some local models don't support tools. Default true. */
39
+ tools?: boolean;
40
+ fetch?: typeof fetch;
41
+ /** Provider id shown in the UI. Default `"openai"`. */
42
+ id?: string;
43
+ }
44
+ export declare function openai(options?: OpenAIOptions): AIProvider;
45
+ /** Any OpenAI-compatible endpoint (Groq, OpenRouter, Together, Mistral, DeepSeek, xAI, Ollama, LM Studio…). */
46
+ export declare function openaiCompatible(options: OpenAIOptions & {
47
+ baseURL: string;
48
+ model: string;
49
+ }): AIProvider;
50
+ /** Local models via Ollama. */
51
+ export declare function ollama(options?: {
52
+ model: string;
53
+ baseURL?: string;
54
+ tools?: boolean;
55
+ }): AIProvider;
56
+ export interface GeminiOptions {
57
+ apiKey?: string;
58
+ /** Default `"gemini-flash-latest"`. */
59
+ model?: string;
60
+ baseURL?: string;
61
+ maxTokens?: number;
62
+ headers?: Record<string, string>;
63
+ fetch?: typeof fetch;
64
+ }
65
+ export declare function gemini(options?: GeminiOptions): AIProvider;
66
+ /**
67
+ * Chrome's built-in on-device model via the Prompt API (`LanguageModel`).
68
+ * Free and private, no API key. No tool calling. Check `browserAI.isAvailable()` first.
69
+ */
70
+ export declare const browserAI: (() => AIProvider) & {
71
+ /** Whether the on-device model can be used in this browser. */
72
+ isAvailable(): Promise<boolean>;
73
+ };
74
+ export interface ProxyOptions {
75
+ /** Your endpoint created with `createHandler()` from `@qikbar/qikbar/server`. */
76
+ url: string;
77
+ headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
78
+ credentials?: RequestCredentials;
79
+ fetch?: typeof fetch;
80
+ }
81
+ /** Stream through your own server so API keys never reach the browser. */
82
+ export declare function proxy(options: ProxyOptions | string): AIProvider;
@@ -0,0 +1,9 @@
1
+ export interface SSEMessage {
2
+ event?: string;
3
+ data: string;
4
+ }
5
+ /** Parse a Server-Sent Events stream. */
6
+ export declare function parseSSE(response: Response): AsyncIterable<SSEMessage>;
7
+ /** Parse a newline-delimited JSON stream. */
8
+ export declare function parseNDJSON<T = unknown>(response: Response): AsyncIterable<T>;
9
+ export declare function errorFromResponse(response: Response, provider: string): Promise<Error>;