beehiiv api tooling

packages/mg-beehiiv-api-members/.eslintrc.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+    parser: '@typescript-eslint/parser',
+    plugins: ['ghost'],
+    extends: [
+        'plugin:ghost/node'
+    ],
+    rules: {
+        'no-unused-vars': 'off', // doesn't work with typescript
+        'no-undef': 'off', // doesn't work with typescript
+        'ghost/filenames/match-regex': 'off'
+    }
+};

packages/mg-beehiiv-api-members/README.md

@@ -0,0 +1,3 @@
+# Migrate beehiiv members API
+
+...

packages/mg-beehiiv-api-members/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tryghost/mg-beehiiv-api-members",
+  "version": "0.1.0",
+  "repository": "https://github.com/TryGhost/migrate/tree/main/packages/mg-beehiiv-api-members",
+  "author": "Ghost Foundation",
+  "license": "MIT",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/types.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "echo \"Implement me!\"",
+    "build:watch": "tsc --watch --preserveWatchOutput --sourceMap",
+    "build": "rm -rf build && rm -rf tsconfig.tsbuildinfo && tsc --build --sourceMap",
+    "prepare": "yarn build",
+    "lint": "eslint src/ --ext .ts --cache",
+    "posttest": "yarn lint",
+    "test": "rm -rf build && yarn build --force && c8 --src src --all --check-coverage --100 --reporter text --reporter cobertura node --test build/test/*.test.js"
+  },
+  "files": [
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "8.0.0",
+    "@typescript-eslint/parser": "8.0.0",
+    "c8": "10.1.3",
+    "eslint": "8.57.0",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@tryghost/errors": "1.3.8",
+    "@tryghost/mg-fs-utils": "0.12.14",
+    "@tryghost/string": "0.2.21"
+  }
+}

packages/mg-beehiiv-api-members/src/index.ts

@@ -0,0 +1,9 @@
+import {listPublications} from './lib/list-pubs.js';
+import {fetchTasks} from './lib/fetch.js';
+import {mapMembersTasks} from './lib/mapper.js';
+
+export default {
+    listPublications,
+    fetchTasks,
+    mapMembersTasks
+};

packages/mg-beehiiv-api-members/src/lib/fetch.ts

@@ -0,0 +1,114 @@
+import errors from '@tryghost/errors';
+
+const API_LIMIT = 100;
+
+const authedClient = async (apiKey: string, theUrl: URL) => {
+    return fetch(theUrl, {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${apiKey}`
+        }
+    });
+};
+
+const discover = async (key: string, pubId: string) => {
+    const url = new URL(`https://api.beehiiv.com/v2/publications/${pubId}`);
+    url.searchParams.append('limit', '1');
+    url.searchParams.append('expand[]', 'stats');
+
+    const response = await authedClient(key, url);
+
+    if (!response.ok) {
+        throw new errors.InternalServerError({message: `Request failed: ${response.status} ${response.statusText}`});
+    }
+
+    const data: BeehiivPublicationResponse = await response.json();
+
+    return data.data.stats?.active_subscriptions;
+};
+
+const cachedFetch = async ({fileCache, key, pubId, cursor, cursorIndex}: {
+    fileCache: any;
+    key: string;
+    pubId: string;
+    cursor: string | null;
+    cursorIndex: number;
+}) => {
+    const filename = `beehiiv_api_members_${cursorIndex}.json`;
+
+    if (fileCache.hasFile(filename, 'tmp')) {
+        return await fileCache.readTmpJSONFile(filename);
+    }
+
+    const url = new URL(`https://api.beehiiv.com/v2/publications/${pubId}/subscriptions`);
+    url.searchParams.append('limit', API_LIMIT.toString());
+    url.searchParams.append('status', 'active');
+    url.searchParams.append('expand[]', 'custom_fields');
+
+    if (cursor) {
+        url.searchParams.append('cursor', cursor);
+    }
+
+    const response = await authedClient(key, url);
+
+    if (!response.ok) {
+        throw new errors.InternalServerError({message: `Request failed: ${response.status} ${response.statusText}`});
+    }
+
+    const data: BeehiivSubscriptionsResponse = await response.json();
+
+    await fileCache.writeTmpFile(data, filename);
+
+    return data;
+};
+
+export const fetchTasks = async (options: any, ctx: any) => {
+    const totalSubscriptions = await discover(options.key, options.id);
+    const estimatedPages = Math.ceil(totalSubscriptions / API_LIMIT);
+
+    const tasks = [
+        {
+            title: `Fetching subscriptions (estimated ${estimatedPages} pages)`,
+            task: async (_: any, task: any) => {
+                let cursor: string | null = null;
+                let hasMore = true;
+                let cursorIndex = 0;
+
+                ctx.result.subscriptions = [];
+
+                while (hasMore) {
+                    try {
+                        const response: BeehiivSubscriptionsResponse = await cachedFetch({
+                            fileCache: ctx.fileCache,
+                            key: options.key,
+                            pubId: options.id,
+                            cursor,
+                            cursorIndex
+                        });
+
+                        ctx.result.subscriptions = ctx.result.subscriptions.concat(response.data);
+                        hasMore = response.has_more;
+                        cursor = response.next_cursor;
+                        cursorIndex += 1;
+
+                        task.output = `Fetched ${ctx.result.subscriptions.length} of ${totalSubscriptions} subscriptions`;
+                    } catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        task.output = errorMessage;
+                        throw error;
+                    }
+                }
+
+                task.output = `Fetched ${ctx.result.subscriptions.length} subscriptions`;
+            }
+        }
+    ];
+
+    return tasks;
+};
+
+export {
+    authedClient,
+    discover,
+    cachedFetch
+};

packages/mg-beehiiv-api-members/src/lib/list-pubs.ts

@@ -0,0 +1,21 @@
+import errors from '@tryghost/errors';
+import {authedClient} from './fetch.js';
+
+const listPublications = async (apiKey: string) => {
+    const url = new URL(`https://api.beehiiv.com/v2/publications`);
+    url.searchParams.append('expand[]', 'stats');
+
+    const response = await authedClient(apiKey, url);
+
+    if (!response.ok) {
+        throw new errors.InternalServerError({message: `Request failed: ${response.status} ${response.statusText}`});
+    }
+
+    const data = await response.json();
+
+    return data.data;
+};
+
+export {
+    listPublications
+};

packages/mg-beehiiv-api-members/src/lib/mapper.ts

@@ -0,0 +1,106 @@
+import {slugify} from '@tryghost/string';
+
+const extractName = (customFields: Array<{name: string; value: string}>): string | null => {
+    const firstNameField = customFields.find(f => f.name.toLowerCase() === 'first_name' || f.name.toLowerCase() === 'firstname');
+    const lastNameField = customFields.find(f => f.name.toLowerCase() === 'last_name' || f.name.toLowerCase() === 'lastname');
+
+    const firstName = firstNameField?.value?.trim() || '';
+    const lastName = lastNameField?.value?.trim() || '';
+
+    const combinedName = [firstName, lastName].filter(name => name.length > 0).join(' ');
+
+    return combinedName.length > 0 ? combinedName : null;
+};
+
+const mapSubscription = (subscription: BeehiivSubscription): GhostMemberObject => {
+    const labels: string[] = [];
+
+    // Add status label
+    labels.push(`beehiiv-status-${subscription.status}`);
+
+    // Add tier label
+    labels.push(`beehiiv-tier-${subscription.subscription_tier}`);
+
+    // Add premium tier names as labels
+    if (subscription.subscription_premium_tier_names && subscription.subscription_premium_tier_names.length > 0) {
+        subscription.subscription_premium_tier_names.forEach((tierName: string) => {
+            const slugifiedTier = slugify(tierName);
+            labels.push(`beehiiv-premium-${slugifiedTier}`);
+        });
+    }
+
+    // Add tags as labels
+    if (subscription.tags && subscription.tags.length > 0) {
+        subscription.tags.forEach((tag: string) => {
+            const slugifiedTag = slugify(tag);
+            labels.push(`beehiiv-tag-${slugifiedTag}`);
+        });
+    }
+
+    // Determine if this is a complimentary plan
+    // A member is on a complimentary plan if they have premium access but no Stripe customer ID
+    const isPremium = subscription.subscription_tier === 'premium';
+    const hasStripeId = Boolean(subscription.stripe_customer_id);
+    const complimentaryPlan = isPremium && !hasStripeId;
+
+    return {
+        email: subscription.email,
+        name: extractName(subscription.custom_fields || []),
+        note: null,
+        subscribed_to_emails: subscription.status === 'active',
+        stripe_customer_id: subscription.stripe_customer_id || '',
+        complimentary_plan: complimentaryPlan,
+        labels,
+        created_at: new Date(subscription.created * 1000)
+    };
+};
+
+const mapSubscriptions = (subscriptions: BeehiivSubscription[]): MappedMembers => {
+    const result: MappedMembers = {
+        free: [],
+        paid: []
+    };
+
+    subscriptions.forEach((subscription) => {
+        const member = mapSubscription(subscription);
+
+        if (member.stripe_customer_id) {
+            result.paid.push(member);
+        } else {
+            result.free.push(member);
+        }
+    });
+
+    return result;
+};
+
+export const mapMembersTasks = (_options: any, ctx: any) => {
+    const tasks = [
+        {
+            title: 'Mapping subscriptions to Ghost member format',
+            task: async (_: any, task: any) => {
+                try {
+                    const subscriptions: BeehiivSubscription[] = ctx.result.subscriptions || [];
+                    ctx.result.members = mapSubscriptions(subscriptions);
+
+                    const freeCount = ctx.result.members.free.length;
+                    const paidCount = ctx.result.members.paid.length;
+
+                    task.output = `Mapped ${freeCount} free and ${paidCount} paid members`;
+                } catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    task.output = errorMessage;
+                    throw error;
+                }
+            }
+        }
+    ];
+
+    return tasks;
+};
+
+export {
+    extractName,
+    mapSubscription,
+    mapSubscriptions
+};