Base code

2026-01-08 22:39:53 +07:00
parent 697115c61a
commit c35fa52117
2169 changed files with 626670 additions and 0 deletions
--- a/docs-site/docs/features/integrations/wix/api.md
+++ b/docs-site/docs/features/integrations/wix/api.md
@@ -0,0 +1,58 @@
+# API (Summary)
+
+Short reference of Wix integration endpoints exposed by ALwrity’s backend.
+
+## Authentication
+### Get Authorization URL
+```http
+GET /api/wix/auth/url?state=optional_state
+```
+
+### OAuth Callback
+```http
+POST /api/wix/auth/callback
+Content-Type: application/json
+{
+  "code": "authorization_code",
+  "state": "optional_state"
+}
+```
+
+## Connection
+### Status
+```http
+GET /api/wix/connection/status
+```
+
+### Disconnect
+```http
+POST /api/wix/disconnect
+```
+
+## Publishing
+### Publish blog post
+```http
+POST /api/wix/publish
+Content-Type: application/json
+{
+  "title": "Blog Post Title",
+  "content": "Markdown",
+  "cover_image_url": "https://example.com/image.jpg",
+  "category_ids": ["category_id"],
+  "tag_ids": ["tag_id_1", "tag_id_2"],
+  "publish": true
+}
+```
+
+## Content Management
+### Categories
+```http
+GET /api/wix/categories
+```
+
+### Tags
+```http
+GET /api/wix/tags
+```
+
+
--- a/docs-site/docs/features/integrations/wix/overview.md
+++ b/docs-site/docs/features/integrations/wix/overview.md
@@ -0,0 +1,33 @@
+# Wix Integration (Overview)
+
+ALwrity’s Wix integration lets you publish AI‑generated blogs directly to your Wix site, including categories/tags and SEO metadata.
+
+## What’s Included
+- OAuth connection (Headless OAuth – Client ID only)
+- Markdown → Wix Ricos JSON conversion
+- Image import to Wix Media Manager
+- Blog creation and publish (draft or published)
+- Categories/tags lookup + auto-create
+- SEO metadata posting (keywords, meta, OG, Twitter, canonical)
+
+## High-level Flow
+1. Connect your Wix account (OAuth)
+2. Convert blog content to Ricos JSON
+3. Import images
+4. Create blog post
+5. Publish and return URL
+
+## Benefits
+- One-click publishing from ALwrity
+- Preserves formatting and images
+- Posts complete SEO metadata
+- Clear error handling and feedback
+
+See also:
+- Setup: setup.md
+- Publishing: publishing.md
+- API: api.md
+- SEO Metadata: seo-metadata.md
+- Testing (Bypass): testing-bypass.md
+
+
--- a/docs-site/docs/features/integrations/wix/publishing.md
+++ b/docs-site/docs/features/integrations/wix/publishing.md
@@ -0,0 +1,28 @@
+# Publishing Flow
+
+End‑to‑end flow for publishing a blog post to Wix.
+
+## Steps
+1. Check connection (tokens + `memberId`)
+2. Convert markdown → Ricos JSON
+3. Import images to Wix Media Manager
+4. Create blog post via Wix Blog API
+5. Publish (or save draft)
+6. Return URL
+
+## From the Blog Writer
+- Generate content in ALwrity
+- Use “Publish to Wix” action
+- The publisher will:
+  - Verify connection
+  - Convert content
+  - Import images
+  - Create & publish
+  - Return published URL
+
+## Notes
+- Categories and tags are looked up/created automatically
+- SEO metadata is posted with the blog (see SEO Metadata)
+- Errors are reported with actionable messages
+
+
--- a/docs-site/docs/features/integrations/wix/seo-metadata.md
+++ b/docs-site/docs/features/integrations/wix/seo-metadata.md
@@ -0,0 +1,52 @@
+# SEO Metadata (Wix)
+
+This page summarizes what ALwrity posts to Wix and what remains out of scope.
+
+## Posted to Wix
+- Keywords (seoData.settings.keywords)
+  - Main keyword: `focus_keyword` → `isMain: true`
+  - Additional: `blog_tags`, `social_hashtags` → `isMain: false`
+- Meta Tags (seoData.tags)
+  - `<meta name="description">` from `meta_description`
+  - `<meta name="title">` from `seo_title`
+- Open Graph (seoData.tags)
+  - `og:title`, `og:description`, `og:image`, `og:type=article`, `og:url`
+- Twitter Card (seoData.tags)
+  - `twitter:title`, `twitter:description`, `twitter:image`, `twitter:card`
+- Canonical URL (seoData.tags)
+  - `<link rel="canonical">`
+- Categories & Tags
+  - Auto‑lookup/create and post as `categoryIds` and `tagIds`
+
+## Not Posted (Limitations)
+- JSON‑LD structured data
+  - Reason: Requires Wix site frontend (`@wix/site-seo`)
+- URL slug customization
+  - Wix auto‑generates from title
+- Reading time / optimization score
+  - Internal metadata, not part of Wix post
+
+## Conversion
+- Markdown → Ricos JSON via official API (with custom parser fallback)
+- Supports headings, paragraphs, lists, images, basic formatting
+
+## Example (structure excerpt)
+```json
+{
+  "draftPost": {
+    "title": "SEO optimized title",
+    "memberId": "author-member-id",
+    "richContent": { /* Ricos JSON */ },
+    "excerpt": "First 200 chars...",
+    "categoryIds": ["uuid1"],
+    "tagIds": ["uuid1","uuid2"],
+    "seoData": {
+      "settings": { "keywords": [ { "term": "main", "isMain": true } ] },
+      "tags": [ { "type": "meta", "props": { "name": "description", "content": "..." } } ]
+    }
+  },
+  "publish": true
+}
+```
+
+
--- a/docs-site/docs/features/integrations/wix/setup.md
+++ b/docs-site/docs/features/integrations/wix/setup.md
@@ -0,0 +1,40 @@
+# Wix Integration Setup
+
+## Wix App Configuration
+1. Go to Wix Developers and create an app
+2. Set redirect URI: `http://localhost:3000/wix/callback` (dev)
+3. Scopes: `BLOG.CREATE-DRAFT`, `BLOG.PUBLISH`, `MEDIA.MANAGE`
+4. Note your Client ID (Headless OAuth uses Client ID only)
+
+## Environment
+```bash
+# .env
+WIX_CLIENT_ID=your_wix_client_id_here
+WIX_REDIRECT_URI=http://localhost:3000/wix/callback
+```
+
+## Database (tokens)
+Store tokens per user:
+```sql
+CREATE TABLE wix_tokens (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id TEXT NOT NULL,
+  access_token TEXT NOT NULL,
+  refresh_token TEXT,
+  expires_at TIMESTAMP,
+  member_id TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+## Third‑Party App Requirement
+`memberId` is mandatory for third‑party blog creation. The OAuth flow retrieves and stores it and it is used when creating posts.
+
+## Key Files
+- Backend service: `backend/services/wix_service.py`
+- API routes: `backend/api/wix_routes.py`
+- Test page: `frontend/src/components/WixTestPage/WixTestPage.tsx`
+- Blog publisher: `frontend/src/components/BlogWriter/Publisher.tsx`
+
+
--- a/docs-site/docs/features/integrations/wix/testing-bypass.md
+++ b/docs-site/docs/features/integrations/wix/testing-bypass.md
@@ -0,0 +1,34 @@
+# Testing (Bypass Guide)
+
+Local testing options to exercise Wix integration without onboarding blockers.
+
+## Routes
+| Option | URL | Purpose |
+| --- | --- | --- |
+| Primary | `http://localhost:3000/wix-test` | Main Wix test page |
+| Backup | `http://localhost:3000/wix-test-direct` | Direct route (no protections) |
+| Backend | `http://localhost:8000/api/wix/auth/url` | Direct API testing |
+
+## How to Test
+1. Start backend: `python start_alwrity_backend.py`  
+2. Start frontend: `npm start`  
+3. Navigate to `/wix-test`, connect account, publish a test post
+
+## Env (backend)
+```bash
+WIX_CLIENT_ID=your_wix_client_id_here
+WIX_REDIRECT_URI=http://localhost:3000/wix/callback
+```
+
+## Restore After Testing
+- Re‑enable monitoring middleware in `backend/app.py` if disabled  
+- Remove any temporary onboarding mocks  
+- Restore `ProtectedRoute` for `/wix-test` if removed
+
+## Expected Results
+- No onboarding redirect
+- Wix OAuth works
+- Blog posting works
+- No rate‑limit errors
+
+