@omega.js/backend 0.1.0

package/dist/manager/routes/content/post/get.js

@@ -0,0 +1,110 @@
+/**
+ * GET /content/post - Fetch blog post from GitHub
+ * Public endpoint to retrieve blog post content
+ */
+const { Octokit } = require('@octokit/rest');
+const { parse } = require('yaml');
+const { brandRepoOwner, brandRepoName } = require('../../../../vendor/config/index.js');
+const env = require('../../../libraries/env.js');
+
+module.exports = async ({ ctx, Manager, settings, analytics }) => {
+
+  // Check for GitHub configuration
+  if (!env.has('GH_TOKEN')) {
+    return ctx.respond('GitHub API key not configured.', { code: 500 });
+  }
+
+  if (!brandRepoOwner(Manager.config) || !brandRepoName(Manager.config)) {
+    return ctx.respond('GitHub repo not configured (set targets.backend.github.repo — "owner/name" or bare name — or repo.providers.github.org + brand.id).', { code: 500 });
+  }
+
+  // Setup Octokit
+  const octokit = new Octokit({
+    auth: env.get('GH_TOKEN'),
+  });
+
+  // Check for required parameters
+  if (!settings.url) {
+    return ctx.respond('Missing required parameter: url', { code: 400 });
+  }
+
+  let url;
+  try {
+    url = new URL(settings.url);
+  } catch (e) {
+    return ctx.respond('Invalid URL', { code: 400 });
+  }
+
+  // Get the post
+  const filename = url.pathname.replace(/blog|\//ig, '');
+  const repoInfo = { user: brandRepoOwner(Manager.config), name: brandRepoName(Manager.config) };
+  const query = `title+repo:${repoInfo.user}/${repoInfo.name}+filename:${filename}`;
+
+  ctx.log('Running search', query, repoInfo);
+
+  // Search the repo for the file matching the url
+  const results = await octokit.rest.search.code({
+    q: query,
+  }).catch(e => e);
+
+  ctx.log('Results', results);
+
+  // Check for errors
+  if (results instanceof Error) {
+    return ctx.respond(`Error searching for post: ${results}`, { code: 500 });
+  }
+  if (results?.data?.total_count === 0) {
+    return ctx.respond('Post not found', { code: 404 });
+  }
+
+  // Get the first result
+  const firstResult = results.data.items[0];
+
+  // Fetch the content of the post
+  const post = await octokit.rest.repos.getContent({
+    owner: repoInfo.user,
+    repo: repoInfo.name,
+    path: firstResult.path,
+  }).catch(e => e);
+
+  ctx.log('Post', post);
+
+  // Check for errors
+  if (post instanceof Error) {
+    return ctx.respond(`Error fetching post: ${post}`, { code: 500 });
+  }
+
+  // Decode the content
+  const fullContent = Buffer.from(post.data.content, 'base64').toString();
+  const splitContent = fullContent.split('---');
+  const frontmatter = splitContent[1].trim();
+  const body = splitContent.slice(2).join('---').trim();
+  const parsed = parse(frontmatter);
+
+  // Track analytics
+  analytics.event('content/post', { action: 'get' });
+
+  return ctx.respond({
+    // Meta
+    name: post.data.name,
+    path: post.data.path,
+    size: post.data.size,
+    sha: post.data.sha,
+
+    // Content
+    frontmatter: frontmatter,
+    body: body,
+
+    // Parsed
+    title: parsed.post.title,
+    description: parsed.post.description,
+    author: parsed.post.author,
+    id: parsed.post.id,
+    tags: parsed.post.tags,
+    categories: parsed.post.categories,
+    source: parsed.post.source || null,
+
+    // Derived
+    headerImageURL: `${url.origin}/assets/images/blog/post-${parsed.post.id}/${filename}.jpg`,
+  });
+};

package/dist/manager/routes/general/email/post.js

@@ -0,0 +1,89 @@
+/**
+ * POST /general/email - Send templated email
+ * Public endpoint to send email using predefined templates
+ */
+const path = require('path');
+const { merge } = require('lodash');
+const { loadTemplate } = require('../../../libraries/load-provider');
+module.exports = async ({ ctx, Manager, settings }) => {
+  // Validate required parameters
+  if (!settings.id) {
+    return ctx.respond('Parameter {id} is required.', { code: 400 });
+  }
+  if (!settings.email) {
+    return ctx.respond('Parameter {email} is required.', { code: 400 });
+  }
+
+  const DEFAULT = {
+    spamFilter: {
+      ip: 3,
+      email: 3,
+    },
+    delay: 1,
+    payload: {},
+  };
+
+  // Load email template — colons in id are converted to nested folders
+  // (e.g. "general:download-app-link" → templates/general/download-app-link.js);
+  // loadTemplate validates the id so it can never resolve outside templates/
+  let emailPayload;
+  try {
+    const script = loadTemplate(path.join(__dirname, 'templates'), settings.id);
+    emailPayload = merge(
+      {},
+      DEFAULT,
+      script(settings, Manager.config),
+    );
+  } catch (e) {
+    return ctx.respond(`${settings.id} is not a valid email ID.`, { code: 400 });
+  }
+
+  // Check spam filter using local storage
+  const storage = Manager.storage({ temporary: true });
+  const ipPath = ['api:general:email', 'ips', ctx.request.geolocation.ip || 'unknown'];
+  const emailPath = ['api:general:email', 'emails', settings.email];
+
+  const ipData = storage.get(ipPath).value() || {};
+  const emailData = storage.get(emailPath).value() || {};
+
+  ipData.count = (ipData.count || 0) + 1;
+  ipData.firstRequestTime = ipData.firstRequestTime || new Date().toISOString();
+  ipData.lastRequestTime = new Date().toISOString();
+
+  emailData.count = (emailData.count || 0) + 1;
+  emailData.firstRequestTime = emailData.firstRequestTime || new Date().toISOString();
+  emailData.lastRequestTime = new Date().toISOString();
+
+  storage.set(ipPath, ipData).write();
+  storage.set(emailPath, emailData).write();
+
+  ctx.log('Storage:', storage.getState()['api:general:email']);
+
+  // Check spam thresholds
+  if (ipData.count >= emailPayload.spamFilter.ip || emailData.count >= emailPayload.spamFilter.email) {
+    ctx.error(`Spam filter triggered ip=${ipData.count}, email=${emailData.count}`);
+    return ctx.respond({ success: true });
+  }
+
+  // Add delay if specified
+  if (emailPayload.delay) {
+    emailPayload.payload.sendAt = Math.round((new Date().getTime() + emailPayload.delay) / 1000);
+  }
+
+  ctx.log('Email payload:', emailPayload);
+
+  // Send email directly via library
+  const email = Manager.Email(ctx);
+  const result = await email.send(emailPayload.payload).catch(e => e);
+
+  if (result instanceof Error) {
+    return ctx.respond(result.message, { code: result.code || 500 });
+  }
+
+  ctx.log('Response:', result.status);
+
+  // Track analytics
+  ctx.analytics.event('general/email', { id: settings.id });
+
+  return ctx.respond({ success: true });
+};

package/dist/manager/routes/general/email/templates/general/download-app-link.js

@@ -0,0 +1,42 @@
+/**
+ * Email template: download-app-link
+ * Sends a download link for the app
+ */
+module.exports = function (payload, config) {
+  const brandName = config.brand.name || '';
+  const brandUrl = config.brand.url || '';
+  const downloadUrl = `${brandUrl}/download`;
+  const name = payload.name || '';
+
+  return {
+    // spamFilter: {
+    //   ip: 3,
+    //   email: 3,
+    // },
+    // delay: 30000,
+    payload: {
+      to: {
+        email: payload.email,
+        name: name,
+      },
+      sender: 'marketing',
+      categories: ['download'],
+      subject: `${name || 'Hey'}, your ${brandName} download link is ready!`,
+      template: 'card',
+      copy: false,
+      data: {
+        email: {
+          preview: `Your ${brandName} download link is inside`,
+        },
+        content: {
+          title: 'Your download link is ready!',
+          message: `Thanks for your interest in **${brandName}**! Click the button below to head to the download page and get started.`,
+          button: {
+            url: downloadUrl,
+            text: 'Download Now',
+          },
+        },
+      },
+    }
+  }
+}

package/dist/manager/routes/general/uuid/post.js

@@ -0,0 +1,31 @@
+const uuid = require('uuid');
+
+module.exports = async ({ ctx, settings, analytics }) => {
+
+  const name = settings.name || settings.input;
+  const version = `${settings.version}`.replace('v', '');
+  const namespace = settings.namespace;
+
+  // Validate version
+  if (version !== '4' && version !== '5') {
+    return ctx.respond(`v${version} is not a valid version.`, { code: 400 });
+  }
+
+  // Validate name for v5
+  if (version === '5' && !name) {
+    return ctx.respond('You must provide a name to hash for UUID v5.', { code: 400 });
+  }
+
+  // Generate UUID
+  const result = version === '5'
+    ? uuid.v5(name, namespace)
+    : uuid.v4();
+
+  // Send analytics event
+  analytics.event('general/uuid', { version });
+
+  // Log and respond
+  ctx.log('UUID Generated', { name, version, namespace, result });
+
+  return ctx.respond({ uuid: result });
+};

package/dist/manager/routes/handler/post/post.js

@@ -0,0 +1,142 @@
+/**
+ * POST /handler/post - Create post handler (with invoice and notification)
+ * Admin-only endpoint that creates invoices and sends notifications for guest posts
+ */
+const env = require('../../../libraries/env.js');
+
+module.exports = async ({ ctx, Manager, user, settings, analytics }) => {
+  const fetch = Manager.require('wonderful-fetch');
+
+  // Require authentication
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+
+  // Require admin
+  if (!user.roles.admin) {
+    return ctx.respond('Admin required.', { code: 403 });
+  }
+
+  const response = {
+    invoice: {
+      success: false,
+      data: {},
+    },
+    notification: {
+      success: false,
+      data: {},
+    }
+  };
+
+  const postSlug = `/blog/${settings.url}`;
+  const invoiceNote = `GP to ${Manager.config.brand.name} \nSlug: ${postSlug} \n\n${settings.invoiceNote}`;
+
+  // Create and send invoice if email and price are provided
+  if (settings.invoiceEmail && settings.invoicePrice) {
+    // Create invoice
+    // ITW wrapper wire contract: the wrapper Cloud Function runs legacy BEM,
+    // whose auth reads exactly this payload field. Flips to the
+    // omega-admin-key header only when ITW's wrapper migrates to the new
+    // stack — never "fix" unilaterally.
+    const createdInvoice = await fetch('https://us-central1-itw-creative-works.cloudfunctions.net/wrapper', {
+      method: 'POST',
+      response: 'json',
+      body: {
+        backendManagerKey: env.get('OMEGA_ADMIN_KEY'),
+        method: 'post',
+        service: 'paypal',
+        command: 'v2/invoicing/invoices',
+        body: {
+          detail: {
+            currency_code: 'USD',
+            note: invoiceNote,
+            memo: invoiceNote,
+          },
+          primary_recipients: [
+            {
+              billing_info: {
+                email_address: settings.invoiceEmail,
+              },
+            }
+          ],
+          items: [
+            {
+              name: 'GP',
+              description: `Slug: ${postSlug}`,
+              quantity: '1',
+              unit_amount: {
+                currency_code: 'USD',
+                value: `${settings.invoicePrice}`
+              },
+              unit_of_measure: 'QUANTITY',
+            },
+          ],
+        }
+      },
+    }).catch(e => e);
+
+    if (createdInvoice instanceof Error) {
+      return ctx.respond(createdInvoice.message, { code: 500 });
+    }
+
+    // Send invoice
+    const createdInvoiceId = (createdInvoice?.href ?? '').split('/').pop();
+    // Send invoice — same ITW-wrapper wire pin as the create call above
+    const sentInvoice = await fetch('https://us-central1-itw-creative-works.cloudfunctions.net/wrapper', {
+      method: 'POST',
+      response: 'json',
+      body: {
+        backendManagerKey: env.get('OMEGA_ADMIN_KEY'),
+        service: 'paypal',
+        command: `v2/invoicing/invoices/${createdInvoiceId}/send`,
+        method: 'post',
+        body: {}
+      },
+    }).catch(e => e);
+
+    if (sentInvoice instanceof Error) {
+      return ctx.respond(sentInvoice.message, { code: 500 });
+    }
+
+    response.invoice = {
+      success: true,
+      data: sentInvoice,
+    };
+  }
+
+  // Send notification (unless explicitly disabled)
+  if (settings.sendNotification !== false) {
+    // Use NEW API format
+    await fetch(`${Manager.getApiUrl()}/omega/admin/notification`, {
+      method: 'POST',
+      response: 'json',
+      headers: {
+        'Authorization': `Bearer ${env.get('OMEGA_ADMIN_KEY')}`,
+      },
+      body: {
+        notification: {
+          title: settings.title,
+          body: `"${settings.title}" was just published on our blog. It's a great read and we think you'll enjoy the content!`,
+          click_action: `${Manager.project.websiteUrl}/blog`,
+          // brand.images stores site-relative paths — the push icon must be a
+          // fetchable URL, resolved against THIS environment's website origin
+          icon: Manager.config.brand.images.brandmark
+            ? new URL(Manager.config.brand.images.brandmark, Manager.project.websiteUrl).href
+            : undefined,
+        }
+      },
+    }).catch(e => {
+      ctx.error('Failed to send notification:', e);
+    });
+
+    response.notification = {
+      success: true,
+      data: {},
+    };
+  }
+
+  // Track analytics
+  analytics.event('handler/post', { action: 'create' });
+
+  return ctx.respond(response);
+};

package/dist/manager/routes/health/get.js

@@ -0,0 +1,43 @@
+const path = require('path');
+const { readTestMode, applyEnvFromFile } = require('../../../test/utils/test-mode-file.js');
+
+/**
+ * GET /health — the deployed backend's liveness + version probe
+ *
+ * Public by design: no auth, and it echoes NO request input, so it is safe at a
+ * production URL. @omega.js/manager's live API check reads it on a real host and
+ * the test runner reads it to confirm the emulator's project + mode. It used to
+ * live at `test/health` and needed a carve-out in the dev-only folder gate; a
+ * liveness probe is not a test route, so it is a real route now and the folder
+ * has zero exceptions ([#238](https://github.com/Omega-JS-Stack/omega/issues/238)).
+ */
+module.exports = async ({ ctx, Manager }) => {
+
+  // Belt-and-suspenders freshness check: re-read the test-mode file before
+  // reporting `testExtendedMode`. fs.watch installed in Manager.init usually
+  // catches changes within ~50ms, but this handler hits the disk directly to
+  // guarantee the runner sees the actual current value even if the watcher
+  // missed an event. ~1ms cost on a debug endpoint.
+  try {
+    const projectDir = path.dirname(Manager.cwd);
+    const data = readTestMode(projectDir);
+    applyEnvFromFile(data);
+  } catch (e) {
+    // Non-fatal — if the file can't be read, fall through to whatever
+    // process.env already has.
+  }
+
+  const response = {
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    environment: ctx.meta?.environment || 'unknown',
+    projectId: Manager.config?.cloud?.config?.projectId || process.env.GCLOUD_PROJECT || 'unknown',
+    version: Manager.package?.version || 'unknown',
+    backendVersion: Manager.version || 'unknown',
+    testExtendedMode: !!process.env.TEST_EXTENDED_MODE,
+  };
+
+  ctx.log('Health check', response);
+
+  return ctx.respond(response);
+};

package/dist/manager/routes/index.js

@@ -0,0 +1,11 @@
+module.exports = async ({ ctx, Manager }) => {
+
+  // Get url
+  const url = Manager.config?.brand?.url;
+
+  // Log
+  ctx.log('Route.main(): Executing route logic', url);
+
+  // Redirect to brand URL
+  return ctx.redirect(url);
+};

package/dist/manager/routes/marketing/campaign/delete.js

@@ -0,0 +1,45 @@
+/**
+ * DELETE /marketing/campaign - Delete a marketing campaign
+ * Admin-only. Can only delete pending campaigns.
+ */
+module.exports = async ({ ctx, user, Manager, settings, analytics }) => {
+
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+  if (!user.roles.admin) {
+    return ctx.respond('Admin access required', { code: 403 });
+  }
+
+  const { admin } = Manager.libraries;
+  const campaignId = (settings.id || '').trim();
+
+  if (!campaignId) {
+    return ctx.respond('Campaign ID is required', { code: 400 });
+  }
+
+  const docRef = admin.firestore().doc(`marketing-campaigns/${campaignId}`);
+  const doc = await docRef.get();
+
+  if (!doc.exists) {
+    return ctx.respond('Campaign not found', { code: 404 });
+  }
+
+  const existing = doc.data();
+
+  // Can only delete pending campaigns (sent/failed are historical records)
+  if (existing.status !== 'pending') {
+    return ctx.respond(`Cannot delete campaign with status "${existing.status}"`, { code: 400 });
+  }
+
+  await docRef.delete();
+
+  ctx.log('marketing/campaign deleted:', { campaignId });
+
+  analytics.event('marketing/campaign', { action: 'delete' });
+
+  return ctx.respond({
+    success: true,
+    deleted: campaignId,
+  });
+};

package/dist/manager/routes/marketing/campaign/get.js

@@ -0,0 +1,69 @@
+/**
+ * GET /marketing/campaign - List or get marketing campaigns
+ * Admin-only. Used by calendar frontend.
+ *
+ * Query params:
+ *   id       — Get a single campaign by ID
+ *   start    — Filter campaigns with sendAt >= start (unix timestamp)
+ *   end      — Filter campaigns with sendAt <= end (unix timestamp)
+ *   status   — Filter by status (pending, sent, failed)
+ *   type     — Filter by type (email, push)
+ *   limit    — Max results (default 100)
+ */
+module.exports = async ({ ctx, user, Manager, settings }) => {
+
+  if (!user.authenticated) {
+    return ctx.respond('Authentication required', { code: 401 });
+  }
+  if (!user.roles.admin) {
+    return ctx.respond('Admin access required', { code: 403 });
+  }
+
+  const { admin } = Manager.libraries;
+
+  // Single campaign by ID
+  if (settings.id) {
+    const doc = await admin.firestore().doc(`marketing-campaigns/${settings.id}`).get();
+
+    if (!doc.exists) {
+      return ctx.respond('Campaign not found', { code: 404 });
+    }
+
+    return ctx.respond({
+      success: true,
+      campaign: { id: doc.id, ...doc.data() },
+    });
+  }
+
+  // List campaigns with filters
+  let query = admin.firestore().collection('marketing-campaigns');
+
+  if (settings.status) {
+    query = query.where('status', '==', settings.status);
+  }
+  if (settings.type) {
+    query = query.where('type', '==', settings.type);
+  }
+  if (settings.start) {
+    query = query.where('sendAt', '>=', parseInt(settings.start, 10));
+  }
+  if (settings.end) {
+    query = query.where('sendAt', '<=', parseInt(settings.end, 10));
+  }
+
+  query = query.orderBy('sendAt', 'asc');
+  query = query.limit(parseInt(settings.limit, 10) || 100);
+
+  const snapshot = await query.get();
+
+  const campaigns = snapshot.docs.map(doc => ({
+    id: doc.id,
+    ...doc.data(),
+  }));
+
+  return ctx.respond({
+    success: true,
+    campaigns,
+    count: campaigns.length,
+  });
+};