# ─── .env additions ──────────────────────────────────────────────────────────
# Add these to your Laravel .env file

# Synthflow AI
SYNTHFLOW_API_KEY=sf_live_xxxxxxxxxxxxxxxxxxxx
SYNTHFLOW_AGENT_ID=agent_xxxxxxxxxxxxxxxxxxxx
SYNTHFLOW_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx
SYNTHFLOW_BASE_URL=https://api.synthflow.ai/v2
SYNTHFLOW_TIMEOUT=15

# Plumbing company identity
PLUMBING_COMPANY_NAME="ProFlow Plumbing"
PLUMBING_LICENSE_NUMBER=PLM-2024-001234
PLUMBING_STATE=Arizona
PLUMBING_PHONE=5550001234
PLUMBING_PHONE_DISPLAY="(555) 000-1234"
PLUMBING_EMAIL=info@proflowplumbing.com
PLUMBING_HOURS="Mon–Fri 8am–6pm · 24/7 Emergency"
PLUMBING_AGENT_NAME=Alex

================================================================================
README — Plumber AI Service Request System (Laravel 10 + Synthflow)
================================================================================

OVERVIEW
────────
This module adds a client-facing plumbing service request form to a Laravel 10
application. When a client submits the form, the Synthflow AI receptionist
automatically calls them back within minutes to confirm the appointment, gather
extra details, and answer questions — acting as a 24/7 phone receptionist.

FILE STRUCTURE
──────────────
resources/views/plumbing/
  request.blade.php          ← Client-facing service request form
  confirmation.blade.php     ← Post-submission confirmation page

app/
  Http/
    Controllers/
      PlumbingRequestController.php   ← Form handler + Synthflow dispatch + webhook
    Requests/
      PlumbingServiceRequest.php      ← Form validation rules
  Models/
    PlumbingRequest.php               ← Eloquent model
  Services/
    SynthflowService.php              ← All Synthflow API communication

database/migrations/
  ..._create_plumbing_requests_table.php   ← Full schema

routes/web.php          ← Route definitions (plumbing + synthflow webhook)
config/synthflow.php    ← Synthflow config (reads from .env)
config/plumbing.php     ← Company identity config (reads from .env)

INSTALLATION STEPS
──────────────────

1. COPY FILES
   Copy all files into your Laravel 10 project following the path structure above.

2. RUN MIGRATION
   php artisan migrate

3. SET ENVIRONMENT VARIABLES
   Copy the .env additions above into your .env file.
   Fill in your actual Synthflow API key and Agent ID.

4. REGISTER CONFIG FILES
   The config files are auto-discovered. Optionally clear config cache:
   php artisan config:clear

5. EXCLUDE WEBHOOK FROM CSRF
   The route file already handles this with ->withoutMiddleware(...).
   Make sure your VerifyCsrfToken middleware is at:
   app/Http/Middleware/VerifyCsrfToken.php

6. SYNTHFLOW DASHBOARD SETUP
   a. Create an Inbound/Outbound Voice Agent in Synthflow
   b. Paste the generated System Prompt (from the onboarding tool) into Agent Settings
   c. Copy your Agent ID → set SYNTHFLOW_AGENT_ID in .env
   d. Create a Webhook endpoint pointing to: https://yourdomain.com/webhooks/synthflow
   e. Copy the Webhook Signing Secret → set SYNTHFLOW_WEBHOOK_SECRET in .env
   f. Copy your API Key → set SYNTHFLOW_API_KEY in .env

7. TEST THE FLOW
   a. Visit /plumbing/request
   b. Fill out the form with a real phone number
   c. Submit → you should receive a call from Synthflow within 1–3 minutes
   d. Check storage/logs/laravel.log for dispatch confirmation

ROUTES
──────
  GET  /plumbing/request                          → Show form
  POST /plumbing/request                          → Submit form (rate limited: 10/min)
  GET  /plumbing/request/{id}/confirmation        → Confirmation page
  POST /webhooks/synthflow                        → Synthflow webhook (no CSRF)

SYNTHFLOW CALL FLOW
───────────────────
  1. Client submits form
  2. PlumbingRequestController::store() saves to DB
  3. SynthflowService::dispatchReceptionistCall() POSTs to Synthflow API
  4. Synthflow dials client's phone number using the AI agent
  5. AI agent speaks the opening line from buildFirstMessage()
  6. AI agent has full client context injected via custom_data
  7. After call ends, Synthflow POSTs webhook to /webhooks/synthflow
  8. SynthflowService::handleWebhook() updates DB with transcript/summary

EMERGENCY HANDLING
──────────────────
When urgency=emergency or service_type=emergency:
  - buildFirstMessage() generates an urgent opening line
  - The AI agent's system prompt (configured in Synthflow) handles escalation
  - Consider adding a queue job to also alert dispatchers via SMS/Slack

CUSTOMIZATION
─────────────
  - Change company name/phone/hours → .env or config/plumbing.php
  - Change AI agent name → PLUMBING_AGENT_NAME in .env
  - Add/remove service types → update the $services array in request.blade.php
                               and the 'in' validation rule in PlumbingServiceRequest
  - Send post-call SMS → add Twilio/Vonage in onCallCompleted() in SynthflowService
  - CRM integration → dispatch a job from onCallCompleted() to push to ServiceTitan,
                       Housecall Pro, Jobber, etc.

SECURITY NOTES
──────────────
  - Webhook signature verification uses HMAC-SHA256 (Synthflow standard)
  - Form rate-limited to 10 submissions/minute per IP
  - Honeypot field (website_url) blocks simple bots via 'prohibited' rule
  - Phone is normalized to E.164 before sending to Synthflow
  - IP address logged for abuse tracking