@struktur/sdk 0.1.0

package/src/artifacts/input.ts

@@ -0,0 +1,360 @@
+import type { Artifact, ArtifactContent, ArtifactImage, ArtifactType } from "../types";
+import { createAjv, validateOrThrow } from "../validation/validator";
+import { defaultArtifactProviders, type ArtifactProviders } from "./providers";
+import type { ParsersConfig } from "../parsers/types";
+import { runParser } from "../parsers/runner";
+import type { ParsePdfOptions } from "../parsers/pdf";
+
+export type SerializedArtifactImage = Omit<ArtifactImage, "contents"> & {
+  contents?: never;
+};
+
+export type SerializedArtifactContent = Omit<ArtifactContent, "media"> & {
+  media?: SerializedArtifactImage[];
+};
+
+export type SerializedArtifact = Omit<Artifact, "raw" | "contents"> & {
+  contents: SerializedArtifactContent[];
+  raw?: never;
+};
+
+export type SerializedArtifacts = SerializedArtifact | SerializedArtifact[];
+
+export type ArtifactInput =
+  | { kind: "artifact-json"; data: unknown }
+  | { kind: "text"; text: string; id?: string }
+  | { kind: "file"; path: string; mimeType?: string; id?: string }
+  | { kind: "buffer"; buffer: Buffer; mimeType: string; id?: string };
+
+export type ArtifactInputParser = {
+  name: string;
+  canParse: (input: ArtifactInput) => boolean;
+  parse: (
+    input: ArtifactInput,
+    options?: { 
+      providers?: ArtifactProviders; 
+      parsers?: ParsersConfig; 
+      includeImages?: boolean;
+      screenshots?: boolean;
+      screenshotScale?: number;
+      screenshotWidth?: number;
+    }
+  ) => Promise<Artifact[]>;
+};
+
+const serializedArtifactImageSchema = {
+  type: "object",
+  required: ["type"],
+  properties: {
+    type: { const: "image" },
+    url: { type: "string", minLength: 1 },
+    base64: { type: "string", minLength: 1 },
+    text: { type: "string" },
+    x: { type: "number" },
+    y: { type: "number" },
+    width: { type: "number" },
+    height: { type: "number" },
+    imageType: { enum: ["embedded", "screenshot"] },
+  },
+  additionalProperties: false,
+  anyOf: [{ required: ["url"] }, { required: ["base64"] }],
+};
+
+const serializedArtifactContentSchema = {
+  type: "object",
+  properties: {
+    page: { type: "number" },
+    text: { type: "string" },
+    media: { type: "array", items: serializedArtifactImageSchema },
+  },
+  additionalProperties: false,
+  anyOf: [{ required: ["text"] }, { required: ["media"] }],
+};
+
+const serializedArtifactSchema = {
+  type: "object",
+  required: ["id", "type", "contents"],
+  properties: {
+    id: { type: "string", minLength: 1 },
+    type: { enum: ["text", "image", "pdf", "file"] as ArtifactType[] },
+    contents: { type: "array", items: serializedArtifactContentSchema },
+    metadata: { type: "object", additionalProperties: true },
+    tokens: { type: "number" },
+  },
+  additionalProperties: false,
+};
+
+const serializedArtifactsSchema = {
+  anyOf: [
+    serializedArtifactSchema,
+    { type: "array", items: serializedArtifactSchema },
+  ],
+};
+
+const inputParsers: ArtifactInputParser[] = [];
+
+export const registerArtifactInputParser = (parser: ArtifactInputParser) => {
+  inputParsers.push(parser);
+};
+
+export const clearArtifactInputParsers = () => {
+  inputParsers.length = 0;
+};
+
+export const validateSerializedArtifacts = (data: unknown): SerializedArtifact[] => {
+  const ajv = createAjv();
+  const parsed = validateOrThrow<SerializedArtifacts>(
+    ajv,
+    serializedArtifactsSchema,
+    data
+  );
+  return Array.isArray(parsed) ? parsed : [parsed];
+};
+
+export const hydrateSerializedArtifacts = (items: SerializedArtifact[]): Artifact[] => {
+  return items.map((item) => ({
+    ...item,
+    raw: async () => Buffer.from(JSON.stringify(item.contents ?? [])),
+  }));
+};
+
+export const parseSerializedArtifacts = (text: string): SerializedArtifact[] => {
+  const parsed = JSON.parse(text) as unknown;
+  return validateSerializedArtifacts(parsed);
+};
+
+export const splitTextIntoContents = (text: string): ArtifactContent[] => {
+  const blocks = text
+    .split(/\n\s*\n/g)
+    .map((block) => block.trim())
+    .filter((block) => block.length > 0);
+
+  if (blocks.length === 0) {
+    return [{ text }];
+  }
+
+  return blocks.map((block) => ({ text: block }));
+};
+
+const detectMimeType = async (path: string) => {
+  const file = Bun.file(path);
+  const type = file.type?.trim();
+  return type && type.length > 0 ? type : "application/octet-stream";
+};
+
+const bufferToTextArtifact = (buffer: Buffer, id?: string): Artifact => {
+  const text = buffer.toString();
+  return {
+    id: id ?? `artifact-${crypto.randomUUID()}`,
+    type: "text",
+    raw: async () => buffer,
+    contents: splitTextIntoContents(text),
+  };
+};
+
+const bufferToImageArtifact = (buffer: Buffer, id?: string): Artifact => {
+  return {
+    id: id ?? `artifact-${crypto.randomUUID()}`,
+    type: "image",
+    raw: async () => buffer,
+    contents: [
+      {
+        media: [{ type: "image", contents: buffer }],
+      },
+    ],
+  };
+};
+
+const parseBufferInput = async (
+  buffer: Buffer,
+  mimeType: string,
+  id?: string,
+  providers?: ArtifactProviders,
+  parsers?: ParsersConfig,
+  includeImages?: boolean,
+  screenshots?: boolean,
+  screenshotScale?: number,
+  screenshotWidth?: number,
+): Promise<Artifact[]> => {
+  // Resolution order:
+  // 1. parsers config (custom ParserDef) — if MIME type has a configured parser, use it
+  if (parsers) {
+    const parserDef = parsers[mimeType];
+    if (parserDef) {
+      return runParser(parserDef, { kind: "buffer", buffer }, mimeType);
+    }
+  }
+
+  // 2. providers registry (user-registered ArtifactProvider functions)
+  const registry = providers ?? defaultArtifactProviders;
+  const provider = registry[mimeType];
+  if (provider) {
+    return [await provider(buffer)];
+  }
+
+  // JSON auto-detection: if MIME is application/json, try to parse as SerializedArtifact[]
+  if (mimeType === "application/json") {
+    try {
+      const parsed = JSON.parse(buffer.toString()) as unknown;
+      const serialized = validateSerializedArtifacts(parsed);
+      return hydrateSerializedArtifacts(serialized);
+    } catch {
+      // If no custom parser is configured for application/json, throw clear error
+      throw new Error(
+        "Input is JSON but not in SerializedArtifact format. To parse arbitrary JSON files, configure a parser: struktur config parsers add --mime application/json ..."
+      );
+    }
+  }
+
+  // 3. Built-in PDF → pdf artifact
+  if (mimeType === "application/pdf") {
+    const { parsePdf } = await import("../parsers/pdf");
+    const pdfOptions: ParsePdfOptions = { 
+      includeImages, 
+      screenshots, 
+      screenshotScale, 
+      screenshotWidth 
+    };
+    return [await parsePdf(buffer, pdfOptions)];
+  }
+
+  // 4. Built-in text/* → text artifact
+  if (mimeType.startsWith("text/")) {
+    return [bufferToTextArtifact(buffer, id)];
+  }
+
+  // 5. Built-in image/* → image artifact
+  if (mimeType.startsWith("image/")) {
+    return [bufferToImageArtifact(buffer, id)];
+  }
+
+  throw new Error(`Unsupported MIME type: ${mimeType}`);
+};
+
+const artifactJsonParser: ArtifactInputParser = {
+  name: "artifact-json",
+  canParse: (input) => input.kind === "artifact-json",
+  parse: async (input) => {
+    if (input.kind !== "artifact-json") {
+      return [];
+    }
+    const serialized = validateSerializedArtifacts(input.data);
+    return hydrateSerializedArtifacts(serialized);
+  },
+};
+
+const textParser: ArtifactInputParser = {
+  name: "text",
+  canParse: (input) => input.kind === "text",
+  parse: async (input) => {
+    if (input.kind !== "text") {
+      return [];
+    }
+    const buffer = Buffer.from(input.text);
+    return [bufferToTextArtifact(buffer, input.id)];
+  },
+};
+
+const fileParser: ArtifactInputParser = {
+  name: "file",
+  canParse: (input) => input.kind === "file",
+  parse: async (input, options) => {
+    if (input.kind !== "file") {
+      return [];
+    }
+    const mimeType = input.mimeType ?? (await detectMimeType(input.path));
+
+    // JSON auto-detection: if MIME type is application/json, first try to validate as SerializedArtifact[]
+    if (mimeType === "application/json") {
+      const text = await Bun.file(input.path).text();
+      try {
+        const parsed = JSON.parse(text) as unknown;
+        const serialized = validateSerializedArtifacts(parsed);
+        return hydrateSerializedArtifacts(serialized);
+      } catch {
+        // Not valid artifact JSON — try custom parser or throw
+        if (options?.parsers) {
+          const parserDef = options.parsers[mimeType];
+          if (parserDef) {
+            return runParser(parserDef, { kind: "file", path: input.path }, mimeType);
+          }
+        }
+        throw new Error(
+          `File "${input.path}" is JSON but not in SerializedArtifact format. To parse arbitrary JSON files, configure a parser: struktur config parsers add --mime application/json ...`
+        );
+      }
+    }
+
+    const file = Bun.file(input.path);
+    const buffer = Buffer.from(await file.arrayBuffer());
+    return parseBufferInput(
+      buffer, 
+      mimeType, 
+      input.id, 
+      options?.providers, 
+      options?.parsers, 
+      options?.includeImages,
+      options?.screenshots,
+      options?.screenshotScale,
+      options?.screenshotWidth,
+    );
+  },
+};
+
+const bufferParser: ArtifactInputParser = {
+  name: "buffer",
+  canParse: (input) => input.kind === "buffer",
+  parse: async (input, options) => {
+    if (input.kind !== "buffer") {
+      return [];
+    }
+    return parseBufferInput(
+      input.buffer,
+      input.mimeType,
+      input.id,
+      options?.providers,
+      options?.parsers,
+      options?.includeImages,
+      options?.screenshots,
+      options?.screenshotScale,
+      options?.screenshotWidth,
+    );
+  },
+};
+
+export const parse = async (
+  input: ArtifactInput,
+  options?: { 
+    parsers?: ArtifactInputParser[]; 
+    providers?: ArtifactProviders; 
+    parserConfig?: ParsersConfig; 
+    includeImages?: boolean;
+    screenshots?: boolean;
+    screenshotScale?: number;
+    screenshotWidth?: number;
+  }
+): Promise<Artifact[]> => {
+  const parsers =
+    options?.parsers ??
+    [
+      ...inputParsers,
+      artifactJsonParser,
+      textParser,
+      fileParser,
+      bufferParser,
+    ];
+  const parser = parsers.find((candidate) => candidate.canParse(input));
+
+  if (!parser) {
+    throw new Error(`No artifact input parser available for ${input.kind}`);
+  }
+
+  return parser.parse(input, { 
+    providers: options?.providers, 
+    parsers: options?.parserConfig, 
+    includeImages: options?.includeImages,
+    screenshots: options?.screenshots,
+    screenshotScale: options?.screenshotScale,
+    screenshotWidth: options?.screenshotWidth,
+  });
+};

package/src/artifacts/providers.test.ts

@@ -0,0 +1,19 @@
+import { test, expect } from "bun:test";
+import { defaultArtifactProviders, type ArtifactProviders } from "./providers";
+
+test("defaultArtifactProviders is an object", () => {
+  expect(defaultArtifactProviders).toBeDefined();
+  expect(typeof defaultArtifactProviders).toBe("object");
+});
+
+test("ArtifactProviders type accepts MIME type keys", () => {
+  const providers: ArtifactProviders = {
+    "application/pdf": async (buffer) => ({
+      id: "pdf-1",
+      type: "pdf",
+      raw: async () => buffer,
+      contents: [{ page: 1, text: "test" }],
+    }),
+  };
+  expect(providers["application/pdf"]).toBeDefined();
+});

package/src/artifacts/providers.ts

@@ -0,0 +1,7 @@
+import type { Artifact } from "../types";
+
+export type ArtifactProvider = (buffer: Buffer) => Promise<Artifact>;
+
+export type ArtifactProviders = Record<string, ArtifactProvider>;
+
+export const defaultArtifactProviders: ArtifactProviders = {};

package/src/artifacts/urlToArtifact.test.ts

@@ -0,0 +1,23 @@
+import { test, expect } from "bun:test";
+import { urlToArtifact } from "./urlToArtifact";
+
+test("urlToArtifact fetches and builds artifact", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    new Response(
+      JSON.stringify({
+        id: "a1",
+        type: "pdf",
+        contents: [{ text: "hello" }],
+      }),
+      { status: 200 }
+    )) as unknown as typeof fetch;
+
+  const artifact = await urlToArtifact("https://example.com/artifact");
+  const raw = await artifact.raw();
+
+  expect(artifact.id).toBe("a1");
+  expect(raw.toString()).toContain("hello");
+
+  globalThis.fetch = originalFetch;
+});

package/src/artifacts/urlToArtifact.ts

@@ -0,0 +1,19 @@
+import type { Artifact } from "../types";
+
+export const urlToArtifact = async (url: string): Promise<Artifact> => {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch artifact: ${response.status} ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as Omit<Artifact, "raw"> & {
+    raw?: () => Promise<Buffer>;
+  };
+
+  return {
+    ...data,
+    raw:
+      data.raw ??
+      (async () => Buffer.from(JSON.stringify(data.contents ?? []))),
+  };
+};

package/src/auth/AGENTS.md

@@ -0,0 +1,11 @@
+Auth module
+
+- Purpose: persist and resolve provider API tokens and CLI defaults.
+- Key files: `tokens.ts`, `config.ts`.
+- Design: prefers macOS Keychain when available; otherwise uses `~/.config/struktur/tokens.json` with strict permissions.
+- Config store (`config.ts`): stores `defaultModel` (string), `aliases` (Record<string, string>), and `parsers` (ParsersConfig) in `~/.config/struktur/config.json`.
+- Alias API: `listAliases`, `getAlias`, `setAlias`, `deleteAlias`, `resolveAlias` (resolves alias → model spec, passthrough if not an alias).
+- Parsers config API: `listParsers`, `getParser`, `setParser`, `deleteParser`.
+  - `setParser` validates that `command-file` type parsers contain `FILE_PATH` in the command string.
+- Environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENCODE_API_KEY, OPENROUTER_API_KEY.
+- Tests: `tokens.test.ts`.

package/src/auth/config.test.ts

@@ -0,0 +1,132 @@
+import { test, expect } from "bun:test";
+import path from "node:path";
+import os from "node:os";
+import { rm } from "node:fs/promises";
+import {
+  listParsers,
+  getParser,
+  setParser,
+  deleteParser,
+} from "./config";
+
+const makeTempDir = () => {
+  const suffix = Math.random().toString(16).slice(2);
+  return path.join(os.tmpdir(), `struktur-test-${suffix}`);
+};
+
+test("listParsers returns empty object when no parsers configured", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    const parsers = await listParsers();
+    expect(parsers).toEqual({});
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("setParser stores an npm parser", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    await setParser("application/pdf", { type: "npm", package: "my-pdf-parser" });
+    const parser = await getParser("application/pdf");
+    expect(parser).toEqual({ type: "npm", package: "my-pdf-parser" });
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("setParser stores a command-file parser", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    await setParser("application/pdf", {
+      type: "command-file",
+      command: "my-cmd FILE_PATH output",
+    });
+    const parser = await getParser("application/pdf");
+    expect(parser).toEqual({ type: "command-file", command: "my-cmd FILE_PATH output" });
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("setParser rejects command-file without FILE_PATH placeholder", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    await expect(
+      setParser("application/pdf", { type: "command-file", command: "my-cmd --input" })
+    ).rejects.toThrow("FILE_PATH");
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("setParser stores a command-stdin parser", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    await setParser("text/csv", { type: "command-stdin", command: "csv-to-json" });
+    const parser = await getParser("text/csv");
+    expect(parser).toEqual({ type: "command-stdin", command: "csv-to-json" });
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("listParsers returns all stored parsers", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    await setParser("application/pdf", { type: "npm", package: "pdf-parser" });
+    await setParser("text/csv", { type: "command-stdin", command: "csv-parse" });
+    const parsers = await listParsers();
+    expect(parsers["application/pdf"]).toEqual({ type: "npm", package: "pdf-parser" });
+    expect(parsers["text/csv"]).toEqual({ type: "command-stdin", command: "csv-parse" });
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("deleteParser removes stored parser and returns true", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    await setParser("application/pdf", { type: "npm", package: "pdf-parser" });
+    const deleted = await deleteParser("application/pdf");
+    expect(deleted).toBe(true);
+    const parser = await getParser("application/pdf");
+    expect(parser).toBeUndefined();
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("deleteParser returns false when parser does not exist", async () => {
+  const tempDir = makeTempDir();
+  process.env.STRUKTUR_CONFIG_DIR = tempDir;
+
+  try {
+    const deleted = await deleteParser("application/pdf");
+    expect(deleted).toBe(false);
+  } finally {
+    delete process.env.STRUKTUR_CONFIG_DIR;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});

package/src/auth/config.ts

@@ -0,0 +1,129 @@
+import path from "node:path";
+import os from "node:os";
+import { chmod, mkdir } from "node:fs/promises";
+import type { ParserDef, ParsersConfig } from "@struktur/sdk";
+
+type ConfigStore = {
+  version: 1;
+  defaultModel?: string;
+  aliases?: Record<string, string>;
+  parsers?: ParsersConfig;
+};
+
+const CONFIG_DIR_ENV = "STRUKTUR_CONFIG_DIR";
+
+const resolveConfigDir = () => {
+  return process.env[CONFIG_DIR_ENV] ?? path.join(os.homedir(), ".config", "struktur");
+};
+
+const resolveConfigPath = () => path.join(resolveConfigDir(), "config.json");
+
+const emptyStore = (): ConfigStore => ({ version: 1 });
+
+const readConfigStore = async (): Promise<ConfigStore> => {
+  const configPath = resolveConfigPath();
+  const exists = await Bun.file(configPath).exists();
+  if (!exists) {
+    return emptyStore();
+  }
+  const raw = await Bun.file(configPath).text();
+  const parsed = JSON.parse(raw) as ConfigStore;
+  if (!parsed || parsed.version !== 1) {
+    return emptyStore();
+  }
+  return parsed;
+};
+
+const writeConfigStore = async (store: ConfigStore) => {
+  const configDir = resolveConfigDir();
+  const configPath = resolveConfigPath();
+  await mkdir(configDir, { recursive: true, mode: 0o700 });
+  await Bun.write(configPath, JSON.stringify(store, null, 2));
+  await chmod(configDir, 0o700);
+  await chmod(configPath, 0o600);
+};
+
+export const getDefaultModel = async () => {
+  const store = await readConfigStore();
+  return store.defaultModel;
+};
+
+export const setDefaultModel = async (model: string) => {
+  const store = await readConfigStore();
+  store.defaultModel = model;
+  await writeConfigStore(store);
+  return model;
+};
+
+// --- Alias management ---
+
+export const listAliases = async (): Promise<Record<string, string>> => {
+  const store = await readConfigStore();
+  return store.aliases ?? {};
+};
+
+export const getAlias = async (alias: string): Promise<string | undefined> => {
+  const store = await readConfigStore();
+  return store.aliases?.[alias];
+};
+
+export const setAlias = async (alias: string, model: string): Promise<string> => {
+  const store = await readConfigStore();
+  store.aliases ??= {};
+  store.aliases[alias] = model;
+  await writeConfigStore(store);
+  return model;
+};
+
+export const deleteAlias = async (alias: string): Promise<boolean> => {
+  const store = await readConfigStore();
+  if (!store.aliases?.[alias]) {
+    return false;
+  }
+  delete store.aliases[alias];
+  await writeConfigStore(store);
+  return true;
+};
+
+/**
+ * Resolve a model spec: if it matches a stored alias, return the aliased model string.
+ * Otherwise return the original spec unchanged.
+ */
+export const resolveAlias = async (modelSpec: string): Promise<string> => {
+  const aliases = await listAliases();
+  return aliases[modelSpec] ?? modelSpec;
+};
+
+// --- Parser config management ---
+
+export const listParsers = async (): Promise<ParsersConfig> => {
+  const store = await readConfigStore();
+  return store.parsers ?? {};
+};
+
+export const getParser = async (mimeType: string): Promise<ParserDef | undefined> => {
+  const store = await readConfigStore();
+  return store.parsers?.[mimeType];
+};
+
+export const setParser = async (mimeType: string, def: ParserDef): Promise<void> => {
+  if (def.type === "command-file" && !def.command.includes("FILE_PATH")) {
+    throw new Error(
+      `command-file parser must contain FILE_PATH placeholder in the command string. Got: "${def.command}"`
+    );
+  }
+  const store = await readConfigStore();
+  store.parsers ??= {};
+  store.parsers[mimeType] = def;
+  await writeConfigStore(store);
+};
+
+export const deleteParser = async (mimeType: string): Promise<boolean> => {
+  const store = await readConfigStore();
+  if (!store.parsers?.[mimeType]) {
+    return false;
+  }
+  delete store.parsers[mimeType];
+  await writeConfigStore(store);
+  return true;
+};