create-nextblock 0.2.78 → 0.8.1

package/templates/nextblock-template/lib/ai-client.ts

@@ -0,0 +1,247 @@
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { getServiceRoleSupabaseClient } from '@nextblock-cms/db/server';
+import { generateText, type LanguageModel } from 'ai';
+
+import {
+  CORTEX_AI_OPENROUTER_MODEL_SELECTION_SETTING_KEY,
+  CORTEX_AI_OPENROUTER_SETTING_KEY,
+  CORTEX_AI_PACKAGE_NAME,
+  decryptStoredOpenRouterApiKey,
+  getOpenRouterEnvApiKey,
+} from './ai-config';
+import {
+  buildCortexAiRoutingPolicy,
+  CORTEX_AI_OPENROUTER_BASE_URL,
+  omitUnsupportedCortexAiModelOptions,
+  safeParseCortexAiModelSelection,
+  type CortexAiModelAttempt,
+  type CortexAiOpenRouterModelId,
+  type CortexAiStoredModelSelection,
+  runWithCortexAiModelFallback,
+} from './ai-model-registry';
+
+type AiGenerateTextOptions = Omit<Parameters<typeof generateText>[0], 'model'>;
+type AiGenerateTextResult = Awaited<ReturnType<typeof generateText>>;
+type FetchFunction = typeof globalThis.fetch;
+
+const SERVER_ONLY_ERROR_MESSAGE =
+  'Cortex AI OpenRouter client can only be imported from server-side code.';
+
+if (typeof window !== 'undefined') {
+  throw new Error(SERVER_ONLY_ERROR_MESSAGE);
+}
+
+export type CortexAiOpenRouterCredentialSource = 'env' | 'stored' | 'manual' | 'none';
+
+export type CortexAiOpenRouterCredential = {
+  apiKey: string | null;
+  source: CortexAiOpenRouterCredentialSource;
+};
+
+export type CortexAiOpenRouterClient = {
+  credentialSource: Exclude<CortexAiOpenRouterCredentialSource, 'none'>;
+  model: (modelId?: CortexAiOpenRouterModelId) => LanguageModel;
+  modelSelection: CortexAiStoredModelSelection | null;
+};
+
+export type CortexAiGenerateTextOptions = AiGenerateTextOptions & {
+  apiKey?: string;
+  fallbackModelIds?: readonly CortexAiOpenRouterModelId[];
+  modelId?: CortexAiOpenRouterModelId;
+};
+
+export type CortexAiGenerateTextResult = {
+  attempts: readonly CortexAiModelAttempt[];
+  credentialSource: Exclude<CortexAiOpenRouterCredentialSource, 'none'>;
+  modelId: CortexAiOpenRouterModelId;
+  result: AiGenerateTextResult;
+};
+
+function buildOpenRouterHeaders() {
+  const referer = process.env.NEXT_PUBLIC_URL?.trim() || 'https://nextblock.dev';
+
+  return {
+    'HTTP-Referer': referer,
+    'X-Title': CORTEX_AI_PACKAGE_NAME,
+  };
+}
+
+export function createCortexAiOpenRouterProvider(params: {
+  apiKey: string;
+  fetch?: FetchFunction;
+}) {
+  return createOpenAICompatible<string, string, string, string>({
+    apiKey: params.apiKey,
+    baseURL: CORTEX_AI_OPENROUTER_BASE_URL,
+    fetch: params.fetch,
+    headers: buildOpenRouterHeaders(),
+    includeUsage: true,
+    name: 'openrouter',
+    supportsStructuredOutputs: true,
+  });
+}
+
+async function readStoredOpenRouterApiKey() {
+  const supabase = getServiceRoleSupabaseClient();
+  const { data, error } = await supabase
+    .from('site_settings')
+    .select('value')
+    .eq('key', CORTEX_AI_OPENROUTER_SETTING_KEY)
+    .maybeSingle();
+
+  if (error) {
+    throw new Error(`Failed to load stored Cortex AI OpenRouter key: ${error.message}`);
+  }
+
+  if (!data?.value) {
+    return null;
+  }
+
+  return decryptStoredOpenRouterApiKey(data.value);
+}
+
+export async function getStoredCortexAiModelSelection(): Promise<CortexAiStoredModelSelection | null> {
+  const supabase = getServiceRoleSupabaseClient();
+  const { data, error } = await supabase
+    .from('site_settings')
+    .select('value')
+    .eq('key', CORTEX_AI_OPENROUTER_MODEL_SELECTION_SETTING_KEY)
+    .maybeSingle();
+
+  if (error) {
+    throw new Error(`Failed to load Cortex AI OpenRouter model selection: ${error.message}`);
+  }
+
+  return safeParseCortexAiModelSelection(data?.value);
+}
+
+export async function resolveCortexAiOpenRouterCredential(params?: {
+  apiKey?: string;
+}): Promise<CortexAiOpenRouterCredential> {
+  const manualApiKey = params?.apiKey?.trim();
+
+  if (manualApiKey) {
+    return {
+      apiKey: manualApiKey,
+      source: 'manual',
+    };
+  }
+
+  const storedApiKey = await readStoredOpenRouterApiKey();
+
+  if (storedApiKey) {
+    return {
+      apiKey: storedApiKey,
+      source: 'stored',
+    };
+  }
+
+  const envApiKey = getOpenRouterEnvApiKey();
+
+  if (envApiKey) {
+    return {
+      apiKey: envApiKey,
+      source: 'env',
+    };
+  }
+
+  return {
+    apiKey: null,
+    source: 'none',
+  };
+}
+
+export async function createCortexAiOpenRouterClient(params?: {
+  apiKey?: string;
+  fetch?: FetchFunction;
+  modelSelection?: CortexAiStoredModelSelection | null;
+}) {
+  const credential = await resolveCortexAiOpenRouterCredential({
+    apiKey: params?.apiKey,
+  });
+
+  if (!credential.apiKey || credential.source === 'none') {
+    throw new Error(
+      'Cortex AI requires OPENROUTER_API_KEY or an encrypted OpenRouter BYOK in site settings.'
+    );
+  }
+
+  const provider = createCortexAiOpenRouterProvider({
+    apiKey: credential.apiKey,
+    fetch: params?.fetch,
+  });
+  const modelSelection =
+    params?.modelSelection !== undefined
+      ? params.modelSelection
+      : credential.source === 'stored'
+        ? await getStoredCortexAiModelSelection()
+        : null;
+
+  return {
+    credentialSource: credential.source,
+    model: (modelId?: CortexAiOpenRouterModelId) => provider.chatModel(modelId || 'openrouter/free'),
+    modelSelection,
+  };
+}
+
+export async function generateCortexAiText({
+  apiKey,
+  fallbackModelIds,
+  modelId,
+  ...options
+}: CortexAiGenerateTextOptions & { modelSelection?: CortexAiStoredModelSelection | null }): Promise<CortexAiGenerateTextResult> {
+  const client = await createCortexAiOpenRouterClient({ apiKey, modelSelection: options.modelSelection });
+  const routingPolicy = buildCortexAiRoutingPolicy({
+    credentialSource: client.credentialSource,
+    fallbackModelIds,
+    requestedModelId: modelId,
+    selectedModel: client.modelSelection,
+  });
+
+  const generation = await runWithCortexAiModelFallback({
+    modelIds: routingPolicy.modelIds,
+    execute: (attemptModelId) => {
+      const attemptOptions = omitUnsupportedCortexAiModelOptions(
+        {
+          ...options,
+          maxRetries: 0,
+        } as Record<string, unknown>,
+        {
+          modelId: attemptModelId,
+          modelSelection: routingPolicy.modelSelection,
+        }
+      );
+
+      return generateText({
+        ...attemptOptions,
+        model: client.model(attemptModelId),
+      } as Parameters<typeof generateText>[0]);
+    },
+  });
+
+  return {
+    attempts: generation.attempts,
+    credentialSource: client.credentialSource,
+    modelId: generation.modelId,
+    result: generation.result,
+  };
+}
+
+export {
+  buildCortexAiModelFallbackChain,
+  buildCortexAiRoutingPolicy,
+  CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY,
+  CORTEX_AI_MODEL_REGISTRY,
+  CORTEX_AI_OPENROUTER_BASE_URL,
+  CORTEX_AI_OPENROUTER_FREE_ROUTER_MODEL,
+  CORTEX_AI_REQUIRED_MODEL_PARAMETERS,
+  CortexAiRoutingError,
+  isOpenRouterRecoverableRoutingError,
+  isOpenRouterRateLimitError,
+  omitUnsupportedCortexAiModelOptions,
+  runWithCortexAiModelFallback,
+  summarizeCortexAiRoutingError,
+} from './ai-model-registry';
+export {
+  listCortexAiCompatibleOpenRouterModels,
+} from './ai-model-catalog';

package/templates/nextblock-template/lib/ai-config.ts

@@ -0,0 +1,81 @@
+import {
+  decryptOpenRouterApiKey,
+  encryptOpenRouterApiKey,
+  getMaskedOpenRouterKey,
+  getOpenRouterKeyEnvelopeStatus,
+  type EncryptedOpenRouterKeyEnvelope,
+} from './ai-key-crypto';
+
+const SERVER_ONLY_ERROR_MESSAGE =
+  'Cortex AI configuration can only be imported from server-side code.';
+
+if (typeof window !== 'undefined') {
+  throw new Error(SERVER_ONLY_ERROR_MESSAGE);
+}
+
+export const CORTEX_AI_PACKAGE_ID = 'cortex-ai';
+export const CORTEX_AI_PACKAGE_NAME = 'NextBlock Cortex AI';
+export const CORTEX_AI_OPENROUTER_SETTING_KEY = 'cortex_ai_openrouter_api_key';
+export const CORTEX_AI_OPENROUTER_MODEL_SELECTION_SETTING_KEY =
+  'cortex_ai_openrouter_model_selection';
+
+function readEnvValue(name: string) {
+  return process.env[name]?.trim() || null;
+}
+
+export function getOpenRouterEnvApiKey() {
+  return readEnvValue('OPENROUTER_API_KEY');
+}
+
+export function getCortexAiEnvConfig() {
+  const openRouterApiKey = getOpenRouterEnvApiKey();
+
+  return {
+    encryptionKey: readEnvValue('CORTEX_AI_ENCRYPTION_KEY'),
+    freemiusSandboxKey: readEnvValue('FREEMIUS_AI_SANDBOX_KEY'),
+    hasEncryptionKey: Boolean(readEnvValue('CORTEX_AI_ENCRYPTION_KEY')),
+    hasOpenRouterEnvKey: Boolean(openRouterApiKey),
+    openRouterEnvKeyLast4: openRouterApiKey ? openRouterApiKey.slice(-4) : null,
+  };
+}
+
+function requireEncryptionKey() {
+  const encryptionKey = readEnvValue('CORTEX_AI_ENCRYPTION_KEY');
+
+  if (!encryptionKey) {
+    throw new Error('CORTEX_AI_ENCRYPTION_KEY is required to manage stored OpenRouter keys.');
+  }
+
+  return encryptionKey;
+}
+
+export function encryptStoredOpenRouterApiKey(apiKey: string) {
+  return encryptOpenRouterApiKey({
+    apiKey,
+    encryptionSecret: requireEncryptionKey(),
+  });
+}
+
+export function decryptStoredOpenRouterApiKey(encryptedKey: unknown) {
+  return decryptOpenRouterApiKey({
+    encryptedKey,
+    encryptionSecret: requireEncryptionKey(),
+  });
+}
+
+export function getStoredOpenRouterKeyStatus(value: unknown) {
+  return getOpenRouterKeyEnvelopeStatus(value);
+}
+
+export function getEnvOpenRouterKeyStatus() {
+  const env = getCortexAiEnvConfig();
+
+  return {
+    hasEnvOpenRouterKey: env.hasOpenRouterEnvKey,
+    maskedEnvOpenRouterKey: env.openRouterEnvKeyLast4
+      ? getMaskedOpenRouterKey(env.openRouterEnvKeyLast4)
+      : null,
+  };
+}
+
+export type { EncryptedOpenRouterKeyEnvelope };

package/templates/nextblock-template/lib/ai-cortex-widget-builder.ts

@@ -0,0 +1,125 @@
+import { generateObject } from 'ai';
+
+import {
+  buildCortexAiRoutingPolicy,
+  createCortexAiOpenRouterClient,
+} from './ai-client';
+import {
+  getHttpStatusCode,
+  isOpenRouterRecoverableRoutingError,
+  omitUnsupportedCortexAiModelOptions,
+  runWithCortexAiModelFallback,
+  type CortexAiModelAttempt,
+  type CortexAiOpenRouterModelId,
+  type CortexAiStoredModelSelection,
+} from './ai-model-registry';
+import {
+  buildCortexWidgetBuilderPrompt,
+  buildCortexWidgetBuilderSystemPrompt,
+  cortexWidgetBuildRequestSchema,
+  validateCortexWidgetDefinitionOutput,
+  type CortexWidgetDefinition,
+  type CortexWidgetBuildRequest,
+} from './cortex-widget-schema';
+
+export type GenerateCortexWidgetDefinitionResult = {
+  attempts: readonly CortexAiModelAttempt[];
+  credentialSource: 'env' | 'stored' | 'manual';
+  definition: CortexWidgetDefinition;
+  modelId: CortexAiOpenRouterModelId;
+};
+
+const CORTEX_WIDGET_BUILD_ATTEMPT_TIMEOUT_MS = 60_000;
+
+function isRecoverableCortexWidgetBuildError(error: unknown) {
+  const statusCode = getHttpStatusCode(error);
+
+  if (statusCode === 401 || statusCode === 402 || statusCode === 403) {
+    return false;
+  }
+
+  if (isOpenRouterRecoverableRoutingError(error)) {
+    return true;
+  }
+
+  if (statusCode && statusCode >= 500) {
+    return true;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return /NoObjectGenerated|No object generated|structured output|schema|validation|Invalid|aborted|abort|timeout|timed out/i.test(
+    message
+  );
+}
+
+export async function generateCortexWidgetDefinition(
+  params: CortexWidgetBuildRequest & {
+    apiKey?: string;
+    fallbackModelIds?: readonly CortexAiOpenRouterModelId[];
+    modelId?: CortexAiOpenRouterModelId;
+    modelSelection?: CortexAiStoredModelSelection | null;
+  }
+): Promise<GenerateCortexWidgetDefinitionResult> {
+  const { apiKey, fallbackModelIds, modelId, modelSelection, ...requestParams } = params;
+  const request = cortexWidgetBuildRequestSchema.parse(requestParams);
+  const client = await createCortexAiOpenRouterClient({ apiKey, modelSelection });
+  const routingPolicy = buildCortexAiRoutingPolicy({
+    credentialSource: client.credentialSource,
+    fallbackModelIds,
+    requestedModelId: modelId ?? request.modelId,
+    selectedModel: client.modelSelection,
+  });
+
+  const generation = await runWithCortexAiModelFallback({
+    modelIds: routingPolicy.modelIds,
+    shouldRetry: isRecoverableCortexWidgetBuildError,
+    execute: async (attemptModelId) => {
+      const abortController = new AbortController();
+      const timeoutId = setTimeout(
+        () => abortController.abort(),
+        CORTEX_WIDGET_BUILD_ATTEMPT_TIMEOUT_MS
+      );
+
+      try {
+        const attemptOptions = omitUnsupportedCortexAiModelOptions(
+          {
+            abortSignal: abortController.signal,
+            maxOutputTokens: 7000,
+            maxRetries: 0,
+            // Use JSON mode WITHOUT a provider-side schema. The widget definition
+            // is a recursive, discriminated-union structure; sending it as a
+            // response_format json_schema is rejected by Google Gemini
+            // ("reference to undefined schema", recursion not supported) and by
+            // OpenAI ("'oneOf' is not permitted"). We instead describe the shape
+            // in the prompt and validate the returned JSON with our own Zod
+            // schema below, which works across every OpenRouter model.
+            output: 'no-schema',
+            prompt: buildCortexWidgetBuilderPrompt(request),
+            system: buildCortexWidgetBuilderSystemPrompt(),
+            temperature: 0.15,
+          } as Record<string, unknown>,
+          {
+            modelId: attemptModelId,
+            modelSelection: routingPolicy.modelSelection,
+          }
+        );
+
+        const result = await generateObject({
+          ...attemptOptions,
+          model: client.model(attemptModelId),
+        } as Parameters<typeof generateObject>[0]);
+
+        return validateCortexWidgetDefinitionOutput(result.object);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    },
+  });
+
+  return {
+    attempts: generation.attempts,
+    credentialSource: client.credentialSource,
+    definition: generation.result,
+    modelId: generation.modelId,
+  };
+}