@cravery/core 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cravery/core",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Clean architecture foundation for Cravery",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,6 +15,8 @@
   },
   "keywords": [],
   "dependencies": {
+    "@genkit-ai/google-genai": "^1.27.0",
+    "genkit": "^1.27.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {

package/src/config/ai.ts

@@ -0,0 +1,34 @@
+import { AIConfig } from "../types";
+
+export const AI_MODELS: AIConfig = {
+  Gemini25Flash: {
+    id: "vertexai/gemini-2.5-flash",
+    name: "Gemini 2.5 Flash",
+    type: "multimodal",
+    cost: { input: 0.3, output: 2.5 },
+  },
+  Gemini25Pro: {
+    id: "vertexai/gemini-2.5-pro",
+    name: "Gemini 2.5 Pro",
+    type: "multimodal",
+    cost: { input: 1.25, output: 10.0 },
+  },
+  Gemini3Flash: {
+    id: "vertexai/gemini-3.0-flash",
+    name: "Gemini 3 Flash",
+    type: "multimodal",
+    cost: { input: 0.5, output: 3.0 },
+  },
+  Imagen4Fast: {
+    id: "vertexai/imagen-4.0-fast-generate-001",
+    name: "Imagen 4 Fast",
+    type: "image",
+    cost: { input: 0, output: 0.02 },
+  },
+  GeminiEmbedding001: {
+    id: "vertexai/gemini-embedding-001",
+    name: "Gemini Embedding 001",
+    type: "embedding",
+    cost: { input: 0.00015, output: 0 },
+  },
+};

package/src/config/collections.ts

@@ -0,0 +1,7 @@
+export const Collections = {
+  Moderations: "moderations",
+  Profiles: "profiles",
+  Recipes: "recipes",
+  Subscriptions: "subscriptions",
+  Users: "users",
+};

package/src/config/common.ts

@@ -0,0 +1 @@
+export const SlugRegex = /^[a-z][a-z0-9-]*[a-z0-9]$/;

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export * from "./ai";
+export * from "./collections";
+export * from "./common";

package/src/enums/allergen.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const ALLERGEN_VALUES = [
+  "celery",
+  "dairy",
+  "eggs",
+  "fish",
+  "gluten",
+  "lupin",
+  "mustard",
+  "nuts",
+  "peanuts",
+  "sesame",
+  "shellfish",
+  "soy",
+  "sulfites",
+] as const;
+export const AllergenSchema = z.enum(ALLERGEN_VALUES);
+export type Allergen = (typeof ALLERGEN_VALUES)[number];

package/src/enums/cuisine.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const CUISINE_VALUES = [
+  "african",
+  "american",
+  "brazilian",
+  "british",
+  "caribbean",
+  "chinese",
+  "egyptian",
+  "emirati",
+  "ethiopian",
+  "filipino",
+  "french",
+  "fusion",
+  "german",
+  "greek",
+  "indian",
+  "indonesian",
+  "italian",
+  "japanese",
+  "korean",
+  "lebanese",
+  "malaysian",
+  "mexican",
+  "moroccan",
+  "pakistani",
+  "persian",
+  "russian",
+  "saudi",
+  "spanish",
+  "sudanese",
+  "thai",
+  "turkish",
+  "vietnamese",
+  "other",
+] as const;
+export const CuisineSchema = z.enum(CUISINE_VALUES);
+export type Cuisine = (typeof CUISINE_VALUES)[number];

package/src/enums/dietary_tag.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const DIETARY_TAG_VALUES = [
+  "dairy_free",
+  "egg_free",
+  "gluten_free",
+  "halal",
+  "high_protein",
+  "keto",
+  "low_carb",
+  "low_fat",
+  "low_sodium",
+  "low_sugar",
+  "nut_free",
+  "pescatarian",
+  "soy_free",
+  "vegan",
+  "vegetarian",
+] as const;
+export const DietaryTagSchema = z.enum(DIETARY_TAG_VALUES);
+export type DietaryTag = (typeof DIETARY_TAG_VALUES)[number];

package/src/enums/difficulty.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const DIFFICULTY_VALUES = [
+  "beginner",
+  "intermediate",
+  "advanced",
+  "expert",
+] as const;
+export const DifficultySchema = z.enum(DIFFICULTY_VALUES);
+export type Difficulty = (typeof DIFFICULTY_VALUES)[number];

package/src/enums/image_type.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const IMAGE_TYPE_VALUES = ["recipe", "ingredients"] as const;
+export const ImageTypeSchema = z.enum(IMAGE_TYPE_VALUES);
+export type ImageType = z.infer<typeof ImageTypeSchema>;

package/src/enums/index.ts

@@ -0,0 +1,21 @@
+export * from "./allergen";
+export * from "./cuisine";
+export * from "./dietary_tag";
+export * from "./difficulty";
+export * from "./image_type";
+export * from "./locale";
+export * from "./meal_type";
+export * from "./moderation_status";
+export * from "./priority";
+export * from "./profile_status";
+export * from "./recipe_source";
+export * from "./recipe_status";
+export * from "./role";
+export * from "./severity";
+export * from "./spiciness";
+export * from "./subscription_tier";
+export * from "./suggestion_category";
+export * from "./temperature_unit";
+export * from "./unit";
+export * from "./url_type";
+export * from "./user_status";

package/src/enums/locale.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const LOCALE_VALUES = ["en", "ar", "es", "fr", "ru"] as const;
+export const LocaleSchema = z.enum(LOCALE_VALUES);
+export type Locale = (typeof LOCALE_VALUES)[number];

package/src/enums/meal_type.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const MEAL_TYPE_VALUES = [
+  "appetizer",
+  "breakfast",
+  "brunch",
+  "dessert",
+  "dinner",
+  "drink",
+  "lunch",
+  "snack",
+] as const;
+export const MealTypeSchema = z.enum(MEAL_TYPE_VALUES);
+export type MealType = (typeof MEAL_TYPE_VALUES)[number];

package/src/enums/moderation_status.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const MODERATION_STATUS_VALUES = [
+  "approved",
+  "pending",
+  "rejected",
+] as const;
+export const ModerationStatusSchema = z.enum(MODERATION_STATUS_VALUES);
+export type ModerationStatus = (typeof MODERATION_STATUS_VALUES)[number];

package/src/enums/priority.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const PRIORITY_VALUES = ["low", "medium", "high"] as const;
+export const PrioritySchema = z.enum(PRIORITY_VALUES);
+export type Priority = (typeof PRIORITY_VALUES)[number];

package/src/enums/profile_status.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const PROFILE_STATUS_VALUES = [
+  "active",
+  "deleted",
+  "pending",
+  "suspended",
+] as const;
+export const ProfileStatusSchema = z.enum(PROFILE_STATUS_VALUES);
+export type ProfileStatus = (typeof PROFILE_STATUS_VALUES)[number];

package/src/enums/recipe_source.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const RECIPE_SOURCE_VALUES = ["image", "text", "url", "video"] as const;
+export const RecipeSourceSchema = z.enum(RECIPE_SOURCE_VALUES);
+export type RecipeSource = (typeof RECIPE_SOURCE_VALUES)[number];

package/src/enums/recipe_status.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const RECIPE_STATUS_VALUES = [
+  "active",
+  "archived",
+  "deleted",
+  "pending",
+] as const;
+export const RecipeStatusSchema = z.enum(RECIPE_STATUS_VALUES);
+export type RecipeStatus = (typeof RECIPE_STATUS_VALUES)[number];

package/src/enums/role.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const ROLE_VALUES = [
+  "admin",
+  "moderator",
+  "translator",
+  "user",
+  "guest",
+] as const;
+export const RoleSchema = z.enum(ROLE_VALUES);
+export type Role = (typeof ROLE_VALUES)[number];

package/src/enums/severity.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const SEVERITY_VALUES = ["low", "medium", "high"] as const;
+export const SeveritySchema = z.enum(SEVERITY_VALUES);
+export type Severity = (typeof SEVERITY_VALUES)[number];

package/src/enums/spiciness.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const SPICINESS_VALUES = ["none", "mild", "medium", "hot"] as const;
+export const SpicinessSchema = z.enum(SPICINESS_VALUES);
+export type Spiciness = (typeof SPICINESS_VALUES)[number];

package/src/enums/status.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const STATUS_VALUES = [
+  "active",
+  "archived",
+  "cancelled",
+  "deleted",
+  "pending",
+] as const;
+export const StatusSchema = z.enum(STATUS_VALUES);
+export type Status = (typeof STATUS_VALUES)[number];

package/src/enums/subscription_tier.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+
+export const SubscriptionTierSchema = z.enum(["family", "free", "pro"]);
+export type SubscriptionTier = z.infer<typeof SubscriptionTierSchema>;

package/src/enums/suggestion_category.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const SUGGESTION_CATEGORY_VALUES = [
+  "missing_info",
+  "unclear_instruction",
+  "image_quality",
+  "nutrition",
+  "safety",
+] as const;
+export const SuggestionCategorySchema = z.enum(SUGGESTION_CATEGORY_VALUES);
+export type SuggestionCategory = z.infer<typeof SuggestionCategorySchema>;

package/src/enums/temperature_unit.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const TEMPERATURE_UNIT_VALUES = ["celsius", "fahrenheit"] as const;
+export const TemperatureUnitSchema = z.enum(TEMPERATURE_UNIT_VALUES);
+export type TemperatureUnit = (typeof TEMPERATURE_UNIT_VALUES)[number];

package/src/enums/unit.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+export const UNIT_VALUES = [
+  // Volume (metric)
+  "ml",
+  "l",
+  // Volume (imperial)
+  "tsp",
+  "tbsp",
+  "fl_oz",
+  "cup",
+  "pint",
+  "quart",
+  "gallon",
+  // Weight (metric)
+  "mg",
+  "g",
+  "kg",
+  // Weight (imperial)
+  "oz",
+  "lb",
+  // Count/portion
+  "piece",
+  "whole",
+  "half",
+  "quarter",
+  "slice",
+  "serving",
+  // Produce-specific
+  "clove",
+  "stalk",
+  "sprig",
+  "leaf",
+  "bunch",
+  "head",
+  "fillet",
+  "stick",
+  "sheet",
+  // Container
+  "can",
+  "package",
+  "bottle",
+  "jar",
+  // Imprecise
+  "handful",
+  "pinch",
+  "dash",
+  "drop",
+] as const;
+export const UnitSchema = z.enum(UNIT_VALUES);
+export type Unit = (typeof UNIT_VALUES)[number];

package/src/enums/url_type.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const URL_TYPE_VALUES = [
+  "facebook",
+  "instagram",
+  "pdf",
+  "pinterest",
+  "tiktok",
+  "website",
+  "youtube",
+] as const;
+export const UrlTypeSchema = z.enum(URL_TYPE_VALUES);
+export type UrlType = z.infer<typeof UrlTypeSchema>;

package/src/enums/user_status.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const USER_STATUS_VALUES = [
+  "active",
+  "deleted",
+  "pending",
+  "suspended",
+] as const;
+export const UserStatusSchema = z.enum(USER_STATUS_VALUES);
+export type UserStatus = (typeof USER_STATUS_VALUES)[number];

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./config";
+export * from "./enums";
+export * from "./lib";
+export * from "./types";

package/src/lib/api.ts

@@ -0,0 +1,90 @@
+import {
+  onCall,
+  HttpsError,
+  CallableRequest,
+  CallableOptions,
+} from "firebase-functions/v2/https";
+import { z } from "zod";
+import { isAdmin, isModerator } from "./iam";
+
+const DEFAULT_OPTIONS: CallableOptions = { cors: true, enforceAppCheck: true };
+
+const handleError = (error: unknown): never => {
+  if (error instanceof z.ZodError) {
+    throw new HttpsError(
+      "invalid-argument",
+      `Validation failed: ${error.message}`,
+    );
+  }
+  if (error instanceof HttpsError) {
+    throw error;
+  }
+  throw new HttpsError(
+    "internal",
+    error instanceof Error ? error.message : "Unknown error",
+  );
+};
+
+class CallableBuilder<T> {
+  private requiresAuth = false;
+  private requiresAdmin = false;
+  private requiresModerator = false;
+  private options: CallableOptions = DEFAULT_OPTIONS;
+
+  constructor(private schema: z.ZodSchema<T>) {}
+
+  withOptions(options: CallableOptions) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    return this;
+  }
+
+  requireUser() {
+    this.requiresAuth = true;
+    return this;
+  }
+
+  requireAdmin() {
+    this.requiresAuth = true;
+    this.requiresAdmin = true;
+    return this;
+  }
+
+  requireModerator() {
+    this.requiresAuth = true;
+    this.requiresModerator = true;
+    return this;
+  }
+
+  handle<R>(handler: (data: T, request: CallableRequest) => Promise<R>) {
+    return onCall(this.options, async (request) => {
+      if (this.requiresAuth && !request.auth) {
+        throw new HttpsError("unauthenticated", "Authentication required");
+      }
+
+      if (request.auth) {
+        const uid = request.auth.uid;
+
+        if (this.requiresAdmin && !(await isAdmin(uid))) {
+          throw new HttpsError("permission-denied", "Admin access required");
+        }
+
+        if (this.requiresModerator && !(await isModerator(uid))) {
+          throw new HttpsError(
+            "permission-denied",
+            "Moderator access required",
+          );
+        }
+      }
+
+      try {
+        const data = this.schema.parse(request.data);
+        return await handler(data, request);
+      } catch (error) {
+        throw handleError(error);
+      }
+    });
+  }
+}
+
+export const callable = <T>(schema: z.ZodSchema<T>) =>
+  new CallableBuilder(schema);

package/src/lib/cost.ts

@@ -0,0 +1,72 @@
+import { getDatabase, ServerValue } from "firebase-admin/database";
+import { AIModelConfig } from "../types";
+
+interface BaseUsage {
+  flowName: string;
+  model: AIModelConfig;
+}
+
+interface MultimodalUsage extends BaseUsage {
+  type: "multimodal";
+  inputTokens: number;
+  outputTokens: number;
+}
+
+interface ImageUsage extends BaseUsage {
+  type: "image";
+  imageCount: number;
+}
+
+interface EmbeddingUsage extends BaseUsage {
+  type: "embedding";
+  tokenCount: number;
+}
+
+export type AIUsage = MultimodalUsage | ImageUsage | EmbeddingUsage;
+
+export const logAIUsage = (usage: AIUsage): number => {
+  const { flowName, model } = usage;
+
+  let cost: number;
+  let metrics: Record<string, number>;
+
+  switch (usage.type) {
+    case "multimodal":
+      cost =
+        (usage.inputTokens / 1_000_000) * model.cost.input +
+        (usage.outputTokens / 1_000_000) * model.cost.output;
+      metrics = {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+      };
+      break;
+    case "image":
+      cost = usage.imageCount * model.cost.output;
+      metrics = { images: usage.imageCount };
+      break;
+    case "embedding":
+      cost = (usage.tokenCount / 1_000) * model.cost.input;
+      metrics = { tokens: usage.tokenCount };
+      break;
+  }
+
+  const db = getDatabase();
+  const date = new Date().toISOString().split("T")[0];
+  const base = `ai_usage/live/${date}`;
+
+  const updates: Record<string, unknown> = {
+    [`${base}/total`]: ServerValue.increment(cost),
+    [`${base}/count`]: ServerValue.increment(1),
+    [`${base}/flows/${flowName}/cost`]: ServerValue.increment(cost),
+    [`${base}/flows/${flowName}/count`]: ServerValue.increment(1),
+    [`${base}/models/${model.id}/cost`]: ServerValue.increment(cost),
+  };
+
+  for (const [key, value] of Object.entries(metrics)) {
+    updates[`${base}/models/${model.id}/${key}`] = ServerValue.increment(value);
+  }
+
+  db.ref().update(updates).catch(console.error);
+
+  return cost;
+};

package/src/lib/embedding.ts

@@ -0,0 +1,53 @@
+import { FieldValue } from "firebase-admin/firestore";
+import { defineFirestoreRetriever } from "@genkit-ai/firebase";
+import { firestore } from "./firebase";
+import { ai, geminiEmbedding001 } from "./genkit";
+import { logAIUsage } from "./cost";
+import { AI_MODELS } from "../config/ai";
+
+export const generateEmbedding = async (text: string, flowName: string) => {
+  if (text.length < 1 || text.length > 7500) {
+    throw new Error("Validation error: Text out of range");
+  }
+  const response = await ai.embed({
+    embedder: geminiEmbedding001,
+    content: text,
+  });
+  logAIUsage({
+    type: "embedding",
+    flowName,
+    model: AI_MODELS.GeminiEmbedding001,
+    tokenCount: text.length,
+  });
+  return response[0]?.embedding;
+};
+
+export const storeEmbedding = async (
+  collection: string,
+  docId: string,
+  text: string,
+  flowName?: string,
+  vectorField: string = "embedding",
+) => {
+  const embedding = await generateEmbedding(
+    text,
+    flowName || `${collection}:embedding`,
+  );
+  await firestore
+    .collection(collection)
+    .doc(docId)
+    .update({
+      [vectorField]: FieldValue.vector(embedding),
+    });
+};
+
+export const recipesRetriever = defineFirestoreRetriever(ai, {
+  name: "recipesRetriever",
+  firestore,
+  collection: "recipes",
+  contentField: "searchTerms",
+  vectorField: "titleEmbedding",
+  embedder: geminiEmbedding001,
+  distanceMeasure: "COSINE",
+  distanceResultField: "distance",
+});

package/src/lib/firebase.ts

@@ -0,0 +1,5 @@
+import { getFirestore } from "firebase-admin/firestore";
+import { getDatabase } from "firebase-admin/database";
+
+export const firestore = getFirestore();
+export const rtdb = getDatabase();