{
  "name": "VoiceCommit Widget Integration",
  "version": "1.0.0",
  "description": "AI-optimized specification for integrating VoiceCommit voice feedback widgets",
  "baseUrl": "https://app.voicecommit.com",
  "requirements": {
    "https": true,
    "microphone": true,
    "browsers": ["Chrome 60+", "Firefox 55+", "Safari 11+", "Edge 79+"]
  },
  "integration": {
    "basic": {
      "description": "Automatic initialization - simplest integration",
      "code": {
        "css": "https://app.voicecommit.com/api/widget/{WIDGET_ID}/widget.css",
        "javascript": "https://app.voicecommit.com/api/widget/{WIDGET_ID}/widget.js",
        "attributes": {
          "data-widget-id": "{WIDGET_ID}"
        }
      },
      "example": "<link rel=\"stylesheet\" href=\"https://app.voicecommit.com/api/widget/{WIDGET_ID}/widget.css\">\n<script src=\"https://app.voicecommit.com/api/widget/{WIDGET_ID}/widget.js\" data-widget-id=\"{WIDGET_ID}\"></script>"
    },
    "manual": {
      "description": "Manual initialization for advanced control",
      "code": {
        "css": "https://app.voicecommit.com/api/widget/{WIDGET_ID}/widget.css",
        "javascript": "https://app.voicecommit.com/api/widget/{WIDGET_ID}/widget.js",
        "attributes": {
          "data-manual": "true"
        },
        "initCode": "window.VoiceCommitWidget.init({ widgetId: '{WIDGET_ID}' })"
      }
    }
  },
  "frameworks": {
    "react": {
      "type": "useEffect",
      "cleanup": true,
      "example": "useEffect(() => {\n  const link = document.createElement('link');\n  link.rel = 'stylesheet';\n  link.href = `https://app.voicecommit.com/api/widget/${widgetId}/widget.css`;\n  document.head.appendChild(link);\n  \n  const script = document.createElement('script');\n  script.src = `https://app.voicecommit.com/api/widget/${widgetId}/widget.js`;\n  script.setAttribute('data-widget-id', widgetId);\n  document.head.appendChild(script);\n  \n  return () => {\n    document.head.removeChild(link);\n    document.head.removeChild(script);\n  };\n}, [widgetId]);"
    },
    "vue": {
      "type": "mounted",
      "lifecycle": "mounted",
      "example": "mounted() {\n  const link = document.createElement('link');\n  link.rel = 'stylesheet';\n  link.href = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.css`;\n  document.head.appendChild(link);\n  \n  const script = document.createElement('script');\n  script.src = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.js`;\n  script.setAttribute('data-widget-id', this.widgetId);\n  document.head.appendChild(script);\n}"
    },
    "angular": {
      "type": "ngOnInit",
      "lifecycle": "OnInit",
      "example": "ngOnInit() {\n  const link = document.createElement('link');\n  link.rel = 'stylesheet';\n  link.href = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.css`;\n  document.head.appendChild(link);\n  \n  const script = document.createElement('script');\n  script.src = `https://app.voicecommit.com/api/widget/${this.widgetId}/widget.js`;\n  script.setAttribute('data-widget-id', this.widgetId);\n  document.head.appendChild(script);\n}"
    }
  },
  "configuration": {
    "widgetTypes": [
      {
        "id": "feedback-dashboard",
        "name": "Feedback Dashboard",
        "description": "Collects feedback in VoiceCommit dashboard"
      },
      {
        "id": "github-issue", 
        "name": "GitHub Issues",
        "description": "Creates GitHub issues from voice input"
      },
      {
        "id": "github-pr",
        "name": "GitHub Pull Requests", 
        "description": "Creates GitHub pull requests from voice input"
      }
    ],
    "positions": ["bottom-right", "bottom-left", "top-right", "top-left"],
    "themes": ["auto", "light", "dark"],
    "rateLimit": {
      "default": 10,
      "unit": "per hour per domain",
      "configurable": true
    }
  },
  "security": {
    "csp": {
      "script-src": "https://app.voicecommit.com",
      "style-src": "https://app.voicecommit.com", 
      "connect-src": "https://app.voicecommit.com",
      "media-src": "blob:"
    },
    "cors": {
      "origin": "configurable per widget",
      "credentials": false
    }
  },
  "troubleshooting": {
    "common_issues": [
      {
        "issue": "Widget not appearing",
        "solutions": [
          "Verify widget ID is correct",
          "Check domain is authorized",
          "Ensure CSS and JS load successfully",
          "Check browser console for errors"
        ]
      },
      {
        "issue": "Voice recording not working", 
        "solutions": [
          "Ensure HTTPS (required)",
          "Check microphone permissions",
          "Test on supported browsers",
          "Verify no CSP blocking"
        ]
      },
      {
        "issue": "CSP blocking resources",
        "solutions": [
          "Add app.voicecommit.com to script-src",
          "Add app.voicecommit.com to style-src", 
          "Add app.voicecommit.com to connect-src",
          "Add blob: to media-src"
        ]
      }
    ]
  },
  "api": {
    "endpoints": {
      "widget_config": {
        "url": "/api/widget/{widgetId}/config",
        "method": "GET",
        "description": "Get widget configuration"
      },
      "submit_feedback": {
        "url": "/api/widget/{widgetId}/submit", 
        "method": "POST",
        "contentType": "application/json",
        "body": {
          "transcript": "string (required)",
          "domain": "string (required)",
          "user_agent": "string (optional)"
        }
      }
    }
  },
  "setup_steps": [
    {
      "step": 1,
      "action": "Create widget at https://app.voicecommit.com/widgets/new"
    },
    {
      "step": 2, 
      "action": "Copy widget ID from settings page"
    },
    {
      "step": 3,
      "action": "Add your domain to widget's allowed domains"
    },
    {
      "step": 4,
      "action": "Integrate code using examples above"
    },
    {
      "step": 5,
      "action": "Test voice recording and submission"
    }
  ],
  "ai_assistant_instructions": {
    "when_helping_with_integration": [
      "Always ask for widget ID first",
      "Remind about HTTPS requirement for voice recording", 
      "Check if domain is added to widget's allowed domains",
      "Provide framework-specific examples when possible",
      "Include CSP configuration if site uses CSP",
      "Test voice recording functionality after integration"
    ],
    "common_ai_tasks": [
      "Generate integration code for specific frameworks",
      "Debug CSP issues with widget loading",
      "Create test pages for widget functionality",
      "Convert basic integration to manual initialization",
      "Add widget to existing component libraries"
    ]
  }
}