{"openapi":"3.0.1","info":{"title":"meet&buy API","version":"1.1.0","description":"Public and admin endpoints for deal management."},"servers":[{"url":"https://meetnbuy.ai"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Admin API token (ADMIN_API_TOKENS env var). Required for all admin endpoints."}},"schemas":{"Deal":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"productDescription":{"type":"string","nullable":true},"starRating":{"type":"number","nullable":true},"reviewCount":{"type":"number","nullable":true},"dealBadge":{"type":"string","nullable":true},"flameCount":{"type":"number","nullable":true},"recommendation":{"type":"string","nullable":true},"oneLineReason":{"type":"string","nullable":true},"marketResearchInsights":{"type":"array","items":{"type":"string"},"nullable":true},"url":{"type":"string"},"category":{"type":"string","nullable":true},"limitedTimeDeal":{"type":"boolean"},"lightningDeal":{"type":"boolean"},"lightningEndsAt":{"type":"number","nullable":true},"couponEnabled":{"type":"boolean"},"couponCode":{"type":"string","nullable":true},"couponAmount":{"type":"number","nullable":true},"salePrice":{"type":"number","nullable":true},"originalPrice":{"type":"number","nullable":true},"currency":{"type":"string"},"imageUrl":{"type":"string","nullable":true},"approved":{"type":"boolean"},"createdAt":{"type":"number","nullable":true},"merchant":{"type":"string","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/api/deals":{"get":{"summary":"List approved deals","description":"Returns a paginated list of approved deals. Lightning deals past their end time are excluded.","parameters":[{"name":"limit","in":"query","description":"Number of deals to return (1–50, default 10)","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"cursor","in":"query","description":"Pagination cursor (createdAt timestamp millis from previous response)","schema":{"type":"string"}},{"name":"q","in":"query","description":"Full-text search query","schema":{"type":"string"}},{"name":"admin","in":"query","description":"Set to '1' to enable admin mode (returns unapproved deals too). Requires Bearer token.","schema":{"type":"string","enum":["1"]}},{"name":"approved","in":"query","description":"Filter by approval status in admin mode. 'true' = approved only, 'false' = unapproved only, omit = all.","schema":{"type":"string","enum":["true","false"]}},{"name":"date","in":"query","description":"Filter by creation date in admin mode (YYYY-MM-DD, UTC). Returns only deals created on that day.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Paginated deal list","content":{"application/json":{"schema":{"type":"object","properties":{"deals":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}},"nextCursor":{"type":"string","nullable":true}}}}}}}},"post":{"summary":"Create a deal (admin)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"approved":{"type":"boolean","default":false},"limitedTimeDeal":{"type":"boolean"},"lightningDeal":{"type":"boolean"},"couponEnabled":{"type":"boolean"},"couponCode":{"type":"string"},"couponAmount":{"type":"number"},"salePrice":{"type":"number"},"originalPrice":{"type":"number"}}}}}},"responses":{"200":{"description":"Created deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/deals/{id}/approve":{"post":{"summary":"Approve or unapprove a deal (admin)","description":"Sets the approved flag on a deal. Approved deals are visible to the public; unapproved deals are hidden.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"approved":{"type":"boolean","description":"true to approve, false to unapprove. Defaults to true if omitted."}}}}}},"responses":{"200":{"description":"Updated approval state","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"approved":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/deals/{id}":{"patch":{"summary":"Update a deal (admin)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approved":{"type":"boolean"},"title":{"type":"string"},"productDescription":{"type":"string","nullable":true},"starRating":{"type":"number","nullable":true},"reviewCount":{"type":"number","nullable":true},"dealBadge":{"type":"string","nullable":true},"flameCount":{"type":"number","nullable":true},"recommendation":{"type":"string","nullable":true},"oneLineReason":{"type":"string","nullable":true},"url":{"type":"string"},"merchant":{"type":"string"},"category":{"type":"string"},"salePrice":{"type":"number"},"originalPrice":{"type":"number"},"currency":{"type":"string"},"limitedTimeDeal":{"type":"boolean"},"lightningDeal":{"type":"boolean"},"lightningDurationHours":{"type":"number"},"lightningDurationMinutes":{"type":"number"},"lightningDurationSeconds":{"type":"number"},"couponEnabled":{"type":"boolean"},"couponCode":{"type":"string","nullable":true},"couponAmount":{"type":"number","nullable":true},"imageUrl":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Updated deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Deal not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a deal (admin)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deal deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/deals/from-url":{"post":{"summary":"Create a deal from URL (admin)","description":"Fetches product data from a URL, extracts deal info with Gemini, and creates a deal.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"category":{"type":"string"},"approved":{"type":"boolean","default":false},"limitedTimeDeal":{"type":"boolean"},"lightningDeal":{"type":"boolean"},"lightningDurationHours":{"type":"number"},"lightningDurationMinutes":{"type":"number"},"lightningDurationSeconds":{"type":"number"},"couponEnabled":{"type":"boolean"},"couponCode":{"type":"string"},"couponAmount":{"type":"number","nullable":true}}}}}},"responses":{"200":{"description":"Created deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/bulkload":{"post":{"summary":"Run a full bulk load job (admin)","description":"Scrapes deal URLs from sourceUrl, fetches metadata via Gemini, scores deals, and writes approved ones to Firestore in a single synchronous pipeline.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string","description":"Amazon deals page URL to scrape. Defaults to the configured gold-box URL."},"maxDeals":{"type":"integer","description":"Maximum number of deals to process (default 20, max 100)."}}}}}},"responses":{"200":{"description":"Bulk load results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"dealId":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"skipped":{"type":"boolean"},"flameCount":{"type":"number","nullable":true},"starRating":{"type":"number","nullable":true},"salePrice":{"type":"number","nullable":true},"originalPrice":{"type":"number","nullable":true},"discountPct":{"type":"number","nullable":true},"error":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/bulkload/collect":{"post":{"summary":"Collect deal URLs (admin)","description":"Scrapes deal URLs from a source page and persists them to the automateddeals staging collection for later metadata/process steps.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string"},"dateKey":{"type":"string","description":"YYYY-MM-DD key. Defaults to today."},"persist":{"type":"boolean","description":"Write results to Firestore. Default true."},"urls":{"type":"array","items":{"type":"string"},"description":"Provide URLs directly instead of scraping."},"progressId":{"type":"string","description":"ID to track progress via /api/admin/bulkload/progress."}}}}}},"responses":{"200":{"description":"Collect results","content":{"application/json":{"schema":{"type":"object","properties":{"dateKey":{"type":"string"},"newAddedCount":{"type":"integer"},"existingSkippedCount":{"type":"integer"},"totalCollected":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/bulkload/metadata":{"post":{"summary":"Fetch metadata for collected URLs (admin)","description":"For each unprocessed URL in the automateddeals staging collection, fetches product metadata (title, price, rating) via Gemini.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string"},"dateKey":{"type":"string"},"count":{"type":"integer","description":"Max number of items to process in this batch."}}}}}},"responses":{"200":{"description":"Metadata batch results","content":{"application/json":{"schema":{"type":"object","properties":{"processed":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"ok":{"type":"boolean"},"skipped":{"type":"boolean"},"title":{"type":"string","nullable":true},"salePrice":{"type":"number","nullable":true},"originalPrice":{"type":"number","nullable":true},"error":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/bulkload/process":{"post":{"summary":"Process staged deals into the deals collection (admin)","description":"Scores and writes metadata-ready staged deals from automateddeals into the main deals collection. Skips deals below the flame threshold.","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceUrl":{"type":"string"},"dateKey":{"type":"string"},"count":{"type":"integer","description":"Max number of items to process in this batch."}}}}}},"responses":{"200":{"description":"Process batch results","content":{"application/json":{"schema":{"type":"object","properties":{"processed":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"ok":{"type":"boolean"},"skipped":{"type":"boolean"},"dealId":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"flameCount":{"type":"number","nullable":true},"starRating":{"type":"number","nullable":true},"salePrice":{"type":"number","nullable":true},"originalPrice":{"type":"number","nullable":true},"discountPct":{"type":"number","nullable":true},"error":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/bulkload/progress":{"get":{"summary":"Poll bulk load progress (admin)","description":"Returns the current status of a running bulk load job by progressId.","security":[{"bearerAuth":[]}],"parameters":[{"name":"progressId","in":"query","required":true,"schema":{"type":"string"},"description":"The progressId returned by /collect or set by the caller."}],"responses":{"200":{"description":"Progress status","content":{"application/json":{"schema":{"type":"object","properties":{"progressId":{"type":"string"},"status":{"type":"string","enum":["running","done","error"]},"total":{"type":"integer"},"processed":{"type":"integer"},"added":{"type":"integer"},"existingSkipped":{"type":"integer"}}}}}},"400":{"description":"Missing progressId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Progress record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/deals/insights":{"post":{"summary":"Generate AI deal insights","description":"Generates market research insights for a deal using Gemini.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"category":{"type":"string"},"salePrice":{"type":"number"},"originalPrice":{"type":"number"},"currency":{"type":"string"},"starRating":{"type":"number"},"reviewCount":{"type":"number"},"flameCount":{"type":"number"},"limitedTimeDeal":{"type":"boolean"},"lightningDeal":{"type":"boolean"},"merchant":{"type":"string"},"productDescription":{"type":"string"},"recommendation":{"type":"string"},"oneLineReason":{"type":"string"},"couponCode":{"type":"string"},"couponAmount":{"type":"number"}}}}}},"responses":{"200":{"description":"Generated insights","content":{"application/json":{"schema":{"type":"object","properties":{"insights":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}