io.github.pooriaarab/agentic-campaign

agentic-campaign

Package · [Quickstart](#export-your-first-campaign-draft) · [Runtime surfaces](#runtime-surfaces)

agentic-campaign is an open-source social campaign planner for developers who need draft calendars, explicit slot approval, and text queue exports.

It runs as a TypeScript SDK, command-line interface (CLI), or Model Context Protocol (MCP) server.

Campaign planning and approval run locally; this package never publishes social posts.

Install

npm install agentic-campaign

Node.js 18 or later is required. TypeScript declarations are included, with two direct runtime dependencies.

Export your first campaign draft

Save this as campaign-demo.mjs. No credentials, environment variables, or .env loader are required.

import { createCampaign, approveSlot, exportQueue } from "agentic-campaign";

const campaign = createCampaign({
  brand: "Acme",
  goal: "launch a feature",
  platforms: ["linkedin", "x"],
  weeks: 1,
  postsPerWeek: 2,
  startDate: "2026-11-01",
});
console.log(campaign.schedule.length);
console.log(exportQueue(campaign).length);
const approved = approveSlot(campaign, "slot-1", { live: true, approved: true });
const queue = exportQueue(approved);
console.log(queue.length, queue[0].brand, queue[0].targets[0]);

node campaign-demo.mjs

Success prints 2, 0, and 1 Acme linkedin.

The approval flags change local state; they do not send a post.

Export text includes an AI-assistance disclosure and needs editorial review.

How it works

Brief -> deterministic pillars and daily draft slots
Draft slot + explicit approval -> approved slot
Approved or scheduled slots -> { brand, text, targets } queue
Queue -> a downstream publisher you implement separately

Why it exists

Developers need campaign planning data they can inspect and pass between tools.

Buffer and Hootsuite provide social calendars with publishing workflows.

agentic-campaign supplies local plan generation and approval-filtered text exports for code and agent sessions.

Compare

Scope checked on 2026-10-14 against the official pages linked below.

Coverage

There are zero social publishing connectors, two shared text-routing adapters, three fixed pillars, and four format labels.

The source and local tests verify planning behavior. Zero external integrations were credential-checked for this rewrite.

Common use cases

1. Node.js release teams generate draft slots for LinkedIn and X (Twitter) labels.
2. TypeScript agencies plan separate campaign objects for client brands.
3. MCP client developers review and approve slots within one agent session.
4. Custom publisher developers consume {brand, text, targets} queue items through their own pipeline.

Features

• Campaign plans: createCampaign builds draft slots; see the [quickstart](#export-your-first-campaign-draft).
• Explicit approvals: approveSlot requires live: true and approved: true.
• Queue exports: exportQueue keeps approved or scheduled slots and includes draft disclosure text.
• Agent sessions: MCP tools retain campaigns in the server's in-memory map.
• Shared utilities: Text summaries, generic dispatch, guards, logging, and in-memory cost reports are SDK exports.

Runtime surfaces

The Node.js SDK exports createCampaign, approveSlot, exportQueue, and shared text utilities.

Run commands with npx agentic-campaign. --help and --version print help and version output.

Separate CLI invocations start fresh maps. Use the SDK or a persistent MCP session for the full lifecycle.

All six MCP tools: create_campaign, list_campaigns, show_campaign, approve_campaign_slot, export_campaign_queue, and get_cost_report.

Start them with npx agentic-campaign mcp or npx agentic-campaign-mcp.

The Worker source exposes GET /health and POST /summarize only.

Optional PACK_NAME changes its health response label. You deploy and secure the Worker yourself.

Delivery and behavior limits

• weeks * postsPerWeek sets total slots across all labels, rather than slots per platform.
• Slots advance one calendar day each. weeks does not bound the schedule to that many weeks.
• Brief quietHours is accepted but ignored. Slots contain dates, without posting times.
• The daily cap is SDK-only input; the generator still advances a day after each slot.
• Pillars, hooks, and formats use fixed code templates. No language model generates campaign text.
• Format labels do not create carousel images, videos, stories, or attachments.
• Campaign IDs use normalized brand and start date. Same-brand, same-date plans can overwrite a session map entry.
• CLI and MCP storage is in memory. There is no file store, database, or restart recovery.
• Only draft-to-approved transitions have an exported helper. Scheduling and completion need application code.
• Queue items omit dates, slot IDs, and media. Downstream code must preserve scheduling metadata separately.
• There is no automatic delivery, retry, deduplication, platform authentication, or engagement analytics.
• Cost reports track generic text dispatch units. Campaign planning and approvals record no costs.

Integration guides

• [Node.js campaign approval and export example](#export-your-first-campaign-draft)
• [CLI and MCP campaign lifecycle reference](#runtime-surfaces)
• [Export and storage constraints](#delivery-and-behavior-limits)

The export tool describes its shape as agentic-publish-compatible in source.

This package does not call agentic-publish or verify delivery compatibility.

No separate public documentation site is configured.

Status

Version 0.1.0 is an early release; APIs can change before 1.0.

Report problems through GitHub issues.

Public case studies are not published in this repository.

FAQ

What is agentic-campaign?

agentic-campaign generates local campaign plans and exports reviewed draft text.

It provides SDK, CLI, and MCP interfaces for developers.

Which integrations are verified?

agentic-campaign has no social publishing connectors or platform credential verification.

Its shared generic HTTP text router is separate from the campaign workflow.

Does agentic-campaign provide a managed publishing service?

agentic-campaign produces data inside your process.

You supply storage, deployment, editorial review, and any publisher.

How is agentic-campaign different from Buffer?

agentic-campaign generates campaign objects and approval-filtered queues in code.

Buffer provides a social planning and publishing product; see its publishing overview.

How is agentic-campaign different from Hootsuite?

agentic-campaign exposes a local planning SDK and agent tools.

Hootsuite provides a content calendar and publishing workflows; see its publishing overview.

Does agentic-campaign publish to LinkedIn or X (Twitter)?

agentic-campaign stores those names as target labels.

It makes no social network requests and validates no platform-specific constraints.

Why does agentic-campaign list show no campaigns after create?

agentic-campaign starts a fresh in-memory map for each standalone CLI invocation.

Use a shared SDK object or one persistent MCP server session to retain campaigns.

Does agentic-campaign generate copy with a language model?

agentic-campaign uses fixed pillar descriptions and hook templates.

Its export includes an AI-assistance disclosure, but no model API is called.

What does live approval do?

agentic-campaign requires both live and approval flags to change a draft slot to approved.

That local state change makes the slot eligible for export and sends nothing externally.

Contributing

Run npm ci, npm run build, npm run typecheck, and npm test from the repository.

License

MIT. See the license text.