@k2b/cloud 0.10.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -89,50 +89,49 @@
     "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
   },
   "dependencies": {
-    "@firecrawl/anydoc": "0.1.9",
-    "@napi-rs/canvas": "1.0.8",
+    "@firecrawl/anydoc": "0.2.4",
+    "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
     "@hono/standard-validator": "0.2.2",
-    "@simplewebauthn/server": "13.3.2",
-    "@tabler/icons": "3.46.0",
+    "@simplewebauthn/server": "14.0.2",
+    "@tabler/icons": "3.47.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
-    "@k2b/ui": "0.4.2",
+    "@k2b/ui": "0.5.0",
     "@k2b/stdlib": "0.25.0",
     "@k2b/sync": "6.4.0",
     "@nats-io/transport-node": "3.4.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.1",
-    "jose": "6.2.5",
-    "katex": "0.16.47",
-    "liquidjs": "10.27.2",
+    "jose": "6.2.12",
+    "katex": "0.18.7",
+    "liquidjs": "10.29.0",
     "marked": "17.0.6",
     "mermaid": "11.16.0",
-    "nodemailer": "9.1.1",
-    "postcss": "8.5.25",
+    "nodemailer": "10.0.10",
+    "postcss": "8.5.28",
     "reflect-metadata": "0.2.2",
-    "sanitize-html": "2.17.6",
-    "seroval": "1.6.0",
+    "sanitize-html": "2.17.7",
+    "seroval": "1.6.7",
     "tailwindcss": "4.3.3",
     "web-push": "3.6.7",
-    "web-vitals": "6.2.1",
-    "yaml": "2.9.0",
+    "web-vitals": "6.2.2",
+    "yaml": "2.9.1",
     "hash-wasm": "4.12.0",
-    "@types/nodemailer": "7.0.12",
     "@types/sanitize-html": "2.16.1",
     "@types/web-push": "3.6.4"
   },
   "devDependencies": {
-    "@babel/core": "7.29.7",
-    "@babel/preset-typescript": "7.29.7",
+    "@babel/core": "8.0.6",
+    "@babel/preset-typescript": "8.0.1",
     "@types/bun": "1.4.2",
-    "babel-preset-solid": "1.9.12",
-    "hono": "4.12.32",
-    "solid-js": "1.9.14",
+    "babel-preset-solid": "1.9.15",
+    "hono": "4.13.8",
+    "solid-js": "1.9.15",
     "typescript": "5.9.3",
-    "zod": "4.6.2"
+    "zod": "4.6.5"
   },
   "peerDependencies": {
     "hono": "^4.12.25",

package/src/ai/settings-messages.ts

@@ -0,0 +1,129 @@
+import { i18n } from "@k2b/stdlib";
+import type { AiModelReferenceSetting, AiSettingsIssue } from "./settings";
+
+type Reference = { setting: string; profile: string; next: string };
+
+const catalog = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      notSaved: "The AI settings were not saved. Resolve the problems below and save again.",
+      defaultModel: "default model",
+      backgroundModel: "background model",
+      workflowModel: "workflow model",
+      visionModel: "Vision tool model",
+      audioModel: "audio model",
+      selectAnother: ({ setting }: { setting: string }) => `Select another ${setting}`,
+      useDefaultModel: "use the default model instead",
+      useBackgroundModel: "use the background model instead",
+      disableVisionFallback: "disable the view_image fallback",
+      disableAudio: "disable audio transcription",
+      or: ({ first, second }: { first: string; second: string }) => `${first} or ${second}`,
+      modelRequired: "Choose a default model while AI is enabled.",
+      profileMissing: ({ setting, profile, next }: Reference) =>
+        `The ${setting} still references “${profile}”. ${next} before removing this profile.`,
+      profileDisabled: ({ setting, profile, next }: Reference) =>
+        `The ${setting} uses “${profile}”, which is disabled. ${next}, or enable the profile again.`,
+      noVision: ({ setting, profile, next }: Reference) => `“${profile}” does not support Vision, so it cannot be the ${setting}. ${next}.`,
+      transcriptionOnly: ({ setting, profile, next }: Reference) =>
+        `“${profile}” only transcribes audio, so it cannot be the ${setting}. ${next}.`,
+      noTranscription: ({ setting, profile, next }: Reference) =>
+        `“${profile}” does not transcribe audio, so it cannot be the ${setting}. ${next}.`,
+      credentialMissing: ({ profile }: { profile: string }) =>
+        `“${profile}” needs a provider API key. Enter the key in the profile or disable the profile.`,
+    },
+    de: {
+      notSaved: "Die KI-Einstellungen wurden nicht gespeichert. Behebe die folgenden Probleme und speichere erneut.",
+      defaultModel: "Standardmodell",
+      backgroundModel: "Hintergrundmodell",
+      workflowModel: "Workflow-Modell",
+      visionModel: "Modell für das Bildwerkzeug",
+      audioModel: "Audio-Modell",
+      selectAnother: ({ setting }) => `Wähle ein anderes ${setting}`,
+      useDefaultModel: "verwende stattdessen das Standardmodell",
+      useBackgroundModel: "verwende stattdessen das Hintergrundmodell",
+      disableVisionFallback: "deaktiviere den view_image-Fallback",
+      disableAudio: "deaktiviere die Audio-Transkription",
+      or: ({ first, second }) => `${first} oder ${second}`,
+      modelRequired: "Wähle ein Standardmodell, solange KI aktiviert ist.",
+      profileMissing: ({ setting, profile, next }) =>
+        `Das ${setting} verweist noch auf „${profile}“. ${next}, bevor du dieses Profil entfernst.`,
+      profileDisabled: ({ setting, profile, next }) =>
+        `Das ${setting} verwendet „${profile}“, aber dieses Profil ist deaktiviert. ${next}. Du kannst das Profil auch wieder aktivieren.`,
+      noVision: ({ setting, profile, next }) =>
+        `„${profile}“ unterstützt keine Bildverarbeitung und kann nicht als ${setting} verwendet werden. ${next}.`,
+      transcriptionOnly: ({ setting, profile, next }) =>
+        `„${profile}“ transkribiert nur Audio und kann nicht als ${setting} verwendet werden. ${next}.`,
+      noTranscription: ({ setting, profile, next }) =>
+        `„${profile}“ transkribiert kein Audio und kann nicht als ${setting} verwendet werden. ${next}.`,
+      credentialMissing: ({ profile }) =>
+        `„${profile}“ benötigt einen API-Schlüssel des Anbieters. Gib den Schlüssel im Profil ein oder deaktiviere das Profil.`,
+    },
+  },
+});
+
+type Messages = ReturnType<typeof catalog.resolve>["t"];
+
+const settingNoun = (t: Messages, setting: AiModelReferenceSetting): string =>
+  ({
+    "ai.default_model_id": t.defaultModel,
+    "ai.background_model_id": t.backgroundModel,
+    "ai.workflow_model_id": t.workflowModel,
+    "ai.vision_model_id": t.visionModel,
+    "ai.audio_model_id": t.audioModel,
+  })[setting];
+
+/** The way out that keeps the feature working without this profile, if the setting is optional. */
+const alternative = (t: Messages, setting: AiModelReferenceSetting): string | undefined =>
+  ({
+    "ai.default_model_id": undefined,
+    "ai.background_model_id": t.useDefaultModel,
+    "ai.workflow_model_id": t.useBackgroundModel,
+    "ai.vision_model_id": t.disableVisionFallback,
+    "ai.audio_model_id": t.disableAudio,
+  })[setting];
+
+export type AiSettingsIssueWithMessage = AiSettingsIssue & { message: string };
+
+/**
+ * Turn validation issues into request-localized, actionable messages.
+ *
+ * `profiles` should list the prospective profiles first and the stored ones
+ * after them, so a profile that is being removed still has its label. Only
+ * ids and labels are read; provider keys never reach the messages.
+ */
+export const describeAiSettingsIssues = (
+  issues: readonly AiSettingsIssue[],
+  options: { locale?: string | null; profiles: ReadonlyArray<{ id: string; label: string }> },
+): { issues: AiSettingsIssueWithMessage[]; errors: Record<string, string> } => {
+  const t = catalog.resolve(options.locale ? [options.locale] : []).t;
+  const labelOf = (profileId: string) => options.profiles.find((profile) => profile.id === profileId)?.label ?? profileId;
+
+  const described = issues.map((issue): AiSettingsIssueWithMessage => {
+    if (issue.code === "model_required") return { ...issue, message: t.modelRequired };
+    const profile = labelOf(issue.profileId);
+    if (issue.code === "provider_credential_missing") return { ...issue, message: t.credentialMissing({ profile }) };
+
+    const setting = settingNoun(t, issue.setting);
+    const other = alternative(t, issue.setting);
+    const select = t.selectAnother({ setting });
+    const reference = { setting, profile, next: other ? t.or({ first: select, second: other }) : select };
+    if (issue.code === "model_profile_missing") return { ...issue, message: t.profileMissing(reference) };
+    if (issue.code === "model_profile_disabled") return { ...issue, message: t.profileDisabled(reference) };
+    const message =
+      issue.setting === "ai.vision_model_id"
+        ? t.noVision(reference)
+        : issue.setting === "ai.audio_model_id"
+          ? t.noTranscription(reference)
+          : t.transcriptionOnly(reference);
+    return { ...issue, message };
+  });
+
+  const errors: Record<string, string> = {};
+  for (const issue of described)
+    errors[issue.setting] = errors[issue.setting] ? `${errors[issue.setting]} ${issue.message}` : issue.message;
+  return { issues: described, errors };
+};
+
+export const aiSettingsNotSavedMessage = (locale?: string | null): string => catalog.resolve(locale ? [locale] : []).t.notSaved;
+export const checkAiSettingsMessages = () => catalog.check();

package/src/ai/settings.ts

@@ -185,6 +185,27 @@ export const parseAiModelProfiles = (rawJson: string): { profiles: AiModelProfil
   return { profiles };
 };
 
+export type AiModelReferenceSetting =
+  | "ai.default_model_id"
+  | "ai.background_model_id"
+  | "ai.workflow_model_id"
+  | "ai.vision_model_id"
+  | "ai.audio_model_id";
+
+/**
+ * One reason why a prospective AI configuration cannot be saved. Codes and
+ * profile ids are stable and locale-free; the admin route turns them into
+ * request-localized messages.
+ */
+export type AiSettingsIssue =
+  | { code: "model_required"; setting: AiModelReferenceSetting }
+  | {
+      code: "model_profile_missing" | "model_profile_disabled" | "model_profile_incompatible";
+      setting: AiModelReferenceSetting;
+      profileId: string;
+    }
+  | { code: "provider_credential_missing"; setting: "ai.model_profiles_json"; profileId: string };
+
 export const validateAiSettingsConfiguration = (input: {
   enabled: boolean;
   defaultModelId: string;
@@ -194,51 +215,41 @@ export const validateAiSettingsConfiguration = (input: {
   workflowModelId: string;
   profiles: readonly AiModelProfile[];
   credentialProfileIds: readonly string[];
-}): Record<string, string> => {
-  if (!input.enabled) return {};
-
-  const errors: Record<string, string> = {};
-  const enabledProfiles = input.profiles.filter((profile) => profile.enabled);
-  const defaultProfile = input.profiles.find((profile) => profile.id === input.defaultModelId);
-  if (!input.defaultModelId || !defaultProfile?.enabled || defaultProfile.capabilities.includes("transcription")) {
-    errors["ai.default_model_id"] = "Choose an enabled model profile.";
-  }
-
-  if (input.backgroundModelId) {
-    const backgroundProfile = input.profiles.find((profile) => profile.id === input.backgroundModelId);
-    if (!backgroundProfile?.enabled || backgroundProfile.capabilities.includes("transcription"))
-      errors["ai.background_model_id"] = "Choose an enabled chat model profile or use the platform default.";
-  }
-
-  if (input.visionModelId) {
-    const visionProfile = input.profiles.find((profile) => profile.id === input.visionModelId);
-    if (!visionProfile?.enabled || !visionProfile.capabilities.includes("vision")) {
-      errors["ai.vision_model_id"] = "Choose an enabled model profile with Vision support or disable the fallback.";
+}): AiSettingsIssue[] => {
+  if (!input.enabled) return [];
+
+  const issues: AiSettingsIssue[] = [];
+  const isChatModel = (profile: AiModelProfile) => !profile.capabilities.includes("transcription");
+  const checkReference = (
+    setting: AiModelReferenceSetting,
+    profileId: string | undefined,
+    fits: (profile: AiModelProfile) => boolean,
+    required = false,
+  ) => {
+    if (!profileId) {
+      if (required) issues.push({ code: "model_required", setting });
+      return;
     }
-  }
-
-  if (input.workflowModelId) {
-    const workflowProfile = input.profiles.find((profile) => profile.id === input.workflowModelId);
-    if (!workflowProfile?.enabled || workflowProfile.capabilities.includes("transcription"))
-      errors["ai.workflow_model_id"] = "Choose an enabled chat model profile or use the background model.";
-  }
+    const profile = input.profiles.find((item) => item.id === profileId);
+    if (!profile) issues.push({ code: "model_profile_missing", setting, profileId });
+    else if (!profile.enabled) issues.push({ code: "model_profile_disabled", setting, profileId });
+    else if (!fits(profile)) issues.push({ code: "model_profile_incompatible", setting, profileId });
+  };
 
-  if (input.audioModelId) {
-    const audioProfile = input.profiles.find((profile) => profile.id === input.audioModelId);
-    if (!audioProfile?.enabled || !audioProfile.capabilities.includes("transcription")) {
-      errors["ai.audio_model_id"] = "Choose an enabled audio transcription profile or disable audio transcription.";
-    }
-  }
+  checkReference("ai.default_model_id", input.defaultModelId, isChatModel, true);
+  checkReference("ai.background_model_id", input.backgroundModelId, isChatModel);
+  checkReference("ai.workflow_model_id", input.workflowModelId, isChatModel);
+  checkReference("ai.vision_model_id", input.visionModelId, (profile) => profile.capabilities.includes("vision"));
+  checkReference("ai.audio_model_id", input.audioModelId, (profile) => profile.capabilities.includes("transcription"));
 
   const configured = new Set(input.credentialProfileIds);
-  const missingCredentials = enabledProfiles.filter(
-    (profile) => providerRequiresCredential(profile.provider) && !configured.has(profile.id),
-  );
-  if (missingCredentials.length > 0) {
-    errors["ai.model_profiles_json"] = `Enter a provider API key for: ${missingCredentials.map((profile) => profile.label).join(", ")}.`;
+  for (const profile of input.profiles) {
+    if (profile.enabled && providerRequiresCredential(profile.provider) && !configured.has(profile.id)) {
+      issues.push({ code: "provider_credential_missing", setting: "ai.model_profiles_json", profileId: profile.id });
+    }
   }
 
-  return errors;
+  return issues;
 };
 
 export const planAiProfileCredentials = (input: {

package/src/api/admin-core-settings.ts

@@ -20,7 +20,8 @@ import {
   splitAiModelAccess,
 } from "../ai/model-access";
 import { parseAiModelProfiles, planAiProfileCredentials, validateAiSettingsConfiguration } from "../ai/settings";
-import { type AuthContext, auth, jsonResponse, requiresAdmin, v } from "../server";
+import { type AiSettingsIssueWithMessage, aiSettingsNotSavedMessage, describeAiSettingsIssues } from "../ai/settings-messages";
+import { type AuthContext, auth, getLocale, jsonResponse, requiresAdmin, v } from "../server";
 import { settingsDeleteLegacyKeys, settingsListLegacyKeys } from "../services";
 import { readAccountCategoryPolicy } from "../services/account-category-policy";
 import { audit } from "../services/audit";
@@ -97,6 +98,8 @@ const storeAiCredentials = async (
 
 type AiSettingsMutationPlan = {
   errors: FieldErrors;
+  /** Structured validation issues with stable codes; `errors` carries the same messages keyed by setting. */
+  issues?: AiSettingsIssueWithMessage[];
   keepCredentialProfileIds?: string[];
   modelProfileIds?: string[];
 };
@@ -111,6 +114,7 @@ const prepareAiSettingsMutation = async (
   updates: Record<string, unknown>,
   resets: readonly string[],
   aiSplit: ReturnType<typeof splitAiProfileCredentials>,
+  locale: string,
 ): Promise<AiSettingsMutationPlan> => {
   const keys = [...Object.keys(updates), ...resets];
   if (!keys.some((key) => AI_CONFIGURATION_KEYS.has(key))) return { errors: {} };
@@ -164,7 +168,7 @@ const prepareAiSettingsMutation = async (
     keepCredentialProfileIds = credentialPlan.keepCredentialProfileIds;
   }
 
-  const errors = validateAiSettingsConfiguration({
+  const issues = validateAiSettingsConfiguration({
     enabled: nextEnabled,
     defaultModelId: String(valueAfterMutation(AI_DEFAULT_MODEL_KEY, currentDefaultModelId ?? "", updates, resets)),
     backgroundModelId: String(valueAfterMutation(AI_BACKGROUND_MODEL_KEY, currentBackgroundModelId ?? "", updates, resets)),
@@ -174,8 +178,11 @@ const prepareAiSettingsMutation = async (
     profiles: nextParsed.profiles,
     credentialProfileIds: keepCredentialProfileIds ?? existingCredentialProfileIds,
   });
+  // Stored profiles come second so a profile that is being removed keeps its label.
+  const described = describeAiSettingsIssues(issues, { locale, profiles: [...nextParsed.profiles, ...currentParsed.profiles] });
   return {
-    errors,
+    errors: described.errors,
+    issues: described.issues,
     keepCredentialProfileIds,
     modelProfileIds: profilesUpdated || profilesReset ? nextParsed.profiles.map((profile) => profile.id) : undefined,
   };
@@ -405,13 +412,13 @@ const app = new Hono<AuthContext>()
 
     let aiPlan: AiSettingsMutationPlan;
     try {
-      aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit);
+      aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit, getLocale(c));
     } catch (error) {
       console.error("[settings] failed to validate the prospective AI configuration", error);
       return c.json({ message: "Failed to validate AI settings" }, 500);
     }
     if (Object.keys(aiPlan.errors).length > 0) {
-      return c.json({ message: "Invalid AI configuration", errors: aiPlan.errors }, 400);
+      return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
     }
 
     const fieldErrors: FieldErrors = {};
@@ -491,13 +498,13 @@ const app = new Hono<AuthContext>()
 
     let aiPlan: AiSettingsMutationPlan;
     try {
-      aiPlan = await prepareAiSettingsMutation({}, [key], null);
+      aiPlan = await prepareAiSettingsMutation({}, [key], null, getLocale(c));
     } catch (error) {
       console.error("[settings] failed to validate the prospective AI configuration", error);
       return c.json({ message: "Failed to validate AI settings" }, 500);
     }
     if (Object.keys(aiPlan.errors).length > 0) {
-      return c.json({ message: "Invalid AI configuration", errors: aiPlan.errors }, 400);
+      return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
     }
 
     try {

package/src/services/document-extraction.ts

@@ -106,6 +106,8 @@ const mapConversionError = (error: unknown, format: DocumentFormat): DocumentExt
     case "malformed":
     case "missingPart":
       return new DocumentExtractionError("malformed", "The document is malformed or incomplete.");
+    case "needsOcr":
+      return new DocumentExtractionError("ocr_required", "The PDF has no readable text and requires OCR.");
     case "unsupported":
       return format === "pdf"
         ? new DocumentExtractionError("ocr_required", "The PDF has no readable text and requires OCR.")

package/src/services/webauthn.ts

@@ -1,7 +1,6 @@
 import { err, fail, ok, type Result } from "@k2b/stdlib";
 import {
   type AuthenticationResponseJSON,
-  type AuthenticatorTransportFuture,
   generateAuthenticationOptions,
   generateRegistrationOptions,
   type PublicKeyCredentialCreationOptionsJSON,
@@ -137,7 +136,7 @@ const toCredential = (row: DbPasskeyRow): WebAuthnCredential => ({
   id: row.credential_id,
   publicKey: new Uint8Array(row.public_key) as WebAuthnCredential["publicKey"],
   counter: Number(row.counter),
-  transports: (row.transports ?? []) as AuthenticatorTransportFuture[],
+  transports: row.transports ?? [],
 });
 
 const isExpired = (date: Date | null): boolean => Boolean(date && date.getTime() <= Date.now());
@@ -176,7 +175,7 @@ export const beginRegistration = async (params: { user: User }): Promise<Result<
     },
     excludeCredentials: existing.map((credential) => ({
       id: credential.credentialId,
-      transports: credential.transports as AuthenticatorTransportFuture[],
+      transports: credential.transports,
     })),
   });