melaka 0.0.0

package/packages/firestore/src/generator.ts

@@ -0,0 +1,270 @@
+/**
+ * Melaka Firestore - Trigger Generator
+ *
+ * Generates Cloud Function code for Firestore triggers.
+ */
+
+import type { MelakaConfig, CollectionConfig } from '@melaka/core';
+
+/**
+ * Options for generating trigger code.
+ */
+export interface GeneratorOptions {
+  /**
+   * Output directory for generated files.
+   */
+  outputDir: string;
+
+  /**
+   * Import path for Melaka packages.
+   * @default '@melaka/firestore'
+   */
+  melakaImport?: string;
+}
+
+/**
+ * Generated file output.
+ */
+export interface GeneratedFile {
+  /**
+   * File path relative to output directory.
+   */
+  path: string;
+
+  /**
+   * File content.
+   */
+  content: string;
+}
+
+/**
+ * Generate trigger code for all configured collections.
+ *
+ * @param config - Melaka configuration
+ * @param options - Generator options
+ * @returns Array of generated files
+ */
+export function generateTriggers(
+  config: MelakaConfig,
+  options: GeneratorOptions
+): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+
+  // Generate triggers file
+  files.push({
+    path: 'triggers.ts',
+    content: generateTriggersFile(config),
+  });
+
+  // Generate task handler file
+  files.push({
+    path: 'task-handler.ts',
+    content: generateTaskHandlerFile(config),
+  });
+
+  // Generate index file
+  files.push({
+    path: 'index.ts',
+    content: generateIndexFile(config),
+  });
+
+  return files;
+}
+
+/**
+ * Generate the triggers.ts file content.
+ */
+function generateTriggersFile(config: MelakaConfig): string {
+  const imports = `
+import { onDocumentWritten } from 'firebase-functions/v2/firestore';
+import { getFunctions } from 'firebase-admin/functions';
+import type { CollectionConfig } from '@melaka/core';
+`.trim();
+
+  const triggerFunctions = config.collections
+    .map((collection) => generateTriggerFunction(collection, config))
+    .join('\n\n');
+
+  const enqueueHelper = `
+/**
+ * Enqueue translation tasks for a document.
+ */
+async function enqueueTranslation(
+  collectionPath: string,
+  documentId: string,
+  languages: string[],
+  config: CollectionConfig,
+  batchId: string
+): Promise<void> {
+  const queue = getFunctions().taskQueue('melakaTranslateTask');
+
+  for (let i = 0; i < languages.length; i++) {
+    const language = languages[i];
+    await queue.enqueue(
+      {
+        collectionPath,
+        documentId,
+        targetLanguage: language,
+        config,
+        batchId,
+      },
+      {
+        scheduleDelaySeconds: i * 2, // Stagger by 2 seconds
+      }
+    );
+  }
+}
+
+/**
+ * Generate a unique batch ID.
+ */
+function generateBatchId(): string {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 8);
+  return \`batch_\${timestamp}_\${random}\`;
+}
+`.trim();
+
+  return `${imports}\n\n${triggerFunctions}\n\n${enqueueHelper}`;
+}
+
+/**
+ * Generate a single trigger function.
+ */
+function generateTriggerFunction(
+  collection: CollectionConfig,
+  config: MelakaConfig
+): string {
+  const functionName = `melakaTranslate${pascalCase(collection.path)}`;
+  const documentPath = collection.isCollectionGroup
+    ? `{parentPath}/${collection.path}/{docId}`
+    : `${collection.path}/{docId}`;
+
+  const collectionConfigStr = JSON.stringify(collection, null, 2)
+    .split('\n')
+    .map((line, i) => (i === 0 ? line : '  ' + line))
+    .join('\n');
+
+  return `
+/**
+ * Auto-generated trigger for ${collection.path} collection.
+ */
+export const ${functionName} = onDocumentWritten(
+  {
+    document: '${documentPath}',
+    region: '${config.region || 'us-central1'}',
+  },
+  async (event) => {
+    // Skip deletes
+    if (!event.data?.after.exists) {
+      return;
+    }
+
+    const collectionPath = ${collection.isCollectionGroup ? 'event.data.after.ref.parent.path' : `'${collection.path}'`};
+    const documentId = event.params.docId;
+    const batchId = generateBatchId();
+
+    const collectionConfig: CollectionConfig = ${collectionConfigStr};
+
+    const languages = ${JSON.stringify(config.languages)};
+
+    await enqueueTranslation(
+      collectionPath,
+      documentId,
+      languages,
+      collectionConfig,
+      batchId
+    );
+  }
+);
+`.trim();
+}
+
+/**
+ * Generate the task-handler.ts file content.
+ */
+function generateTaskHandlerFile(config: MelakaConfig): string {
+  const apiKeySecret = config.ai.apiKeySecret || 'GEMINI_API_KEY';
+
+  return `
+import { onTaskDispatched } from 'firebase-functions/v2/tasks';
+import { defineSecret } from 'firebase-functions/params';
+import { getFirestore } from 'firebase-admin/firestore';
+import { handleTranslationTask } from '@melaka/firestore';
+import type { MelakaConfig } from '@melaka/core';
+
+const apiKeySecret = defineSecret('${apiKeySecret}');
+
+/**
+ * Melaka configuration.
+ * 
+ * This is a copy of your melaka.config.ts for runtime use.
+ * If you update melaka.config.ts, run \`melaka deploy\` to regenerate.
+ */
+const config: MelakaConfig = ${JSON.stringify(config, null, 2)};
+
+/**
+ * Task handler for processing translation tasks.
+ */
+export const melakaTranslateTask = onTaskDispatched(
+  {
+    secrets: [apiKeySecret],
+    retryConfig: {
+      maxAttempts: 3,
+      minBackoffSeconds: 60,
+      maxBackoffSeconds: 300,
+    },
+    rateLimits: {
+      maxConcurrentDispatches: ${config.defaults?.maxConcurrency || 10},
+    },
+    region: '${config.region || 'us-central1'}',
+  },
+  async (request) => {
+    const result = await handleTranslationTask(request.data, {
+      firestore: getFirestore(),
+      config,
+      apiKey: apiKeySecret.value(),
+    });
+
+    if (!result.success && !result.skipped) {
+      // Throw to trigger retry
+      throw new Error(result.error || 'Translation failed');
+    }
+  }
+);
+`.trim();
+}
+
+/**
+ * Generate the index.ts file content.
+ */
+function generateIndexFile(config: MelakaConfig): string {
+  const triggerExports = config.collections
+    .map((c) => `melakaTranslate${pascalCase(c.path)}`)
+    .join(',\n  ');
+
+  return `
+/**
+ * Melaka - Auto-generated Cloud Functions
+ * 
+ * This file exports all Melaka triggers and task handlers.
+ * Import these in your main functions/src/index.ts file.
+ */
+
+export {
+  ${triggerExports},
+} from './triggers';
+
+export { melakaTranslateTask } from './task-handler';
+`.trim();
+}
+
+/**
+ * Convert a string to PascalCase.
+ */
+function pascalCase(str: string): string {
+  return str
+    .split(/[-_\/]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+}

package/packages/firestore/src/i18n.ts

@@ -0,0 +1,262 @@
+/**
+ * Melaka Firestore - i18n Operations
+ *
+ * Functions for reading/writing to i18n subcollections.
+ */
+
+import type { Firestore, DocumentReference, DocumentData, Timestamp } from 'firebase-admin/firestore';
+import type { MelakaMetadata, TranslationStatus } from '@melaka/core';
+
+/**
+ * Path to i18n subcollection for a document.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @returns Path string to i18n document
+ *
+ * @example
+ * ```typescript
+ * const path = getI18nPath(docRef, 'ms-MY');
+ * // 'products/abc123/i18n/ms-MY'
+ * ```
+ */
+export function getI18nPath(docRef: DocumentReference, locale: string): string {
+  return `${docRef.path}/i18n/${locale}`;
+}
+
+/**
+ * Get the i18n document reference for a locale.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @returns DocumentReference to i18n document
+ */
+export function getI18nRef(
+  docRef: DocumentReference,
+  locale: string
+): DocumentReference {
+  return docRef.collection('i18n').doc(locale);
+}
+
+/**
+ * Read an existing translation from i18n subcollection.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @returns Translation data or null if not exists
+ */
+export async function readTranslation(
+  docRef: DocumentReference,
+  locale: string
+): Promise<DocumentData | null> {
+  const i18nRef = getI18nRef(docRef, locale);
+  const snapshot = await i18nRef.get();
+
+  if (!snapshot.exists) {
+    return null;
+  }
+
+  return snapshot.data() || null;
+}
+
+/**
+ * Read the Melaka metadata from an existing translation.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @returns Melaka metadata or null if not exists
+ */
+export async function readMelakaMetadata(
+  docRef: DocumentReference,
+  locale: string
+): Promise<MelakaMetadata | null> {
+  const translation = await readTranslation(docRef, locale);
+
+  if (!translation || !translation._melaka) {
+    return null;
+  }
+
+  return translation._melaka as MelakaMetadata;
+}
+
+/**
+ * Write a translation to i18n subcollection.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @param translatedContent - Translated fields
+ * @param nonTranslatableContent - Copied fields
+ * @param metadata - Melaka metadata
+ */
+export async function writeTranslation(
+  docRef: DocumentReference,
+  locale: string,
+  translatedContent: Record<string, unknown>,
+  nonTranslatableContent: Record<string, unknown>,
+  metadata: MelakaMetadata
+): Promise<void> {
+  const i18nRef = getI18nRef(docRef, locale);
+
+  const finalDoc = {
+    ...translatedContent,
+    ...nonTranslatableContent,
+    _melaka: metadata,
+  };
+
+  await i18nRef.set(finalDoc);
+}
+
+/**
+ * Update the Melaka metadata for an existing translation.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @param metadata - Partial metadata to update
+ */
+export async function updateMelakaMetadata(
+  docRef: DocumentReference,
+  locale: string,
+  metadata: Partial<MelakaMetadata>
+): Promise<void> {
+  const i18nRef = getI18nRef(docRef, locale);
+
+  const updates: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    updates[`_melaka.${key}`] = value;
+  }
+
+  await i18nRef.update(updates);
+}
+
+/**
+ * Mark a translation as failed.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @param error - Error message
+ * @param timestamp - Timestamp for the failure
+ */
+export async function markTranslationFailed(
+  docRef: DocumentReference,
+  locale: string,
+  error: string,
+  timestamp: Timestamp
+): Promise<void> {
+  const i18nRef = getI18nRef(docRef, locale);
+  const existing = await i18nRef.get();
+
+  if (existing.exists) {
+    // Update existing document
+    await i18nRef.update({
+      '_melaka.status': 'failed' as TranslationStatus,
+      '_melaka.error': error,
+      '_melaka.translated_at': timestamp,
+    });
+  } else {
+    // Create minimal failed document
+    await i18nRef.set({
+      _melaka: {
+        status: 'failed' as TranslationStatus,
+        error,
+        translated_at: timestamp,
+        source_hash: '',
+        model: '',
+        reviewed: false,
+      },
+    });
+  }
+}
+
+/**
+ * Delete a translation from i18n subcollection.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ */
+export async function deleteTranslation(
+  docRef: DocumentReference,
+  locale: string
+): Promise<void> {
+  const i18nRef = getI18nRef(docRef, locale);
+  await i18nRef.delete();
+}
+
+/**
+ * Delete all translations for a document.
+ *
+ * @param docRef - Parent document reference
+ */
+export async function deleteAllTranslations(
+  docRef: DocumentReference
+): Promise<void> {
+  const i18nCollection = docRef.collection('i18n');
+  const snapshots = await i18nCollection.get();
+
+  const batch = docRef.firestore.batch();
+  for (const doc of snapshots.docs) {
+    batch.delete(doc.ref);
+  }
+
+  await batch.commit();
+}
+
+/**
+ * List all locales that have translations for a document.
+ *
+ * @param docRef - Parent document reference
+ * @returns Array of locale codes
+ */
+export async function listTranslationLocales(
+  docRef: DocumentReference
+): Promise<string[]> {
+  const i18nCollection = docRef.collection('i18n');
+  const snapshots = await i18nCollection.select().get();
+
+  return snapshots.docs.map((doc) => doc.id);
+}
+
+/**
+ * Check if a translation exists and is up-to-date.
+ *
+ * @param docRef - Parent document reference
+ * @param locale - Target locale code
+ * @param sourceHash - Current source content hash
+ * @returns Whether translation exists and matches source hash
+ */
+export async function isTranslationCurrent(
+  docRef: DocumentReference,
+  locale: string,
+  sourceHash: string
+): Promise<boolean> {
+  const metadata = await readMelakaMetadata(docRef, locale);
+
+  if (!metadata) {
+    return false;
+  }
+
+  return (
+    metadata.status === 'completed' &&
+    metadata.source_hash === sourceHash
+  );
+}
+
+/**
+ * Get translation status summary for a document.
+ *
+ * @param docRef - Parent document reference
+ * @param locales - Locales to check
+ * @returns Status for each locale
+ */
+export async function getTranslationStatus(
+  docRef: DocumentReference,
+  locales: string[]
+): Promise<Record<string, TranslationStatus | 'missing'>> {
+  const status: Record<string, TranslationStatus | 'missing'> = {};
+
+  for (const locale of locales) {
+    const metadata = await readMelakaMetadata(docRef, locale);
+    status[locale] = metadata?.status || 'missing';
+  }
+
+  return status;
+}

package/packages/firestore/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @melaka/firestore
+ *
+ * Firestore adapter and triggers for Melaka - AI-powered Firestore localization.
+ *
+ * @packageDocumentation
+ */
+
+// i18n operations
+export {
+  getI18nPath,
+  getI18nRef,
+  readTranslation,
+  readMelakaMetadata,
+  writeTranslation,
+  updateMelakaMetadata,
+  markTranslationFailed,
+  deleteTranslation,
+  deleteAllTranslations,
+  listTranslationLocales,
+  isTranslationCurrent,
+  getTranslationStatus,
+} from './i18n';
+
+// Translation processor
+export {
+  processTranslation,
+  processAllLanguages,
+  type ProcessOptions,
+  type ProcessResult,
+} from './processor';
+
+// Task handling
+export {
+  handleTranslationTask,
+  createTaskPayload,
+  type TaskHandlerContext,
+} from './task-handler';
+
+// Task queue
+export {
+  enqueueDocumentTranslation,
+  enqueueCollectionTranslation,
+  type TaskQueue,
+  type EnqueueOptions,
+  type EnqueueResult,
+} from './queue';
+
+// Code generator
+export {
+  generateTriggers,
+  type GeneratorOptions,
+  type GeneratedFile,
+} from './generator';