@omega.js/backend 0.1.0

package/dist/manager/libraries/email/data/typo-domains.js

@@ -0,0 +1,83 @@
+/**
+ * Common email domain typos/misspellings.
+ *
+ * Each entry is a prefix string (without the leading @). The validator checks
+ * if the domain STARTS WITH any of these prefixes, so "gamil." catches
+ * gamil.com, gamil.con, gamil.co, etc.
+ *
+ * Only include patterns with ZERO chance of false positives — these must be
+ * domains that are clearly misspelled versions of real providers and would
+ * never host legitimate email.
+ */
+module.exports = [
+  // Gmail typos
+  'gamil.',
+  'gmai.',
+  'gmial.',
+  'gmal.',
+  'gmali.',
+  'gmil.',
+  'gnail.',
+  'gmeil.',
+  'gmaill.',
+  'gmail.con',
+  'gmail.com.',
+  'gmail.co.',
+  'gmail.cm',
+  'gmail.om',
+  'gmail.cok',
+  'gmaul.',
+  'gmqil.',
+
+  // Yahoo typos
+  'yaho.',
+  'yahooo.',
+  'yahho.',
+  'yhaoo.',
+  'yahoo.con',
+  'yahoo.cok',
+
+  // Hotmail typos
+  'hotmal.',
+  'hotmial.',
+  'hotmil.',
+  'hotamil.',
+  'hotmail.con',
+  'hotmail.cok',
+  'hotnail.',
+
+  // Outlook typos
+  'outloo.',
+  'outlok.',
+  'outllook.',
+  'outlook.con',
+  'outlook.cok',
+  'outlool.',
+
+  // iCloud typos
+  'icloud.con',
+  'icloud.cok',
+  'iclould.',
+  'icoud.',
+  'iclod.',
+
+  // AOL typos
+  'aol.con',
+  'aol.cok',
+
+  // Protonmail typos
+  'protonmal.',
+  'protonmial.',
+  'protonmail.con',
+
+  // Generic TLD typos (provider-agnostic, only on major providers)
+  'gmail.cim',
+  'yahoo.cim',
+  'hotmail.cim',
+  'outlook.cim',
+
+  // Fake gmail-lookalike domains (disposable services mimicking gmail)
+  'gmail10p.',
+  'oegmail.',
+  'gmailx.',
+];

package/dist/manager/libraries/email/disposable-domains.js

@@ -0,0 +1,92 @@
+/**
+ * The disposable-email-domain dataset — a committed SEED plus a gitignored refresh CACHE.
+ *
+ * Source: https://github.com/disposable-email-domains/disposable-email-domains
+ * (curated, low false-positive rate)
+ *
+ * The contract (issue #68):
+ * - `data/disposable-domains.json` is the SEED: committed, and only ever written
+ *   by the deliberate `promote()` step. Refreshes never touch it, so a suite run
+ *   or a prepare build can no longer dirty the git tree.
+ * - `refresh()` fetches the upstream list and writes ONLY to the gitignored cache
+ *   at `<package>/.cache/email/disposable-domains.json`.
+ * - `load()` reads the cache when it is present and parseable, else the seed.
+ *   No network, no cache, offline clone — the seed always answers.
+ * - `promote()` copies cache → seed when the committed baseline should advance.
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const SOURCE_URL = 'https://raw.githubusercontent.com/disposable-email-domains/disposable-email-domains/main/disposable_email_blocklist.conf';
+
+// The committed baseline, beside the other email data files.
+const SEED_PATH = path.join(__dirname, 'data', 'disposable-domains.json');
+
+// The gitignored refresh cache. The package root is four levels up from here in
+// BOTH trees — src/manager/libraries/email/ and the staged dist/manager/libraries/email/.
+const CACHE_PATH = path.join(__dirname, '..', '..', '..', '..', '.cache', 'email', 'disposable-domains.json');
+
+/**
+ * The active domain list: the refresh cache if usable, else the committed seed.
+ *
+ * @returns {string[]}
+ */
+function load() {
+  try {
+    const cached = jetpack.read(CACHE_PATH, 'json');
+    if (Array.isArray(cached) && cached.length > 0) {
+      return cached;
+    }
+  } catch (e) {
+    // A truncated/corrupt cache (interrupted write) is an expected external
+    // condition, not a bug — never fail an email lookup over it, use the seed.
+  }
+
+  return require(SEED_PATH);
+}
+
+/**
+ * Fetch the upstream list and write it to the gitignored cache. Never writes the seed.
+ *
+ * @returns {Promise<{ path: string, count: number }>}
+ */
+async function refresh() {
+  const response = await fetch(SOURCE_URL);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch: ${response.status} ${response.statusText}`);
+  }
+
+  const text = await response.text();
+  const domains = text
+    .trim()
+    .split('\n')
+    .map(d => d.trim().toLowerCase())
+    .filter(Boolean);
+
+  const unique = [...new Set(domains)].sort();
+
+  jetpack.write(CACHE_PATH, `${JSON.stringify(unique, null, 2)}\n`);
+
+  return { path: CACHE_PATH, count: unique.length };
+}
+
+/**
+ * Advance the committed baseline: copy the refresh cache over the seed.
+ * Deliberate only — nothing calls this automatically.
+ *
+ * @returns {{ path: string, count: number }}
+ */
+function promote() {
+  const cached = jetpack.read(CACHE_PATH, 'json');
+
+  if (!Array.isArray(cached) || cached.length === 0) {
+    throw new Error(`No usable refresh cache at ${CACHE_PATH} — run \`node scripts/update-disposable-domains.js\` first.`);
+  }
+
+  jetpack.write(SEED_PATH, `${JSON.stringify(cached, null, 2)}\n`);
+
+  return { path: SEED_PATH, count: cached.length };
+}
+
+module.exports = { SOURCE_URL, SEED_PATH, CACHE_PATH, load, refresh, promote };

package/dist/manager/libraries/email/generators/lib/filter.js

@@ -0,0 +1,179 @@
+/**
+ * Brand-fit filter for newsletter sources.
+ *
+ * Given a pool of raw newsletter sources and a brand's `marketing.newsletter.content`
+ * config, asks an AI to score each source for brand fit (0-10), then drops
+ * anything below the threshold. This prevents off-topic sources from leaking
+ * into the structure generator.
+ *
+ * Fit scoring is a single AI call (one round-trip for the whole pool), using
+ * a small/cheap model by default.
+ */
+const DEFAULT_MODELS = {
+  openai: 'gpt-5.4-mini',
+  anthropic: 'claude-opus',
+  'claude-code': 'claude-opus-4-7',
+};
+
+const DEFAULT_THRESHOLD = 6; // 0-10 scale; only sources scoring >= this make it through
+
+const FILTER_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['scores'],
+  properties: {
+    scores: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'fit', 'reason'],
+        properties: {
+          id:     { type: 'string' },
+          fit:    { type: 'integer', minimum: 0, maximum: 10 },
+          reason: { type: 'string' },
+        },
+      },
+    },
+  },
+};
+
+/**
+ * Score sources for brand fit and return only the ones above threshold.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.sources - raw source records
+ * @param {object} args.brand - { name, description }
+ * @param {object} args.newsletterConfig
+ * @param {object} args.ai
+ * @param {object} args.ctx
+ * @param {number} [args.threshold] - override fit threshold (default 6)
+ * @returns {Promise<{kept: object[], scores: object[]}>}
+ */
+async function filterSources({ sources, brand, newsletterConfig, ai, ctx, threshold }) {
+  if (!sources?.length) {
+    return { kept: [], scores: [] };
+  }
+
+  const t = typeof threshold === 'number' ? threshold : DEFAULT_THRESHOLD;
+  const provider = newsletterConfig?.provider?.filter || 'openai';
+  const model = newsletterConfig?.model?.filter || DEFAULT_MODELS[provider];
+  const startTime = Date.now();
+
+  ctx.log(`Newsletter filter: scoring ${sources.length} sources (provider=${provider} threshold=${t})`);
+
+  const systemPrompt = buildSystemPrompt(brand, newsletterConfig);
+  const userPrompt = buildUserPrompt(sources);
+
+  let scores = [];
+  let aiResult = null;
+
+  try {
+    aiResult = await ai.request({
+      provider,
+      model,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user',   content: userPrompt },
+      ],
+      response: 'json',
+      schema: FILTER_SCHEMA,
+      maxTokens: 8000,
+      temperature: 0.2,
+      moderate: false,
+    });
+
+    scores = aiResult.content?.scores || [];
+
+    if (!scores.length) {
+      ctx.log(`Newsletter filter: AI returned no scores. Raw content: ${JSON.stringify(aiResult.content)?.slice(0, 500)}`);
+    }
+  } catch (e) {
+    ctx.error(`Filter failed: ${e.message}. Falling back to no filtering.`);
+    return {
+      kept: sources,
+      scores: [],
+      meta: { provider, model, durationMs: Date.now() - startTime, error: e.message },
+    };
+  }
+
+  // Index scores by source id
+  const scoreById = new Map(scores.map((s) => [s.id, s]));
+
+  // Log all scores up front for visibility (sorted highest fit first)
+  const sortedScores = [...scores].sort((a, b) => b.fit - a.fit);
+  for (const s of sortedScores) {
+    ctx.log(`  fit=${s.fit} ${s.id} — ${s.reason}`);
+  }
+
+  // Keep sources scoring >= threshold; preserve original order
+  const kept = sources.filter((s) => {
+    const score = scoreById.get(s.id);
+    return score && score.fit >= t;
+  });
+
+  ctx.log(`Newsletter filter: kept ${kept.length}/${sources.length} sources (threshold=${t})`);
+
+  return {
+    kept,
+    scores,
+    meta: {
+      provider,
+      model,
+      durationMs: Date.now() - startTime,
+      threshold: t,
+      sourcesIn: sources.length,
+      sourcesKept: kept.length,
+      tokens: aiResult?.tokens || null,
+    },
+  };
+}
+
+function buildSystemPrompt(brand, config) {
+  const tone = config?.tone || 'professional';
+  const instructions = config?.instructions || '';
+  const categories = (config?.categories || []).join(', ') || 'general';
+
+  return [
+    `You evaluate which third-party newsletter content is on-brand for ${brand?.name || 'a brand'} to feature in their own newsletter.`,
+    brand?.tagline     ? `\n${brand.name} tagline: ${brand.tagline}`         : '',
+    brand?.description ? `\n${brand.name} description: ${brand.description}` : '',
+    instructions       ? `\nNewsletter focus: ${instructions}`               : '',
+    `\nContent categories this brand wants: ${categories}`,
+    `\nIntended tone: ${tone}`,
+    '',
+    'The user will give you a JSON array of source articles (forwarded newsletter excerpts).',
+    'For EACH source, judge whether the topic fits this brand\'s audience and assign a fit score 0–10:',
+    '  10 = directly about this brand\'s domain — their audience definitely cares',
+    '   7 = adjacent/related topic — plausible audience interest',
+    '   4 = tangentially relevant',
+    '   0 = off-topic — wrong audience or wrong domain',
+    '',
+    'Be honest and discerning — off-topic content should score low even if interesting.',
+    'Fit is about whether THIS BRAND\'S audience would care, not about the article\'s general quality.',
+    '',
+    'Output schema: { "scores": [{ "id": string, "fit": integer, "reason": string }] }',
+    'RULES:',
+    '  • Use the EXACT id value from each input source (e.g. "-OsTDh6dAWqUQrcq7B3T"). Do NOT invent or rename ids.',
+    '  • Return one entry per input source — same count, same ids.',
+    '  • reason: one short sentence (≤20 words).',
+  ].filter(Boolean).join('\n');
+}
+
+function buildUserPrompt(sources) {
+  // Hand the AI a JSON array — eliminates ambiguity about what the id is
+  const payload = sources.map((s) => {
+    const raw = s.source || {};
+    return {
+      id: s.id,
+      from: raw.from || s.from || '',
+      subject: raw.subject || s.subject || '',
+      categories: s.categories || (s.category ? [s.category] : []),
+      preview: (raw.content || '').slice(0, 400).replace(/\s+/g, ' '),
+    };
+  });
+
+  return `Score these ${sources.length} sources for brand fit. Return EXACTLY one score per source, using the "id" field verbatim from the input.\n\nInput sources:\n${JSON.stringify(payload, null, 2)}`;
+}
+
+module.exports = { filterSources, FILTER_SCHEMA, DEFAULT_THRESHOLD };

package/dist/manager/libraries/email/generators/lib/image-host.js

@@ -0,0 +1,344 @@
+/**
+ * Asset host — uploads newsletter assets (per-section PNGs + the final
+ * rendered `newsletter.html`) to the public `itw-creative-works/newsletter-assets`
+ * GitHub repo as a single atomic commit.
+ *
+ * Each brand pushes to its own branch (branch name = brandId). This
+ * eliminates race conditions — 30+ brands can upload concurrently with
+ * zero contention. The `main` branch hosts only the viewer page
+ * (index.html on GitHub Pages) for browser-renderable previews.
+ *
+ * Returns publicly resolvable URLs:
+ *   - Image URLs (`raw.githubusercontent.com/{owner}/{repo}/{brandId}/...`):
+ *     embedded in the HTML via <img src=...>
+ *   - HTML URL (`raw.githubusercontent.com`): download link for manual paste
+ *   - Preview URL (`*.github.io/?path=...`): viewer page that fetches and
+ *     renders the newsletter HTML in-browser
+ *
+ * Public-safety guarantees baked in:
+ *   - Only accepts PNG buffers for images — verified by magic-byte check
+ *   - HTML must be a non-empty string (no buffers, no other types)
+ *   - Path validated against a strict allowlist regex per file kind
+ *   - Repo owner hardcoded (no env override) so a misconfigured caller
+ *     can't redirect uploads elsewhere
+ *   - One atomic commit per newsletter (Git Trees API)
+ *
+ * Pattern lifted from src/manager/routes/admin/post/post.js#commitAll —
+ * keep them in sync if the GitHub upload conventions change.
+ */
+const { Octokit } = require('@octokit/rest');
+const env = require('../../../env.js');
+
+const REPO_OWNER = 'itw-creative-works';
+const REPO_NAME  = 'newsletter-assets';
+
+// When true, asset URLs use the parent CDN (cdn.{parentDomain}/newsletters/...)
+// instead of raw.githubusercontent.com. Requires a Cloudflare redirect rule
+// on the CDN domain that maps /newsletters/* to raw.githubusercontent.com.
+// Set to false to revert to direct GitHub URLs.
+const USE_CDN_URLS = true;
+
+const PAGES_BASE = `https://${REPO_OWNER}.github.io/${REPO_NAME}`;
+
+// Fallback RAW_BASE for callers that don't have a brand context
+const RAW_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main`;
+
+// `content/{campaignId}/section-N.png` — brand is the branch, not the path
+const CONTENT_DIR = 'content';
+const IMAGE_PATH_REGEX = /^content\/[A-Za-z0-9_-]+\/section-\d+\.png$/;
+const HTML_PATH_REGEX  = /^content\/[A-Za-z0-9_-]+\/newsletter\.html$/;
+const MARKDOWN_PATH_REGEX = /^content\/[A-Za-z0-9_-]+\/newsletter\.md$/;
+const SUMMARY_PATH_REGEX  = /^content\/[A-Za-z0-9_-]+\/summary\.md$/;
+
+// PNG magic bytes: 89 50 4E 47 0D 0A 1A 0A
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * Upload newsletter assets (PNGs + optional HTML) as a single atomic commit.
+ *
+ * @param {object} args
+ * @param {Array<{png: Buffer}>} [args.images] - section images (only `png` is used).
+ *                                                Optional — pass an empty array or omit if
+ *                                                you only want to upload the HTML (rare).
+ * @param {string} [args.html] - The final rendered newsletter HTML. Uploaded as
+ *                                `content/{campaignId}/newsletter.html`.
+ * @param {string} [args.markdown] - Programmatic markdown view of the newsletter.
+ *                                    Uploaded as `content/{campaignId}/newsletter.md`.
+ * @param {string} [args.summary] - Short editorial recap (2-3 sentences). Uploaded
+ *                                   as `content/{campaignId}/summary.md`.
+ * @param {string} args.brandId - lowercase brand slug (e.g. 'somiibo')
+ * @param {string} args.campaignId - Consumer-side `marketing-campaigns/{id}` Firestore doc ID.
+ *                                   Folder names use this verbatim — stable forever.
+ * @param {string} [args.subject] - Newsletter subject. Embedded in the commit message so
+ *                                  `git log` reads as a human-browseable history.
+ * @param {string} [args.commitMessage] - Full override of the default commit message
+ * @param {string} [args.cdnBase] - CDN base URL (e.g. 'https://cdn.itwcreativeworks.com/newsletters').
+ *                                  When provided and USE_CDN_URLS is true, asset URLs use this
+ *                                  instead of raw.githubusercontent.com.
+ * @param {string} [args.token] - GitHub token (defaults to env.get('GH_TOKEN'))
+ * @param {object} [args.ctx] - logger
+ * @returns {Promise<{ urls: string[], paths: string[], htmlUrl?: string, htmlPath?: string, previewUrl?: string, folderUrl: string, commitSha: string }>}
+ */
+async function uploadAssets({ images, html, markdown, summary, brandId, campaignId, subject, commitMessage, cdnBase, token, ctx }) {
+  const hasImages = Array.isArray(images) && images.length > 0;
+  const hasHtml = typeof html === 'string' && html.length > 0;
+  const hasMarkdown = typeof markdown === 'string' && markdown.length > 0;
+  const hasSummary = typeof summary === 'string' && summary.length > 0;
+
+  if (!hasImages && !hasHtml && !hasMarkdown && !hasSummary) {
+    throw new Error('image-host: at least one of images[] / html / markdown / summary must be provided');
+  }
+
+  validateBrandId(brandId);
+  validateCampaignId(campaignId);
+
+  const githubToken = token || env.get('GH_TOKEN');
+
+  if (!githubToken) {
+    throw new Error('image-host: GH_TOKEN env var (or token arg) is required');
+  }
+
+  const log = (msg) => ctx?.log ? ctx.log(`image-host: ${msg}`) : null;
+
+  // Brand branch — each brand gets its own branch, zero cross-brand contention
+  const branch = brandId;
+  const gitRawBase = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/${branch}`;
+
+  // CDN URLs: cdn.{parentDomain}/newsletters/{brandId}/content/{campaignId}/...
+  // The CDN redirect maps /newsletters/{brandId}/* → raw.githubusercontent.com/{brandId}/*
+  const assetBase = (USE_CDN_URLS && cdnBase) ? `${cdnBase}/${brandId}` : gitRawBase;
+
+  // 1. Build the list of files to commit. Validate each before we touch GitHub.
+  const files = [];
+
+  if (hasImages) {
+    for (let i = 0; i < images.length; i++) {
+      const img = images[i];
+      const path = `${CONTENT_DIR}/${campaignId}/section-${i + 1}.png`;
+
+      if (!IMAGE_PATH_REGEX.test(path)) {
+        throw new Error(`image-host: refusing to upload — invalid image path "${path}"`);
+      }
+
+      if (!Buffer.isBuffer(img.png)) {
+        throw new Error(`image-host: section ${i + 1} png is not a Buffer (got ${typeof img.png})`);
+      }
+
+      if (!img.png.slice(0, 8).equals(PNG_MAGIC)) {
+        throw new Error(`image-host: section ${i + 1} buffer is not a valid PNG (magic bytes mismatch)`);
+      }
+
+      files.push({
+        path,
+        contentBase64: img.png.toString('base64'),
+        kind: 'image',
+      });
+    }
+  }
+
+  if (hasHtml) {
+    const path = `${CONTENT_DIR}/${campaignId}/newsletter.html`;
+
+    if (!HTML_PATH_REGEX.test(path)) {
+      throw new Error(`image-host: refusing to upload — invalid html path "${path}"`);
+    }
+
+    files.push({
+      path,
+      contentBase64: Buffer.from(html, 'utf8').toString('base64'),
+      kind: 'html',
+    });
+  }
+
+  if (hasMarkdown) {
+    const path = `${CONTENT_DIR}/${campaignId}/newsletter.md`;
+
+    if (!MARKDOWN_PATH_REGEX.test(path)) {
+      throw new Error(`image-host: refusing to upload — invalid markdown path "${path}"`);
+    }
+
+    files.push({
+      path,
+      contentBase64: Buffer.from(markdown, 'utf8').toString('base64'),
+      kind: 'markdown',
+    });
+  }
+
+  if (hasSummary) {
+    const path = `${CONTENT_DIR}/${campaignId}/summary.md`;
+
+    if (!SUMMARY_PATH_REGEX.test(path)) {
+      throw new Error(`image-host: refusing to upload — invalid summary path "${path}"`);
+    }
+
+    files.push({
+      path,
+      contentBase64: Buffer.from(summary, 'utf8').toString('base64'),
+      kind: 'summary',
+    });
+  }
+
+  const imageCount = files.filter((f) => f.kind === 'image').length;
+  const fileSummary = [
+    imageCount ? `${imageCount} PNG${imageCount === 1 ? '' : 's'}` : null,
+    hasHtml ? 'newsletter.html' : null,
+    hasMarkdown ? 'newsletter.md' : null,
+    hasSummary ? 'summary.md' : null,
+  ].filter(Boolean).join(' + ');
+
+  log(`uploading ${fileSummary} to ${REPO_OWNER}/${REPO_NAME}:${branch} → ${CONTENT_DIR}/${campaignId}/`);
+
+  const octokit = new Octokit({ auth: githubToken });
+
+  // 2. Ensure the brand branch exists. New branches start empty (orphan
+  //    commit with an empty tree) — no files from main, no shared history.
+  let branchSha;
+  try {
+    const { data } = await octokit.rest.git.getRef({ owner: REPO_OWNER, repo: REPO_NAME, ref: `heads/${branch}` });
+    branchSha = data.object.sha;
+  } catch (e) {
+    if (e.status === 404) {
+      // Create an empty tree → orphan commit → brand branch
+      const { data: emptyTree } = await octokit.rest.git.createTree({
+        owner: REPO_OWNER, repo: REPO_NAME, tree: [],
+      });
+      const { data: orphanCommit } = await octokit.rest.git.createCommit({
+        owner: REPO_OWNER, repo: REPO_NAME,
+        message: `Initialize ${branch} branch`,
+        tree: emptyTree.sha,
+        parents: [],
+      });
+      await octokit.rest.git.createRef({
+        owner: REPO_OWNER, repo: REPO_NAME,
+        ref: `refs/heads/${branch}`,
+        sha: orphanCommit.sha,
+      });
+      branchSha = orphanCommit.sha;
+      log(`created empty branch "${branch}"`);
+    } else {
+      throw e;
+    }
+  }
+
+  // 3. Create blobs (content-addressed — safe to reuse if we ever add retries)
+  const treeItems = [];
+
+  for (const file of files) {
+    const { data: blob } = await octokit.rest.git.createBlob({
+      owner: REPO_OWNER,
+      repo: REPO_NAME,
+      content: file.contentBase64,
+      encoding: 'base64',
+    });
+
+    treeItems.push({
+      path: file.path,
+      mode: '100644',
+      type: 'blob',
+      sha: blob.sha,
+    });
+  }
+
+  // 4. Commit + push with retry. Per-brand branches make ref races effectively
+  //    impossible (one writer per branch), but keep a defensive retry in case
+  //    the same brand ever uploads concurrently or GitHub returns a stale ref.
+  const defaultSubject = subject ? subject.trim() : `${files.length} newsletter asset${files.length === 1 ? '' : 's'}`;
+  const message = commitMessage || `[${brandId}] ${campaignId} — ${defaultSubject}`;
+  const MAX_RETRIES = 3;
+  let newCommit;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    const { data: refData } = await octokit.rest.git.getRef({
+      owner: REPO_OWNER, repo: REPO_NAME, ref: `heads/${branch}`,
+    });
+    const tipSha = refData.object.sha;
+
+    const { data: baseCommit } = await octokit.rest.git.getCommit({
+      owner: REPO_OWNER, repo: REPO_NAME, commit_sha: tipSha,
+    });
+
+    const { data: newTree } = await octokit.rest.git.createTree({
+      owner: REPO_OWNER, repo: REPO_NAME,
+      base_tree: baseCommit.tree.sha,
+      tree: treeItems,
+    });
+
+    newCommit = (await octokit.rest.git.createCommit({
+      owner: REPO_OWNER, repo: REPO_NAME,
+      message,
+      tree: newTree.sha,
+      parents: [tipSha],
+    })).data;
+
+    try {
+      await octokit.rest.git.updateRef({
+        owner: REPO_OWNER, repo: REPO_NAME,
+        ref: `heads/${branch}`,
+        sha: newCommit.sha,
+      });
+      break;
+    } catch (e) {
+      if (attempt < MAX_RETRIES && /fast.forward/i.test(e.message)) {
+        const jitter = 500 + Math.floor(Math.random() * 1500);
+        log(`updateRef race (attempt ${attempt}/${MAX_RETRIES}), retrying in ${jitter}ms...`);
+        await new Promise(r => setTimeout(r, jitter));
+        continue;
+      }
+      throw e;
+    }
+  }
+
+  // 7. Split the URL list by kind so callers can grab each independently.
+  const imageFiles = files.filter((f) => f.kind === 'image');
+  const htmlFile = files.find((f) => f.kind === 'html');
+  const markdownFile = files.find((f) => f.kind === 'markdown');
+  const summaryFile = files.find((f) => f.kind === 'summary');
+
+  const result = {
+    urls: imageFiles.map((f) => `${assetBase}/${f.path}`),
+    paths: imageFiles.map((f) => f.path),
+    folderUrl: `https://github.com/${REPO_OWNER}/${REPO_NAME}/tree/${branch}/${CONTENT_DIR}/${campaignId}`,
+    commitSha: newCommit.sha,
+  };
+
+  if (htmlFile) {
+    result.htmlUrl = `${assetBase}/${htmlFile.path}`;
+    result.htmlPath = htmlFile.path;
+    result.previewUrl = `${PAGES_BASE}/?path=${encodeURIComponent(htmlFile.path)}&branch=${encodeURIComponent(branch)}`;
+  }
+
+  if (markdownFile) {
+    result.markdownUrl = `${assetBase}/${markdownFile.path}`;
+    result.markdownPath = markdownFile.path;
+  }
+
+  if (summaryFile) {
+    result.summaryUrl = `${assetBase}/${summaryFile.path}`;
+    result.summaryPath = summaryFile.path;
+  }
+
+  log(`committed ${newCommit.sha.slice(0, 7)} to ${branch} — folder: ${result.folderUrl}`);
+
+  return result;
+}
+
+function validateBrandId(brandId) {
+  if (!brandId || !/^[a-z0-9-]+$/.test(brandId)) {
+    throw new Error(`image-host: brandId must be lowercase alphanumeric+hyphens (got "${brandId}")`);
+  }
+}
+
+function validateCampaignId(campaignId) {
+  if (!campaignId || !/^[A-Za-z0-9_-]+$/.test(campaignId)) {
+    throw new Error(`image-host: campaignId must be alphanumeric/_/- (got "${campaignId}")`);
+  }
+}
+
+module.exports = {
+  uploadAssets,
+  USE_CDN_URLS,
+  REPO_OWNER,
+  REPO_NAME,
+  RAW_BASE,
+  PAGES_BASE,
+};