@aliou/pi-ts-aperture 0.3.2 → 0.4.0

package/src/core/plan.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import {
+  APERTURE_PROVENANCE_HEADERS,
+  buildApplyPlan,
+  planConfigChange,
+  resolveProviderHeaders,
+} from "./plan";
+import type { ApertureConfig, Api, Model } from "./types";
+
+describe("resolveProviderHeaders", () => {
+  it("includes provenance headers", () => {
+    const models: Model<Api>[] = [{ id: "gpt-4", provider: "openai" }];
+    const headers = resolveProviderHeaders(models);
+    expect(headers).toMatchObject(APERTURE_PROVENANCE_HEADERS);
+  });
+
+  it("merges model headers when present", () => {
+    const models: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai", headers: { "X-Custom": "value" } },
+    ];
+    const headers = resolveProviderHeaders(models);
+    expect(headers).toEqual({
+      ...APERTURE_PROVENANCE_HEADERS,
+      "X-Custom": "value",
+    });
+  });
+
+  it("model headers take precedence over provenance headers", () => {
+    const models: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai", headers: { Referer: "custom" } },
+    ];
+    const headers = resolveProviderHeaders(models);
+    expect(headers.Referer).toBe("custom");
+  });
+
+  it("uses first model with headers", () => {
+    const models: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai" },
+      { id: "gpt-3", provider: "openai", headers: { "X-Auth": "token" } },
+      { id: "gpt-4o", provider: "openai", headers: { "X-Other": "other" } },
+    ];
+    const headers = resolveProviderHeaders(models);
+    expect(headers["X-Auth"]).toBe("token");
+    expect(headers["X-Other"]).toBeUndefined();
+  });
+
+  it("returns only provenance headers when no model has headers", () => {
+    const models: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai" },
+      { id: "gpt-3", provider: "openai" },
+    ];
+    const headers = resolveProviderHeaders(models);
+    expect(headers).toEqual(APERTURE_PROVENANCE_HEADERS);
+  });
+});
+
+describe("buildApplyPlan", () => {
+  const baseConfig: ApertureConfig = {
+    baseUrl: "https://aperture.example.com",
+    providers: ["openai", "anthropic"],
+  };
+
+  const baseUrl = "https://aperture.example.com/v1";
+
+  it("returns empty registrations for empty config", () => {
+    const config: ApertureConfig = { baseUrl: "", providers: [] };
+    const plan = buildApplyPlan(config, [], baseUrl, []);
+    expect(plan.registrations).toEqual([]);
+    expect(plan.missingModels).toEqual([]);
+  });
+
+  it("skips providers with no models in registry", () => {
+    const registryModels: Model<Api>[] = [{ id: "gpt-4", provider: "openai" }];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations).toHaveLength(1);
+    expect(plan.registrations[0].provider).toBe("openai");
+  });
+
+  it("creates registrations for configured providers with models", () => {
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai", api: "openai-completions" },
+      { id: "claude-3", provider: "anthropic", api: "anthropic-messages" },
+    ];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations).toHaveLength(2);
+    expect(plan.registrations.map((r) => r.provider)).toContain("openai");
+    expect(plan.registrations.map((r) => r.provider)).toContain("anthropic");
+  });
+
+  it("registration has correct baseUrl", () => {
+    const registryModels: Model<Api>[] = [{ id: "gpt-4", provider: "openai" }];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations[0].baseUrl).toBe(baseUrl);
+  });
+
+  it("registration has apiKey set to dash", () => {
+    const registryModels: Model<Api>[] = [{ id: "gpt-4", provider: "openai" }];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations[0].apiKey).toBe("-");
+  });
+
+  it("registration includes merged headers", () => {
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai", headers: { "X-Custom": "value" } },
+    ];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations[0].headers).toEqual({
+      ...APERTURE_PROVENANCE_HEADERS,
+      "X-Custom": "value",
+    });
+  });
+
+  it("registration uses first model's api", () => {
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai", api: "openai-completions" },
+      { id: "gpt-3", provider: "openai", api: "openai-chat" },
+    ];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations[0].api).toBe("openai-completions");
+  });
+
+  it("registration defaults api when not specified", () => {
+    const registryModels: Model<Api>[] = [{ id: "gpt-4", provider: "openai" }];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations[0].api).toBe("openai-completions");
+  });
+
+  it("registration includes all models for provider", () => {
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai" },
+      { id: "gpt-3", provider: "openai" },
+      { id: "gpt-4o", provider: "openai" },
+    ];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.registrations[0].models).toHaveLength(3);
+  });
+
+  it("computes missing models when gateway IDs provided", () => {
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai" },
+      { id: "gpt-3", provider: "openai" },
+    ];
+    const gatewayIds = ["gpt-4"];
+    const plan = buildApplyPlan(
+      baseConfig,
+      registryModels,
+      baseUrl,
+      gatewayIds,
+    );
+    expect(plan.missingModels).toEqual(["gpt-3"]);
+  });
+
+  it("missingModels is empty when gateway IDs empty", () => {
+    const registryModels: Model<Api>[] = [{ id: "gpt-4", provider: "openai" }];
+    const plan = buildApplyPlan(baseConfig, registryModels, baseUrl, []);
+    expect(plan.missingModels).toEqual([]);
+  });
+
+  it("missingModels is empty when all models present on gateway", () => {
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai" },
+      { id: "gpt-3", provider: "openai" },
+    ];
+    const gatewayIds = ["gpt-4", "gpt-3"];
+    const plan = buildApplyPlan(
+      baseConfig,
+      registryModels,
+      baseUrl,
+      gatewayIds,
+    );
+    expect(plan.missingModels).toEqual([]);
+  });
+
+  it("only checks missing models for configured providers", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://aperture.example.com",
+      providers: ["openai"],
+    };
+    const registryModels: Model<Api>[] = [
+      { id: "gpt-4", provider: "openai" },
+      { id: "claude-3", provider: "anthropic" },
+    ];
+    const gatewayIds: string[] = [];
+    const plan = buildApplyPlan(config, registryModels, baseUrl, gatewayIds);
+    // Only openai models are considered, but since gatewayIds is empty, missingModels is empty
+    expect(plan.missingModels).toEqual([]);
+  });
+});
+
+describe("planConfigChange", () => {
+  it("detects removed providers", () => {
+    const prev = ["openai", "anthropic"];
+    const next = ["openai"];
+    const plan = planConfigChange(prev, next);
+    expect(plan.removedProviders).toEqual(["anthropic"]);
+  });
+
+  it("returns empty removedProviders when no providers removed", () => {
+    const prev = ["openai", "anthropic"];
+    const next = ["openai", "anthropic", "google"];
+    const plan = planConfigChange(prev, next);
+    expect(plan.removedProviders).toEqual([]);
+  });
+
+  it("returns empty removedProviders when providers unchanged", () => {
+    const prev = ["openai", "anthropic"];
+    const next = ["openai", "anthropic"];
+    const plan = planConfigChange(prev, next);
+    expect(plan.removedProviders).toEqual([]);
+  });
+
+  it("detects all providers removed", () => {
+    const prev = ["openai", "anthropic"];
+    const next: string[] = [];
+    const plan = planConfigChange(prev, next);
+    expect(plan.removedProviders).toEqual(["openai", "anthropic"]);
+  });
+
+  it("shouldRefreshModel is true when active model provider is in next providers", () => {
+    const prev = ["openai"];
+    const next = ["openai", "anthropic"];
+    const plan = planConfigChange(prev, next, "openai");
+    expect(plan.shouldRefreshModel).toBe(true);
+  });
+
+  it("shouldRefreshModel is false when active model provider was removed", () => {
+    const prev = ["openai", "anthropic"];
+    const next = ["openai"];
+    const plan = planConfigChange(prev, next, "anthropic");
+    expect(plan.shouldRefreshModel).toBe(false);
+  });
+
+  it("shouldRefreshModel is false when no active model", () => {
+    const prev = ["openai"];
+    const next = ["openai", "anthropic"];
+    const plan = planConfigChange(prev, next);
+    expect(plan.shouldRefreshModel).toBe(false);
+  });
+
+  it("shouldRefreshModel is true when adding provider that matches active model", () => {
+    const prev: string[] = [];
+    const next = ["openai"];
+    const plan = planConfigChange(prev, next, "openai");
+    expect(plan.shouldRefreshModel).toBe(true);
+  });
+
+  it("shouldRefreshModel is false when active model provider not in next", () => {
+    const prev = ["openai"];
+    const next = ["anthropic"];
+    const plan = planConfigChange(prev, next, "openai");
+    expect(plan.shouldRefreshModel).toBe(false);
+  });
+});

package/src/core/plan.ts

@@ -0,0 +1,107 @@
+/**
+ * Core decision logic -- all pure functions.
+ */
+
+import type {
+  ApertureConfig,
+  Api,
+  ApplyPlan,
+  ConfigChangePlan,
+  Model,
+  ProviderRegistration,
+} from "./types";
+
+/**
+ * Preserve provenance similarly to pi-synthetic so downstream providers can
+ * attribute traffic to Pi / this extension.
+ */
+export const APERTURE_PROVENANCE_HEADERS = {
+  Referer: "https://pi.dev",
+  "X-Title": "npm:@aliou/pi-ts-aperture",
+};
+
+/**
+ * Resolves headers for a provider registration.
+ * Merges provenance headers with the first model's headers (if any).
+ */
+export function resolveProviderHeaders(
+  models: Model<Api>[],
+): Record<string, string> {
+  const modelHeaders = models.find((m) => m.headers)?.headers ?? {};
+  return {
+    ...APERTURE_PROVENANCE_HEADERS,
+    ...modelHeaders,
+  };
+}
+
+/**
+ * Builds a plan for applying Aperture configuration.
+ *
+ * Groups registry models by configured provider, builds registrations,
+ * and computes missing models (if gateway model IDs are provided).
+ *
+ * Providers with no models in the registry are skipped (nothing to reroute).
+ */
+export function buildApplyPlan(
+  config: ApertureConfig,
+  registryModels: Model<Api>[],
+  providerBaseUrl: string,
+  gatewayModelIds: string[],
+): ApplyPlan {
+  const { providers } = config;
+
+  const registrations: ProviderRegistration[] = [];
+
+  for (const provider of providers) {
+    const existingModels = registryModels.filter(
+      (m) => m.provider === provider,
+    );
+
+    if (existingModels.length === 0) continue;
+
+    registrations.push({
+      provider,
+      baseUrl: providerBaseUrl,
+      apiKey: "-",
+      headers: resolveProviderHeaders(existingModels),
+      api: existingModels[0].api ?? "openai-completions",
+      models: existingModels,
+    });
+  }
+
+  let missingModels: string[] = [];
+  if (gatewayModelIds.length > 0) {
+    const routedModelIds = registryModels
+      .filter((m) => providers.includes(m.provider))
+      .map((m) => m.id);
+    missingModels = routedModelIds.filter(
+      (id) => !gatewayModelIds.includes(id),
+    );
+  }
+
+  return { registrations, missingModels };
+}
+
+/**
+ * Plans the effects of a configuration change.
+ *
+ * @param prevProviders - Providers that were previously configured
+ * @param nextProviders - Providers that are now configured
+ * @param activeModelProvider - Provider of the currently active model (if any)
+ * @returns ConfigChangePlan with removed providers and refresh decision
+ */
+export function planConfigChange(
+  prevProviders: string[],
+  nextProviders: string[],
+  activeModelProvider?: string,
+): ConfigChangePlan {
+  const removedProviders = prevProviders.filter(
+    (provider) => !nextProviders.includes(provider),
+  );
+
+  const shouldRefreshModel =
+    activeModelProvider !== undefined &&
+    nextProviders.includes(activeModelProvider);
+
+  return { removedProviders, shouldRefreshModel };
+}

package/src/core/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Plain data types used by core functions.
+ * Model is re-exported from @mariozechner/pi-ai for internal use.
+ */
+import type { Api, Model } from "@mariozechner/pi-ai";
+
+export interface ApertureConfig {
+  baseUrl: string;
+  providers: string[];
+  checkGatewayModels: string[];
+}
+
+export interface ProviderRegistration {
+  provider: string;
+  baseUrl: string;
+  apiKey: string;
+  headers: Record<string, string>;
+  api: string;
+  models: Model<Api>[];
+}
+
+// Re-export Model for use in other core files
+export type { Model, Api };
+
+export interface ApplyPlan {
+  registrations: ProviderRegistration[];
+  missingModels: string[];
+}
+
+export interface ConfigChangePlan {
+  removedProviders: string[];
+  shouldRefreshModel: boolean;
+}

package/src/core/url.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import type { ApertureConfig } from "./types";
+import {
+  normalizeInputUrl,
+  resolveGatewayUrl,
+  resolveProviderBaseUrl,
+} from "./url";
+
+describe("normalizeInputUrl", () => {
+  it("returns empty string for empty input", () => {
+    expect(normalizeInputUrl("")).toBe("");
+  });
+
+  it("trims whitespace", () => {
+    expect(normalizeInputUrl("  https://example.com  ")).toBe(
+      "https://example.com",
+    );
+  });
+
+  it("adds http:// scheme when missing", () => {
+    expect(normalizeInputUrl("example.com")).toBe("http://example.com");
+  });
+
+  it("preserves https:// scheme", () => {
+    expect(normalizeInputUrl("https://example.com")).toBe(
+      "https://example.com",
+    );
+  });
+
+  it("preserves http:// scheme", () => {
+    expect(normalizeInputUrl("http://example.com")).toBe("http://example.com");
+  });
+
+  it("strips trailing /v1", () => {
+    expect(normalizeInputUrl("https://example.com/v1")).toBe(
+      "https://example.com",
+    );
+  });
+
+  it("strips trailing /v1/", () => {
+    expect(normalizeInputUrl("https://example.com/v1/")).toBe(
+      "https://example.com",
+    );
+  });
+
+  it("strips trailing slashes", () => {
+    expect(normalizeInputUrl("https://example.com/")).toBe(
+      "https://example.com",
+    );
+  });
+
+  it("strips multiple trailing slashes", () => {
+    expect(normalizeInputUrl("https://example.com///")).toBe(
+      "https://example.com",
+    );
+  });
+
+  it("handles already-normalized URL", () => {
+    expect(normalizeInputUrl("https://example.com")).toBe(
+      "https://example.com",
+    );
+  });
+});
+
+describe("resolveGatewayUrl", () => {
+  it("returns null when baseUrl is empty", () => {
+    const config: ApertureConfig = { baseUrl: "", providers: ["openai"] };
+    expect(resolveGatewayUrl(config)).toBeNull();
+  });
+
+  it("returns null when providers is empty", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://example.com",
+      providers: [],
+    };
+    expect(resolveGatewayUrl(config)).toBeNull();
+  });
+
+  it("returns null when both baseUrl and providers are empty", () => {
+    const config: ApertureConfig = { baseUrl: "", providers: [] };
+    expect(resolveGatewayUrl(config)).toBeNull();
+  });
+
+  it("returns URL without trailing slash", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://example.com/",
+      providers: ["openai"],
+    };
+    expect(resolveGatewayUrl(config)).toBe("https://example.com");
+  });
+
+  it("returns URL as-is when no trailing slash", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://example.com",
+      providers: ["openai"],
+    };
+    expect(resolveGatewayUrl(config)).toBe("https://example.com");
+  });
+
+  it("strips multiple trailing slashes", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://example.com///",
+      providers: ["openai"],
+    };
+    expect(resolveGatewayUrl(config)).toBe("https://example.com");
+  });
+});
+
+describe("resolveProviderBaseUrl", () => {
+  it("returns null when gateway URL cannot be resolved", () => {
+    const config: ApertureConfig = { baseUrl: "", providers: ["openai"] };
+    expect(resolveProviderBaseUrl(config)).toBeNull();
+  });
+
+  it("appends /v1 to gateway URL", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://example.com",
+      providers: ["openai"],
+    };
+    expect(resolveProviderBaseUrl(config)).toBe("https://example.com/v1");
+  });
+
+  it("handles trailing slashes correctly", () => {
+    const config: ApertureConfig = {
+      baseUrl: "https://example.com/",
+      providers: ["openai"],
+    };
+    expect(resolveProviderBaseUrl(config)).toBe("https://example.com/v1");
+  });
+});

package/src/core/url.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure URL helpers.
+ */
+
+import type { ApertureConfig } from "./types";
+
+/**
+ * Normalizes a user-input URL:
+ * - Trims whitespace
+ * - Adds http:// scheme if missing
+ * - Strips trailing /v1 or /v1/
+ * - Strips trailing slashes
+ */
+export function normalizeInputUrl(raw: string): string {
+  let result = raw.trim();
+  if (!result) return result;
+  if (!result.startsWith("http://") && !result.startsWith("https://")) {
+    result = `http://${result}`;
+  }
+  return result.replace(/\/v1\/?$/, "").replace(/\/+$/, "");
+}
+
+/**
+ * Returns configured gateway URL without trailing slash.
+ * Returns null when baseUrl is empty or providers list is empty.
+ */
+export function resolveGatewayUrl(config: ApertureConfig): string | null {
+  const { baseUrl, providers } = config;
+  if (!baseUrl || providers.length === 0) return null;
+  return baseUrl.replace(/\/+$/, "");
+}
+
+/**
+ * Returns the Aperture provider base URL used for provider registration.
+ * Appends /v1 to the gateway URL.
+ * Returns null when gateway URL cannot be resolved.
+ */
+export function resolveProviderBaseUrl(config: ApertureConfig): string | null {
+  const gateway = resolveGatewayUrl(config);
+  if (!gateway) return null;
+  return `${gateway}/v1`;
+}