melaka 0.0.0

package/packages/firestore/src/processor.ts

@@ -0,0 +1,245 @@
+/**
+ * Melaka Firestore - Translation Processor
+ *
+ * Core translation logic that processes documents and writes translations.
+ */
+
+import type { DocumentReference, DocumentData, Timestamp } from 'firebase-admin/firestore';
+import {
+  separateContent,
+  hashContent,
+  mergeGlossaries,
+  createTranslationSchema,
+  type MelakaConfig,
+  type CollectionConfig,
+  type MelakaMetadata,
+  getEffectiveAIConfig,
+} from '@melaka/core';
+import { createTranslationFacade, type TranslationResponse } from '@melaka/ai';
+import {
+  readMelakaMetadata,
+  writeTranslation,
+  markTranslationFailed,
+} from './i18n';
+
+/**
+ * Options for processing a translation.
+ */
+export interface ProcessOptions {
+  /**
+   * Force re-translation even if content unchanged.
+   */
+  forceUpdate?: boolean;
+
+  /**
+   * Timestamp to use for translated_at field.
+   */
+  timestamp?: Timestamp;
+}
+
+/**
+ * Result of processing a translation.
+ */
+export interface ProcessResult {
+  /**
+   * Whether processing succeeded.
+   */
+  success: boolean;
+
+  /**
+   * Whether translation was skipped (content unchanged).
+   */
+  skipped: boolean;
+
+  /**
+   * Error message if failed.
+   */
+  error?: string;
+
+  /**
+   * Duration in milliseconds.
+   */
+  durationMs?: number;
+}
+
+/**
+ * Process a single document translation.
+ *
+ * @param docRef - Document reference to translate
+ * @param docData - Document data
+ * @param targetLanguage - Target locale code
+ * @param config - Root Melaka configuration
+ * @param collectionConfig - Collection-specific configuration
+ * @param options - Processing options
+ * @returns Processing result
+ */
+export async function processTranslation(
+  docRef: DocumentReference,
+  docData: DocumentData,
+  targetLanguage: string,
+  config: MelakaConfig,
+  collectionConfig: CollectionConfig,
+  options: ProcessOptions = {}
+): Promise<ProcessResult> {
+  const startTime = Date.now();
+
+  try {
+    // 1. Separate content into translatable and non-translatable
+    const { translatable, nonTranslatable, detectedTypes } = separateContent(
+      docData as Record<string, unknown>,
+      collectionConfig.fields
+    );
+
+    // Check if there's anything to translate
+    if (Object.keys(translatable).length === 0) {
+      return {
+        success: true,
+        skipped: true,
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    // 2. Calculate content hash for change detection
+    const sourceHash = hashContent(translatable);
+
+    // 3. Check if translation is already current (unless forceUpdate)
+    if (!options.forceUpdate) {
+      const existingMetadata = await readMelakaMetadata(docRef, targetLanguage);
+
+      if (
+        existingMetadata &&
+        existingMetadata.status === 'completed' &&
+        existingMetadata.source_hash === sourceHash
+      ) {
+        return {
+          success: true,
+          skipped: true,
+          durationMs: Date.now() - startTime,
+        };
+      }
+    }
+
+    // 4. Create translation schema
+    const schema = createTranslationSchema({ translatable, detectedTypes });
+
+    // 5. Get effective AI config and create facade
+    const aiConfig = getEffectiveAIConfig(config, collectionConfig);
+    const facade = createTranslationFacade(aiConfig);
+
+    // 6. Merge glossaries
+    const glossary = mergeGlossaries(config.glossary, collectionConfig.glossary);
+
+    // 7. Perform translation
+    const response: TranslationResponse<Record<string, unknown>> = await facade.translate(
+      translatable,
+      schema,
+      {
+        targetLanguage,
+        prompt: collectionConfig.prompt,
+        glossary,
+        temperature: aiConfig.temperature,
+      }
+    );
+
+    // 8. Handle translation result
+    const timestamp = options.timestamp || (await getTimestamp(docRef));
+
+    if (!response.success || !response.output) {
+      await markTranslationFailed(
+        docRef,
+        targetLanguage,
+        response.error || 'Unknown translation error',
+        timestamp
+      );
+
+      return {
+        success: false,
+        skipped: false,
+        error: response.error,
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    // 9. Create metadata
+    const metadata: MelakaMetadata = {
+      source_hash: sourceHash,
+      translated_at: timestamp,
+      model: facade.getModel(),
+      status: 'completed',
+      reviewed: false,
+    };
+
+    // 10. Write translation
+    await writeTranslation(
+      docRef,
+      targetLanguage,
+      response.output,
+      nonTranslatable,
+      metadata
+    );
+
+    return {
+      success: true,
+      skipped: false,
+      durationMs: Date.now() - startTime,
+    };
+  } catch (error) {
+    const timestamp = options.timestamp || (await getTimestamp(docRef));
+
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    try {
+      await markTranslationFailed(docRef, targetLanguage, errorMessage, timestamp);
+    } catch {
+      // Ignore errors while marking failed
+    }
+
+    return {
+      success: false,
+      skipped: false,
+      error: errorMessage,
+      durationMs: Date.now() - startTime,
+    };
+  }
+}
+
+/**
+ * Process translations for all configured languages.
+ *
+ * @param docRef - Document reference to translate
+ * @param docData - Document data
+ * @param config - Root Melaka configuration
+ * @param collectionConfig - Collection-specific configuration
+ * @param options - Processing options
+ * @returns Results for each language
+ */
+export async function processAllLanguages(
+  docRef: DocumentReference,
+  docData: DocumentData,
+  config: MelakaConfig,
+  collectionConfig: CollectionConfig,
+  options: ProcessOptions = {}
+): Promise<Record<string, ProcessResult>> {
+  const results: Record<string, ProcessResult> = {};
+
+  for (const language of config.languages) {
+    results[language] = await processTranslation(
+      docRef,
+      docData,
+      language,
+      config,
+      collectionConfig,
+      options
+    );
+  }
+
+  return results;
+}
+
+/**
+ * Get a Firestore Timestamp.
+ */
+async function getTimestamp(docRef: DocumentReference): Promise<Timestamp> {
+  const { Timestamp } = await import('firebase-admin/firestore');
+  return Timestamp.now();
+}

package/packages/firestore/src/queue.ts

@@ -0,0 +1,202 @@
+/**
+ * Melaka Firestore - Task Queue
+ *
+ * Functions for enqueueing translation tasks to Cloud Tasks.
+ */
+
+import type { Firestore } from 'firebase-admin/firestore';
+import {
+  generateBatchId,
+  type MelakaConfig,
+  type CollectionConfig,
+  getEffectiveMaxConcurrency,
+} from '@melaka/core';
+import type { TranslationTaskPayload } from '@melaka/core';
+import { createTaskPayload } from './task-handler';
+
+/**
+ * Task queue interface for Cloud Functions.
+ */
+export interface TaskQueue {
+  enqueue(
+    data: TranslationTaskPayload,
+    options?: { scheduleDelaySeconds?: number }
+  ): Promise<void>;
+}
+
+/**
+ * Options for enqueueing translations.
+ */
+export interface EnqueueOptions {
+  /**
+   * Task queue instance.
+   */
+  queue: TaskQueue;
+
+  /**
+   * Base delay between task scheduling (staggering).
+   */
+  staggerDelayMs?: number;
+}
+
+/**
+ * Result of enqueueing translations.
+ */
+export interface EnqueueResult {
+  /**
+   * Batch ID for tracking.
+   */
+  batchId: string;
+
+  /**
+   * Number of tasks enqueued.
+   */
+  tasksEnqueued: number;
+
+  /**
+   * Number of tasks that failed to enqueue.
+   */
+  failed: number;
+
+  /**
+   * Error messages for failed tasks.
+   */
+  errors: string[];
+}
+
+/**
+ * Enqueue translation tasks for a single document.
+ *
+ * Creates one task per target language.
+ *
+ * @param collectionPath - Collection path
+ * @param documentId - Document ID
+ * @param config - Melaka configuration
+ * @param collectionConfig - Collection configuration
+ * @param options - Queue options
+ * @returns Enqueue result
+ */
+export async function enqueueDocumentTranslation(
+  collectionPath: string,
+  documentId: string,
+  config: MelakaConfig,
+  collectionConfig: CollectionConfig,
+  options: EnqueueOptions
+): Promise<EnqueueResult> {
+  const batchId = generateBatchId();
+  const staggerDelay = options.staggerDelayMs || 100;
+  let tasksEnqueued = 0;
+  let failed = 0;
+  const errors: string[] = [];
+
+  for (let i = 0; i < config.languages.length; i++) {
+    const language = config.languages[i];
+
+    try {
+      const payload = createTaskPayload(
+        collectionPath,
+        documentId,
+        language,
+        collectionConfig,
+        batchId
+      );
+
+      await options.queue.enqueue(payload, {
+        scheduleDelaySeconds: Math.floor((i * staggerDelay) / 1000),
+      });
+
+      tasksEnqueued++;
+    } catch (error) {
+      failed++;
+      errors.push(
+        `Failed to enqueue ${documentId}/${language}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  return {
+    batchId,
+    tasksEnqueued,
+    failed,
+    errors,
+  };
+}
+
+/**
+ * Enqueue translation tasks for all documents in a collection.
+ *
+ * @param firestore - Firestore instance
+ * @param config - Melaka configuration
+ * @param collectionConfig - Collection configuration
+ * @param options - Queue options
+ * @returns Enqueue result
+ */
+export async function enqueueCollectionTranslation(
+  firestore: Firestore,
+  config: MelakaConfig,
+  collectionConfig: CollectionConfig,
+  options: EnqueueOptions
+): Promise<EnqueueResult> {
+  const batchId = generateBatchId();
+  const maxConcurrency = getEffectiveMaxConcurrency(config, collectionConfig);
+  const staggerDelay = options.staggerDelayMs || 100;
+
+  let tasksEnqueued = 0;
+  let failed = 0;
+  const errors: string[] = [];
+
+  // Query collection
+  let query: FirebaseFirestore.Query;
+  if (collectionConfig.isCollectionGroup) {
+    query = firestore.collectionGroup(collectionConfig.path);
+  } else {
+    query = firestore.collection(collectionConfig.path);
+  }
+
+  const snapshots = await query.select().get();
+  const totalDocs = snapshots.docs.length;
+  const totalTasks = totalDocs * config.languages.length;
+
+  let taskIndex = 0;
+
+  for (const doc of snapshots.docs) {
+    const collectionPath = collectionConfig.isCollectionGroup
+      ? doc.ref.parent.path
+      : collectionConfig.path;
+
+    for (const language of config.languages) {
+      try {
+        const payload = createTaskPayload(
+          collectionPath,
+          doc.id,
+          language,
+          collectionConfig,
+          batchId
+        );
+
+        // Calculate delay for staggering
+        const delaySeconds = Math.floor((taskIndex * staggerDelay) / 1000);
+
+        await options.queue.enqueue(payload, {
+          scheduleDelaySeconds: delaySeconds,
+        });
+
+        tasksEnqueued++;
+      } catch (error) {
+        failed++;
+        errors.push(
+          `Failed to enqueue ${doc.id}/${language}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+
+      taskIndex++;
+    }
+  }
+
+  return {
+    batchId,
+    tasksEnqueued,
+    failed,
+    errors,
+  };
+}

package/packages/firestore/src/task-handler.ts

@@ -0,0 +1,164 @@
+/**
+ * Melaka Firestore - Cloud Task Handler
+ *
+ * Task queue handler for async translation processing.
+ */
+
+import type { DocumentReference } from 'firebase-admin/firestore';
+import {
+  TranslationTaskPayloadSchema,
+  type TranslationTaskPayload,
+  type MelakaConfig,
+  findCollectionConfig,
+} from '@melaka/core';
+import { processTranslation, type ProcessResult } from './processor';
+
+/**
+ * Task handler context with Firebase dependencies.
+ */
+export interface TaskHandlerContext {
+  /**
+   * Firestore instance.
+   */
+  firestore: FirebaseFirestore.Firestore;
+
+  /**
+   * Melaka configuration.
+   */
+  config: MelakaConfig;
+
+  /**
+   * API key for AI provider (resolved from secret).
+   */
+  apiKey: string;
+}
+
+/**
+ * Handle a translation task from Cloud Tasks.
+ *
+ * This function is called by the `onTaskDispatched` Cloud Function.
+ *
+ * @param payload - Task payload
+ * @param context - Handler context with Firestore and config
+ * @returns Processing result
+ *
+ * @example
+ * ```typescript
+ * // In generated Cloud Function:
+ * export const melakaTranslateTask = onTaskDispatched(
+ *   { secrets: [geminiApiKey] },
+ *   async (request) => {
+ *     const result = await handleTranslationTask(request.data, {
+ *       firestore: getFirestore(),
+ *       config: await loadConfig(),
+ *       apiKey: geminiApiKey.value(),
+ *     });
+ *
+ *     if (!result.success) {
+ *       throw new Error(result.error);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function handleTranslationTask(
+  payload: unknown,
+  context: TaskHandlerContext
+): Promise<ProcessResult> {
+  // 1. Validate payload
+  const parseResult = TranslationTaskPayloadSchema.safeParse(payload);
+  if (!parseResult.success) {
+    return {
+      success: false,
+      skipped: false,
+      error: `Invalid task payload: ${parseResult.error.message}`,
+    };
+  }
+
+  const taskPayload = parseResult.data as TranslationTaskPayload;
+
+  // 2. Get document reference
+  const docRef = context.firestore
+    .collection(taskPayload.collectionPath)
+    .doc(taskPayload.documentId);
+
+  // 3. Read document
+  const docSnapshot = await docRef.get();
+  if (!docSnapshot.exists) {
+    return {
+      success: true,
+      skipped: true,
+      error: 'Document no longer exists',
+    };
+  }
+
+  const docData = docSnapshot.data();
+  if (!docData) {
+    return {
+      success: true,
+      skipped: true,
+      error: 'Document has no data',
+    };
+  }
+
+  // 4. Find collection config
+  const collectionConfig = findCollectionConfig(
+    context.config,
+    taskPayload.collectionPath
+  );
+
+  if (!collectionConfig) {
+    return {
+      success: false,
+      skipped: false,
+      error: `Collection not configured: ${taskPayload.collectionPath}`,
+    };
+  }
+
+  // 5. Inject API key into config
+  const configWithKey: MelakaConfig = {
+    ...context.config,
+    ai: {
+      ...context.config.ai,
+      apiKey: context.apiKey,
+    },
+  };
+
+  // 6. Process translation
+  return processTranslation(
+    docRef,
+    docData,
+    taskPayload.targetLanguage,
+    configWithKey,
+    collectionConfig,
+    {
+      forceUpdate: collectionConfig.forceUpdate,
+    }
+  );
+}
+
+/**
+ * Create task payload for enqueueing.
+ *
+ * @param collectionPath - Collection path
+ * @param documentId - Document ID
+ * @param targetLanguage - Target locale
+ * @param config - Collection configuration
+ * @param batchId - Batch identifier
+ * @returns Task payload
+ */
+export function createTaskPayload(
+  collectionPath: string,
+  documentId: string,
+  targetLanguage: string,
+  config: import('@melaka/core').CollectionConfig,
+  batchId: string
+): TranslationTaskPayload {
+  return {
+    collectionPath,
+    documentId,
+    targetLanguage,
+    config,
+    batchId,
+  };
+}

package/packages/firestore/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "packages/*"

package/turbo.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": ["**/.env.*local"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "outputs": ["coverage/**"]
+    },
+    "test:watch": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": {
+      "dependsOn": ["^build"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    },
+    "clean": {
+      "cache": false
+    }
+  }
+}