backend-manager 5.0.153 → 5.0.156

package/src/manager/events/auth/on-create.js

@@ -14,7 +14,10 @@ const RETRY_DELAY_MS = 1000;
  * - Batch writes user doc + increment count atomically
  * - Retries up to 3 times with exponential backoff on failure
  *
- * Non-critical work (name inference, welcome emails, marketing contact) is handled
+ * If the user signed up via a provider (Google, Facebook, etc.), their display name
+ * is extracted and stored as personal.name.first/last on the user doc.
+ *
+ * Non-critical work (welcome emails, marketing contact) is handled
  * by the user/signup endpoint, which the frontend calls after account creation.
  */
 module.exports = async ({ Manager, assistant, user, context, libraries }) => {
@@ -42,12 +45,20 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
     return;
   }
 
+  // Extract name from provider data (e.g., Google, Facebook, GitHub)
+  const providerName = extractProviderName(user);
+
+  assistant.log(`onCreate: Inferred name from provider:`, providerName);
+
   // Create user record using Manager.User() helper
   const userRecord = Manager.User({
     auth: {
       uid: user.uid,
       email: user.email,
     },
+    personal: providerName ? {
+      name: providerName,
+    } : undefined,
   }).properties;
 
   // Add metadata tag (merge into existing metadata to preserve metadata.created from User schema)
@@ -81,6 +92,30 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   }
 };
 
+/**
+ * Extract first/last name from provider data (Google, Facebook, GitHub, etc.)
+ * Returns { first, last } or null if no name found
+ */
+function extractProviderName(user) {
+  // Try provider-specific displayName first, then top-level displayName
+  const displayName = user.providerData?.find(p =>
+    p.providerId !== 'password'
+    && p.providerId !== 'anonymous'
+    && p.displayName
+  )?.displayName || user.displayName;
+
+  if (!displayName) {
+    return null;
+  }
+
+  const parts = displayName.trim().split(/\s+/);
+
+  return {
+    first: parts[0] || null,
+    last: parts.slice(1).join(' ') || null,
+  };
+}
+
 /**
  * Retry a function up to maxRetries times with exponential backoff
  */

package/src/manager/libraries/email/constants.js

@@ -122,10 +122,10 @@ function errorWithCode(message, code) {
   return err;
 }
 
-// Master field dictionary — the key IS the field name used in both providers.
+// Master field dictionary — SSOT for all marketing custom fields.
 //
-// SendGrid: key is matched against custom field names at runtime (fetched + cached).
-// Beehiiv: key is used directly as the custom field name.
+// SendGrid: `display` is the custom field name (created by OMEGA, resolved by ID at runtime).
+// Beehiiv: `display` is the custom field name (matched by display name).
 //
 // Source types:
 //   'user'     — read from user doc via _.get(userDoc, path)
@@ -133,37 +133,86 @@ function errorWithCode(message, code) {
 //   'config'   — read from Manager.config via _.get(config, path)
 //
 // To add a new tracked marketing field:
-//   1. Add an entry here — the key becomes the field name in both providers
-//   2. Add matching entry in OMEGA's src/lib/bem-fields.js (name, display, type)
-//   3. Run OMEGA: npm start -- --service=sendgrid,beehiiv --brand=X
-//   4. BEM resolves field IDs at runtime — no provider code changes needed
-//   5. If 'resolved' source, ensure resolveFieldValues() computes it
+//   1. Add an entry here (key, display, source, path, type)
+//   2. Run OMEGA: npm start -- --service=sendgrid,beehiiv --brand=X
+//   3. BEM resolves field IDs at runtime — no provider code changes needed
+//   4. If 'resolved' source, ensure resolveFieldValues() computes it
+//
+// Flags:
+//   skip — Array of provider names to skip field creation for (e.g., ['sendgrid'])
+//          SendGrid has first_name/last_name as built-in contact fields
+//          Beehiiv needs them created as custom fields (preset templates)
 const FIELDS = {
   // Brand
-  brand_id:                              { source: 'config', path: 'brand.id', type: 'text' },
+  brand_id:                              { display: 'Brand ID', source: 'config', path: 'brand.id', type: 'text' },
 
   // User identity
-  user_auth_uid:                         { source: 'user', path: 'auth.uid', type: 'text' },
-  user_personal_company:                 { source: 'user', path: 'personal.company.name', type: 'text' },
-  user_personal_country:                 { source: 'user', path: 'personal.location.country', type: 'text' },
-  user_metadata_signup_date:             { source: 'user', path: 'metadata.created.timestamp', type: 'date' },
-  user_metadata_last_activity:           { source: 'user', path: 'metadata.updated.timestamp', type: 'date' },
+  user_auth_uid:                         { display: 'User UID', source: 'user', path: 'auth.uid', type: 'text' },
+  user_personal_name_first:              { display: 'First Name', source: 'user', path: 'personal.name.first', type: 'text', skip: ['sendgrid'] },
+  user_personal_name_last:               { display: 'Last Name', source: 'user', path: 'personal.name.last', type: 'text', skip: ['sendgrid'] },
+  user_personal_company:                 { display: 'Company', source: 'user', path: 'personal.company.name', type: 'text' },
+  user_personal_country:                 { display: 'Country', source: 'user', path: 'personal.location.country', type: 'text', skip: ['beehiiv'] },
+  user_metadata_signup_date:             { display: 'Signup Date', source: 'user', path: 'metadata.created.timestamp', type: 'date' },
+  user_metadata_last_activity:           { display: 'Last Activity', source: 'user', path: 'metadata.updated.timestamp', type: 'date' },
 
   // Subscription
-  user_subscription_plan:                { source: 'resolved', path: 'plan', type: 'text' },
-  user_subscription_status:              { source: 'resolved', path: 'status', type: 'text' },
-  user_subscription_trialing:            { source: 'resolved', path: 'trialing', type: 'text' },
-  user_subscription_cancelling:          { source: 'resolved', path: 'cancelling', type: 'text' },
-  user_subscription_ever_paid:           { source: 'resolved', path: 'everPaid', type: 'text' },
-  user_subscription_payment_processor:   { source: 'user', path: 'subscription.payment.processor', type: 'text' },
-  user_subscription_payment_frequency:   { source: 'user', path: 'subscription.payment.frequency', type: 'text' },
-  user_subscription_payment_price:       { source: 'user', path: 'subscription.payment.price', type: 'number' },
-  user_subscription_payment_last_date:   { source: 'user', path: 'subscription.payment.updatedBy.date.timestamp', type: 'date' },
+  user_subscription_plan:                { display: 'Plan', source: 'resolved', path: 'plan', type: 'text' },
+  user_subscription_status:              { display: 'Status', source: 'resolved', path: 'status', type: 'text' },
+  user_subscription_trialing:            { display: 'Trialing', source: 'resolved', path: 'trialing', type: 'text' },
+  user_subscription_cancelling:          { display: 'Cancelling', source: 'resolved', path: 'cancelling', type: 'text' },
+  user_subscription_ever_paid:           { display: 'Ever Paid', source: 'resolved', path: 'everPaid', type: 'text' },
+  user_subscription_payment_processor:   { display: 'Payment Processor', source: 'user', path: 'subscription.payment.processor', type: 'text' },
+  user_subscription_payment_frequency:   { display: 'Payment Frequency', source: 'user', path: 'subscription.payment.frequency', type: 'text' },
+  user_subscription_payment_price:       { display: 'Payment Price', source: 'user', path: 'subscription.payment.price', type: 'number' },
+  user_subscription_payment_last_date:   { display: 'Last Payment Date', source: 'user', path: 'subscription.payment.updatedBy.date.timestamp', type: 'date' },
 
   // Attribution
-  user_attribution_utm_source:           { source: 'user', path: 'attribution.utm.tags.utm_source', type: 'text' },
+  user_attribution_utm_source:           { display: 'UTM Source', source: 'user', path: 'attribution.utm.tags.utm_source', type: 'text', skip: ['beehiiv'] },
 };
 
+// Master segment dictionary — SSOT for all marketing segments.
+//
+// Segments are created in each provider by OMEGA (like custom fields).
+// BEM references them by key. Provider-specific IDs are resolved at runtime.
+//
+// Condition types:
+//   'field'      — custom field condition (uses FIELDS above)
+//   'engagement' — provider built-in engagement tracking (opens, clicks)
+//
+// To add a new segment:
+//   1. Add an entry here
+//   2. Add matching entry in OMEGA's src/lib/bem-segments.js
+//   3. Run OMEGA: npm start -- --service=sendgrid,beehiiv --brand=X
+//
+// Providers:
+//   skip — Array of provider names to skip segment creation for
+//          (e.g., engagement segments may not be supported on all providers)
+const SEGMENTS = {
+  // Subscription
+  subscription_free:          { display: 'Free Users', conditions: [{ field: 'user_subscription_plan', op: '==', value: 'basic' }] },
+  subscription_paid:          { display: 'Paid Users', conditions: [{ field: 'user_subscription_plan', op: '!=', value: 'basic' }, { field: 'user_subscription_status', op: '==', value: 'active' }] },
+  subscription_trialing:      { display: 'Trialing', conditions: [{ field: 'user_subscription_trialing', op: '==', value: 'true' }] },
+  subscription_cancelling:    { display: 'Cancelling', conditions: [{ field: 'user_subscription_cancelling', op: '==', value: 'true' }] },
+  subscription_suspended:     { display: 'Suspended', conditions: [{ field: 'user_subscription_status', op: '==', value: 'suspended' }] },
+  subscription_cancelled:     { display: 'Cancelled', conditions: [{ field: 'user_subscription_status', op: '==', value: 'cancelled' }] },
+  subscription_churned:       { display: 'Churned (Paid → Cancelled)', conditions: [{ field: 'user_subscription_ever_paid', op: '==', value: 'true' }, { field: 'user_subscription_status', op: '==', value: 'cancelled' }] },
+  subscription_ever_paid:     { display: 'Ever Paid', conditions: [{ field: 'user_subscription_ever_paid', op: '==', value: 'true' }] },
+  subscription_never_paid:    { display: 'Never Paid', conditions: [{ field: 'user_subscription_ever_paid', op: '!=', value: 'true' }] },
+
+  // Lifecycle (time since signup)
+  lifecycle_7d:               { display: 'Signed Up Last 7 Days', conditions: [{ field: 'user_metadata_signup_date', op: 'within', value: '7d' }] },
+  lifecycle_30d:              { display: 'Signed Up Last 30 Days', conditions: [{ field: 'user_metadata_signup_date', op: 'within', value: '30d' }] },
+  lifecycle_90d:              { display: 'Signed Up Last 90 Days', conditions: [{ field: 'user_metadata_signup_date', op: 'within', value: '90d' }] },
+  lifecycle_6m:               { display: 'Signed Up Last 6 Months', conditions: [{ field: 'user_metadata_signup_date', op: 'within', value: '180d' }] },
+  lifecycle_1y:               { display: 'Signed Up Last 1 Year', conditions: [{ field: 'user_metadata_signup_date', op: 'within', value: '365d' }] },
+
+  // Engagement (provider built-in open/click tracking)
+  engagement_active_30d:      { display: 'Engaged Last 30 Days', conditions: [{ type: 'engagement', op: 'opened_or_clicked', value: '30d' }] },
+  engagement_active_90d:      { display: 'Engaged Last 90 Days', conditions: [{ type: 'engagement', op: 'opened_or_clicked', value: '90d' }] },
+  engagement_inactive_90d:    { display: 'Inactive 90+ Days', conditions: [{ type: 'engagement', op: 'not_opened', value: '90d' }] },
+  engagement_inactive_5m:     { display: 'Inactive 5+ Months', conditions: [{ type: 'engagement', op: 'not_opened', value: '150d' }] },
+  engagement_inactive_6m:     { display: 'Inactive 6+ Months', conditions: [{ type: 'engagement', op: 'not_opened', value: '180d' }] },
+};
 
 /**
  * Resolve all field values from a user doc + config.
@@ -233,6 +282,7 @@ module.exports = {
   GROUPS,
   SENDERS,
   FIELDS,
+  SEGMENTS,
   SEND_AT_LIMIT,
   sanitizeImagesForEmail,
   encode,

package/src/manager/libraries/email/index.js

@@ -104,7 +104,17 @@ Email.prototype.remove = function (email) {
 };
 
 /**
- * Cancel a scheduled marketing campaign.
+ * Create and optionally schedule a marketing campaign across enabled providers.
+ *
+ * @param {object} settings - See Marketing.sendCampaign() for full options
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
+ */
+Email.prototype.sendCampaign = function (settings) {
+  return this._marketing.sendCampaign(settings);
+};
+
+/**
+ * Cancel a scheduled marketing campaign (SendGrid only).
  *
  * @param {string} campaignId - Single Send ID
  * @returns {{ success: boolean, error?: string }}
@@ -114,7 +124,7 @@ Email.prototype.cancelCampaign = function (campaignId) {
 };
 
 /**
- * Get a marketing campaign by ID.
+ * Get a marketing campaign by ID (SendGrid only).
  *
  * @param {string} campaignId - Single Send ID
  * @returns {object|null}
@@ -124,7 +134,7 @@ Email.prototype.getCampaign = function (campaignId) {
 };
 
 /**
- * List marketing campaigns.
+ * List marketing campaigns (SendGrid only).
  *
  * @param {object} [options] - { status: 'draft' | 'scheduled' | 'triggered' }
  * @returns {Array<object>}

package/src/manager/libraries/email/marketing/index.js

@@ -24,8 +24,11 @@
  * - Campaign cron jobs (send campaigns)
  */
 const _ = require('lodash');
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt({ html: true, breaks: true, linkify: true });
 
 const { TEMPLATES, GROUPS, SENDERS } = require('../constants.js');
+const { tagLinks } = require('../utm.js');
 const sendgridProvider = require('../providers/sendgrid.js');
 const beehiivProvider = require('../providers/beehiiv.js');
 
@@ -235,29 +238,120 @@ Marketing.prototype.remove = async function (email) {
 };
 
 /**
- * Create and optionally schedule a marketing campaign (SendGrid Single Send).
+ * Create and optionally schedule a marketing campaign across enabled providers.
+ *
+ * Unified interface — each provider handles what it supports:
+ *   SendGrid: Single Send with lists, segments, excludes, templates
+ *   Beehiiv:  Post with segments, HTML content, scheduling
  *
  * @param {object} settings
- * @param {string} settings.name - Campaign name
- * @param {string} settings.subject - Email subject
+ * @param {string} settings.name - Campaign name (internal, used as title for Beehiiv)
+ * @param {string} settings.subject - Email subject line
+ * @param {string} [settings.preheader] - Email preview text
  * @param {string} [settings.template] - Template shortcut or SendGrid template ID
+ * @param {string} [settings.content] - Markdown content (converted to HTML per provider)
+ * @param {object} [settings.data] - Dynamic template variables (SendGrid only)
  * @param {string} [settings.sender] - Sender category ('marketing', 'newsletter', etc.)
- * @param {Array<string>} [settings.segments] - Segment IDs to target
- * @param {Array<string>} [settings.lists] - List IDs to target
- * @param {boolean} [settings.all] - Target all contacts
- * @param {string|number} [settings.sendAt] - ISO datetime or 'now' to schedule immediately
- * @param {Array<string>} [settings.categories] - Email categories
- * @returns {{ success: boolean, id?: string, scheduled?: boolean, error?: string }}
+ * @param {Array<string>} [settings.lists] - SendGrid list IDs (defaults to brand list)
+ * @param {Array<string>} [settings.segments] - Segment IDs to target (both providers)
+ * @param {Array<string>} [settings.excludeSegments] - Segment IDs to exclude (both providers)
+ * @param {boolean} [settings.all] - Target all contacts (SendGrid only)
+ * @param {string} [settings.sendAt] - ISO datetime, 'now', or omit for draft
+ * @param {string} [settings.group] - ASM unsubscribe group (SendGrid only)
+ * @param {Array<string>} [settings.categories] - Analytics categories (SendGrid only)
+ * @param {Array<string>} [settings.providers] - Override which providers to use
+ * @returns {{ sendgrid?: object, beehiiv?: object }}
  */
 Marketing.prototype.sendCampaign = async function (settings) {
   const self = this;
   const Manager = self.Manager;
   const assistant = self.assistant;
 
-  if (!self.providers.sendgrid) {
-    return { success: false, error: 'SendGrid not enabled' };
+  const useProviders = settings.providers || Object.keys(self.providers).filter(p => self.providers[p]);
+  const results = {};
+  const promises = [];
+
+  // Convert markdown content to HTML, then tag links with UTM params
+  const brand = Manager.config?.brand;
+  let contentHtml = settings.content ? md.render(settings.content) : '';
+
+  if (contentHtml) {
+    contentHtml = tagLinks(contentHtml, {
+      brandUrl: brand?.url,
+      brandId: brand?.id,
+      campaign: settings.name,
+      type: 'marketing',
+      utm: settings.utm,
+    });
+  }
+
+  // Resolve SSOT segment keys → provider segment IDs
+  const resolvedSegments = {};
+
+  if (useProviders.includes('sendgrid') && self.providers.sendgrid) {
+    const segmentIdMap = await sendgridProvider.resolveSegmentIds();
+
+    resolvedSegments.sendgrid = {
+      segments: (settings.segments || []).map(key => segmentIdMap[key] || key).filter(Boolean),
+      excludeSegments: (settings.excludeSegments || []).map(key => segmentIdMap[key] || key).filter(Boolean),
+    };
+  }
+
+  // Beehiiv: segment resolution will go here when Beehiiv segments are supported
+
+  assistant.log('Marketing.sendCampaign():', {
+    name: settings.name,
+    providers: useProviders,
+    sendAt: settings.sendAt || 'draft',
+  });
+
+  // --- SendGrid ---
+  if (useProviders.includes('sendgrid') && self.providers.sendgrid) {
+    const sgSettings = {
+      ...settings,
+      segments: resolvedSegments.sendgrid?.segments || [],
+      excludeSegments: resolvedSegments.sendgrid?.excludeSegments || [],
+    };
+
+    promises.push(
+      self._sendCampaignSendGrid(sgSettings, contentHtml)
+        .then((r) => { results.sendgrid = r; })
+        .catch((e) => { results.sendgrid = { success: false, error: e.message }; })
+    );
   }
 
+  // --- Beehiiv ---
+  if (useProviders.includes('beehiiv') && self.providers.beehiiv) {
+    promises.push(
+      beehiivProvider.createPost({
+        title: settings.name,
+        subject: settings.subject,
+        preheader: settings.preheader,
+        content: contentHtml,
+        sendAt: settings.sendAt,
+        segments: settings.segments,
+        excludeSegments: settings.excludeSegments,
+      })
+        .then((r) => { results.beehiiv = r; })
+        .catch((e) => { results.beehiiv = { success: false, error: e.message }; })
+    );
+  }
+
+  await Promise.all(promises);
+
+  assistant.log('Marketing.sendCampaign() results:', results);
+
+  return results;
+};
+
+/**
+ * SendGrid-specific campaign creation (Single Send + optional schedule).
+ * @private
+ */
+Marketing.prototype._sendCampaignSendGrid = async function (settings, contentHtml) {
+  const self = this;
+  const Manager = self.Manager;
+
   const templateId = TEMPLATES[settings.template] || settings.template || TEMPLATES['default'];
 
   // Resolve sender
@@ -295,61 +389,57 @@ Marketing.prototype.sendCampaign = async function (settings) {
     ...require('node-powertools').arrayify(settings.categories),
   ].filter(Boolean));
 
-  assistant.log('Marketing.sendCampaign():', { name: settings.name, sendTo, templateId });
-
   // Create the Single Send
   const createResult = await sendgridProvider.createSingleSend({
     name: settings.name,
     subject: settings.subject,
+    preheader: settings.preheader,
     templateId,
     from,
     sendTo,
+    excludeSegments: settings.excludeSegments,
     asmGroupId,
     categories,
+    dynamicTemplateData: {
+      ...settings.data,
+      ...(contentHtml ? { content: contentHtml } : {}),
+    },
   });
 
   if (!createResult.success) {
-    assistant.error('Marketing.sendCampaign() create failed:', createResult.error);
     return createResult;
   }
 
   // Schedule if sendAt is provided
-  if (settings.sendAt) {
-    const sendAt = settings.sendAt === 'now' ? 'now' : new Date(settings.sendAt).toISOString();
-
-    const scheduleResult = await sendgridProvider.scheduleSingleSend(createResult.id, sendAt);
-
-    if (!scheduleResult.success) {
-      assistant.error('Marketing.sendCampaign() schedule failed:', scheduleResult.error);
-      return { success: false, id: createResult.id, error: scheduleResult.error };
-    }
+  if (!settings.sendAt) {
+    return { success: true, id: createResult.id, scheduled: false };
+  }
 
-    assistant.log('Marketing.sendCampaign() scheduled:', createResult.id);
+  const sendAt = settings.sendAt === 'now' ? 'now' : new Date(settings.sendAt).toISOString();
+  const scheduleResult = await sendgridProvider.scheduleSingleSend(createResult.id, sendAt);
 
-    return { success: true, id: createResult.id, scheduled: true };
+  if (!scheduleResult.success) {
+    return { success: false, id: createResult.id, error: scheduleResult.error };
   }
 
-  // Created but not scheduled (draft)
-  return { success: true, id: createResult.id, scheduled: false };
+  return { success: true, id: createResult.id, scheduled: true };
 };
 
 /**
- * Cancel a scheduled campaign.
+ * Cancel a scheduled campaign (SendGrid only).
  *
  * @param {string} campaignId - Single Send ID
  * @returns {{ success: boolean, error?: string }}
  */
 Marketing.prototype.cancelCampaign = async function (campaignId) {
   const self = this;
-  const assistant = self.assistant;
-
-  assistant.log('Marketing.cancelCampaign():', campaignId);
+  self.assistant.log('Marketing.cancelCampaign():', campaignId);
 
   return sendgridProvider.cancelSingleSend(campaignId);
 };
 
 /**
- * Get a campaign by ID.
+ * Get a campaign by ID (SendGrid only).
  *
  * @param {string} campaignId - Single Send ID
  * @returns {object|null}
@@ -359,7 +449,7 @@ Marketing.prototype.getCampaign = async function (campaignId) {
 };
 
 /**
- * List campaigns with optional status filter.
+ * List campaigns with optional status filter (SendGrid only).
  *
  * @param {object} [options]
  * @param {string} [options.status] - Filter: draft, scheduled, triggered

package/src/manager/libraries/email/providers/beehiiv.js

@@ -5,7 +5,7 @@
  */
 const fetch = require('wonderful-fetch');
 const Manager = require('../../../index.js');
-const { resolveFieldValues } = require('../constants.js');
+const { FIELDS, resolveFieldValues } = require('../constants.js');
 
 const BASE_URL = 'https://api.beehiiv.com/v2';
 
@@ -255,7 +255,8 @@ async function removeContact(email) {
 
 /**
  * Build Beehiiv custom_fields array from a user doc.
- * Resolves all field values — the key IS the field name in Beehiiv.
+ * Resolves all field values, then maps to display names for Beehiiv.
+ * Beehiiv matches custom fields by their display name.
  *
  * @param {object} userDoc - User document from Firestore
  * @returns {Array<{name: string, value: string}>} Custom fields in Beehiiv format
@@ -265,15 +266,107 @@ function buildFields(userDoc) {
   const fields = [];
 
   for (const [name, value] of Object.entries(values)) {
-    fields.push({ name, value: String(value) });
+    const fieldConfig = FIELDS[name];
+    const displayName = fieldConfig?.display || name;
+    fields.push({ name: displayName, value: String(value) });
   }
 
   return fields;
 }
 
+// --- Campaigns (Posts) ---
+
+/**
+ * Create a Beehiiv post (their equivalent of a campaign/newsletter).
+ *
+ * @param {object} options
+ * @param {string} options.title - Post title (required)
+ * @param {string} [options.subject] - Email subject line (defaults to title)
+ * @param {string} [options.preheader] - Email preview text
+ * @param {string} [options.content] - HTML content body
+ * @param {string} [options.status] - 'draft' or 'confirmed' (default: confirmed = send)
+ * @param {string} [options.sendAt] - ISO datetime to schedule, or null for immediate
+ * @param {Array<string>} [options.segments] - Segment IDs to include
+ * @param {Array<string>} [options.excludeSegments] - Segment IDs to exclude
+ * @returns {{ success: boolean, id?: string, scheduled?: boolean, error?: string }}
+ */
+async function createPost(options) {
+  const publicationId = await getPublicationId();
+
+  if (!publicationId) {
+    return { success: false, error: 'Publication not found' };
+  }
+
+  const { title, subject, preheader, content, status, sendAt, segments, excludeSegments } = options;
+
+  try {
+    const body = {
+      title,
+      status: sendAt ? 'confirmed' : (status || 'confirmed'),
+    };
+
+    // Content
+    if (content) {
+      body.body_content = content;
+    }
+
+    // Scheduling
+    if (sendAt && sendAt !== 'now') {
+      body.scheduled_at = new Date(sendAt).toISOString();
+    }
+
+    // Email settings
+    const emailSettings = {};
+
+    if (subject) {
+      emailSettings.subject_line = subject;
+    }
+    if (preheader) {
+      emailSettings.preview_text = preheader;
+    }
+
+    if (Object.keys(emailSettings).length) {
+      body.email_settings = emailSettings;
+    }
+
+    // Audience targeting (segments)
+    if ((segments && segments.length) || (excludeSegments && excludeSegments.length)) {
+      body.recipients = {};
+
+      if (segments && segments.length) {
+        body.recipients.segment_ids = segments;
+      }
+      if (excludeSegments && excludeSegments.length) {
+        body.recipients.exclude_segment_ids = excludeSegments;
+      }
+    }
+
+    const data = await fetch(`${BASE_URL}/publications/${publicationId}/posts`, {
+      method: 'post',
+      response: 'json',
+      headers: headers(),
+      timeout: 15000,
+      body,
+    });
+
+    if (data.data?.id) {
+      const scheduled = !!sendAt;
+      return { success: true, id: data.data.id, scheduled };
+    }
+
+    return { success: false, error: data.message || 'Unknown error' };
+  } catch (e) {
+    console.error('Beehiiv createPost error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
 module.exports = {
   // Contacts
   addContact,
   removeContact,
   buildFields,
+
+  // Campaigns
+  createPost,
 };