@shipfox/client-agent 0.2.0

package/src/components/custom-model-provider-payload.test.ts

@@ -0,0 +1,170 @@
+import type {CustomModelProviderConfigDto} from '@shipfox/api-agent-dto';
+import {
+  buildCreateCustomModelProviderBody,
+  buildDiscoverModelsBody,
+  buildDiscoverModelsBySlugBody,
+  buildUpdateCustomModelProviderBody,
+  customHeadersDirty,
+  customModelsDirty,
+  editCustomModelProviderFormValues,
+  formatBaseUrlHost,
+} from './custom-model-provider-payload.js';
+
+describe('custom model provider payload mappers', () => {
+  test('builds create bodies from complete form rows and filters blanks', () => {
+    const body = buildCreateCustomModelProviderBody({
+      slug: ' local-vllm ',
+      display_name: ' Local vLLM ',
+      api: 'openai-completions',
+      base_url: ' http://localhost:8000/v1 ',
+      api_key: ' sk-local ',
+      headers: [
+        {
+          client_id: 'header-1',
+          name: ' Authorization ',
+          value: ' Bearer token ',
+          secret: true,
+          hasStoredValue: false,
+          storedName: '',
+        },
+        {
+          client_id: 'header-2',
+          name: '',
+          value: '',
+          secret: false,
+          hasStoredValue: false,
+          storedName: '',
+        },
+      ],
+      models: [
+        {
+          client_id: 'model-1',
+          id: ' llama-3.1 ',
+          label: ' Llama 3.1 ',
+          context_window: '128000',
+          max_output_tokens: '16384',
+          input_image: true,
+          reasoning: false,
+        },
+        {
+          client_id: 'model-2',
+          id: '',
+          label: '',
+          context_window: '',
+          max_output_tokens: '',
+          input_image: false,
+          reasoning: false,
+        },
+      ],
+      default_model: ' llama-3.1 ',
+    });
+
+    expect(body).toEqual({
+      slug: 'local-vllm',
+      display_name: 'Local vLLM',
+      api: 'openai-completions',
+      base_url: 'http://localhost:8000/v1',
+      api_key: 'sk-local',
+      headers: [{name: 'authorization', value: 'Bearer token', secret: true}],
+      models: [
+        {
+          id: 'llama-3.1',
+          label: 'Llama 3.1',
+          context_window: 128000,
+          max_output_tokens: 16384,
+          input_image: true,
+        },
+      ],
+      default_model: 'llama-3.1',
+    });
+  });
+
+  test('keeps unchanged stored secret headers out of update bodies', () => {
+    const config = customConfig();
+    const values = editCustomModelProviderFormValues(config);
+
+    const body = buildUpdateCustomModelProviderBody(config, values);
+
+    expect(customHeadersDirty(config, values.headers)).toBe(false);
+    expect(customModelsDirty(config, values.models)).toBe(false);
+    expect(body).toEqual({});
+  });
+
+  test('serializes kept secret headers for slug-scoped discovery', () => {
+    const config = customConfig();
+    const values = editCustomModelProviderFormValues(config);
+
+    const body = buildDiscoverModelsBySlugBody(config, values);
+
+    expect(body).toEqual({
+      headers: [
+        {name: 'x-region', value: 'us', secret: false},
+        {name: 'authorization', secret: true, keep: true},
+      ],
+    });
+  });
+
+  test('requires secret values again when stored secret headers are renamed', () => {
+    const config = customConfig();
+    const values = editCustomModelProviderFormValues(config);
+    values.headers = values.headers.map((header) =>
+      header.secret ? {...header, name: 'x-authorization'} : header,
+    );
+
+    const body = buildUpdateCustomModelProviderBody(config, values);
+
+    expect(body.headers).toEqual([
+      {name: 'x-region', value: 'us', secret: false},
+      {name: 'x-authorization', value: '', secret: true},
+    ]);
+  });
+
+  test('builds unsaved discovery bodies without keep markers', () => {
+    const config = customConfig();
+    const values = editCustomModelProviderFormValues(config);
+    values.api_key = 'sk-new';
+    values.headers = values.headers.map((header) =>
+      header.secret ? {...header, value: 'Bearer new'} : header,
+    );
+
+    const body = buildDiscoverModelsBody(values);
+
+    expect(body).toEqual({
+      api: 'openai-responses',
+      base_url: 'https://llm.example.test/v1',
+      api_key: 'sk-new',
+      headers: [
+        {name: 'x-region', value: 'us'},
+        {name: 'authorization', value: 'Bearer new'},
+      ],
+    });
+  });
+
+  test('formats valid base URL hosts and falls back for raw values', () => {
+    expect(formatBaseUrlHost('https://llm.example.test/v1')).toBe('llm.example.test');
+    expect(formatBaseUrlHost('not a url')).toBe('not a url');
+  });
+});
+
+function customConfig(): CustomModelProviderConfigDto {
+  return {
+    kind: 'custom',
+    provider_id: 'local-vllm',
+    display_name: 'Local vLLM',
+    api: 'openai-responses',
+    base_url: 'https://llm.example.test/v1',
+    headers: [{name: 'x-region', value: 'us'}],
+    secret_header_names: ['authorization'],
+    models: [
+      {
+        id: 'llama-3.1',
+        label: 'Llama 3.1',
+        context_window: 128000,
+        max_output_tokens: 16384,
+      },
+    ],
+    default_model: 'llama-3.1',
+    created_at: '2026-05-08T00:00:00.000Z',
+    updated_at: '2026-05-08T00:00:00.000Z',
+  };
+}

package/src/components/custom-model-provider-payload.ts

@@ -0,0 +1,264 @@
+import type {
+  CreateCustomModelProviderBodyDto,
+  CustomAgentModelDto,
+  CustomModelProviderConfigDto,
+  DiscoverCustomModelProviderModelsBodyDto,
+  DiscoverCustomModelProviderModelsBySlugBodyDto,
+  ModelProviderApi,
+  UpdateCustomModelProviderBodyDto,
+} from '@shipfox/api-agent-dto';
+
+type CreateHeaderRequest = NonNullable<CreateCustomModelProviderBodyDto['headers']>[number];
+type UpdateHeaderRequest = NonNullable<UpdateCustomModelProviderBodyDto['headers']>[number];
+
+export interface CustomModelProviderHeaderFormValue {
+  client_id: string;
+  name: string;
+  value: string;
+  secret: boolean;
+  hasStoredValue: boolean;
+  storedName: string;
+}
+
+export interface CustomModelProviderModelFormValue {
+  client_id: string;
+  id: string;
+  label: string;
+  context_window: string;
+  max_output_tokens: string;
+  input_image: boolean;
+  reasoning: boolean;
+}
+
+export interface CustomModelProviderFormValues {
+  slug: string;
+  display_name: string;
+  api: ModelProviderApi;
+  base_url: string;
+  api_key: string;
+  headers: CustomModelProviderHeaderFormValue[];
+  models: CustomModelProviderModelFormValue[];
+  default_model: string;
+}
+
+export function createCustomModelProviderFormValues(): CustomModelProviderFormValues {
+  return {
+    slug: '',
+    display_name: '',
+    api: 'openai-completions',
+    base_url: '',
+    api_key: '',
+    headers: [],
+    models: [
+      {
+        client_id: createFormRowId(),
+        id: '',
+        label: '',
+        context_window: '',
+        max_output_tokens: '',
+        input_image: false,
+        reasoning: false,
+      },
+    ],
+    default_model: '',
+  };
+}
+
+export function editCustomModelProviderFormValues(
+  config: CustomModelProviderConfigDto,
+): CustomModelProviderFormValues {
+  return {
+    slug: config.provider_id,
+    display_name: config.display_name,
+    api: config.api,
+    base_url: config.base_url,
+    api_key: '',
+    headers: [
+      ...config.headers.map((header) => ({
+        client_id: createFormRowId(),
+        name: header.name,
+        value: header.value,
+        secret: false,
+        hasStoredValue: false,
+        storedName: header.name,
+      })),
+      ...config.secret_header_names.map((name) => ({
+        client_id: createFormRowId(),
+        name,
+        value: '',
+        secret: true,
+        hasStoredValue: true,
+        storedName: normalizeHeaderName(name),
+      })),
+    ],
+    models: config.models.map(modelFormValue),
+    default_model: config.default_model ?? '',
+  };
+}
+
+export function buildCreateCustomModelProviderBody(
+  values: CustomModelProviderFormValues,
+): CreateCustomModelProviderBodyDto {
+  return {
+    slug: values.slug.trim(),
+    display_name: values.display_name.trim(),
+    api: values.api,
+    base_url: values.base_url.trim(),
+    ...(values.api_key.trim() ? {api_key: values.api_key.trim()} : {}),
+    ...(requestHeaders(values.headers).length > 0 ? {headers: requestHeaders(values.headers)} : {}),
+    models: requestModels(values.models),
+    ...(values.default_model.trim() ? {default_model: values.default_model.trim()} : {}),
+  };
+}
+
+export function buildUpdateCustomModelProviderBody(
+  config: CustomModelProviderConfigDto,
+  values: CustomModelProviderFormValues,
+): UpdateCustomModelProviderBodyDto {
+  const body: UpdateCustomModelProviderBodyDto = {};
+  if (values.display_name.trim() !== config.display_name)
+    body.display_name = values.display_name.trim();
+  if (values.api !== config.api) body.api = values.api;
+  if (values.base_url.trim() !== config.base_url) body.base_url = values.base_url.trim();
+  if (values.api_key.trim()) body.api_key = values.api_key.trim();
+  if (customHeadersDirty(config, values.headers)) body.headers = updateHeaders(values.headers);
+  if (customModelsDirty(config, values.models)) body.models = requestModels(values.models);
+
+  const nextDefault = values.default_model.trim() || null;
+  if (nextDefault !== config.default_model) body.default_model = nextDefault;
+  return body;
+}
+
+export function customHeadersDirty(
+  config: CustomModelProviderConfigDto,
+  headers: CustomModelProviderHeaderFormValue[],
+): boolean {
+  return (
+    JSON.stringify(updateHeaders(headers)) !==
+    JSON.stringify([
+      ...config.headers.map((header) => ({
+        name: normalizeHeaderName(header.name),
+        value: header.value,
+        secret: false,
+      })),
+      ...config.secret_header_names.map((name) => ({
+        name: normalizeHeaderName(name),
+        secret: true,
+        keep: true,
+      })),
+    ])
+  );
+}
+
+export function customModelsDirty(
+  config: CustomModelProviderConfigDto,
+  models: CustomModelProviderModelFormValue[],
+): boolean {
+  return JSON.stringify(requestModels(models)) !== JSON.stringify(config.models);
+}
+
+export function buildDiscoverModelsBody(
+  values: CustomModelProviderFormValues,
+): DiscoverCustomModelProviderModelsBodyDto {
+  return {
+    api: values.api,
+    base_url: values.base_url.trim(),
+    ...(values.api_key.trim() ? {api_key: values.api_key.trim()} : {}),
+    ...(requestHeaders(values.headers).length > 0
+      ? {
+          headers: requestHeaders(values.headers).map(({name, value}) => ({
+            name,
+            value,
+          })),
+        }
+      : {}),
+  };
+}
+
+export function buildDiscoverModelsBySlugBody(
+  config: CustomModelProviderConfigDto,
+  values: CustomModelProviderFormValues,
+): DiscoverCustomModelProviderModelsBySlugBodyDto {
+  const body: DiscoverCustomModelProviderModelsBySlugBodyDto = {};
+  if (values.api !== config.api) body.api = values.api;
+  if (values.base_url.trim() !== config.base_url) body.base_url = values.base_url.trim();
+  if (values.api_key.trim()) body.api_key = values.api_key.trim();
+  body.headers = updateHeaders(values.headers);
+  return body;
+}
+
+export function formatBaseUrlHost(baseUrl: string): string {
+  try {
+    const url = new URL(baseUrl);
+    return url.host;
+  } catch {
+    return baseUrl;
+  }
+}
+
+export function createFormRowId(): string {
+  return crypto.randomUUID();
+}
+
+function updateHeaders(headers: CustomModelProviderHeaderFormValue[]): UpdateHeaderRequest[] {
+  const result: UpdateHeaderRequest[] = [];
+  for (const header of headers) {
+    const name = normalizeHeaderName(header.name);
+    if (!name) continue;
+    if (
+      header.secret &&
+      header.hasStoredValue &&
+      header.value.trim() === '' &&
+      name === header.storedName
+    ) {
+      result.push({name, secret: true, keep: true});
+      continue;
+    }
+    result.push({name, value: header.value.trim(), secret: header.secret});
+  }
+  return result;
+}
+
+function requestHeaders(headers: CustomModelProviderHeaderFormValue[]): CreateHeaderRequest[] {
+  return updateHeaders(headers).flatMap((header) =>
+    'value' in header && header.value
+      ? [{name: header.name, value: header.value, secret: header.secret}]
+      : [],
+  );
+}
+
+function requestModels(models: CustomModelProviderModelFormValue[]): CustomAgentModelDto[] {
+  return models.flatMap((model) => {
+    const id = model.id.trim();
+    const label = model.label.trim();
+    if (!id || !label) return [];
+    return [
+      {
+        id,
+        label,
+        ...(model.context_window.trim() ? {context_window: Number(model.context_window)} : {}),
+        ...(model.max_output_tokens.trim()
+          ? {max_output_tokens: Number(model.max_output_tokens)}
+          : {}),
+        ...(model.input_image ? {input_image: true} : {}),
+        ...(model.reasoning ? {reasoning: true} : {}),
+      },
+    ];
+  });
+}
+
+function modelFormValue(model: CustomAgentModelDto): CustomModelProviderModelFormValue {
+  return {
+    client_id: createFormRowId(),
+    id: model.id,
+    label: model.label,
+    context_window: model.context_window?.toString() ?? '',
+    max_output_tokens: model.max_output_tokens?.toString() ?? '',
+    input_image: model.input_image ?? false,
+    reasoning: model.reasoning ?? false,
+  };
+}
+
+function normalizeHeaderName(name: string): string {
+  return name.trim().toLowerCase();
+}

package/src/components/custom-model-provider-slug.test.ts

@@ -0,0 +1,40 @@
+import {
+  customModelProviderSlugError,
+  deriveCustomModelProviderSlug,
+} from './custom-model-provider-slug.js';
+
+describe('deriveCustomModelProviderSlug', () => {
+  test('derives lowercase dash-separated slugs from display names', () => {
+    const result = deriveCustomModelProviderSlug('My OpenAI Gateway!');
+
+    expect(result).toBe('my-openai-gateway');
+  });
+
+  test('removes accents and trims dash boundaries', () => {
+    const result = deriveCustomModelProviderSlug('  Équipe LLM  ');
+
+    expect(result).toBe('equipe-llm');
+  });
+});
+
+describe('customModelProviderSlugError', () => {
+  test('accepts valid custom provider ids', () => {
+    const result = customModelProviderSlugError('local-vllm');
+
+    expect(result).toBeUndefined();
+  });
+
+  test('rejects reserved built-in provider ids', () => {
+    const result = customModelProviderSlugError('anthropic');
+
+    expect(result).toBe('This id is reserved for a built-in provider.');
+  });
+
+  test('rejects malformed provider ids', () => {
+    const result = customModelProviderSlugError('Local_VLLM');
+
+    expect(result).toBe(
+      'Use 3-40 lowercase letters, digits, and dashes; start and end with a letter or digit.',
+    );
+  });
+});

package/src/components/custom-model-provider-slug.ts

@@ -0,0 +1,23 @@
+import {isReservedModelProviderId, MODEL_PROVIDER_SLUG_PATTERN} from '@shipfox/api-agent-dto';
+
+const MAX_SLUG_LENGTH = 40;
+const SLUG_FORMAT_ERROR =
+  'Use 3-40 lowercase letters, digits, and dashes; start and end with a letter or digit.';
+
+export function deriveCustomModelProviderSlug(displayName: string): string {
+  return displayName
+    .normalize('NFKD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_SLUG_LENGTH)
+    .replace(/-+$/g, '');
+}
+
+export function customModelProviderSlugError(slug: string): string | undefined {
+  const trimmed = slug.trim();
+  if (!MODEL_PROVIDER_SLUG_PATTERN.test(trimmed)) return SLUG_FORMAT_ERROR;
+  if (isReservedModelProviderId(trimmed)) return 'This id is reserved for a built-in provider.';
+  return undefined;
+}

package/src/components/default-model-field.tsx

@@ -0,0 +1,85 @@
+import type {ModelProviderCatalogEntryDto} from '@shipfox/api-agent-dto';
+import {FormField, useFormField} from '@shipfox/react-ui/form-field';
+import {cn} from '@shipfox/react-ui/utils';
+import type {ComponentProps, ReactNode} from 'react';
+
+export const LATEST_MODEL_VALUE = '__latest__';
+
+export function DefaultModelField({
+  entry,
+  value,
+  error,
+  children,
+  onChange,
+  onBlur,
+}: {
+  entry: ModelProviderCatalogEntryDto;
+  value: string;
+  error: string | undefined;
+  children?: ReactNode;
+  onChange: ComponentProps<'select'>['onChange'];
+  onBlur: ComponentProps<'select'>['onBlur'];
+}) {
+  return (
+    <FormField
+      label="Default model"
+      id={`model-provider-${entry.id}-default-model`}
+      error={error}
+      description={defaultModelDescription(entry, value)}
+    >
+      <FormFieldSelect value={value} onChange={onChange} onBlur={onBlur}>
+        <option value={LATEST_MODEL_VALUE}>Latest</option>
+        {entry.models.map((model) => (
+          <option key={model.id} value={model.id}>
+            {model.label}
+          </option>
+        ))}
+      </FormFieldSelect>
+      {children}
+    </FormField>
+  );
+}
+
+export function defaultModelFormValue(defaultModel: string | null | undefined): string {
+  return defaultModel ?? LATEST_MODEL_VALUE;
+}
+
+export function selectedModelForCredentialsPayload(selectedModel: string): string | null {
+  return selectedModel === LATEST_MODEL_VALUE ? null : selectedModel.trim();
+}
+
+export function selectedModelForModelPayload(selectedModel: string): string | null {
+  return selectedModel === LATEST_MODEL_VALUE ? null : selectedModel.trim();
+}
+
+function defaultModelLabel(entry: ModelProviderCatalogEntryDto): string {
+  const defaultModel = entry.default_model ?? entry.models[0]?.id ?? '';
+  return entry.models.find((model) => model.id === defaultModel)?.label ?? defaultModel;
+}
+
+function defaultModelDescription(
+  entry: ModelProviderCatalogEntryDto,
+  selectedModel: string | undefined,
+): string | undefined {
+  if (selectedModel === LATEST_MODEL_VALUE) {
+    return `Latest follows the provider catalog default. Currently resolves to ${defaultModelLabel(entry)}.`;
+  }
+  if (!selectedModel) return undefined;
+  return selectedModel;
+}
+
+export function FormFieldSelect({className, ...props}: ComponentProps<'select'>) {
+  const wiring = useFormField();
+  return (
+    <select
+      className={cn(
+        'w-full min-w-0 rounded-6 bg-background-field-base px-8 py-6 text-sm leading-20 text-foreground-neutral-base shadow-button-neutral outline-none transition-[color,box-shadow]',
+        'hover:bg-background-field-hover focus-visible:shadow-border-interactive-with-active disabled:cursor-not-allowed disabled:bg-background-neutral-disabled disabled:text-foreground-neutral-disabled',
+        'aria-invalid:shadow-border-error',
+        className,
+      )}
+      {...props}
+      {...wiring}
+    />
+  );
+}