1016 lines
27 KiB
Markdown
1016 lines
27 KiB
Markdown
# Site API Implementation (WordPress Site Management)
|
|
|
|
This document describes the implementation of the WordPress Site Management API endpoints for the MaplePress frontend, integrated with the MaplePress backend API.
|
|
|
|
## Overview
|
|
|
|
The Site API endpoints manage WordPress sites and their API credentials for the MaplePress plugin. Sites are automatically scoped to tenants (determined from JWT token) and include API key management, usage tracking, and search index configuration.
|
|
|
|
## Backend API Endpoints
|
|
|
|
### Create WordPress Site
|
|
**Endpoint**: `POST /api/v1/sites`
|
|
**Authentication**: Required (JWT token)
|
|
|
|
### List WordPress Sites
|
|
**Endpoint**: `GET /api/v1/sites`
|
|
**Authentication**: Required (JWT token)
|
|
|
|
### Get WordPress Site
|
|
**Endpoint**: `GET /api/v1/sites/{id}`
|
|
**Authentication**: Required (JWT token)
|
|
|
|
### Delete WordPress Site
|
|
**Endpoint**: `DELETE /api/v1/sites/{id}`
|
|
**Authentication**: Required (JWT token)
|
|
|
|
### Rotate Site API Key
|
|
**Endpoint**: `POST /api/v1/sites/{id}/rotate-api-key`
|
|
**Authentication**: Required (JWT token)
|
|
|
|
**Documentation**: `/cloud/maplepress-backend/docs/API.md` (lines 805-1085)
|
|
|
|
## Request/Response Structures
|
|
|
|
### Create Site Request
|
|
```json
|
|
{
|
|
"site_url": "https://example.com"
|
|
}
|
|
```
|
|
|
|
**Note**: The backend automatically extracts the domain from the `site_url`.
|
|
|
|
**Headers Required:**
|
|
- `Content-Type: application/json`
|
|
- `Authorization: JWT {access_token}`
|
|
|
|
### Create Site Response
|
|
```json
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"domain": "example.com",
|
|
"site_url": "https://example.com",
|
|
"api_key": "live_sk_1234567890abcdef...",
|
|
"verification_token": "verify_abc123...",
|
|
"status": "pending",
|
|
"search_index_name": "site_550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
```
|
|
|
|
**⚠️ IMPORTANT**: The `api_key` is shown **ONLY ONCE** on site creation. Store it immediately!
|
|
|
|
### List Sites Request
|
|
```
|
|
GET /api/v1/sites?page_size=20&page_state=encoded_token
|
|
```
|
|
|
|
**Query Parameters:**
|
|
- `page_size` (optional): Number of results per page (default: 20, max: 100)
|
|
- `page_state` (optional): Pagination token from previous response
|
|
|
|
### List Sites Response
|
|
```json
|
|
{
|
|
"sites": [
|
|
{
|
|
"id": "550e8400-...",
|
|
"domain": "example.com",
|
|
"status": "active",
|
|
"is_verified": true,
|
|
"created_at": "2024-10-24T00:00:00Z"
|
|
}
|
|
],
|
|
"page_state": "encoded_pagination_token"
|
|
}
|
|
```
|
|
|
|
### Get Site Response
|
|
```json
|
|
{
|
|
"id": "550e8400-...",
|
|
"tenant_id": "850e8400-...",
|
|
"domain": "example.com",
|
|
"site_url": "https://example.com",
|
|
"api_key_prefix": "live_sk_",
|
|
"api_key_last_four": "f123",
|
|
"status": "active",
|
|
"is_verified": true,
|
|
"search_index_name": "site_550e8400-...",
|
|
"total_pages_indexed": 150,
|
|
"last_indexed_at": "2024-10-24T12:00:00Z",
|
|
"plugin_version": "1.0.0",
|
|
"storage_used_bytes": 52428800,
|
|
"search_requests_count": 1250,
|
|
"monthly_pages_indexed": 45,
|
|
"last_reset_at": "2024-10-01T00:00:00Z",
|
|
"created_at": "2024-10-01T00:00:00Z",
|
|
"updated_at": "2024-10-24T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Rotate API Key Response
|
|
```json
|
|
{
|
|
"new_api_key": "live_sk_9876543210fedcba...",
|
|
"old_key_last_four": "f123",
|
|
"rotated_at": "2024-10-24T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
**⚠️ CRITICAL**:
|
|
- The `new_api_key` is shown **ONLY ONCE**. Store it immediately!
|
|
- The old API key is **immediately invalidated** - no grace period!
|
|
- Your WordPress site will stop working until you update the plugin with the new key
|
|
|
|
## Frontend Implementation
|
|
|
|
### SiteService (`src/services/API/SiteService.js`)
|
|
|
|
Handles all WordPress Site Management operations.
|
|
|
|
**Key Features:**
|
|
- Create new WordPress sites with API key generation
|
|
- List all sites with pagination support
|
|
- Get detailed site information including usage statistics
|
|
- Hard delete sites (irreversible)
|
|
- Rotate API keys with grace period
|
|
- Client-side validation (domain and URL)
|
|
- Response transformation (snake_case to camelCase)
|
|
- User-friendly error message mapping
|
|
|
|
**Methods:**
|
|
|
|
#### `createSite(siteData)`
|
|
Create a new WordPress site and generate API credentials.
|
|
|
|
```javascript
|
|
import SiteService from './services/API/SiteService';
|
|
|
|
const site = await SiteService.createSite({
|
|
siteUrl: "https://example.com"
|
|
});
|
|
|
|
console.log(site);
|
|
// Output:
|
|
// {
|
|
// id: "550e8400-...",
|
|
// domain: "example.com", // Extracted from siteUrl by backend
|
|
// siteUrl: "https://example.com",
|
|
// apiKey: "live_sk_...", // SAVE THIS NOW!
|
|
// verificationToken: "verify_...",
|
|
// status: "pending",
|
|
// searchIndexName: "site_550e8400-..."
|
|
// }
|
|
```
|
|
|
|
**Parameters:**
|
|
- `siteData.siteUrl` (string, required): Full WordPress site URL (e.g., https://example.com)
|
|
|
|
**Note**: The backend automatically extracts the domain (e.g., "example.com") from the `siteUrl`.
|
|
|
|
**Returns:**
|
|
```javascript
|
|
{
|
|
id: string, // Site ID (UUID)
|
|
domain: string, // Site domain
|
|
siteUrl: string, // Full site URL
|
|
apiKey: string, // API key (SHOWN ONLY ONCE!)
|
|
verificationToken: string, // Token for plugin verification
|
|
status: string, // Site status ("pending" or "active")
|
|
searchIndexName: string // Meilisearch index name
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
- "Site data is required" - If siteData is missing
|
|
- "Site URL is required" - If siteUrl is missing
|
|
- "Invalid site URL format" - If URL format is invalid
|
|
- "Could not extract domain from URL" - If domain cannot be extracted
|
|
- "This domain is already registered. Each domain can only be registered once." - Domain conflict (409)
|
|
- "Authentication required. Please log in to continue." - Missing/invalid token
|
|
|
|
#### `listSites(options)`
|
|
List all WordPress sites for the authenticated user's tenant with pagination.
|
|
|
|
```javascript
|
|
// First page
|
|
const result = await SiteService.listSites({ pageSize: 20 });
|
|
console.log(result.sites); // Array of sites
|
|
console.log(result.pageState); // Token for next page
|
|
|
|
// Next page
|
|
if (result.pageState) {
|
|
const nextPage = await SiteService.listSites({
|
|
pageSize: 20,
|
|
pageState: result.pageState
|
|
});
|
|
}
|
|
```
|
|
|
|
**Parameters:**
|
|
- `options.pageSize` (number, optional): Number of results per page (default: 20, max: 100)
|
|
- `options.pageState` (string, optional): Pagination token from previous response
|
|
|
|
**Returns:**
|
|
```javascript
|
|
{
|
|
sites: Array<{
|
|
id: string,
|
|
domain: string,
|
|
status: string,
|
|
isVerified: boolean,
|
|
createdAt: Date
|
|
}>,
|
|
pageState: string|null // Pagination token for next page
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
- "Page size must be between 1 and 100" - Invalid page size
|
|
- "Authentication required. Please log in to continue." - Missing/invalid token
|
|
|
|
#### `getSiteById(siteId)`
|
|
Get detailed information about a specific WordPress site including usage statistics.
|
|
|
|
```javascript
|
|
const site = await SiteService.getSiteById("550e8400-...");
|
|
console.log(site.domain); // "example.com"
|
|
console.log(site.totalPagesIndexed); // 150
|
|
console.log(site.storageUsedBytes); // 52428800
|
|
|
|
// Format storage for display
|
|
const storage = SiteService.formatStorage(site.storageUsedBytes);
|
|
console.log(storage); // "50 MB"
|
|
```
|
|
|
|
**Parameters:**
|
|
- `siteId` (string, required): Site ID (UUID format)
|
|
|
|
**Returns:**
|
|
```javascript
|
|
{
|
|
id: string,
|
|
tenantId: string,
|
|
domain: string,
|
|
siteUrl: string,
|
|
apiKeyPrefix: string,
|
|
apiKeyLastFour: string,
|
|
status: string,
|
|
isVerified: boolean,
|
|
searchIndexName: string,
|
|
totalPagesIndexed: number,
|
|
lastIndexedAt: Date|null,
|
|
pluginVersion: string,
|
|
storageUsedBytes: number,
|
|
searchRequestsCount: number,
|
|
monthlyPagesIndexed: number,
|
|
lastResetAt: Date|null,
|
|
createdAt: Date,
|
|
updatedAt: Date
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
- "Site ID is required" - If ID is missing
|
|
- "Invalid site ID format" - If ID is not a valid UUID
|
|
- "Site not found or doesn't belong to your organization." - If site doesn't exist (404)
|
|
- "Authentication required. Please log in to continue." - Missing/invalid token
|
|
|
|
#### `deleteSite(siteId)`
|
|
Delete a WordPress site and all associated data (irreversible).
|
|
|
|
```javascript
|
|
const result = await SiteService.deleteSite("550e8400-...");
|
|
console.log(result.success); // true
|
|
console.log(result.message); // "Site deleted successfully"
|
|
```
|
|
|
|
**⚠️ WARNING**: This is a **hard delete** operation. All site data, including:
|
|
- API keys (immediately invalidated)
|
|
- Search index data
|
|
- Usage statistics
|
|
- Configuration
|
|
|
|
...will be permanently deleted and **cannot be recovered**.
|
|
|
|
**Parameters:**
|
|
- `siteId` (string, required): Site ID (UUID format)
|
|
|
|
**Returns:**
|
|
```javascript
|
|
{
|
|
success: boolean,
|
|
message: string
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
- "Site ID is required" - If ID is missing
|
|
- "Invalid site ID format" - If ID is not a valid UUID
|
|
- "Site not found or doesn't belong to your organization." - If site doesn't exist (404)
|
|
- "Authentication required. Please log in to continue." - Missing/invalid token
|
|
|
|
#### `rotateApiKey(siteId)`
|
|
Rotate a site's API key (use when the key is compromised).
|
|
|
|
```javascript
|
|
const result = await SiteService.rotateApiKey("550e8400-...");
|
|
console.log(result.newApiKey); // "live_sk_..." - SAVE THIS NOW!
|
|
console.log(result.oldKeyLastFour); // "f123"
|
|
console.log(result.rotatedAt); // Date (now)
|
|
```
|
|
|
|
**🚨 CRITICAL**:
|
|
- The `newApiKey` is shown **ONLY ONCE**. Store it immediately!
|
|
- The old API key is **immediately invalidated** - no grace period!
|
|
- Your WordPress site will stop working until you update the plugin with the new key
|
|
- Update your WordPress plugin settings RIGHT NOW to restore functionality
|
|
|
|
**Parameters:**
|
|
- `siteId` (string, required): Site ID (UUID format)
|
|
|
|
**Returns:**
|
|
```javascript
|
|
{
|
|
newApiKey: string, // New API key (shown only once!)
|
|
oldKeyLastFour: string, // Last 4 chars of old key
|
|
rotatedAt: Date // Rotation timestamp
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
- "Site ID is required" - If ID is missing
|
|
- "Invalid site ID format" - If ID is not a valid UUID
|
|
- "Site not found or doesn't belong to your organization." - If site doesn't exist (404)
|
|
- "Authentication required. Please log in to continue." - Missing/invalid token
|
|
|
|
#### `validateDomain(domain)`
|
|
Validate domain format.
|
|
|
|
```javascript
|
|
const result = SiteService.validateDomain("example.com");
|
|
console.log(result); // { valid: true, error: null }
|
|
|
|
const invalid = SiteService.validateDomain("invalid..domain");
|
|
console.log(invalid); // { valid: false, error: "Invalid domain format" }
|
|
```
|
|
|
|
**Returns:** `{ valid: boolean, error: string|null }`
|
|
|
|
**Validation Rules:**
|
|
- Required (non-empty)
|
|
- Valid domain format (e.g., example.com, subdomain.example.com)
|
|
- No protocol (http/https should be in siteUrl)
|
|
|
|
#### `validateSiteUrl(url)`
|
|
Validate site URL format.
|
|
|
|
```javascript
|
|
const result = SiteService.validateSiteUrl("https://example.com");
|
|
console.log(result); // { valid: true, error: null }
|
|
|
|
const invalid = SiteService.validateSiteUrl("ftp://example.com");
|
|
console.log(invalid); // { valid: false, error: "Site URL must use http or https protocol" }
|
|
```
|
|
|
|
**Returns:** `{ valid: boolean, error: string|null }`
|
|
|
|
**Validation Rules:**
|
|
- Required (non-empty)
|
|
- Valid URL format
|
|
- Must use http:// or https:// protocol
|
|
|
|
#### `formatStorage(bytes)`
|
|
Format storage bytes to human-readable format.
|
|
|
|
```javascript
|
|
const formatted = SiteService.formatStorage(52428800);
|
|
console.log(formatted); // "50 MB"
|
|
|
|
const kb = SiteService.formatStorage(2048);
|
|
console.log(kb); // "2 KB"
|
|
```
|
|
|
|
**Returns:** `string` (e.g., "50 MB", "2 KB", "1.5 GB")
|
|
|
|
## Data Flow
|
|
|
|
### Create Site Flow
|
|
```
|
|
User provides site URL
|
|
↓
|
|
SiteService.createSite()
|
|
↓
|
|
Validate URL (client-side)
|
|
↓
|
|
ApiClient.post() with JWT token
|
|
↓
|
|
Token automatically refreshed if needed
|
|
↓
|
|
POST /api/v1/sites with tenant from JWT
|
|
↓
|
|
Backend extracts domain from site URL
|
|
↓
|
|
Backend validates domain format
|
|
↓
|
|
Backend generates API key and verification token
|
|
↓
|
|
Backend creates Meilisearch index
|
|
↓
|
|
Backend returns site data with API key and extracted domain
|
|
↓
|
|
SiteService transforms response
|
|
↓
|
|
Component displays API key (ONLY TIME IT'S SHOWN!)
|
|
```
|
|
|
|
### List Sites Flow
|
|
```
|
|
Component needs site list
|
|
↓
|
|
SiteService.listSites()
|
|
↓
|
|
ApiClient.get() with JWT token and pagination params
|
|
↓
|
|
Token automatically refreshed if needed
|
|
↓
|
|
GET /api/v1/sites with tenant from JWT
|
|
↓
|
|
Backend retrieves sites for tenant
|
|
↓
|
|
Backend returns paginated results
|
|
↓
|
|
SiteService transforms response
|
|
↓
|
|
Component receives sites array and next page token
|
|
```
|
|
|
|
### Rotate API Key Flow
|
|
```
|
|
User requests key rotation
|
|
↓
|
|
SiteService.rotateApiKey()
|
|
↓
|
|
ApiClient.post() with JWT token
|
|
↓
|
|
Token automatically refreshed if needed
|
|
↓
|
|
POST /api/v1/sites/{id}/rotate-api-key
|
|
↓
|
|
Backend generates new API key
|
|
↓
|
|
Backend IMMEDIATELY invalidates old key (DELETE from DB)
|
|
↓
|
|
Backend inserts new key into database
|
|
↓
|
|
Backend returns new key (old key NO LONGER WORKS!)
|
|
↓
|
|
SiteService transforms response
|
|
↓
|
|
Component displays new key (ONLY TIME IT'S SHOWN!)
|
|
↓
|
|
User MUST update WordPress plugin NOW to restore functionality
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Error Types
|
|
|
|
| Error Condition | Response | Frontend Behavior |
|
|
|----------------|----------|-------------------|
|
|
| Missing authentication | 401 Unauthorized | "Authentication required." |
|
|
| Invalid site data | 400 Bad Request | Specific validation error |
|
|
| Domain already exists | 409 Conflict | "Domain already registered by another user." |
|
|
| Site not found | 404 Not Found | "Site not found or doesn't belong to your organization." |
|
|
| Server error | 500 Internal Server Error | Generic error message |
|
|
|
|
## Usage Examples
|
|
|
|
### Create a New Site
|
|
|
|
```javascript
|
|
import React, { useState } from 'react';
|
|
import SiteService from '../../services/API/SiteService';
|
|
|
|
function CreateSiteForm() {
|
|
const [siteUrl, setSiteUrl] = useState('');
|
|
const [apiKey, setApiKey] = useState('');
|
|
const [error, setError] = useState('');
|
|
const [loading, setLoading] = useState(false);
|
|
|
|
const handleSubmit = async (e) => {
|
|
e.preventDefault();
|
|
setError('');
|
|
setLoading(true);
|
|
|
|
// Validate URL before sending
|
|
const urlValidation = SiteService.validateSiteUrl(siteUrl);
|
|
if (!urlValidation.valid) {
|
|
setError(urlValidation.error);
|
|
setLoading(false);
|
|
return;
|
|
}
|
|
|
|
try {
|
|
const site = await SiteService.createSite({ siteUrl });
|
|
|
|
// CRITICAL: Display API key immediately - it's shown only once!
|
|
setApiKey(site.apiKey);
|
|
alert(`IMPORTANT: Save this API key now! ${site.apiKey}`);
|
|
|
|
console.log("Site created:", site);
|
|
console.log("Domain extracted by backend:", site.domain);
|
|
// Reset form
|
|
setSiteUrl('');
|
|
} catch (err) {
|
|
setError(err.message);
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
|
|
return (
|
|
<form onSubmit={handleSubmit}>
|
|
<div>
|
|
<label>WordPress Site URL:</label>
|
|
<input
|
|
type="url"
|
|
value={siteUrl}
|
|
onChange={(e) => setSiteUrl(e.target.value)}
|
|
placeholder="https://example.com"
|
|
/>
|
|
<p className="help-text">
|
|
The domain will be automatically extracted from this URL
|
|
</p>
|
|
</div>
|
|
|
|
{error && <p className="error">{error}</p>}
|
|
|
|
{apiKey && (
|
|
<div className="api-key-display">
|
|
<h3>⚠️ API Key (Save Now!)</h3>
|
|
<code>{apiKey}</code>
|
|
<p>This key will not be shown again!</p>
|
|
</div>
|
|
)}
|
|
|
|
<button type="submit" disabled={loading}>
|
|
{loading ? 'Creating...' : 'Create Site'}
|
|
</button>
|
|
</form>
|
|
);
|
|
}
|
|
|
|
export default CreateSiteForm;
|
|
```
|
|
|
|
### List Sites with Pagination
|
|
|
|
```javascript
|
|
import React, { useEffect, useState } from 'react';
|
|
import SiteService from '../../services/API/SiteService';
|
|
|
|
function SiteList() {
|
|
const [sites, setSites] = useState([]);
|
|
const [pageState, setPageState] = useState(null);
|
|
const [loading, setLoading] = useState(true);
|
|
const [error, setError] = useState('');
|
|
|
|
const loadSites = async (nextPageState = null) => {
|
|
try {
|
|
setLoading(true);
|
|
const result = await SiteService.listSites({
|
|
pageSize: 20,
|
|
pageState: nextPageState
|
|
});
|
|
|
|
if (nextPageState) {
|
|
// Append to existing sites
|
|
setSites(prev => [...prev, ...result.sites]);
|
|
} else {
|
|
// First page
|
|
setSites(result.sites);
|
|
}
|
|
|
|
setPageState(result.pageState);
|
|
} catch (err) {
|
|
setError(err.message);
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
|
|
useEffect(() => {
|
|
loadSites();
|
|
}, []);
|
|
|
|
return (
|
|
<div className="site-list">
|
|
<h2>WordPress Sites</h2>
|
|
|
|
{error && <p className="error">{error}</p>}
|
|
|
|
{sites.map(site => (
|
|
<div key={site.id} className="site-item">
|
|
<h3>{site.domain}</h3>
|
|
<p>Status: {site.status}</p>
|
|
<p>Verified: {site.isVerified ? 'Yes' : 'No'}</p>
|
|
<p>Created: {site.createdAt.toLocaleDateString()}</p>
|
|
</div>
|
|
))}
|
|
|
|
{loading && <p>Loading sites...</p>}
|
|
|
|
{pageState && !loading && (
|
|
<button onClick={() => loadSites(pageState)}>
|
|
Load More
|
|
</button>
|
|
)}
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export default SiteList;
|
|
```
|
|
|
|
### Display Site Details with Usage
|
|
|
|
```javascript
|
|
import React, { useEffect, useState } from 'react';
|
|
import SiteService from '../../services/API/SiteService';
|
|
|
|
function SiteDetails({ siteId }) {
|
|
const [site, setSite] = useState(null);
|
|
const [loading, setLoading] = useState(true);
|
|
const [error, setError] = useState('');
|
|
|
|
useEffect(() => {
|
|
const fetchSite = async () => {
|
|
try {
|
|
const data = await SiteService.getSiteById(siteId);
|
|
setSite(data);
|
|
} catch (err) {
|
|
setError(err.message);
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
|
|
fetchSite();
|
|
}, [siteId]);
|
|
|
|
if (loading) return <div>Loading site...</div>;
|
|
if (error) return <div>Error: {error}</div>;
|
|
if (!site) return null;
|
|
|
|
return (
|
|
<div className="site-details">
|
|
<h2>{site.domain}</h2>
|
|
<p>URL: <a href={site.siteUrl}>{site.siteUrl}</a></p>
|
|
<p>Status: {site.status}</p>
|
|
<p>Verified: {site.isVerified ? 'Yes' : 'No'}</p>
|
|
|
|
<h3>API Key</h3>
|
|
<p>Prefix: {site.apiKeyPrefix}</p>
|
|
<p>Last 4 digits: {site.apiKeyLastFour}</p>
|
|
|
|
<h3>Usage Statistics</h3>
|
|
<p>Total Pages Indexed: {site.totalPagesIndexed}</p>
|
|
<p>Monthly Pages Indexed: {site.monthlyPagesIndexed}</p>
|
|
<p>Storage Used: {SiteService.formatStorage(site.storageUsedBytes)}</p>
|
|
<p>Search Requests: {site.searchRequestsCount}</p>
|
|
|
|
{site.lastIndexedAt && (
|
|
<p>Last Indexed: {site.lastIndexedAt.toLocaleString()}</p>
|
|
)}
|
|
|
|
<h3>Plugin</h3>
|
|
<p>Version: {site.pluginVersion || 'Not connected'}</p>
|
|
|
|
<h3>Search Index</h3>
|
|
<p>Index Name: {site.searchIndexName}</p>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export default SiteDetails;
|
|
```
|
|
|
|
### Rotate API Key
|
|
|
|
```javascript
|
|
import React, { useState } from 'react';
|
|
import SiteService from '../../services/API/SiteService';
|
|
|
|
function RotateApiKey({ siteId, onRotated }) {
|
|
const [newKey, setNewKey] = useState('');
|
|
const [loading, setLoading] = useState(false);
|
|
const [error, setError] = useState('');
|
|
|
|
const handleRotate = async () => {
|
|
if (!confirm('🚨 CRITICAL WARNING: Are you sure you want to rotate the API key?\n\nThe old key will be IMMEDIATELY INVALIDATED (no grace period).\nYour WordPress site will stop working until you update the plugin!')) {
|
|
return;
|
|
}
|
|
|
|
setLoading(true);
|
|
setError('');
|
|
|
|
try {
|
|
const result = await SiteService.rotateApiKey(siteId);
|
|
|
|
// CRITICAL: Display new API key immediately - it's shown only once!
|
|
setNewKey(result.newApiKey);
|
|
alert(`🚨 CRITICAL: Save this new API key NOW!\n\n${result.newApiKey}\n\nOld key (ending in ${result.oldKeyLastFour}) has been IMMEDIATELY INVALIDATED.\n\nUpdate your WordPress plugin RIGHT NOW to restore functionality!`);
|
|
|
|
if (onRotated) {
|
|
onRotated(result);
|
|
}
|
|
} catch (err) {
|
|
setError(err.message);
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
|
|
return (
|
|
<div className="rotate-api-key">
|
|
<h3>Rotate API Key</h3>
|
|
<p>Use this if your API key has been compromised.</p>
|
|
|
|
{error && <p className="error">{error}</p>}
|
|
|
|
{newKey && (
|
|
<div className="api-key-display">
|
|
<h4>🚨 New API Key (Save Now!)</h4>
|
|
<code>{newKey}</code>
|
|
<p>This key will not be shown again!</p>
|
|
<p className="critical">Old key is IMMEDIATELY INVALIDATED - Update your WordPress plugin NOW!</p>
|
|
</div>
|
|
)}
|
|
|
|
<button onClick={handleRotate} disabled={loading}>
|
|
{loading ? 'Rotating...' : 'Rotate API Key'}
|
|
</button>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export default RotateApiKey;
|
|
```
|
|
|
|
### Delete Site
|
|
|
|
```javascript
|
|
import React, { useState } from 'react';
|
|
import SiteService from '../../services/API/SiteService';
|
|
|
|
function DeleteSite({ siteId, siteDomain, onDeleted }) {
|
|
const [loading, setLoading] = useState(false);
|
|
const [error, setError] = useState('');
|
|
|
|
const handleDelete = async () => {
|
|
const confirmed = confirm(
|
|
`⚠️ WARNING: This will PERMANENTLY delete "${siteDomain}" and ALL associated data:\n\n` +
|
|
`- API keys (immediately invalidated)\n` +
|
|
`- Search index data\n` +
|
|
`- Usage statistics\n` +
|
|
`- Configuration\n\n` +
|
|
`This action CANNOT be undone!\n\n` +
|
|
`Are you absolutely sure?`
|
|
);
|
|
|
|
if (!confirmed) return;
|
|
|
|
// Double confirmation
|
|
const doubleConfirm = prompt(`Type "${siteDomain}" to confirm deletion:`);
|
|
if (doubleConfirm !== siteDomain) {
|
|
alert('Domain name did not match. Deletion cancelled.');
|
|
return;
|
|
}
|
|
|
|
setLoading(true);
|
|
setError('');
|
|
|
|
try {
|
|
const result = await SiteService.deleteSite(siteId);
|
|
console.log(result.message);
|
|
|
|
if (onDeleted) {
|
|
onDeleted(siteId);
|
|
}
|
|
} catch (err) {
|
|
setError(err.message);
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
};
|
|
|
|
return (
|
|
<div className="delete-site">
|
|
<h3>Danger Zone</h3>
|
|
{error && <p className="error">{error}</p>}
|
|
<button
|
|
onClick={handleDelete}
|
|
disabled={loading}
|
|
className="btn-danger"
|
|
>
|
|
{loading ? 'Deleting...' : 'Delete Site'}
|
|
</button>
|
|
<p className="warning">This action cannot be undone!</p>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
export default DeleteSite;
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Test Create Site
|
|
|
|
```javascript
|
|
// In browser console after login
|
|
|
|
import SiteService from './services/API/SiteService';
|
|
|
|
// Validate URL
|
|
const urlValidation = SiteService.validateSiteUrl("https://example.com");
|
|
console.log("URL valid:", urlValidation.valid);
|
|
|
|
// Create site (backend extracts domain automatically)
|
|
const site = await SiteService.createSite({
|
|
siteUrl: "https://example.com"
|
|
});
|
|
|
|
console.log("Created site:", site);
|
|
console.log("Domain extracted:", site.domain); // "example.com"
|
|
console.log("⚠️ SAVE THIS API KEY:", site.apiKey);
|
|
```
|
|
|
|
### Test List Sites
|
|
|
|
```javascript
|
|
// List first page
|
|
const result = await SiteService.listSites({ pageSize: 10 });
|
|
console.log("Sites:", result.sites);
|
|
console.log("Next page token:", result.pageState);
|
|
|
|
// Load next page
|
|
if (result.pageState) {
|
|
const nextPage = await SiteService.listSites({
|
|
pageSize: 10,
|
|
pageState: result.pageState
|
|
});
|
|
console.log("Next page:", nextPage.sites);
|
|
}
|
|
```
|
|
|
|
### Test Get Site
|
|
|
|
```javascript
|
|
// Using site ID from creation
|
|
const site = await SiteService.getSiteById("550e8400-...");
|
|
console.log("Site details:", site);
|
|
console.log("Storage used:", SiteService.formatStorage(site.storageUsedBytes));
|
|
```
|
|
|
|
### Test Rotate API Key
|
|
|
|
```javascript
|
|
const result = await SiteService.rotateApiKey("550e8400-...");
|
|
console.log("🚨 SAVE THIS NEW KEY NOW:", result.newApiKey);
|
|
console.log("Old key (immediately invalidated):", result.oldKeyLastFour);
|
|
console.log("Rotated at:", result.rotatedAt);
|
|
```
|
|
|
|
### Test with curl
|
|
|
|
```bash
|
|
# 1. Login and get access token
|
|
ACCESS_TOKEN=$(curl -X POST http://localhost:8000/api/v1/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"email": "test@example.com",
|
|
"password": "SecurePass123!"
|
|
}' | jq -r '.access_token')
|
|
|
|
# 2. Create site
|
|
curl -X POST http://localhost:8000/api/v1/sites \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: JWT $ACCESS_TOKEN" \
|
|
-d '{
|
|
"domain": "example.com",
|
|
"site_url": "https://example.com"
|
|
}' | jq
|
|
|
|
# 3. List sites
|
|
curl -X GET "http://localhost:8000/api/v1/sites?page_size=10" \
|
|
-H "Authorization: JWT $ACCESS_TOKEN" | jq
|
|
|
|
# 4. Get site by ID (use ID from creation response)
|
|
SITE_ID="550e8400-..."
|
|
curl -X GET "http://localhost:8000/api/v1/sites/$SITE_ID" \
|
|
-H "Authorization: JWT $ACCESS_TOKEN" | jq
|
|
|
|
# 5. Rotate API key
|
|
curl -X POST "http://localhost:8000/api/v1/sites/$SITE_ID/rotate-api-key" \
|
|
-H "Authorization: JWT $ACCESS_TOKEN" | jq
|
|
|
|
# 6. Delete site
|
|
curl -X DELETE "http://localhost:8000/api/v1/sites/$SITE_ID" \
|
|
-H "Authorization: JWT $ACCESS_TOKEN" | jq
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
### API Key Security
|
|
|
|
1. **API keys are shown only once** - on site creation and API key rotation
|
|
2. Store API keys securely immediately after receiving them
|
|
3. Never log or display API keys in client-side code after initial display
|
|
4. Use HTTPS for all API communications
|
|
5. Rotate keys immediately if compromised
|
|
|
|
### Site Status
|
|
|
|
- **pending**: Site created but WordPress plugin not yet verified
|
|
- **active**: Plugin successfully verified and connected
|
|
|
|
Sites remain in "pending" status until the WordPress plugin makes its first authenticated request using the verification token.
|
|
|
|
### Hard Delete Warning
|
|
|
|
The `deleteSite()` operation is **irreversible**. All data is immediately and permanently deleted:
|
|
- API keys are invalidated (plugin stops working immediately)
|
|
- Search index is destroyed (all indexed content lost)
|
|
- Usage statistics are deleted
|
|
- Configuration is removed
|
|
|
|
There is **no recovery** or "soft delete" option.
|
|
|
|
### Immediate Invalidation
|
|
|
|
When rotating an API key:
|
|
- The new key is active immediately
|
|
- The old key is **immediately invalidated** - no grace period!
|
|
- Your WordPress site functionality stops working instantly
|
|
- You must update the WordPress plugin configuration RIGHT NOW to restore functionality
|
|
|
|
### Pagination
|
|
|
|
- Default page size: 20 sites
|
|
- Maximum page size: 100 sites
|
|
- Use `page_state` token to get next page
|
|
- When `pageState` is null, you've reached the last page
|
|
|
|
### Storage Formatting
|
|
|
|
The `formatStorage()` helper formats bytes to human-readable strings:
|
|
- 0 Bytes
|
|
- 2 KB
|
|
- 50 MB
|
|
- 1.5 GB
|
|
- 2.5 TB
|
|
|
|
## Related Files
|
|
|
|
### Created Files
|
|
```
|
|
src/services/API/SiteService.js
|
|
docs/SITE_API.md
|
|
```
|
|
|
|
### Backend Reference Files
|
|
```
|
|
cloud/maplepress-backend/docs/API.md (lines 805-1085)
|
|
cloud/maplepress-backend/internal/interface/http/site_http.go
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [USER_API.md](./USER_API.md) - User management (similar pattern)
|
|
- [TENANT_API.md](./TENANT_API.md) - Tenant management (parent context)
|
|
- [ME_API.md](./ME_API.md) - Current user profile includes tenant ID
|
|
- [FRONTEND_ARCHITECTURE.md](./FRONTEND_ARCHITECTURE.md) - Architecture overview
|
|
- [README.md](./README.md) - Documentation index
|
|
|
|
## Summary
|
|
|
|
The Site API implementation provides:
|
|
|
|
1. **Site Creation**: Register WordPress sites with automatic API key generation
|
|
2. **Site Listing**: Paginated list of all sites in tenant
|
|
3. **Site Details**: Comprehensive site info with usage statistics
|
|
4. **API Key Rotation**: Secure key rotation with immediate invalidation (no grace period)
|
|
5. **Site Deletion**: Hard delete with immediate key invalidation
|
|
6. **Validation Helpers**: Client-side validation before API calls
|
|
7. **Storage Formatting**: Human-readable storage display
|
|
|
|
Essential for managing WordPress sites using the MaplePress plugin for cloud-powered search and other services.
|
|
|
|
---
|
|
|
|
**Last Updated**: October 30, 2024
|
|
**Frontend Version**: 0.0.0
|
|
**Documentation Version**: 1.0.0
|