@khirby/plugin-ai-compose 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khirby Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@khirby/plugin-ai-compose",
+  "version": "1.0.0",
+  "description": "Khirby — AI-powered reply draft suggestions (BYOK, OpenAI-compatible)",
+  "main": "src/index.ts",
+  "keywords": [
+    "khirby-plugin"
+  ],
+  "peerDependencies": {
+    "@khirby/plugin-host": "^1.0.0",
+    "@khirby/plugin-sdk": "^1.0.0",
+    "@nestjs/common": "*",
+    "@nestjs/swagger": "*",
+    "drizzle-orm": "*"
+  },
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/ai-compose-crypto.ts

@@ -0,0 +1,60 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+function getKey(): Buffer {
+  const raw = process.env.AI_COMPOSE_SECRETS_KEY?.trim();
+  if (!raw) {
+    throw new Error('AI_COMPOSE_SECRETS_KEY is not set');
+  }
+  let buf: Buffer;
+  if (/^[0-9a-fA-F]{64}$/.test(raw)) {
+    buf = Buffer.from(raw, 'hex');
+  } else {
+    buf = Buffer.from(raw, 'base64');
+  }
+  if (buf.length !== 32) {
+    throw new Error(
+      "AI_COMPOSE_SECRETS_KEY must be 32 bytes as hex (64 chars) or base64 — generate with: node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"",
+    );
+  }
+  return buf;
+}
+
+export function isAiComposeSecretsKeyConfigured(): boolean {
+  try {
+    getKey();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Encrypts plaintext using AES-256-GCM.
+ * Returns a base64 string: iv(12) + ciphertext + tag(16)
+ */
+export function encrypt(plaintext: string): string {
+  const key = getKey();
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, encrypted, tag]).toString('base64');
+}
+
+/**
+ * Decrypts a base64 blob produced by `encrypt`.
+ */
+export function decrypt(ciphertext: string): string {
+  const key = getKey();
+  const buf = Buffer.from(ciphertext, 'base64');
+  const iv = buf.subarray(0, IV_BYTES);
+  const tag = buf.subarray(buf.length - TAG_BYTES);
+  const encrypted = buf.subarray(IV_BYTES, buf.length - TAG_BYTES);
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+  return decipher.update(encrypted) + decipher.final('utf8');
+}

package/src/ai-compose-generate.controller.ts

@@ -0,0 +1,69 @@
+import { Controller, Get, Post, Body, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import {
+  SessionGuard,
+  PermissionGuard,
+  RequireAnyPermission,
+  RequirePluginEnabled,
+  PluginEnabledGuard,
+} from '../../../packages/plugin-host/src';
+import { AiComposeSuggestService, type NewsletterContentType } from './ai-compose-suggest.service';
+import { AI_COMPOSE_PLUGIN_NAME } from './ai-compose-settings.service';
+
+@ApiTags('plugins-ai-compose')
+@Controller('plugins/ai-compose')
+@UseGuards(SessionGuard, PermissionGuard, PluginEnabledGuard)
+@RequirePluginEnabled(AI_COMPOSE_PLUGIN_NAME)
+export class AiComposeGenerateController {
+  constructor(private readonly suggest: AiComposeSuggestService) {}
+
+  @Get('availability')
+  @ApiOperation({
+    summary:
+      'Whether AI Compose can generate (plugin enabled + API key). For feature gates in other plugins.',
+  })
+  availability() {
+    return this.suggest.availability();
+  }
+
+  @Get('models/compose')
+  @RequireAnyPermission(
+    ['newsletter', 'manage'],
+    ['leads', 'manage'],
+    ['contacts', 'manage'],
+    ['integrations', 'manage'],
+  )
+  @ApiOperation({
+    summary:
+      'Allowed models for compose UIs (mail / newsletter) — not limited to integrations admins',
+  })
+  composeModels() {
+    return this.suggest.getComposeModels();
+  }
+
+  @Post('generate')
+  @RequireAnyPermission(
+    ['newsletter', 'manage'],
+    ['leads', 'manage'],
+    ['contacts', 'manage'],
+    ['integrations', 'manage'],
+  )
+  @ApiOperation({
+    summary:
+      'Generate newsletter campaign body in the requested format (html / markdown / plain / richtext)',
+  })
+  generate(
+    @Body()
+    dto: {
+      contentType: NewsletterContentType;
+      name?: string;
+      subject?: string;
+      instruction?: string;
+      existingBody?: string;
+      templateName?: string;
+      model?: string;
+    },
+  ) {
+    return this.suggest.generateNewsletter(dto);
+  }
+}

package/src/ai-compose-settings.controller.ts

@@ -0,0 +1,95 @@
+import { Controller, Get, Patch, Body, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import {
+  SessionGuard,
+  PermissionGuard,
+  RequirePermission,
+  RequirePluginEnabled,
+  PluginEnabledGuard,
+  AppException,
+} from '../../../packages/plugin-host/src';
+import { AiComposeSettingsService } from './ai-compose-settings.service';
+import { AiComposeSuggestService } from './ai-compose-suggest.service';
+import { AI_COMPOSE_PLUGIN_NAME } from './ai-compose-settings.service';
+
+@ApiTags('plugins-ai-compose')
+@Controller('plugins/ai-compose')
+@UseGuards(SessionGuard, PermissionGuard, PluginEnabledGuard)
+@RequirePermission('integrations', 'manage')
+@RequirePluginEnabled(AI_COMPOSE_PLUGIN_NAME)
+export class AiComposeSettingsController {
+  constructor(
+    private readonly settings: AiComposeSettingsService,
+    private readonly suggest: AiComposeSuggestService,
+  ) {}
+
+  @Get('settings')
+  @ApiOperation({ summary: 'Get AI Compose settings (API key never returned)' })
+  getSettings() {
+    return this.settings.getSettings();
+  }
+
+  @Patch('settings')
+  @ApiOperation({ summary: 'Update AI Compose settings' })
+  updateSettings(
+    @Body()
+    dto: {
+      apiKey?: string;
+      baseUrl?: string;
+      defaultModel?: string | null;
+      allowedModels?: string[];
+      systemPrompt?: string | null;
+    },
+  ) {
+    return this.settings.updateSettings(dto);
+  }
+
+  @Get('models')
+  @ApiOperation({ summary: 'Fetch available models from the configured AI provider' })
+  async getModels() {
+    const { apiKey, baseUrl } = await this.settings.getDecryptedApiKey().catch(() => {
+      throw AppException.badRequest('API key is not configured. Save your settings first.');
+    });
+    return this.suggest.fetchModels(baseUrl, apiKey);
+  }
+
+  @Get('models/allowed')
+  @ApiOperation({ summary: 'Get intersection of allowed models (admin allowlist) + default' })
+  async getAllowedModels() {
+    const defaultModel = await this.settings.getDefaultModel();
+    const allowedModels = await this.settings.getAllowedModels();
+
+    const toEntries = (ids: string[]) => ids.map((m) => ({ id: m, label: m }));
+
+    if (allowedModels.length === 0) {
+      const { apiKey, baseUrl } = await this.settings.getDecryptedApiKey().catch(() => ({
+        apiKey: '',
+        baseUrl: '',
+      }));
+      if (apiKey) {
+        try {
+          const all = await this.suggest.fetchModels(baseUrl, apiKey);
+          return { models: all, defaultModel };
+        } catch {
+          return { models: [], defaultModel };
+        }
+      }
+      return { models: [], defaultModel };
+    }
+
+    try {
+      const { apiKey, baseUrl } = await this.settings.getDecryptedApiKey();
+      const allModels = await this.suggest.fetchModels(baseUrl, apiKey);
+      const allIds = new Set(allModels.map((m) => m.id));
+      const models = allowedModels
+        .filter((m) => allIds.has(m))
+        .map((m) => {
+          const found = allModels.find((x) => x.id === m);
+          return { id: m, label: found?.label ?? m };
+        });
+      return { models, defaultModel };
+    } catch {
+      return { models: toEntries(allowedModels), defaultModel };
+    }
+  }
+}

package/src/ai-compose-settings.service.ts

@@ -0,0 +1,139 @@
+import { Injectable, Inject, Logger } from '@nestjs/common';
+import { eq } from 'drizzle-orm';
+import {
+  Db,
+  DB_TOKEN,
+  PLUGIN_REGISTRY,
+  type PluginRegistryLike,
+  AppException,
+} from '../../../packages/plugin-host/src';
+import { aiComposeSettings } from './schema';
+import { encrypt, decrypt, isAiComposeSecretsKeyConfigured } from './ai-compose-crypto';
+
+export const AI_COMPOSE_PLUGIN_NAME = 'crm_ai_compose';
+
+export type AiComposeSettingsPublic = {
+  baseUrl: string;
+  defaultModel: string | null;
+  allowedModels: string[];
+  systemPrompt: string | null;
+  apiKeyConfigured: boolean;
+};
+
+@Injectable()
+export class AiComposeSettingsService {
+  private readonly logger = new Logger(AiComposeSettingsService.name);
+
+  constructor(
+    @Inject(DB_TOKEN) private readonly db: Db,
+    @Inject(PLUGIN_REGISTRY) private readonly registry: PluginRegistryLike,
+  ) {}
+
+  async assertPluginEnabled(): Promise<void> {
+    const plugin = await this.registry.findByName(AI_COMPOSE_PLUGIN_NAME);
+    if (!plugin?.enabled) {
+      throw AppException.pluginDisabled('ai-compose');
+    }
+  }
+
+  private async getRow() {
+    const [row] = await this.db.select().from(aiComposeSettings).limit(1);
+    return row ?? null;
+  }
+
+  async getSettings(): Promise<AiComposeSettingsPublic> {
+    await this.assertPluginEnabled();
+    const row = await this.getRow();
+    return {
+      baseUrl: row?.baseUrl ?? 'https://api.openai.com/v1',
+      defaultModel: row?.defaultModel ?? null,
+      allowedModels: row?.allowedModels ?? [],
+      systemPrompt: row?.systemPrompt ?? null,
+      apiKeyConfigured: !!row?.apiKeyEnc,
+    };
+  }
+
+  async updateSettings(dto: {
+    apiKey?: string;
+    baseUrl?: string;
+    defaultModel?: string | null;
+    allowedModels?: string[];
+    systemPrompt?: string | null;
+  }): Promise<AiComposeSettingsPublic> {
+    await this.assertPluginEnabled();
+
+    const existing = await this.getRow();
+
+    let apiKeyEnc: string | undefined = undefined;
+    if (dto.apiKey !== undefined && dto.apiKey.trim()) {
+      if (!isAiComposeSecretsKeyConfigured()) {
+        throw AppException.badRequest('AI_COMPOSE_SECRETS_KEY is not configured');
+      }
+      apiKeyEnc = encrypt(dto.apiKey.trim());
+    }
+
+    const baseUrl = dto.baseUrl ?? existing?.baseUrl ?? 'https://api.openai.com/v1';
+    if (
+      !baseUrl.startsWith('https://') &&
+      baseUrl !== 'http://localhost' &&
+      !baseUrl.startsWith('http://localhost:')
+    ) {
+      throw AppException.badRequest(
+        'baseUrl must use https:// (or http://localhost for local models)',
+      );
+    }
+
+    const patch: Record<string, unknown> = {
+      baseUrl,
+      defaultModel:
+        dto.defaultModel !== undefined ? dto.defaultModel : (existing?.defaultModel ?? null),
+      allowedModels: dto.allowedModels ?? existing?.allowedModels ?? [],
+      systemPrompt:
+        dto.systemPrompt !== undefined ? dto.systemPrompt : (existing?.systemPrompt ?? null),
+      updatedAt: new Date(),
+    };
+
+    if (apiKeyEnc !== undefined) {
+      patch.apiKeyEnc = apiKeyEnc;
+    }
+
+    if (!existing) {
+      await this.db.insert(aiComposeSettings).values(patch as any);
+    } else {
+      await this.db
+        .update(aiComposeSettings)
+        .set(patch as any)
+        .where(eq(aiComposeSettings.id, existing.id));
+    }
+
+    this.logger.log('AI Compose settings updated');
+    return this.getSettings();
+  }
+
+  /** Decrypt the stored API key for internal use; throws if missing. */
+  async getDecryptedApiKey(): Promise<{ apiKey: string; baseUrl: string }> {
+    const row = await this.getRow();
+    if (!row?.apiKeyEnc) {
+      throw AppException.badRequest('AI Compose API key is not configured');
+    }
+    return {
+      apiKey: decrypt(row.apiKeyEnc),
+      baseUrl: row.baseUrl,
+    };
+  }
+
+  async getAllowedModels(): Promise<string[]> {
+    const row = await this.getRow();
+    return row?.allowedModels ?? [];
+  }
+
+  async getDefaultModel(): Promise<string | null> {
+    const row = await this.getRow();
+    return row?.defaultModel ?? null;
+  }
+
+  async getSystemPrompt(): Promise<string | null> {
+    const row = await this.getRow();
+    return row?.systemPrompt ?? null;
+  }
+}

package/src/ai-compose-suggest.controller.ts

@@ -0,0 +1,37 @@
+import { Controller, Post, Body, UseGuards } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import {
+  SessionGuard,
+  PermissionGuard,
+  RequireAnyPermission,
+  RequirePluginEnabled,
+  PluginEnabledGuard,
+} from '../../../packages/plugin-host/src';
+import { AiComposeSuggestService } from './ai-compose-suggest.service';
+import { AI_COMPOSE_PLUGIN_NAME } from './ai-compose-settings.service';
+
+@ApiTags('plugins-ai-compose')
+@Controller('plugins/ai-compose')
+@UseGuards(SessionGuard, PermissionGuard, PluginEnabledGuard)
+@RequireAnyPermission(['leads', 'manage'], ['contacts', 'manage'])
+@RequirePluginEnabled(AI_COMPOSE_PLUGIN_NAME)
+export class AiComposeSuggestController {
+  constructor(private readonly suggest: AiComposeSuggestService) {}
+
+  @Post('suggest')
+  @ApiOperation({
+    summary:
+      'Generate an AI draft for a mail thread reply or a first outbound to a lead (never auto-sends)',
+  })
+  generateSuggestion(
+    @Body()
+    dto: {
+      threadId?: string;
+      leadId?: string;
+      model?: string;
+      instruction?: string;
+    },
+  ) {
+    return this.suggest.suggest(dto);
+  }
+}