@moxxy/plugin-provider-openai 0.1.0

package/src/translate.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineTool } from '@moxxy/sdk';
+import { toOpenAIMessages, toOpenAITools } from './translate.js';
+
+describe('toOpenAIMessages', () => {
+  it('flattens text into role+content', () => {
+    const out = toOpenAIMessages([
+      { role: 'system', content: [{ type: 'text', text: 'be terse' }] },
+      { role: 'user', content: [{ type: 'text', text: 'hi' }] },
+    ]);
+    expect(out).toEqual([
+      { role: 'system', content: 'be terse' },
+      { role: 'user', content: 'hi' },
+    ]);
+  });
+
+  it('translates assistant tool_use into tool_calls', () => {
+    const out = toOpenAIMessages([
+      {
+        role: 'assistant',
+        content: [{ type: 'tool_use', id: 'c1', name: 'Read', input: { path: '/a' } }],
+      },
+    ]);
+    expect(out[0].role).toBe('assistant');
+    expect(out[0].content).toBeNull();
+    expect(out[0].tool_calls).toEqual([
+      { id: 'c1', type: 'function', function: { name: 'Read', arguments: '{"path":"/a"}' } },
+    ]);
+  });
+
+  it('translates tool_result into role: tool messages', () => {
+    const out = toOpenAIMessages([
+      {
+        role: 'tool_result',
+        content: [{ type: 'tool_result', toolUseId: 'c1', content: 'ok', isError: false }],
+      },
+    ]);
+    expect(out).toEqual([{ role: 'tool', tool_call_id: 'c1', content: 'ok' }]);
+  });
+
+  it('emits a content parts array when a user message has an image', () => {
+    const out = toOpenAIMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this?' },
+          { type: 'image', mediaType: 'image/png', data: 'AAAA' },
+        ],
+      },
+    ]);
+    expect(out).toEqual([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'what is this?' },
+          { type: 'image_url', image_url: { url: 'data:image/png;base64,AAAA' } },
+        ],
+      },
+    ]);
+  });
+
+  it('emits a file content part when a user message has a document', () => {
+    const out = toOpenAIMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'summarize this' },
+          { type: 'document', mediaType: 'application/pdf', data: 'JVBERi0=', name: 'report.pdf' },
+        ],
+      },
+    ]);
+    expect(out).toEqual([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'summarize this' },
+          {
+            type: 'file',
+            file: { filename: 'report.pdf', file_data: 'data:application/pdf;base64,JVBERi0=' },
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('keeps user content as plain text when no images are present', () => {
+    const out = toOpenAIMessages([
+      { role: 'user', content: [{ type: 'text', text: 'hello' }, { type: 'text', text: 'world' }] },
+    ]);
+    expect(out[0].content).toBe('hello\nworld');
+  });
+
+  it('handles assistant with both text and tool_calls', () => {
+    const out = toOpenAIMessages([
+      {
+        role: 'assistant',
+        content: [
+          { type: 'text', text: 'let me check' },
+          { type: 'tool_use', id: 'c1', name: 'Read', input: {} },
+        ],
+      },
+    ]);
+    expect(out[0].content).toBe('let me check');
+    expect(out[0].tool_calls).toHaveLength(1);
+  });
+});
+
+describe('toOpenAITools', () => {
+  it('wraps each tool in { type: function, function: { ... } }', () => {
+    const tool = defineTool({
+      name: 'Read',
+      description: 'read file',
+      inputSchema: z.object({ path: z.string() }),
+      handler: () => null,
+    });
+    const out = toOpenAITools([tool]);
+    expect(out[0].type).toBe('function');
+    expect(out[0].function.name).toBe('Read');
+    expect(out[0].function.description).toBe('read file');
+    expect((out[0].function.parameters as { type: string }).type).toBe('object');
+  });
+
+  it('prefers inputJsonSchema when present', () => {
+    const tool = defineTool({
+      name: 'X',
+      description: 'x',
+      inputSchema: z.any(),
+      inputJsonSchema: { type: 'object', properties: { custom: { type: 'integer' } } },
+      handler: () => null,
+    });
+    const out = toOpenAITools([tool]);
+    expect((out[0].function.parameters as { properties: { custom: unknown } }).properties.custom).toEqual({
+      type: 'integer',
+    });
+  });
+});

package/src/translate.ts

@@ -0,0 +1,120 @@
+import type { ProviderMessage, ToolDef } from '@moxxy/sdk';
+import { zodToJsonSchema } from '@moxxy/sdk';
+
+export type OpenAIUserContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string } }
+  | { type: 'file'; file: { filename?: string; file_data: string } };
+
+export interface OpenAIChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content?: string | ReadonlyArray<OpenAIUserContentPart> | null;
+  tool_calls?: Array<{
+    id: string;
+    type: 'function';
+    function: { name: string; arguments: string };
+  }>;
+  tool_call_id?: string;
+  name?: string;
+}
+
+export interface OpenAIToolDef {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: unknown;
+  };
+}
+
+export function toOpenAIMessages(messages: ReadonlyArray<ProviderMessage>): OpenAIChatMessage[] {
+  const out: OpenAIChatMessage[] = [];
+  for (const msg of messages) {
+    if (msg.role === 'system') {
+      const text = msg.content.find((c): c is { type: 'text'; text: string } => c.type === 'text')?.text ?? '';
+      if (text) out.push({ role: 'system', content: text });
+      continue;
+    }
+    if (msg.role === 'user') {
+      const hasRichPart = msg.content.some((c) => c.type === 'image' || c.type === 'document');
+      if (hasRichPart) {
+        // Vision/document user message: emit content as a parts array so
+        // base64 images and documents (PDFs) ride alongside text. Non-vision
+        // / non-document OpenAI models will 400 on this shape — callers gate
+        // by `supportsImages` / `supportsDocuments` on the model descriptor
+        // before attaching.
+        const parts: OpenAIUserContentPart[] = [];
+        for (const c of msg.content) {
+          if (c.type === 'text') {
+            parts.push({ type: 'text', text: c.text });
+          } else if (c.type === 'image') {
+            parts.push({
+              type: 'image_url',
+              image_url: { url: `data:${c.mediaType};base64,${c.data}` },
+            });
+          } else if (c.type === 'document') {
+            parts.push({
+              type: 'file',
+              file: {
+                ...(c.name ? { filename: c.name } : {}),
+                file_data: `data:${c.mediaType};base64,${c.data}`,
+              },
+            });
+          }
+        }
+        out.push({ role: 'user', content: parts });
+      } else {
+        const text = msg.content
+          .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+          .map((c) => c.text)
+          .join('\n');
+        out.push({ role: 'user', content: text });
+      }
+      continue;
+    }
+    if (msg.role === 'assistant') {
+      const text = msg.content
+        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+        .map((c) => c.text)
+        .join('');
+      const toolUses = msg.content.filter(
+        (c): c is { type: 'tool_use'; id: string; name: string; input: unknown } =>
+          c.type === 'tool_use',
+      );
+      const message: OpenAIChatMessage = { role: 'assistant', content: text || null };
+      if (toolUses.length > 0) {
+        message.tool_calls = toolUses.map((u) => ({
+          id: u.id,
+          type: 'function' as const,
+          function: { name: u.name, arguments: JSON.stringify(u.input ?? {}) },
+        }));
+      }
+      out.push(message);
+      continue;
+    }
+    if (msg.role === 'tool_result') {
+      for (const block of msg.content) {
+        if (block.type === 'tool_result') {
+          out.push({
+            role: 'tool',
+            tool_call_id: block.toolUseId,
+            content: block.content,
+          });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+export function toOpenAITools(tools: ReadonlyArray<ToolDef>): OpenAIToolDef[] {
+  return tools.map((t) => ({
+    type: 'function' as const,
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: (t.inputJsonSchema ?? zodToJsonSchema(t.inputSchema)) as unknown,
+    },
+  }));
+}
+

package/src/validate.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+import { validateKey } from './validate.js';
+
+describe('openai validateKey', () => {
+  it('rejects empty/short keys without any network call', async () => {
+    const make = vi.fn();
+    const res = await validateKey('', { client: make as never });
+    expect(res).toEqual({ ok: false, message: 'key looks too short' });
+    expect(make).not.toHaveBeenCalled();
+  });
+
+  it('success path lists models', async () => {
+    const list = vi.fn().mockResolvedValue({ data: [] });
+    const make = vi.fn().mockReturnValue({ models: { list } });
+    const res = await validateKey('sk-very-long-test-key', { client: make });
+    expect(res).toEqual({ ok: true });
+    expect(list).toHaveBeenCalledOnce();
+  });
+
+  it('SDK throw → ok:false with the underlying message', async () => {
+    const make = () => ({
+      models: {
+        list: async () => {
+          throw new Error('Incorrect API key provided');
+        },
+      },
+    });
+    const res = await validateKey('sk-bad-but-long-enough', { client: make });
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.message).toContain('Incorrect API key');
+  });
+});

package/src/validate.ts

@@ -0,0 +1,42 @@
+import OpenAI from 'openai';
+
+export type ValidationResult = { ok: true } | { ok: false; message: string };
+
+export interface ValidateKeyDeps {
+  /** Inject the OpenAI SDK constructor for tests. */
+  readonly client?: (apiKey: string) => {
+    models: { list: () => Promise<unknown> };
+  };
+  /**
+   * Endpoint to probe. Omit for OpenAI itself; pass a vendor base URL to
+   * validate an OpenAI-compatible provider (groq, deepseek, openrouter, …)
+   * against its own `/v1/models`. Lets `@moxxy/plugin-provider-admin` reuse
+   * this validator instead of duplicating the OpenAI-compatible probe.
+   */
+  readonly baseURL?: string;
+}
+
+/**
+ * "Is this key accepted by the endpoint?" Lists models — free, no inference
+ * cost. Validates OpenAI by default, or an OpenAI-compatible vendor when a
+ * `baseURL` is supplied.
+ */
+export async function validateKey(key: string, deps: ValidateKeyDeps = {}): Promise<ValidationResult> {
+  if (!key || key.trim().length < 8) {
+    return { ok: false, message: 'key looks too short' };
+  }
+  const make = deps.client ?? ((k: string) => defaultMaker(k, deps.baseURL));
+  try {
+    const client = make(key);
+    await client.models.list();
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function defaultMaker(apiKey: string, baseURL?: string): { models: { list: () => Promise<unknown> } } {
+  return new OpenAI({ apiKey, ...(baseURL ? { baseURL } : {}) }) as unknown as {
+    models: { list: () => Promise<unknown> };
+  };
+}