@qevrion/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @qevrion/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small, dependency-free TypeScript client for QevrionAI text chat, streaming, and model discovery. ESM, Node.js 20.3+. Keep API keys in your server environment.
+
+## Install
+
+After publication:
+
+```sh
+npm install @qevrion/sdk
+```
+
+```ts
+import { Qevrion } from '@qevrion/sdk';
+
+const client = new Qevrion({ apiKey: process.env.QEVRION_API_KEY! });
+const { data: models } = await client.models.list();
+const model = models[0]?.id;
+if (!model) throw new Error('No models are enabled.');
+
+const result = await client.chat.completions.create({
+  model,
+  messages: [{ role: 'user', content: 'Hello!' }],
+  max_tokens: 256,
+});
+console.log(result.choices[0]?.message.content);
+
+for await (const chunk of client.chat.completions.stream({
+  model,
+  messages: [{ role: 'user', content: 'Tell me a short story.' }],
+})) {
+  process.stdout.write(chunk.choices[0]?.delta.content ?? '');
+}
+```
+
+`create()` returns a JSON completion; `stream()` returns an async iterable of raw chat chunks, including usage-only chunks. Breaking the loop cancels the reader and aborts the HTTP request. A stream ending without `[DONE]` raises `QevrionProtocolError` so interrupted responses are detectable. Cancellation cannot guarantee that the upstream provider stops generating or charging.
+
+Supported input: text `system`, `user`, and `assistant` messages; `max_tokens` (1–4096, default 1024), `temperature` (0–2), and `top_p` (0–1). Model IDs must be enabled in the catalog. Tool calls, images, embeddings, and native JSON schema output are not supported by the current API. Upstream `usage.cost`, when included, is not the final Qevrion account charge.
+
+## Configuration and errors
+
+The default API root is `https://useqevrion.com/v1`. For local development pass `baseURL: 'http://localhost:3000/v1'`. A custom `fetch` can be supplied for testing or transport integration. Redirects are rejected.
+
+All operations accept a second options argument (the first argument for `models.list`) with `signal` and `timeoutMs`. The default deadline is 120 seconds and includes reading the response body or stream. Network failures and aborts propagate from fetch. Automatic retries are disabled because chat requests can incur charges.
+
+```ts
+import { QevrionAPIError } from '@qevrion/sdk';
+
+try {
+  await client.chat.completions.create({ model, messages: [] });
+} catch (error) {
+  if (error instanceof QevrionAPIError) {
+    console.error(error.status, error.type, error.code, error.requestId);
+  } else {
+    throw error;
+  }
+}
+```
+
+API errors include HTTP `status`, provider `type`/`code` when supplied, and the Qevrion request ID when supplied. An error delivered inside an established SSE stream has HTTP status 200; use its type/code to diagnose it. JSON responses have TypeScript declarations; they are not runtime schema validated.
+
+## Genkit
+
+Install the optional peer only if you use the separate Genkit entry point:
+
+```sh
+npm install genkit
+```
+
+```ts
+import { genkit } from 'genkit';
+import { qevrion, qevrionModel } from '@qevrion/sdk/genkit';
+
+const ai = genkit({
+  plugins: [qevrion({ apiKey: process.env.QEVRION_API_KEY! })],
+});
+
+const response = await ai.generate({
+  // Replace with an enabled catalog ID.
+  model: qevrionModel('openai/gpt-4o-mini'),
+  prompt: 'Hello!',
+  config: { maxOutputTokens: 256, temperature: 0 },
+});
+console.log(response.text);
+```
+
+The adapter uses the SDK transport, including its cancellation, deadlines, errors, and disabled retries. It accepts `baseURL`, `timeoutMs`, a custom `fetch`, and a plugin `name` (default `qevrion`). If you change the name, pass the same name as the second argument to `qevrionModel`. It supports `generate` and `generateStream`, advertises text chat capabilities only, and maps `maxOutputTokens`, `temperature`, and `topP` to the API parameters. Unsupported configuration is rejected rather than silently ignored.
+
+## Build and release
+
+From `packages/sdk`:
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+npm pack
+```
+
+Install the generated tarball in another project to try it before publication. The package name is proposed; scope ownership and name availability must be checked by the publisher. Set the intended license before release (currently `UNLICENSED`), then publish with `npm publish --access public` using an account authorized for the `@qevrion` scope. This repository does not publish automatically. Only compiled files and this README are included in the package.

package/dist/genkit.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'genkit';
+import { type QevrionOptions } from './index.js';
+export interface QevrionGenkitOptions extends QevrionOptions {
+    name?: string;
+}
+export declare function qevrion(options: QevrionGenkitOptions): import("genkit/plugin").GenkitPluginV2Instance;
+/** Pass a catalog model ID, including its provider, e.g. openai/gpt-4o-mini. */
+export declare function qevrionModel(modelId: string, pluginName?: string): import("genkit").ModelReference<z.ZodObject<{
+    version: z.ZodOptional<z.ZodUndefined>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    version?: undefined;
+    maxOutputTokens?: number | undefined;
+    temperature?: number | undefined;
+    topP?: number | undefined;
+}, {
+    version?: undefined;
+    maxOutputTokens?: number | undefined;
+    temperature?: number | undefined;
+    topP?: number | undefined;
+}>>;

package/dist/genkit.js

@@ -0,0 +1,110 @@
+import { modelRef, z } from 'genkit';
+import { genkitPluginV2, model } from 'genkit/plugin';
+import { Qevrion } from './index.js';
+const configSchema = z
+    .object({
+    // Genkit injects this field even when no model version was requested.
+    version: z.undefined().optional(),
+    maxOutputTokens: z.number().int().min(1).max(4096).optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    topP: z.number().min(0).max(1).optional(),
+})
+    .strict();
+const supports = {
+    multiturn: true,
+    tools: false,
+    media: false,
+    systemRole: true,
+    output: ['text'],
+};
+function usage(value) {
+    return value
+        ? {
+            inputTokens: value.prompt_tokens,
+            outputTokens: value.completion_tokens,
+            totalTokens: value.total_tokens,
+        }
+        : undefined;
+}
+function finishReason(value) {
+    if (value === 'stop' || value === 'length')
+        return value;
+    return value === 'content_filter' ? 'blocked' : 'other';
+}
+export function qevrion(options) {
+    const client = new Qevrion(options);
+    const name = options.name ?? 'qevrion';
+    return genkitPluginV2({
+        name,
+        async resolve(actionType, actionName) {
+            if (actionType !== 'model')
+                return undefined;
+            const id = actionName.startsWith(`${name}/`) ? actionName.slice(name.length + 1) : actionName;
+            return model({ name: `${name}/${id}`, supports, configSchema }, async (request, context) => {
+                const config = configSchema.parse(request.config ?? {});
+                if (request.tools?.length || (request.output?.format && request.output.format !== 'text')) {
+                    throw new TypeError('Qevrion supports text chat only.');
+                }
+                const params = {
+                    model: id,
+                    messages: request.messages.map((message) => {
+                        if (!['user', 'model', 'system'].includes(message.role) ||
+                            message.content.some((part) => typeof part.text !== 'string')) {
+                            throw new TypeError('Qevrion supports text system, user, and assistant messages only.');
+                        }
+                        return {
+                            role: message.role === 'model' ? 'assistant' : message.role,
+                            content: message.content.map((part) => part.text).join(''),
+                        };
+                    }),
+                    max_tokens: config.maxOutputTokens,
+                    temperature: config.temperature,
+                    top_p: config.topP,
+                };
+                const requestOptions = { signal: context.abortSignal };
+                if (!context.streamingRequested) {
+                    const result = await client.chat.completions.create(params, requestOptions);
+                    const choice = result.choices[0];
+                    if (!choice)
+                        throw new Error('Qevrion returned no completion choices.');
+                    return {
+                        message: { role: 'model', content: [{ text: choice.message.content ?? '' }] },
+                        finishReason: finishReason(choice.finish_reason),
+                        usage: usage(result.usage),
+                        raw: result,
+                    };
+                }
+                let text = '';
+                let reason = null;
+                let finalUsage;
+                for await (const chunk of client.chat.completions.stream(params, requestOptions)) {
+                    if (chunk.usage)
+                        finalUsage = chunk.usage;
+                    const choice = chunk.choices.find((item) => item.index === 0);
+                    if (!choice)
+                        continue;
+                    if (choice.finish_reason)
+                        reason = choice.finish_reason;
+                    if (choice.delta.content) {
+                        text += choice.delta.content;
+                        await context.sendChunk({ index: 0, content: [{ text: choice.delta.content }] });
+                    }
+                }
+                return {
+                    message: { role: 'model', content: [{ text }] },
+                    finishReason: finishReason(reason),
+                    usage: usage(finalUsage),
+                };
+            });
+        },
+    });
+}
+/** Pass a catalog model ID, including its provider, e.g. openai/gpt-4o-mini. */
+export function qevrionModel(modelId, pluginName = 'qevrion') {
+    return modelRef({
+        name: `${pluginName}/${modelId}`,
+        configSchema,
+        info: { label: modelId, supports },
+    });
+}
+//# sourceMappingURL=genkit.js.map

package/dist/genkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genkit.js","sourceRoot":"","sources":["../src/genkit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,OAAO,EAAoD,MAAM,YAAY,CAAC;AAMvF,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,sEAAsE;IACtE,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE;IACjC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAC7D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,QAAQ,GAAG;IACf,SAAS,EAAE,IAAI;IACf,KAAK,EAAE,KAAK;IACZ,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,CAAC,MAAe,CAAC;CAC1B,CAAC;AAEF,SAAS,KAAK,CAAC,KAAoB;IACjC,OAAO,KAAK;QACV,CAAC,CAAC;YACE,WAAW,EAAE,KAAK,CAAC,aAAa;YAChC,YAAY,EAAE,KAAK,CAAC,iBAAiB;YACrC,WAAW,EAAE,KAAK,CAAC,YAAY;SAChC;QACH,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CAAC,KAAoB;IACxC,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACzD,OAAO,KAAK,KAAK,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAA6B;IACnD,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC;IACvC,OAAO,cAAc,CAAC;QACpB,IAAI;QACJ,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU;YAClC,IAAI,UAAU,KAAK,OAAO;gBAAE,OAAO,SAAS,CAAC;YAC7C,MAAM,EAAE,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;YAC9F,OAAO,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE;gBACzF,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;gBACxD,IAAI,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;oBAC1F,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;gBAC1D,CAAC;gBACD,MAAM,MAAM,GAAe;oBACzB,KAAK,EAAE,EAAE;oBACT,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;wBACzC,IACE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;4BACnD,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,EAC7D,CAAC;4BACD,MAAM,IAAI,SAAS,CACjB,kEAAkE,CACnE,CAAC;wBACJ,CAAC;wBACD,OAAO;4BACL,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,OAAO,CAAC,IAA0B;4BAClF,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;yBAC3D,CAAC;oBACJ,CAAC,CAAC;oBACF,UAAU,EAAE,MAAM,CAAC,eAAe;oBAClC,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC/B,KAAK,EAAE,MAAM,CAAC,IAAI;iBACnB,CAAC;gBACF,MAAM,cAAc,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;gBACvD,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;oBAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;oBAC5E,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;oBACjC,IAAI,CAAC,MAAM;wBAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;oBACxE,OAAO;wBACL,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,EAAE;wBAC7E,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC;wBAChD,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC;wBAC1B,GAAG,EAAE,MAAM;qBACZ,CAAC;gBACJ,CAAC;gBACD,IAAI,IAAI,GAAG,EAAE,CAAC;gBACd,IAAI,MAAM,GAAkB,IAAI,CAAC;gBACjC,IAAI,UAAoC,CAAC;gBACzC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC;oBACjF,IAAI,KAAK,CAAC,KAAK;wBAAE,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC;oBAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;oBAC9D,IAAI,CAAC,MAAM;wBAAE,SAAS;oBACtB,IAAI,MAAM,CAAC,aAAa;wBAAE,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC;oBACxD,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;wBACzB,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;wBAC7B,MAAM,OAAO,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;oBACnF,CAAC;gBACH,CAAC;gBACD,OAAO;oBACL,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;oBAC/C,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC;oBAClC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC;iBACzB,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,UAAU,GAAG,SAAS;IAClE,OAAO,QAAQ,CAAC;QACd,IAAI,EAAE,GAAG,UAAU,IAAI,OAAO,EAAE;QAChC,YAAY;QACZ,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE;KACnC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { modelRef, z } from 'genkit';\nimport { genkitPluginV2, model } from 'genkit/plugin';\nimport { Qevrion, type ChatParams, type QevrionOptions, type Usage } from './index.js';\n\nexport interface QevrionGenkitOptions extends QevrionOptions {\n  name?: string;\n}\n\nconst configSchema = z\n  .object({\n    // Genkit injects this field even when no model version was requested.\n    version: z.undefined().optional(),\n    maxOutputTokens: z.number().int().min(1).max(4096).optional(),\n    temperature: z.number().min(0).max(2).optional(),\n    topP: z.number().min(0).max(1).optional(),\n  })\n  .strict();\n\nconst supports = {\n  multiturn: true,\n  tools: false,\n  media: false,\n  systemRole: true,\n  output: ['text' as const],\n};\n\nfunction usage(value?: Usage | null) {\n  return value\n    ? {\n        inputTokens: value.prompt_tokens,\n        outputTokens: value.completion_tokens,\n        totalTokens: value.total_tokens,\n      }\n    : undefined;\n}\n\nfunction finishReason(value: string | null): 'stop' | 'length' | 'blocked' | 'other' {\n  if (value === 'stop' || value === 'length') return value;\n  return value === 'content_filter' ? 'blocked' : 'other';\n}\n\nexport function qevrion(options: QevrionGenkitOptions) {\n  const client = new Qevrion(options);\n  const name = options.name ?? 'qevrion';\n  return genkitPluginV2({\n    name,\n    async resolve(actionType, actionName) {\n      if (actionType !== 'model') return undefined;\n      const id = actionName.startsWith(`${name}/`) ? actionName.slice(name.length + 1) : actionName;\n      return model({ name: `${name}/${id}`, supports, configSchema }, async (request, context) => {\n        const config = configSchema.parse(request.config ?? {});\n        if (request.tools?.length || (request.output?.format && request.output.format !== 'text')) {\n          throw new TypeError('Qevrion supports text chat only.');\n        }\n        const params: ChatParams = {\n          model: id,\n          messages: request.messages.map((message) => {\n            if (\n              !['user', 'model', 'system'].includes(message.role) ||\n              message.content.some((part) => typeof part.text !== 'string')\n            ) {\n              throw new TypeError(\n                'Qevrion supports text system, user, and assistant messages only.',\n              );\n            }\n            return {\n              role: message.role === 'model' ? 'assistant' : (message.role as 'system' | 'user'),\n              content: message.content.map((part) => part.text).join(''),\n            };\n          }),\n          max_tokens: config.maxOutputTokens,\n          temperature: config.temperature,\n          top_p: config.topP,\n        };\n        const requestOptions = { signal: context.abortSignal };\n        if (!context.streamingRequested) {\n          const result = await client.chat.completions.create(params, requestOptions);\n          const choice = result.choices[0];\n          if (!choice) throw new Error('Qevrion returned no completion choices.');\n          return {\n            message: { role: 'model', content: [{ text: choice.message.content ?? '' }] },\n            finishReason: finishReason(choice.finish_reason),\n            usage: usage(result.usage),\n            raw: result,\n          };\n        }\n        let text = '';\n        let reason: string | null = null;\n        let finalUsage: Usage | null | undefined;\n        for await (const chunk of client.chat.completions.stream(params, requestOptions)) {\n          if (chunk.usage) finalUsage = chunk.usage;\n          const choice = chunk.choices.find((item) => item.index === 0);\n          if (!choice) continue;\n          if (choice.finish_reason) reason = choice.finish_reason;\n          if (choice.delta.content) {\n            text += choice.delta.content;\n            await context.sendChunk({ index: 0, content: [{ text: choice.delta.content }] });\n          }\n        }\n        return {\n          message: { role: 'model', content: [{ text }] },\n          finishReason: finishReason(reason),\n          usage: usage(finalUsage),\n        };\n      });\n    },\n  });\n}\n\n/** Pass a catalog model ID, including its provider, e.g. openai/gpt-4o-mini. */\nexport function qevrionModel(modelId: string, pluginName = 'qevrion') {\n  return modelRef({\n    name: `${pluginName}/${modelId}`,\n    configSchema,\n    info: { label: modelId, supports },\n  });\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { ChatChunk, ChatCompletion, ChatParams, ModelList, QevrionOptions, RequestOptions } from './types.js';
+export type * from './types.js';
+export declare const DEFAULT_BASE_URL = "https://useqevrion.com/v1";
+export declare class QevrionAPIError extends Error {
+    readonly status: number;
+    readonly type?: string;
+    readonly code?: string;
+    readonly requestId?: string;
+    constructor(message: string, status: number, details?: {
+        type?: string;
+        code?: string;
+        requestId?: string;
+    });
+}
+export declare class QevrionProtocolError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function normalizeBaseURL(value?: string): string;
+export declare function validateApiKey(apiKey: string): void;
+/** Server-side ESM client. Requests are never automatically retried. */
+export declare class Qevrion {
+    #private;
+    constructor(options: QevrionOptions);
+    readonly models: {
+        list: (options?: RequestOptions) => Promise<ModelList>;
+    };
+    readonly chat: {
+        completions: {
+            create: (params: ChatParams, options?: RequestOptions) => Promise<ChatCompletion>;
+            stream: (params: ChatParams, options?: RequestOptions) => AsyncGenerator<ChatChunk>;
+        };
+    };
+}

package/dist/index.js

@@ -0,0 +1,192 @@
+export const DEFAULT_BASE_URL = 'https://useqevrion.com/v1';
+export class QevrionAPIError extends Error {
+    status;
+    type;
+    code;
+    requestId;
+    constructor(message, status, details = {}) {
+        super(message);
+        this.name = 'QevrionAPIError';
+        this.status = status;
+        this.type = details.type;
+        this.code = details.code;
+        this.requestId = details.requestId;
+    }
+}
+export class QevrionProtocolError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'QevrionProtocolError';
+    }
+}
+export function normalizeBaseURL(value = DEFAULT_BASE_URL) {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new TypeError('baseURL must be an HTTP(S) API root without credentials, query, or fragment.');
+    }
+    return url.href.replace(/\/+$/, '');
+}
+export function validateApiKey(apiKey) {
+    if (typeof apiKey !== 'string' || !/^qv_[a-zA-Z0-9_-]+$/.test(apiKey)) {
+        throw new TypeError('A Qevrion API key beginning with qv_ is required.');
+    }
+}
+function validateTimeout(timeout) {
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
+        throw new TypeError('timeoutMs must be a positive integer no greater than 2147483647.');
+    }
+}
+function apiError(body, response) {
+    const error = body
+        ?.error;
+    return new QevrionAPIError(typeof error?.message === 'string'
+        ? error.message
+        : `Qevrion request failed (${response.status}).`, response.status, {
+        type: typeof error?.type === 'string' ? error.type : undefined,
+        code: typeof error?.code === 'string' ? error.code : undefined,
+        requestId: response.headers.get('x-qevrionai-request-id') ?? undefined,
+    });
+}
+/** Server-side ESM client. Requests are never automatically retried. */
+export class Qevrion {
+    #apiKey;
+    #baseURL;
+    #timeoutMs;
+    #fetch;
+    constructor(options) {
+        validateApiKey(options.apiKey);
+        this.#apiKey = options.apiKey;
+        this.#baseURL = normalizeBaseURL(options.baseURL);
+        this.#timeoutMs = options.timeoutMs ?? 120_000;
+        validateTimeout(this.#timeoutMs);
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    models = {
+        list: (options) => this.#json('/models', undefined, options),
+    };
+    chat = {
+        completions: {
+            create: (params, options) => this.#json('/chat/completions', { ...params, stream: false }, options),
+            stream: (params, options) => this.#stream(params, options),
+        },
+    };
+    async #request(path, body, options = {}) {
+        const timeout = options.timeoutMs ?? this.#timeoutMs;
+        validateTimeout(timeout);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new DOMException('Qevrion request timed out.', 'TimeoutError')), timeout);
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, controller.signal])
+            : controller.signal;
+        try {
+            const response = await this.#fetch(`${this.#baseURL}${path}`, {
+                method: body === undefined ? 'GET' : 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.#apiKey}`,
+                    ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal,
+                redirect: 'error',
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    /* Proxy errors can be HTML. */
+                }
+                throw apiError(parsed, response);
+            }
+            return {
+                response,
+                dispose: () => {
+                    clearTimeout(timer);
+                    controller.abort();
+                },
+            };
+        }
+        catch (error) {
+            clearTimeout(timer);
+            controller.abort();
+            throw error;
+        }
+    }
+    async #json(path, body, options) {
+        const { response, dispose } = await this.#request(path, body, options);
+        try {
+            const text = await response.text();
+            try {
+                return JSON.parse(text);
+            }
+            catch (cause) {
+                throw new QevrionProtocolError('Qevrion returned invalid JSON.', { cause });
+            }
+        }
+        finally {
+            dispose();
+        }
+    }
+    async *#stream(params, options) {
+        const { response, dispose } = await this.#request('/chat/completions', { ...params, stream: true }, options);
+        let reader;
+        try {
+            if (!response.headers.get('content-type')?.toLowerCase().startsWith('text/event-stream') ||
+                !response.body) {
+                throw new QevrionProtocolError('Expected a text/event-stream response.');
+            }
+            reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            while (true) {
+                const { value, done } = await reader.read();
+                buffer += decoder.decode(value, { stream: !done });
+                let boundary;
+                while ((boundary = /\r?\n\r?\n/.exec(buffer)) !== null || (done && buffer.length > 0)) {
+                    const frame = boundary ? buffer.slice(0, boundary.index) : buffer;
+                    buffer = boundary ? buffer.slice(boundary.index + boundary[0].length) : '';
+                    const data = frame
+                        .split(/\r?\n/)
+                        .filter((line) => line.startsWith('data:'))
+                        .map((line) => line.slice(5).replace(/^ /, ''))
+                        .join('\n');
+                    if (!data)
+                        continue;
+                    if (data.trim() === '[DONE]')
+                        return;
+                    let chunk;
+                    try {
+                        chunk = JSON.parse(data);
+                    }
+                    catch (cause) {
+                        throw new QevrionProtocolError('Invalid JSON in Qevrion stream.', { cause });
+                    }
+                    if (chunk && typeof chunk === 'object' && 'error' in chunk)
+                        throw apiError(chunk, response);
+                    yield chunk;
+                }
+                if (done)
+                    throw new QevrionProtocolError('Qevrion stream ended before [DONE].');
+            }
+        }
+        finally {
+            dispose();
+            if (reader) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    /* An aborted reader may already be closed. */
+                }
+                reader.releaseLock();
+            }
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ChatChunk,\n  ChatCompletion,\n  ChatParams,\n  ModelList,\n  QevrionOptions,\n  RequestOptions,\n} from './types.js';\nexport type * from './types.js';\n\nexport const DEFAULT_BASE_URL = 'https://useqevrion.com/v1';\n\nexport class QevrionAPIError extends Error {\n  readonly status: number;\n  readonly type?: string;\n  readonly code?: string;\n  readonly requestId?: string;\n\n  constructor(\n    message: string,\n    status: number,\n    details: {\n      type?: string;\n      code?: string;\n      requestId?: string;\n    } = {},\n  ) {\n    super(message);\n    this.name = 'QevrionAPIError';\n    this.status = status;\n    this.type = details.type;\n    this.code = details.code;\n    this.requestId = details.requestId;\n  }\n}\n\nexport class QevrionProtocolError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'QevrionProtocolError';\n  }\n}\n\nexport function normalizeBaseURL(value: string = DEFAULT_BASE_URL): string {\n  const url = new URL(value);\n  if (\n    !['http:', 'https:'].includes(url.protocol) ||\n    url.username ||\n    url.password ||\n    url.search ||\n    url.hash\n  ) {\n    throw new TypeError(\n      'baseURL must be an HTTP(S) API root without credentials, query, or fragment.',\n    );\n  }\n  return url.href.replace(/\\/+$/, '');\n}\n\nexport function validateApiKey(apiKey: string): void {\n  if (typeof apiKey !== 'string' || !/^qv_[a-zA-Z0-9_-]+$/.test(apiKey)) {\n    throw new TypeError('A Qevrion API key beginning with qv_ is required.');\n  }\n}\n\nfunction validateTimeout(timeout: number): void {\n  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {\n    throw new TypeError('timeoutMs must be a positive integer no greater than 2147483647.');\n  }\n}\n\nfunction apiError(body: unknown, response: Response): QevrionAPIError {\n  const error = (body as { error?: { message?: unknown; type?: unknown; code?: unknown } } | null)\n    ?.error;\n  return new QevrionAPIError(\n    typeof error?.message === 'string'\n      ? error.message\n      : `Qevrion request failed (${response.status}).`,\n    response.status,\n    {\n      type: typeof error?.type === 'string' ? error.type : undefined,\n      code: typeof error?.code === 'string' ? error.code : undefined,\n      requestId: response.headers.get('x-qevrionai-request-id') ?? undefined,\n    },\n  );\n}\n\n/** Server-side ESM client. Requests are never automatically retried. */\nexport class Qevrion {\n  readonly #apiKey: string;\n  readonly #baseURL: string;\n  readonly #timeoutMs: number;\n  readonly #fetch: typeof globalThis.fetch;\n\n  constructor(options: QevrionOptions) {\n    validateApiKey(options.apiKey);\n    this.#apiKey = options.apiKey;\n    this.#baseURL = normalizeBaseURL(options.baseURL);\n    this.#timeoutMs = options.timeoutMs ?? 120_000;\n    validateTimeout(this.#timeoutMs);\n    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  readonly models = {\n    list: (options?: RequestOptions): Promise<ModelList> =>\n      this.#json('/models', undefined, options),\n  };\n\n  readonly chat = {\n    completions: {\n      create: (params: ChatParams, options?: RequestOptions): Promise<ChatCompletion> =>\n        this.#json('/chat/completions', { ...params, stream: false }, options),\n      stream: (params: ChatParams, options?: RequestOptions): AsyncGenerator<ChatChunk> =>\n        this.#stream(params, options),\n    },\n  };\n\n  async #request(path: string, body: unknown, options: RequestOptions = {}) {\n    const timeout = options.timeoutMs ?? this.#timeoutMs;\n    validateTimeout(timeout);\n    const controller = new AbortController();\n    const timer = setTimeout(\n      () => controller.abort(new DOMException('Qevrion request timed out.', 'TimeoutError')),\n      timeout,\n    );\n    const signal = options.signal\n      ? AbortSignal.any([options.signal, controller.signal])\n      : controller.signal;\n    try {\n      const response = await this.#fetch(`${this.#baseURL}${path}`, {\n        method: body === undefined ? 'GET' : 'POST',\n        headers: {\n          Authorization: `Bearer ${this.#apiKey}`,\n          ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),\n        },\n        body: body === undefined ? undefined : JSON.stringify(body),\n        signal,\n        redirect: 'error',\n      });\n      if (!response.ok) {\n        const text = await response.text();\n        let parsed: unknown;\n        try {\n          parsed = JSON.parse(text);\n        } catch {\n          /* Proxy errors can be HTML. */\n        }\n        throw apiError(parsed, response);\n      }\n      return {\n        response,\n        dispose: () => {\n          clearTimeout(timer);\n          controller.abort();\n        },\n      };\n    } catch (error) {\n      clearTimeout(timer);\n      controller.abort();\n      throw error;\n    }\n  }\n\n  async #json<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T> {\n    const { response, dispose } = await this.#request(path, body, options);\n    try {\n      const text = await response.text();\n      try {\n        return JSON.parse(text) as T;\n      } catch (cause) {\n        throw new QevrionProtocolError('Qevrion returned invalid JSON.', { cause });\n      }\n    } finally {\n      dispose();\n    }\n  }\n\n  async *#stream(params: ChatParams, options?: RequestOptions): AsyncGenerator<ChatChunk> {\n    const { response, dispose } = await this.#request(\n      '/chat/completions',\n      { ...params, stream: true },\n      options,\n    );\n    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;\n    try {\n      if (\n        !response.headers.get('content-type')?.toLowerCase().startsWith('text/event-stream') ||\n        !response.body\n      ) {\n        throw new QevrionProtocolError('Expected a text/event-stream response.');\n      }\n      reader = response.body.getReader();\n      const decoder = new TextDecoder();\n      let buffer = '';\n      while (true) {\n        const { value, done } = await reader.read();\n        buffer += decoder.decode(value, { stream: !done });\n        let boundary: RegExpExecArray | null;\n        while ((boundary = /\\r?\\n\\r?\\n/.exec(buffer)) !== null || (done && buffer.length > 0)) {\n          const frame = boundary ? buffer.slice(0, boundary.index) : buffer;\n          buffer = boundary ? buffer.slice(boundary.index + boundary[0].length) : '';\n          const data = frame\n            .split(/\\r?\\n/)\n            .filter((line) => line.startsWith('data:'))\n            .map((line) => line.slice(5).replace(/^ /, ''))\n            .join('\\n');\n          if (!data) continue;\n          if (data.trim() === '[DONE]') return;\n          let chunk: ChatChunk;\n          try {\n            chunk = JSON.parse(data) as ChatChunk;\n          } catch (cause) {\n            throw new QevrionProtocolError('Invalid JSON in Qevrion stream.', { cause });\n          }\n          if (chunk && typeof chunk === 'object' && 'error' in chunk)\n            throw apiError(chunk, response);\n          yield chunk;\n        }\n        if (done) throw new QevrionProtocolError('Qevrion stream ended before [DONE].');\n      }\n    } finally {\n      dispose();\n      if (reader) {\n        try {\n          await reader.cancel();\n        } catch {\n          /* An aborted reader may already be closed. */\n        }\n        reader.releaseLock();\n      }\n    }\n  }\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+export interface Message {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface ChatParams {
+    model: string;
+    messages: Message[];
+    /** Between 1 and 4096. Server default: 1024. */
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+}
+export interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    /** Upstream cost, when present; not the final Qevrion account charge. */
+    cost?: number;
+}
+export interface ChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: 'assistant';
+            content: string | null;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: Usage;
+}
+export interface ChatChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: 'assistant';
+            content?: string | null;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: Usage | null;
+}
+export interface Model {
+    id: string;
+    object: 'model';
+    owned_by: string;
+    name: string;
+    context_length: number;
+}
+export interface ModelList {
+    object: 'list';
+    data: Model[];
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    /** Deadline for the entire request, including stream consumption. */
+    timeoutMs?: number;
+}
+export interface QevrionOptions {
+    apiKey: string;
+    /** API root including /v1. */
+    baseURL?: string;
+    /** Default: 120000 milliseconds. */
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["export interface Message {\n  role: 'system' | 'user' | 'assistant';\n  content: string;\n}\n\nexport interface ChatParams {\n  model: string;\n  messages: Message[];\n  /** Between 1 and 4096. Server default: 1024. */\n  max_tokens?: number;\n  temperature?: number;\n  top_p?: number;\n}\n\nexport interface Usage {\n  prompt_tokens: number;\n  completion_tokens: number;\n  total_tokens: number;\n  /** Upstream cost, when present; not the final Qevrion account charge. */\n  cost?: number;\n}\n\nexport interface ChatCompletion {\n  id: string;\n  object: 'chat.completion';\n  created: number;\n  model: string;\n  choices: Array<{\n    index: number;\n    message: { role: 'assistant'; content: string | null };\n    finish_reason: string | null;\n  }>;\n  usage?: Usage;\n}\n\nexport interface ChatChunk {\n  id: string;\n  object: 'chat.completion.chunk';\n  created: number;\n  model: string;\n  choices: Array<{\n    index: number;\n    delta: { role?: 'assistant'; content?: string | null };\n    finish_reason: string | null;\n  }>;\n  usage?: Usage | null;\n}\n\nexport interface Model {\n  id: string;\n  object: 'model';\n  owned_by: string;\n  name: string;\n  context_length: number;\n}\n\nexport interface ModelList {\n  object: 'list';\n  data: Model[];\n}\n\nexport interface RequestOptions {\n  signal?: AbortSignal;\n  /** Deadline for the entire request, including stream consumption. */\n  timeoutMs?: number;\n}\n\nexport interface QevrionOptions {\n  apiKey: string;\n  /** API root including /v1. */\n  baseURL?: string;\n  /** Default: 120000 milliseconds. */\n  timeoutMs?: number;\n  fetch?: typeof globalThis.fetch;\n}\n"]}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@qevrion/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Small TypeScript client for QevrionAI with optional Genkit integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./genkit": {
+      "types": "./dist/genkit.d.ts",
+      "import": "./dist/genkit.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.3"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ultimaterichy/useqevrion.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "peerDependencies": {
+    "genkit": "^1.42.0"
+  },
+  "peerDependenciesMeta": {
+    "genkit": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "genkit": "^1.42.0",
+    "typescript": "^5.9.3"
+  }
+}