@omega.js/backend 0.1.0

package/dist/manager/libraries/auth-user.js

@@ -0,0 +1,46 @@
+/**
+ * Does a uid belong to THIS project? — the one place that question is asked.
+ *
+ * A user doc is born at signup, behind a real Firebase auth user. Both payment
+ * seams (the webhook pipeline and the checkout route) need to know a uid is one
+ * of ours before anything is written under it
+ * ([#399](https://github.com/Omega-JS-Stack/omega/issues/399)), and the sign-in
+ * heal needs the record itself before it recreates a doc under one
+ * ([#405](https://github.com/Omega-JS-Stack/omega/issues/405)).
+ */
+
+/**
+ * The Firebase auth user for this uid in this project, or null when there is none
+ *
+ * @param {object} admin - The firebase-admin app
+ * @param {string} uid - The uid to look up
+ * @returns {Promise<object|null>} The UserRecord, or null when the user does not exist
+ * @throws {Error} When the Auth service itself failed — never read as an absence
+ */
+async function getAuthUser(admin, uid) {
+  try {
+    return await admin.auth().getUser(uid);
+  } catch (e) {
+    if (e.code === 'auth/user-not-found') {
+      return null;
+    }
+
+    // Anything else is Auth being unreachable or misconfigured, which is no proof
+    // the user is missing — swallowing it here would refuse a real customer.
+    throw e;
+  }
+}
+
+/**
+ * Whether a Firebase auth user exists for this uid in this project
+ *
+ * @param {object} admin - The firebase-admin app
+ * @param {string} uid - The uid to look up
+ * @returns {Promise<boolean>}
+ * @throws {Error} When the Auth service itself failed — never read as an absence
+ */
+async function hasAuthUser(admin, uid) {
+  return !!await getAuthUser(admin, uid);
+}
+
+module.exports = { getAuthUser, hasAuthUser };

package/dist/manager/libraries/content/feed-parser.js

@@ -0,0 +1,198 @@
+/**
+ * Feed Parser — RSS 2.0, Atom 1.0, and JSON Feed parser + article content extractor.
+ *
+ * Parses standard syndication feeds into a normalized item array and extracts
+ * readable article text from URLs. Used by the blog-auto-publisher cron to
+ * select individual articles from third-party feeds for AI-assisted content
+ * generation.
+ *
+ * @module feed-parser
+ */
+const { XMLParser } = require('fast-xml-parser');
+const cheerio = require('cheerio');
+const fetch = require('wonderful-fetch');
+
+const MAX_CONTENT_LENGTH = 1024 * 14;
+const USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36';
+
+/**
+ * Parse an RSS 2.0, Atom 1.0, or JSON Feed string into a normalized item array.
+ *
+ * @param {string} text - Raw feed text (XML or JSON).
+ * @returns {{ items: FeedItem[] }} Normalized feed items. Empty array on unparseable input.
+ *
+ * @typedef {object} FeedItem
+ * @property {string} id - Stable unique identifier (guid / atom:id / url).
+ * @property {string} title - Item title.
+ * @property {string} url - Link to the full article.
+ * @property {string} summary - Short excerpt (max 500 chars, HTML stripped).
+ * @property {string} content - Full inline content if available (max 14KB, HTML stripped).
+ * @property {string} publishedAt - Publication date string (ISO or RFC-822).
+ */
+function parseFeed(text) {
+  if (!text || typeof text !== 'string') {
+    return { items: [] };
+  }
+
+  const clean = text.replace(/^/, '').trim();
+  if (!clean) {
+    return { items: [] };
+  }
+
+  // JSON Feed
+  try {
+    const json = JSON.parse(clean);
+    if (json && Array.isArray(json.items)) {
+      return { items: normalizeJsonFeed(json.items) };
+    }
+    return { items: [] };
+  } catch (e) {
+    // Not JSON — try XML
+  }
+
+  // XML (RSS 2.0 / Atom 1.0)
+  try {
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_',
+      isArray: (name) => ['item', 'entry'].includes(name),
+    });
+    const doc = parser.parse(clean);
+
+    if (doc.rss?.channel) {
+      return { items: normalizeRss(doc.rss.channel) };
+    }
+
+    if (doc.feed) {
+      return { items: normalizeAtom(doc.feed) };
+    }
+  } catch (e) {
+    // Unparseable XML
+  }
+
+  return { items: [] };
+}
+
+/**
+ * JSON Feed (jsonfeed.org) + rss.app format normalizer.
+ */
+function normalizeJsonFeed(items) {
+  return (items || []).map((item) => ({
+    id: String(item.id || item.url || ''),
+    title: String(item.title || ''),
+    url: String(item.url || item.link || ''),
+    summary: String(item.summary || item.content_text || '').slice(0, 500),
+    content: String(item.content_html || item.content_text || '').slice(0, MAX_CONTENT_LENGTH),
+    publishedAt: String(item.date_published || item.date_modified || ''),
+  })).filter((item) => item.id || item.url);
+}
+
+/**
+ * RSS 2.0 normalizer — handles <item> with guid, title, link, description, content:encoded, pubDate.
+ */
+function normalizeRss(channel) {
+  const items = channel.item || [];
+
+  return items.map((item) => {
+    const link = Array.isArray(item.link) ? item.link[0] : (item.link || '');
+    const guid = item.guid?.['#text'] || item.guid || '';
+
+    return {
+      id: String(guid || link),
+      title: String(item.title || ''),
+      url: String(link),
+      summary: stripHtml(String(item.description || '')).slice(0, 500),
+      content: stripHtml(String(item['content:encoded'] || item.description || '')).slice(0, MAX_CONTENT_LENGTH),
+      publishedAt: String(item.pubDate || ''),
+    };
+  }).filter((item) => item.id || item.url);
+}
+
+/**
+ * Atom 1.0 normalizer — handles <entry> with id, title, link href, summary, content, published.
+ */
+function normalizeAtom(feed) {
+  const entries = feed.entry || [];
+
+  return entries.map((entry) => {
+    const links = Array.isArray(entry.link) ? entry.link : [entry.link].filter(Boolean);
+    const altLink = links.find((l) => l?.['@_rel'] === 'alternate' || !l?.['@_rel']);
+    const url = altLink?.['@_href'] || links[0]?.['@_href'] || '';
+
+    const title = entry.title?.['#text'] || entry.title || '';
+    const summary = entry.summary?.['#text'] || entry.summary || '';
+    const content = entry.content?.['#text'] || entry.content || '';
+
+    return {
+      id: String(entry.id || url),
+      title: String(title),
+      url: String(url),
+      summary: stripHtml(String(summary)).slice(0, 500),
+      content: stripHtml(String(content)).slice(0, MAX_CONTENT_LENGTH),
+      publishedAt: String(entry.published || entry.updated || ''),
+    };
+  }).filter((item) => item.id || item.url);
+}
+
+/**
+ * Fetch a URL and extract the readable article text from its HTML via Cheerio.
+ *
+ * Priority: `<article>` → `<main>` → `<body>`. Removes non-content elements
+ * (scripts, styles, nav, ads, forms, widgets) before extracting text.
+ * Truncates to 14KB.
+ *
+ * @param {string} url - The article URL to fetch.
+ * @returns {Promise<string>} Extracted plain text (empty string on failure).
+ */
+async function extractArticleContent(url) {
+  if (!url) {
+    return '';
+  }
+
+  const res = await fetch(url, {
+    timeout: 30000,
+    tries: 2,
+    response: 'raw',
+    headers: { 'User-Agent': USER_AGENT },
+  });
+
+  const html = await res.text();
+  if (!html) {
+    return '';
+  }
+
+  return extractTextFromHtml(html).slice(0, MAX_CONTENT_LENGTH);
+}
+
+/**
+ * Extract readable text from an HTML string using Cheerio.
+ *
+ * @param {string} html - Raw HTML string.
+ * @returns {string} Clean plain text.
+ */
+function extractTextFromHtml(html) {
+  const $ = cheerio.load(html);
+
+  // Remove non-content elements
+  $('script, style, noscript, nav, footer, header, aside, form, button, svg, iframe, figure, figcaption, [role="navigation"], [role="banner"], [role="complementary"], [aria-hidden="true"], .ad, .ads, .advertisement, .social-share, .related-articles, .sidebar').remove();
+
+  // Extract from the most specific content container
+  const $content = $('article').length ? $('article')
+    : $('main').length ? $('main')
+    : $('body');
+
+  const text = $content.text().replace(/\s+/g, ' ').trim();
+  return text;
+}
+
+/**
+ * Strip all HTML tags from a string and normalize whitespace.
+ *
+ * @param {string} html - HTML string to clean.
+ * @returns {string} Plain text.
+ */
+function stripHtml(html) {
+  return html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+module.exports = { parseFeed, extractArticleContent, extractTextFromHtml, stripHtml };

package/dist/manager/libraries/content/ghostii.js

@@ -0,0 +1,191 @@
+/**
+ * Ghostii article engine — shared helpers for AI article generation + publishing.
+ *
+ * Ghostii (api.ghostii.ai) is UNOPINIONATED about @omega.js/backend. It returns a generic,
+ * structured article: a `json` block array ([{ name, content }]) plus `title`,
+ * `description`, `headerImageUrl`, `categories`, `keywords`. It is NOT shaped to
+ * @omega.js/backend's post format — @omega.js/backend is responsible for transforming Ghostii's output into
+ * what its `admin/post` route expects.
+ *
+ * `blocksToPost()` is that transform: it digests the JSON blocks and pulls out
+ * the title (heading-1), the header image (first image block), and the clean
+ * body (every remaining block — sections, paragraphs, section images, quotes —
+ * joined as markdown, with NO title or header image embedded, since admin/post
+ * adds those itself from the separate `title`/`headerImageURL` fields).
+ *
+ * Two consumers:
+ *   - events/cron/daily/blog-auto-publisher.js — standalone daily article job
+ *   - libraries/email/generators/newsletter.js — newsletter-driven linked article
+ *
+ * Both call writeArticle() then publishArticle(). Kept here as the single source
+ * of truth for the Ghostii request shape and the admin/post payload.
+ */
+const fetch = require('wonderful-fetch');
+const powertools = require('node-powertools');
+const env = require('../env.js');
+
+/**
+ * Generate an article via the Ghostii API.
+ *
+ * @param {object} args
+ * @param {object} args.brand - Public brand config ({ brand: { url, ... }, repo: { ... } })
+ * @param {string} args.description - The article brief / prompt content
+ * @param {string[]} [args.links] - Optional links to inject into the article body
+ * @param {string} [args.sourceContent] - Reference article text for source-based generation
+ * @param {object} [args.overrides] - Per-entry overrides for Ghostii API params
+ * @returns {Promise<object>} Ghostii's generic article response:
+ *   { title, description, body, json, headerImageUrl, images, categories, keywords, links, outline }
+ *   where `json` is the structured block array ([{ name, content }]) that
+ *   blocksToPost() consumes to build @omega.js/backend's post shape.
+ */
+async function writeArticle({ brand, description, links, sourceContent, overrides }) {
+  const o = overrides || {};
+
+  const body = {
+    // Ghostii's LIVE wire contract: its production backend runs legacy BEM,
+    // whose auth reads exactly this payload field. Renames to the
+    // omega-admin-key header only when Ghostii itself migrates to the new
+    // stack — never "fix" unilaterally (it would break article generation).
+    backendManagerKey: env.get('OMEGA_ADMIN_KEY'),
+    keywords: o.keywords || [],
+    description: description,
+    insertLinks: o.insertLinks ?? true,
+    research: o.research ?? true,
+    insertImages: o.insertImages ?? true,
+    length: o.length || 'long',
+    maxLinks: o.maxLinks || 6,
+    headerImageUrl: o.headerImageUrl || 'unsplash',
+    url: brand.brand.url,
+    sectionQuantity: o.sectionQuantity || powertools.random(3, 6, { mode: 'gaussian' }),
+    feedUrl: o.feedUrl || `${brand.brand.url}/feeds/posts.json`,
+    links: links || [],
+  };
+
+  if (sourceContent) {
+    body.sourceContent = sourceContent;
+  }
+
+  const start = Date.now();
+
+  // Original URL: https://api.ghostii.ai/write/article
+  // Firebase Hosting rewrites have a hard 60s proxy timeout that causes 502s
+  // on slow AI pipelines. The raw Cloud Functions URL uses the function's own
+  // 5-minute timeout instead.
+  const result = await fetch('https://us-central1-ghostii.cloudfunctions.net/writeGlobal/write/article', {
+    method: 'post',
+    timeout: 180000,
+    tries: 1,
+    response: 'json',
+    body: body,
+  });
+
+  const duration = Date.now() - start;
+  console.log(`[@omega.js/backend:ghostii] writeArticle() completed in ${duration}ms (${(duration / 1000).toFixed(1)}s)`);
+
+  return result;
+}
+
+/**
+ * Transform Ghostii's generic JSON block array into @omega.js/backend's post shape.
+ *
+ * Ghostii returns `json: [{ name, content }]` where name ∈ heading-1..6, image,
+ * paragraph, blockquote, list. @omega.js/backend's admin/post wants the title + header image as
+ * SEPARATE fields and a body that is ONLY the content below them. So we extract:
+ *   - title       ← first heading-1 block (markdown `#` stripped)
+ *   - headerImageUrl ← first image block's URL
+ *   - body        ← every remaining block, joined as markdown
+ *
+ * @param {Array} json - Ghostii's block array.
+ * @returns {{ title: string, headerImageUrl: string, body: string }}
+ */
+function blocksToPost(json) {
+  const blocks = Array.isArray(json) ? json : [];
+
+  const titleBlock = blocks.find((b) => b.name === 'heading-1');
+  const imageBlock = blocks.find((b) => b.name === 'image');
+
+  // Title: strip the leading markdown heading marker.
+  const title = (titleBlock?.content || '').replace(/^#+\s*/, '').trim();
+
+  // Header image: pull the URL out of `![alt](url)`.
+  const imageMatch = (imageBlock?.content || '').match(/\((.*?)\)\s*$/);
+  const headerImageUrl = imageMatch ? imageMatch[1] : '';
+
+  // Body: everything except the title block and the header-image block.
+  const body = blocks
+    .filter((b) => b !== titleBlock && b !== imageBlock)
+    .map((b) => b.content)
+    .join('\n\n')
+    .trim();
+
+  return { title, headerImageUrl, body };
+}
+
+/**
+ * Publish a Ghostii article to the brand's website repo via the admin/post route.
+ *
+ * @param {object} ctx - @omega.js/backend ctx instance
+ * @param {object} args
+ * @param {object} args.brand - Public brand config ({ brand: { url, ... } }); the target repo is
+ *   never sent — admin/post always derives it from ITS OWN brand config
+ * @param {object} args.article - The article from writeArticle(). When it carries a
+ *   `json` block array, the post is reconstructed via blocksToPost() (title + header
+ *   image extracted, body = content only). Falls back to article.{title,body,headerImageUrl}.
+ * @param {number} args.id - Post ID (unix timestamp)
+ * @param {string} [args.author] - Author slug (admin/post picks a default if unset)
+ * @param {string} [args.postPath='ghostii'] - Sub-folder under _posts/{year}/
+ * @returns {Promise<object>} { post, url, slug, path } — `url` is the public blog URL
+ */
+async function publishArticle(ctx, { brand, article, id, author, postPath, source }) {
+  const apiUrl = ctx.Manager.getApiUrl();
+
+  // Transform Ghostii's generic JSON into @omega.js/backend's post shape (title + header image
+  // as separate fields, body = content only). Fall back to the legacy flat fields
+  // for older Ghostii responses that don't include `json`.
+  const post = blocksToPost(article.json);
+  const title = post.title || article.title;
+  const headerImageUrl = post.headerImageUrl || article.headerImageUrl;
+  const body = article.json ? post.body : article.body;
+
+  const postBody = {
+    title: title,
+    url: title,
+    description: article.description,
+    headerImageURL: headerImageUrl,
+    body: body,
+    id: id,
+    author: author,
+    categories: article.categories,
+    tags: article.keywords,
+    postPath: postPath || 'ghostii',
+    source: source || null,
+  };
+
+  console.log(`[@omega.js/backend:ghostii] publishArticle() source=${postBody.source}`);
+
+  const result = await fetch(`${apiUrl}/omega/admin/post`, {
+    method: 'POST',
+    timeout: 90000,
+    tries: 1,
+    response: 'json',
+    headers: {
+      'omega-admin-key': env.get('OMEGA_ADMIN_KEY'),
+    },
+    body: postBody,
+  });
+
+  // admin/post returns the resolved `settings` (incl. the slugified `url` and repo `path`).
+  // The post template sets no permalink, so the public URL follows the Jekyll/UJM
+  // blog convention: {brand.url}/blog/{slug}.
+  const slug = result?.url || '';
+  const publicUrl = `${(brand.brand.url || '').replace(/\/$/, '')}/blog/${slug}`;
+
+  return {
+    post: result,
+    url: slug ? publicUrl : null,
+    slug,
+    path: result?.path || null,
+  };
+}
+
+module.exports = { writeArticle, publishArticle, blocksToPost };