ALwrity/docs/WIX_INTEGRATION_README.md

Wix Integration for ALwrity

This document describes the Wix integration feature that allows ALwrity users to publish their generated blogs directly to their Wix websites.

Overview

The Wix integration provides a seamless way for ALwrity users to:

• Connect their Wix account to ALwrity
• Publish blog posts directly from ALwrity to their Wix website
• Manage blog categories and tags
• Import images to Wix Media Manager

Architecture

Backend Components

1. WixService (services/wix_service.py)

   • Handles OAuth 2.0 authentication with Wix
   • Manages token refresh and validation
   • Converts content to Wix Ricos JSON format
   • Imports images to Wix Media Manager
   • Creates and publishes blog posts

2. Wix Routes (api/wix_routes.py)

   • /api/wix/auth/url - Get OAuth authorization URL
   • /api/wix/auth/callback - Handle OAuth callback
   • /api/wix/connection/status - Check connection status
   • /api/wix/publish - Publish blog post to Wix
   • /api/wix/categories - Get blog categories
   • /api/wix/tags - Get blog tags
   • /api/wix/disconnect - Disconnect Wix account

Frontend Components

1. WixTestPage (frontend/src/components/WixTestPage/WixTestPage.tsx)

   • Test page for Wix integration functionality
   • Connection status display
   • Blog post creation and publishing form
   • Category and tag management

2. Enhanced Publisher (frontend/src/components/BlogWriter/Publisher.tsx)

   • Integrated Wix publishing into existing blog writer
   • Connection status checking
   • Enhanced error handling and user feedback

Setup Instructions

1. Wix App Configuration

1. Go to Wix Developers
2. Create a new app or use an existing one
3. Configure OAuth settings:
   • Redirect URI: http://localhost:3000/wix/callback (for development)
   • Scopes: BLOG.CREATE-DRAFT, BLOG.PUBLISH, MEDIA.MANAGE
4. Note down your Client ID (no Client Secret required for Wix Headless OAuth)

2. Environment Configuration

Add the following environment variables to your .env file:

# Wix Integration (Headless OAuth - Client ID only, no Client Secret required)
WIX_CLIENT_ID=your_wix_client_id_here
WIX_REDIRECT_URI=http://localhost:3000/wix/callback

Important Note: Wix Headless OAuth only requires a Client ID and does NOT use a Client Secret. This is different from traditional OAuth implementations and is designed for public clients like single-page applications.

3. Database Setup

The integration requires storing user tokens securely. You'll need to:

1. Create a table to store Wix tokens:

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,  -- Store member ID for third-party app requirements
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2. Implement token storage and retrieval functions in the WixService

4. Important: Third-Party App Requirements

CRITICAL: When creating blog posts as a third-party app, Wix requires a memberId field. This is mandatory and cannot be omitted. The integration will:

1. Automatically retrieve the current member ID during the OAuth flow
2. Store the member ID with the user's tokens
3. Use the member ID when creating blog posts

This requirement is enforced by Wix's API and cannot be bypassed.

Usage

1. Testing the Integration

1. Navigate to /wix-test in your ALwrity application
2. Click "Connect to Wix" to authorize the integration
3. Complete the OAuth flow in the popup window
4. Once connected, you can:
   • Load categories and tags from your Wix blog
   • Create and publish test blog posts
   • Check connection status

2. Publishing from Blog Writer

1. Generate your blog content using ALwrity's AI tools
2. Use the CopilotKit action: "Publish to Wix"
3. The system will:
   • Check your Wix connection status
   • Convert your content to Wix format
   • Import any images to Wix Media Manager
   • Create and publish the blog post
   • Return the published post URL

API Endpoints

Authentication

Get Authorization URL

GET /api/wix/auth/url?state=optional_state

Handle OAuth Callback

POST /api/wix/auth/callback
Content-Type: application/json

{
  "code": "authorization_code",
  "state": "optional_state"
}

Connection Management

Check Connection Status

GET /api/wix/connection/status

Disconnect Account

POST /api/wix/disconnect

Publishing

Publish Blog Post

POST /api/wix/publish
Content-Type: application/json

{
  "title": "Blog Post Title",
  "content": "Blog content in markdown",
  "cover_image_url": "https://example.com/image.jpg",
  "category_ids": ["category_id_1"],
  "tag_ids": ["tag_id_1", "tag_id_2"],
  "publish": true
}

Content Management

Get Blog Categories

GET /api/wix/categories

Get Blog Tags

GET /api/wix/tags

Content Format Conversion

The integration automatically converts ALwrity's markdown content to Wix's Ricos JSON format:

Supported Elements

• Headings: # Heading → HEADING node
• Paragraphs: Regular text → PARAGRAPH node
• Images: External URLs → Imported to Wix Media Manager
• Lists: Markdown lists → ORDERED_LIST/BULLETED_LIST nodes

Example Conversion

Markdown Input:

# Welcome to My Blog

This is a paragraph with some content.

## Features

- Feature 1
- Feature 2

Ricos JSON Output:

{
  "nodes": [
    {
      "type": "HEADING",
      "nodes": [{
        "type": "TEXT",
        "textData": {
          "text": "Welcome to My Blog",
          "decorations": []
        }
      }],
      "headingData": { "level": 1 }
    },
    {
      "type": "PARAGRAPH",
      "nodes": [{
        "type": "TEXT",
        "textData": {
          "text": "This is a paragraph with some content.",
          "decorations": []
        }
      }],
      "paragraphData": {}
    }
  ]
}

Error Handling

The integration includes comprehensive error handling for:

• Authentication Errors: Invalid tokens, expired sessions
• Permission Errors: Insufficient Wix app permissions
• Content Errors: Invalid content format, missing required fields
• Network Errors: API timeouts, connection issues

Security Considerations

1. Token Storage: Access and refresh tokens are stored securely
2. HTTPS: All API calls use HTTPS in production
3. Scope Limitation: Only requests necessary permissions
4. Token Refresh: Automatic token refresh when expired

Troubleshooting

Common Issues

1. "Wix account not connected"

   • Solution: Use the Wix Test Page to connect your account

2. "Insufficient permissions"

   • Solution: Reconnect your Wix account with proper permissions

3. "Failed to import image"

   • Solution: Check image URL accessibility and format

4. "Content format error"

   • Solution: Ensure content is valid markdown

Debug Mode

Enable debug logging by setting the log level to DEBUG in your environment:

LOG_LEVEL=DEBUG

Future Enhancements

1. Scheduled Publishing: Support for scheduled blog posts
2. Bulk Publishing: Publish multiple posts at once
3. Content Templates: Pre-defined content templates for Wix
4. Analytics Integration: Track published post performance
5. Advanced Formatting: Support for more Ricos node types

Support

For issues or questions about the Wix integration:

1. Check the troubleshooting section above
2. Review the Wix API documentation
3. Check the application logs for detailed error messages
4. Contact the development team

Related Documentation

• Wix REST API Documentation
• Wix Blog API
• Wix OAuth 2.0
• Ricos JSON Format