beehiiv

What this skill does

Beehiiv API v2 skill for managing newsletter posts and drafts. All commands go through a single entry point: `node <base_directory>/beehiiv.js <command> [flags]`. Each command has its own doc file with the full reference for flags and behavior.

[!SETUP] Before first use, check whether `<base_directory>/node_modules` exists. If it does NOT exist, run `npm install --prefix <base_directory>`. Then check whether `<base_directory>/dist/beehiiv.js` exists. If it does NOT exist, run `npm run build --prefix <base_directory>`. NEVER cd into the skill directory; use --prefix to target it without changing your working directory.

[!COMMANDS]

Reading:
a) `publications` — list all publications associated with the API key. @docs/publications.md.
b) `publication` — get a single publication's details and stats. @docs/publication.md.
c) `posts` — list posts with filters (status, tags, authors, audience, platform). This is the primary search mechanism. @docs/posts.md.
d) `get` — retrieve a single post by ID with full HTML content. @docs/get.md.

Writing:
e) `draft` — create a draft post from a title + optional .md/.html file. Enterprise-only endpoint (beta). @docs/draft.md.

Utility:
f) `templates` — list available post templates. @docs/templates.md.

[!CREDENTIALS] One variable is REQUIRED: `BEEHIIV_API_KEY`. One variable is OPTIONAL: `BEEHIIV_PUBLICATION_ID` (default publication — if set, commands use it automatically; if not, pass `--pub-id <id>`). They resolve from the first source that provides them: a) `.env.local` in cwd, b) `.env` in cwd, c) `.env.local` in the plugin directory, d) `.env` in the plugin directory, e) environment variables. Obtain the API key from the Beehiiv dashboard (Settings > Integrations > API).

[!PUB-ID] All commands except `publications` require a publication ID. If `BEEHIIV_PUBLICATION_ID` is set, it is used by default. Any command can override it with `--pub-id <id>`. To discover your publication ID, run `publications` first.

[!API-COVERAGE]
Covered resources:
- Publications: list, get (commands: publications, publication)
- Posts: list, get single, create as draft (commands: posts, get, draft)
- PostTemplates: list (command: templates)

NOT covered (future TODO):
- Subscriptions: list, create, get by email/id, update, delete, bulk actions, JWT token, tags
- Authors: list, get single
- Automations: list, get single, journeys list/get
- BulkSubscriptions: create, updates status
- ConditionSets: list, get single
- CustomFields: list, get, create, update, delete
- EmailBlasts: list, get single
- Engagements: list
- Polls: list, get single, responses
- PostAggregateStats: get
- ReferralProgram: get
- Segments: list, get, recalculate, members, results
- Tiers: list, get single
- Webhooks: list, get, create, update, delete, test
- AdvertisementOpportunities: list