feat: Implement premium AI natural language search endpoint and middleware for tier-based access control

Author: myProjectsRavi

README.md

@@ -329,10 +329,11 @@ The `/v1/search` endpoint returns detailed nutritional information. The `primary
 
 Performs a search using a natural language query to identify a food and its quantity.
 
-- **Endpoint**: `GET /v1/natural-language-search`
-- **Authentication**: Required (API Key)
-- **Query Parameters**:
-  - `query` (required): A natural language query (e.g., "100g of cheddar cheese").
+- **Endpoint**: `POST /v1/natural-language-search`
+- **Authentication**: Required (API Key – Free or Pro)
+- **Body**:
+  - `text` (string, required): A natural language query (e.g., "100g of cheddar cheese").
+  - `maxResults`, `confidence`, `filterForSuggestions` (optional): Advanced controls for USDA lookups.
 - **Success Response (`200 OK`)**:
   ```json
   {
@@ -364,6 +365,21 @@ Performs a search using a natural language query to identify a food and its quan
   }
   ```
 
+### Premium AI Natural Language Search (Pro Tier)
+
+Unlock the Workers AI-powered parser for more nuanced, multi-item meal descriptions.
+
+- **Endpoint**: `POST /v2/ai-natural-language-search`
+- **Authentication**: Requires a **Pro tier** API key
+- **Body**:
+  - `text` (string, required): Meal description (max 500 characters)
+  - Optional knobs: `maxResults`, `confidence`, `filterForSuggestions`
+- **What you get**:
+  - AI-interpreted items with unit normalization and gram estimates
+  - USDA-backed search results with confidence scores
+  - Response meta showing cache status and model identifier (`@cf/meta/llama-2-7b-chat-int8`)
+- **Generate a Pro key**: `GET /_admin/generate-key?tier=pro`
+
 ---
 
 ## Getting Started & Deployment
@@ -576,6 +592,8 @@ We offer the following tiers for our API:
 | Pro    | $50/month  | 100,000        |
 | Enterprise | Custom | Custom         |
 
+- **Premium Features**: The `POST /v2/ai-natural-language-search` endpoint and future AI add-ons are available to Pro keys (and above) only. Requests from Free keys return `403 Forbidden`.
+
 For more details, please visit our pricing page at [example.com/pricing](https://example.com/pricing).
 
 ---

openapi.json

@@ -235,6 +235,95 @@
           "429": { "$ref": "#/components/responses/TooManyRequests" }
         }
       }
+    },
+    "/v2/ai-natural-language-search": {
+      "post": {
+        "summary": "Premium AI-Powered Natural Language Search",
+        "description": "Parses complex meal descriptions using Cloudflare Workers AI (Meta Llama 2 7B) to produce structured food items, quantity estimates, and confidence scores. **Requires a Pro-tier API key.** The endpoint caches responses and returns USDA search suggestions alongside the AI interpretation.",
+        "operationId": "ai_natural_language_search",
+        "security": [{ "ApiKeyAuth": [] }],
+        "tags": ["Food", "Premium"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["text"],
+                "properties": {
+                  "text": {
+                    "type": "string",
+                    "description": "Natural language meal description (500 characters max).",
+                    "example": "A grilled chicken breast with 2 cups of steamed broccoli"
+                  },
+                  "maxResults": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 25,
+                    "default": 5,
+                    "description": "Maximum USDA search results to return per parsed food item."
+                  },
+                  "confidence": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1,
+                    "default": 0.8,
+                    "description": "Minimum string-similarity confidence required for USDA results."
+                  },
+                  "filterForSuggestions": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "When true, results are filtered to only suggestions above the confidence threshold."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful AI parsing and USDA lookup.",
+            "headers": {
+              "X-Cache-Status": {
+                "schema": { "type": "string" },
+                "description": "Cache status for the AI response (MISS, HIT, or STALE)."
+              },
+              "X-RateLimit-Limit": {
+                "schema": { "type": "integer" },
+                "description": "Maximum requests allowed in the current window."
+              },
+              "X-RateLimit-Remaining": {
+                "schema": { "type": "integer" },
+                "description": "Remaining requests in the current window."
+              },
+              "X-RateLimit-Reset": {
+                "schema": { "type": "integer" },
+                "description": "Seconds until the current window resets."
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AiNaturalLanguageSearchResponse"
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/BadRequest" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": {
+            "description": "Forbidden – API key tier is not authorized for premium AI endpoints.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "429": { "$ref": "#/components/responses/TooManyRequests" }
+        }
+      }
     }
   },
   "components": {
@@ -406,6 +495,59 @@
           }
         }
       },
+      "ParsedAiFoodItem": {
+        "type": "object",
+        "properties": {
+          "quantity": { "type": "number" },
+          "unit": { "type": "string", "nullable": true },
+          "foodName": { "type": "string" },
+          "quantityInGrams": { "type": "number", "nullable": true },
+          "modifiers": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Preparation or context modifiers detected by Workers AI."
+          },
+          "category": { "type": "string", "nullable": true },
+          "combinedWith": { "type": "string", "nullable": true }
+        }
+      },
+      "AiNaturalLanguageSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean" },
+          "data": {
+            "type": "object",
+            "properties": {
+              "query": { "type": "string" },
+              "searchResults": {
+                "type": "array",
+                "description": "Filtered USDA search results enriched with confidence scores.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              },
+              "totalResults": { "type": "integer" },
+              "foodNameConfidence": {
+                "type": "number",
+                "description": "Average confidence score across parsed items."
+              },
+              "parsedItems": {
+                "type": "array",
+                "items": { "$ref": "#/components/schemas/ParsedAiFoodItem" }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "requestId": { "type": "string" },
+              "cacheStatus": { "type": "string" },
+              "model": { "type": "string", "example": "@cf/meta/llama-2-7b-chat-int8" }
+            }
+          }
+        }
+      },
       "ParsedFoodItem": {
         "type": "object",
         "properties": {

package-lock.json

@@ -28,6 +28,7 @@
     "npm": ">=8.0.0"
   },
   "dependencies": {
+    "@cloudflare/ai": "^1.0.0",
     "itty-router": "^4.0.23",
     "zod": "^3.25.76"
   },