# social-scheduler

Social-media posting-schedule & content-calendar intelligence microservice: return platform-specific best-time-to-post slots (Instagram, Facebook, X/Twitter, LinkedIn, TikTok, YouTube, Pinterest...


A social-media posting-cadence & content-calendar intelligence microservice. **Pure deterministic
heuristics** driven by platform best-practice tables — no network, no model, fully offline and
reproducible. Every result is a plain JSON object.

## Tools

| Tool | Args | What it does |
|---|---|---|
| `bestTimes` | `{ platform, count?, timezone? }` | Ranked best-time-to-post slots + best weekdays for a platform (instagram, facebook, twitter/x, linkedin, tiktok, youtube, pinterest, threads), each with a strength weight and daypart. |
| `buildCalendar` | `{ posts, cadence?, start?, postsPerWeek?, timezone? }` | Lays a list of posts onto dated calendar entries by cadence (`daily`, `weekdays`, `everyOtherDay`, `weekly`, `3xWeek`, `2xWeek`, or a number/week). |
| `cadencePlan` | `{ platform, goal?, count?, postsPerWeek? }` | Recommends a weekly posting cadence for a platform + goal, spread over N weeks across the platform's best days. |
| `spacingCheck` | `{ datetimes, platform? }` | Analyzes an array of planned post datetimes for clustering (too close), over/under-posting vs the platform's healthy rate, and evenness (coefficient of variation). |
| `frequencyByGoal` | `{ goal, platform? }` | Maps a marketing goal (awareness, engagement, growth, sales, community) to a recommended posts-per-week per platform, with a healthy range. |

## Example

```js
import pack from './index.js';
pack.adapters.bestTimes({ platform: 'linkedin', count: 3 });
pack.adapters.buildCalendar({ posts: ['Launch teaser', 'Feature deep-dive', 'Customer story'], cadence: '3xWeek', start: '2026-08-03' });
pack.adapters.frequencyByGoal({ goal: 'growth', platform: 'tiktok' });
pack.adapters.spacingCheck({ datetimes: ['2026-08-03T09:00Z', '2026-08-03T10:30Z', '2026-08-05T12:00Z'], platform: 'instagram' });
```

## DRY boundaries

- Low-level date parsing / interval math / recurrence (`'5m'`-style parsing) → `datetime` / `ical` /
  `cron`. This pack owns social posting-cadence **strategy** (best-time tables, calendar layout,
  spacing analysis, goal→frequency mapping).
- No cross-pack imports. No LLM — schedules must be exact and reproducible.


---
Source: shared/engines/adapters/domain/social-scheduler/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/social-scheduler