synthos 0.7.2 → 0.8.0

package/src/connectors/pexels/connector.json

@@ -0,0 +1,27 @@
+{
+    "id": "pexels",
+    "name": "Pexels",
+    "category": "Image",
+    "description": "Free stock photos and videos. Search a curated library of high-quality, royalty-free images and video clips.",
+    "baseUrl": "https://api.pexels.com",
+    "authStrategy": "header",
+    "authKey": "Authorization",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Search photos: GET https://api.pexels.com/v1/search?query={term}&per_page=10 — params: query (required), orientation (landscape|portrait|square), size (large|medium|small), color (red|orange|yellow|green|turquoise|blue|violet|pink|brown|black|gray|white|#hex), page (default:1), per_page (default:15, max:80)",
+        "Get a Photo by ID: GET https://api.pexels.com/v1/photos/{id} — params: id (required)",
+        "Response (search&get): { photos: [{ id, width, height, src: { original, large, medium, small, tiny }, alt, photographer }] }",
+        "Whenever you are doing an API request make sure to show a prominent link to Pexels. You can use a text link (e.g. 'Photos provided by Pexels').",
+        "Rate limit: 200 requests/hour, 20,000 requests/month."
+    ],
+    "onboarding": {
+        "url": "https://www.pexels.com/api",
+        "steps": [
+            "Create an account at pexels.com",
+            "Go to pexels.com/api to request API access",
+            "Copy your API key from the dashboard"
+        ]
+    }
+}

package/src/connectors/registry.ts

@@ -1,98 +1,22 @@
-import { ConnectorDefinition } from './types';
+import * as fs from 'fs';
+import * as path from 'path';
+import { ConnectorDefinition, ConnectorJson } from './types';
 
-export const CONNECTOR_REGISTRY: ConnectorDefinition[] = [
-    {
-        id: 'brave-search',
-        name: 'Brave Search',
-        category: 'Search',
-        description: 'Web search powered by the Brave Search API. Provides real-time search results from the web.',
-        baseUrl: 'https://api.search.brave.com',
-        authStrategy: 'header',
-        authKey: 'X-Subscription-Token',
-        fields: [
-            { name: 'apiKey', label: 'API Key', type: 'password' }
-        ],
-        hints: [
-            'Endpoint: GET /res/v1/web/search',
-            'Query params: q (required), count (1-20, default 10), country, freshness',
-            'Response: { web: { results: [{ title, url, description }] } }',
-            'Note: synthos.search.web() is a convenience wrapper — prefer it over raw connector calls for basic web search.'
-        ].join('\n')
-    },
-    {
-        id: 'elevenlabs',
-        name: 'ElevenLabs',
-        category: 'Audio',
-        description: 'AI-powered text-to-speech and voice synthesis. Generate natural-sounding audio from text.',
-        baseUrl: 'https://api.elevenlabs.io',
-        authStrategy: 'header',
-        authKey: 'xi-api-key',
-        fields: [
-            { name: 'apiKey', label: 'API Key', type: 'password' }
-        ],
-        hints: [
-            'List voices: GET /v1/voices → { voices: [{ voice_id, name, category }] }',
-            'Text-to-speech: POST /v1/text-to-speech/{voice_id}?output_format=mp3_44100_128',
-            '  Request headers: Accept: audio/mpeg, Content-Type: application/json',
-            '  Request body: { text: string, model_id: "eleven_multilingual_v2" }',
-            '  Response: raw audio/mpeg binary — use resp.arrayBuffer() then new Blob([buf], {type:"audio/mpeg"}) and URL.createObjectURL() to play',
-            '  IMPORTANT: The proxy returns raw binary, NOT JSON. Call fetch("/api/connectors", ...) directly instead of synthos.connectors.call() for TTS, since the helper parses JSON.',
-            'Default voice: "Rachel" (voice_id: 21m00Tcm4TlvDq8ikWAM) is a good general-purpose voice.',
-            'Max text length: 5000 characters per request.'
-        ].join('\n')
-    },
-    {
-        id: 'stability-ai',
-        name: 'Stability AI',
-        category: 'Image',
-        description: 'AI image generation powered by Stable Diffusion. Create images from text prompts.',
-        baseUrl: 'https://api.stability.ai',
-        authStrategy: 'bearer',
-        authKey: 'Authorization',
-        fields: [
-            { name: 'apiKey', label: 'API Key', type: 'password' }
-        ],
-        hints: [
-            'Text-to-image: POST /v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image',
-            '  Request headers: Content-Type: application/json, Accept: application/json',
-            '  Request body: { text_prompts: [{ text: string, weight: 1 }], cfg_scale: 7, steps: 30, width: 1024, height: 1024 }',
-            '  Response: { artifacts: [{ base64: string, finishReason: string }] }',
-            '  Display with: <img src="data:image/png;base64,{base64}">'
-        ].join('\n')
-    },
-    {
-        id: 'instagram',
-        name: 'Instagram',
-        category: 'Social',
-        description: 'Post photos and videos to Instagram via the Instagram Graph API.',
-        baseUrl: 'https://graph.facebook.com/v21.0',
-        authStrategy: 'oauth2',
-        authKey: 'access_token',
-        authorizationUrl: 'https://www.facebook.com/v21.0/dialog/oauth',
-        tokenUrl: 'https://graph.facebook.com/v21.0/oauth/access_token',
-        scopes: [
-            'instagram_basic',
-            'instagram_content_publish',
-            'pages_show_list',
-            'pages_read_engagement'
-        ],
-        fields: [
-            { name: 'clientId', label: 'App ID', type: 'text' },
-            { name: 'clientSecret', label: 'App Secret', type: 'password' }
-        ],
-        hints: [
-            'Publishing flow (two-step):',
-            '  1. Create media container: POST /{ig-user-id}/media',
-            '     Body (photo): { image_url, caption }',
-            '     Body (reel/video): { video_url, caption, media_type: "REELS" }',
-            '     Response: { id: "<container-id>" }',
-            '  2. Publish container: POST /{ig-user-id}/media_publish',
-            '     Body: { creation_id: "<container-id>" }',
-            '     Response: { id: "<media-id>" }',
-            'IMPORTANT: Do NOT include access_token in body or query params — the proxy attaches it automatically.',
-            'IMPORTANT: Images must be publicly accessible URLs. Use a hosting service or the data API to serve local images.',
-            'Rate limit: 25 posts per 24-hour period.',
-            'Requires a Business or Creator Instagram account linked to a Facebook Page.'
-        ].join('\n')
-    }
-];
+const connectorsDir = __dirname;
+
+function loadConnectorJson(dir: string): ConnectorDefinition | null {
+    const file = path.join(dir, 'connector.json');
+    if (!fs.existsSync(file)) return null;
+    const raw: ConnectorJson = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return {
+        ...raw,
+        hints: raw.hints ? raw.hints.join('\n') : undefined
+    };
+}
+
+export const CONNECTOR_REGISTRY: ConnectorDefinition[] = fs
+    .readdirSync(connectorsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => loadConnectorJson(path.join(connectorsDir, d.name)))
+    .filter((d): d is ConnectorDefinition => d !== null)
+    .sort((a, b) => a.name.localeCompare(b.name));

package/src/connectors/resend/connector.json

@@ -0,0 +1,29 @@
+{
+    "id": "resend",
+    "name": "Resend",
+    "category": "Communication",
+    "description": "Modern email delivery API. Send transactional emails with a clean, developer-friendly interface.",
+    "baseUrl": "https://api.resend.com",
+    "authStrategy": "bearer",
+    "authKey": "Authorization",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Send email: POST /emails",
+        "  Body: { from: \"you@yourdomain.com\", to: [\"recipient@example.com\"], subject: \"...\", html: \"<p>Hello</p>\" }",
+        "  Response: { id: \"email-id\" }",
+        "Get email: GET /emails/{id}",
+        "  Response: { id, from, to, subject, created_at, last_event }",
+        "IMPORTANT: 'from' must use a verified domain. Use 'onboarding@resend.dev' for testing.",
+        "Free tier: 100 emails/day, 3,000 emails/month."
+    ],
+    "onboarding": {
+        "url": "https://resend.com/signup",
+        "steps": [
+            "Create an account at resend.com",
+            "Go to API Keys in the dashboard",
+            "Create a new API key and copy it"
+        ]
+    }
+}

package/src/connectors/rss2json/connector.json

@@ -0,0 +1,27 @@
+{
+    "id": "rss2json",
+    "name": "RSS/Atom Feed",
+    "category": "News",
+    "description": "Convert any RSS or Atom feed into JSON. Fetch and parse blog posts, podcasts, and news feeds from any source.",
+    "baseUrl": "https://api.rss2json.com",
+    "authStrategy": "query",
+    "authKey": "api_key",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Parse feed: GET /v1/api.json?rss_url={encoded_feed_url}",
+        "Response: { status: \"ok\", feed: { title, link, description }, items: [{ title, link, pubDate, description, content, thumbnail }] }",
+        "The rss_url param must be URL-encoded.",
+        "Free tier: 10,000 requests/day, up to 10 items per feed.",
+        "Paid plans return more items and support count, order_by, order_dir params."
+    ],
+    "onboarding": {
+        "url": "https://rss2json.com/",
+        "steps": [
+            "Create a free account at rss2json.com",
+            "Your API key is shown on the dashboard after sign-up",
+            "Copy the API key"
+        ]
+    }
+}

package/src/connectors/sendgrid/connector.json

@@ -0,0 +1,27 @@
+{
+    "id": "sendgrid",
+    "name": "SendGrid",
+    "category": "Communication",
+    "description": "Email delivery service. Send transactional and marketing emails at scale via API.",
+    "baseUrl": "https://api.sendgrid.com",
+    "authStrategy": "bearer",
+    "authKey": "Authorization",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Send email: POST /v3/mail/send",
+        "  Body: { personalizations: [{ to: [{ email }] }], from: { email }, subject: \"...\", content: [{ type: \"text/plain\", value: \"...\" }] }",
+        "  Returns 202 Accepted (no body) on success.",
+        "List templates: GET /v3/templates?generations=dynamic",
+        "Free tier: 100 emails/day."
+    ],
+    "onboarding": {
+        "url": "https://signup.sendgrid.com/",
+        "steps": [
+            "Create an account at sendgrid.com",
+            "Go to Settings > API Keys",
+            "Create a new API key with appropriate permissions and copy it"
+        ]
+    }
+}

package/src/connectors/spoonacular/connector.json

@@ -0,0 +1,28 @@
+{
+    "id": "spoonacular",
+    "name": "Spoonacular",
+    "category": "Food",
+    "description": "Food and recipe API. Search recipes, get nutritional data, meal planning, and ingredient information.",
+    "baseUrl": "https://api.spoonacular.com",
+    "authStrategy": "header",
+    "authKey": "x-api-key",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Search recipes: GET /recipes/complexSearch?query={term}&number=10",
+        "Get recipe: GET /recipes/{id}/information",
+        "Random recipes: GET /recipes/random?number=5",
+        "Nutritional info: GET /recipes/{id}/nutritionWidget.json",
+        "Response (search): { results: [{ id, title, image }], totalResults }",
+        "Free tier: 150 requests/day."
+    ],
+    "onboarding": {
+        "url": "https://spoonacular.com/food-api/console#Dashboard",
+        "steps": [
+            "Create an account at spoonacular.com/food-api",
+            "Go to your Dashboard / Profile",
+            "Copy your API key"
+        ]
+    }
+}

package/src/connectors/stability-ai/connector.json

@@ -0,0 +1,27 @@
+{
+    "id": "stability-ai",
+    "name": "Stability AI",
+    "category": "Image",
+    "description": "AI image generation powered by Stable Diffusion. Create images from text prompts.",
+    "baseUrl": "https://api.stability.ai",
+    "authStrategy": "bearer",
+    "authKey": "Authorization",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Text-to-image: POST /v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image",
+        "  Request headers: Content-Type: application/json, Accept: application/json",
+        "  Request body: { text_prompts: [{ text: string, weight: 1 }], cfg_scale: 7, steps: 30, width: 1024, height: 1024 }",
+        "  Response: { artifacts: [{ base64: string, finishReason: string }] }",
+        "  Display with: <img src=\"data:image/png;base64,{base64}\">"
+    ],
+    "onboarding": {
+        "url": "https://platform.stability.ai/",
+        "steps": [
+            "Create an account at platform.stability.ai",
+            "Go to Account > API Keys",
+            "Create and copy your API key"
+        ]
+    }
+}

package/src/connectors/twilio/connector.json

@@ -0,0 +1,28 @@
+{
+    "id": "twilio",
+    "name": "Twilio",
+    "category": "Communication",
+    "description": "SMS, voice, and messaging APIs. Send text messages, make calls, and build communication workflows.",
+    "baseUrl": "https://api.twilio.com",
+    "authStrategy": "header",
+    "authKey": "Authorization",
+    "fields": [
+        { "name": "apiKey", "label": "Auth Token (Base64 SID:Token)", "type": "password" }
+    ],
+    "hints": [
+        "Send SMS: POST /2010-04-01/Accounts/{AccountSid}/Messages.json",
+        "  Body (form-encoded): To=+1234567890&From=+0987654321&Body=Hello",
+        "  IMPORTANT: Twilio uses Basic auth. Save your key as 'Basic base64(AccountSID:AuthToken)'.",
+        "  Content-Type must be application/x-www-form-urlencoded for SMS.",
+        "List messages: GET /2010-04-01/Accounts/{AccountSid}/Messages.json",
+        "Free trial: requires verified phone numbers."
+    ],
+    "onboarding": {
+        "url": "https://www.twilio.com/try-twilio",
+        "steps": [
+            "Create a Twilio account at twilio.com/try-twilio",
+            "Find your Account SID and Auth Token on the Console dashboard",
+            "Base64-encode 'AccountSID:AuthToken' and paste as your key"
+        ]
+    }
+}

package/src/connectors/types.ts

@@ -6,6 +6,11 @@ export interface ConnectorField {
     type: 'password' | 'text';
 }
 
+export interface ConnectorOnboarding {
+    url: string;
+    steps: string[];
+}
+
 export interface ConnectorDefinition {
     id: string;
     name: string;
@@ -17,6 +22,8 @@ export interface ConnectorDefinition {
     fields: ConnectorField[];
     /** Usage hints shown to the LLM — recommended endpoints, default settings, gotchas. */
     hints?: string;
+    /** Onboarding instructions — signup URL and steps to get an API key. */
+    onboarding?: ConnectorOnboarding;
     /** OAuth2: Authorization endpoint URL. */
     authorizationUrl?: string;
     /** OAuth2: Token exchange endpoint URL. */
@@ -25,6 +32,22 @@ export interface ConnectorDefinition {
     scopes?: string[];
 }
 
+export interface ConnectorJson {
+    id: string;
+    name: string;
+    category: string;
+    description: string;
+    baseUrl: string;
+    authStrategy: AuthStrategy;
+    authKey: string;
+    fields: ConnectorField[];
+    hints?: string[];
+    onboarding?: ConnectorOnboarding;
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    scopes?: string[];
+}
+
 export interface ConnectorConfig {
     apiKey: string;
     enabled: boolean;
@@ -46,7 +69,9 @@ export interface ConnectorSummary {
     id: string;
     name: string;
     category: string;
+    description: string;
     configured: boolean;
+    enabled: boolean;
 }
 
 export interface ConnectorDetail extends ConnectorDefinition {

package/src/connectors/unsplash/connector.json

@@ -0,0 +1,27 @@
+{
+    "id": "unsplash",
+    "name": "Unsplash",
+    "category": "Image",
+    "description": "Access a vast library of free high-resolution photos. Search, browse, and download professional photography.",
+    "baseUrl": "https://api.unsplash.com",
+    "authStrategy": "header",
+    "authKey": "Authorization",
+    "fields": [
+        { "name": "apiKey", "label": "Access Key", "type": "password" }
+    ],
+    "hints": [
+        "Search photos: GET /search/photos?query={term}&per_page=10",
+        "Random photo: GET /photos/random?query={term}",
+        "Response: { results: [{ urls: { regular, small, thumb }, description, user: { name } }] }",
+        "IMPORTANT: Save your key as 'Client-ID YOUR_ACCESS_KEY' (the proxy sends raw header value).",
+        "Free tier: 50 requests/hour."
+    ],
+    "onboarding": {
+        "url": "https://unsplash.com/developers",
+        "steps": [
+            "Create a developer account at unsplash.com/developers",
+            "Register a new application",
+            "Copy your Access Key from the app settings"
+        ]
+    }
+}

package/src/connectors/wolfram-alpha/connector.json

@@ -0,0 +1,26 @@
+{
+    "id": "wolfram-alpha",
+    "name": "Wolfram Alpha",
+    "category": "Science",
+    "description": "Computational intelligence engine. Get answers to factual queries, math, science, and data analysis.",
+    "baseUrl": "https://api.wolframalpha.com",
+    "authStrategy": "query",
+    "authKey": "appid",
+    "fields": [
+        { "name": "apiKey", "label": "App ID", "type": "password" }
+    ],
+    "hints": [
+        "Short answer: GET /v1/result?i={query} — returns plain text",
+        "Full results: GET /v2/query?input={query}&output=json",
+        "Response (v2): { queryresult: { pods: [{ title, subpods: [{ plaintext, img: { src } }] }] } }",
+        "Free tier: 2,000 queries/month."
+    ],
+    "onboarding": {
+        "url": "https://developer.wolframalpha.com/portal/myapps/",
+        "steps": [
+            "Create a Wolfram ID at developer.wolframalpha.com",
+            "Go to My Apps and create a new app",
+            "Copy the AppID from your app settings"
+        ]
+    }
+}

package/src/connectors/youtube-data/connector.json

@@ -0,0 +1,30 @@
+{
+    "id": "youtube-data",
+    "name": "YouTube Data",
+    "category": "Media",
+    "description": "Search YouTube videos, retrieve channel info, playlists, and video metadata via the YouTube Data API v3.",
+    "baseUrl": "https://www.googleapis.com/youtube/v3",
+    "authStrategy": "query",
+    "authKey": "key",
+    "fields": [
+        { "name": "apiKey", "label": "API Key", "type": "password" }
+    ],
+    "hints": [
+        "Search videos: GET /search?part=snippet&q={query}&type=video&maxResults=10",
+        "Get video details: GET /videos?part=snippet,statistics&id={videoId}",
+        "Get channel: GET /channels?part=snippet,statistics&id={channelId}",
+        "Get playlist items: GET /playlistItems?part=snippet&playlistId={playlistId}&maxResults=10",
+        "Response (search): { items: [{ id: { videoId }, snippet: { title, description, thumbnails, channelTitle } }] }",
+        "Embed video: <iframe src=\"https://www.youtube.com/embed/{videoId}\"></iframe>",
+        "Free quota: 10,000 units/day. Search costs 100 units, most reads cost 1-3 units."
+    ],
+    "onboarding": {
+        "url": "https://console.cloud.google.com/apis/library/youtube.googleapis.com",
+        "steps": [
+            "Go to the Google Cloud Console and create or select a project",
+            "Enable the YouTube Data API v3",
+            "Go to Credentials and create an API key",
+            "Copy the API key"
+        ]
+    }
+}

package/src/files.ts

@@ -55,6 +55,20 @@ export async function deleteFile(path: string): Promise<void> {
     await fs.unlink(path);
 }
 
+export async function copyFolderRecursive(srcFolder: string, destFolder: string): Promise<void> {
+    await ensureFolderExists(destFolder);
+    const entries = await fs.readdir(srcFolder, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcFolder, entry.name);
+        const destPath = path.join(destFolder, entry.name);
+        if (entry.isDirectory()) {
+            await copyFolderRecursive(srcPath, destPath);
+        } else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
+
 export async function deleteFolder(dirPath: string): Promise<void> {
     await fs.rm(dirPath, { recursive: true });
 }

package/src/init.ts

@@ -3,6 +3,7 @@ import path from "path";
 import { checkIfExists, copyFile, copyFiles, deleteFile, ensureFolderExists, listFiles, saveFile } from "./files";
 import { PAGE_VERSION } from "./pages";
 import { DefaultSettings } from "./settings";
+import { getOutdatedThemes, parseThemeFilename } from "./themes";
 
 export interface SynthOSConfig {
     pagesFolder: string;
@@ -112,6 +113,30 @@ async function repairMissingFolders(config: SynthOSConfig): Promise<void> {
         console.log(`Restoring default themes to .synthos folder...`);
         await ensureFolderExists(themesFolder);
         await copyFiles(config.defaultThemesFolder, themesFolder);
+    } else {
+        // Upgrade outdated themes — copy newer versioned CSS from defaults
+        const outdated = await getOutdatedThemes(config);
+        if (outdated.length > 0) {
+            console.log(`Upgrading ${outdated.length} theme(s): ${outdated.join(', ')}...`);
+            const defaultFiles = await listFiles(config.defaultThemesFolder);
+            for (const themeName of outdated) {
+                // Remove old versioned CSS files for this theme
+                const localFiles = await listFiles(themesFolder);
+                for (const f of localFiles) {
+                    const parsed = parseThemeFilename(f);
+                    if (parsed && parsed.name === themeName) {
+                        await deleteFile(path.join(themesFolder, f));
+                    }
+                }
+                // Copy the new versioned CSS from defaults
+                for (const f of defaultFiles) {
+                    const parsed = parseThemeFilename(f);
+                    if (parsed && parsed.name === themeName) {
+                        await copyFile(path.join(config.defaultThemesFolder, f), themesFolder);
+                    }
+                }
+            }
+        }
     }
 
     // Ensure pages/ subfolder exists
@@ -164,6 +189,7 @@ async function migrateFlatPages(pagesFolder: string): Promise<void> {
                 title,
                 categories: [category],
                 pinned: false,
+                showInAll: true,
                 createdDate: now,
                 lastModified: now,
                 pageVersion: 1,
@@ -201,6 +227,7 @@ async function copyDefaultPages(srcFolder: string, destFolder: string): Promise<
             title: typeof metadata.title === 'string' ? metadata.title : '',
             categories: Array.isArray(metadata.categories) ? metadata.categories : [],
             pinned: typeof metadata.pinned === 'boolean' ? metadata.pinned : false,
+            showInAll: typeof metadata.showInAll === 'boolean' ? metadata.showInAll : true,
             createdDate: now,
             lastModified: now,
             pageVersion: typeof metadata.pageVersion === 'number' ? metadata.pageVersion