postemi 0.0.0-stage → 1.0.1

package/PROVIDER_SETTINGS.md

@@ -0,0 +1,374 @@
+# Provider-specific settings
+
+Every channel Postemi supports, and every field its `--settings` payload accepts.
+
+**The channels below are the whole list.** Postemi's server carries inherited
+code for many other providers — Reddit, Mastodon, Medium, Dev.to, Hashnode,
+WordPress, Lemmy, Nostr, VK, Tumblr, Dribbble, Farcaster and others.
+None of them are enabled or supported. Do not build a settings payload for one.
+
+| Channel | `__type` | Has settings? | Status |
+|---|---|---|---|
+| X (Twitter) | `x` | yes | Publishing verified |
+| Facebook | `facebook` | yes, all optional | Publishing verified |
+| Instagram | `instagram` | yes | Publishing verified |
+| Threads | `threads` | **no** | Publishing verified |
+| Bluesky | `bluesky` | **no** | Publishing verified |
+| LinkedIn | `linkedin` | yes, all optional | Publishing verified |
+| Telegram | `telegram` | **no** | Publishing verified |
+| Discord | `discord` | yes, `channel` required | Publishing verified |
+| Slack | `slack` | yes, `channel` required | Publishing verified |
+| YouTube | `youtube` | yes | Publishing verified |
+| TikTok | `tiktok` | yes | Publishing verified |
+| Pinterest | `pinterest` | yes, `board` required | BETA: pins visible only to their creator until Pinterest grants Standard access |
+
+Source of truth for everything on this page:
+`libraries/nestjs-libraries/src/dtos/posts/providers-settings/*.ts` in the Postemi
+server. If this file and a DTO disagree, the DTO is right — and the
+`integrations:settings` route serves those DTOs as live JSON schema, so you can
+always ask instead of trusting a document:
+
+```bash
+postemi integrations:settings <integration-id> | jq '.output.settings'
+```
+
+---
+
+## How to pass settings
+
+### Command line
+
+```bash
+postemi posts:create \
+  -c "Your content" \
+  -s "2026-12-31T12:00:00Z" \
+  --settings '<json>' \
+  -i "<integration-id>"
+```
+
+The backend fills in `__type` from the integration's provider. You do not send
+it on the command line.
+
+### JSON file
+
+```bash
+postemi posts:create --json post.json
+```
+
+```json
+{
+  "type": "schedule",
+  "date": "2026-12-31T12:00:00Z",
+  "shortLink": false,
+  "tags": [],
+  "posts": [{
+    "integration": { "id": "<youtube-integration-id>" },
+    "value": [{ "content": "Video description", "image": [{ "id": "…", "path": "https://…" }] }],
+    "settings": {
+      "__type": "youtube",
+      "title": "Video title",
+      "type": "public",
+      "tags": [{ "value": "tech", "label": "Tech" }]
+    }
+  }]
+}
+```
+
+You do not have to write `__type` even here: the server stamps it from the
+integration's provider before validating, overwriting whatever you sent. Write
+it for readability if you like — a stale or wrong value cannot break the
+request, because it is replaced, not checked.
+
+**Two behaviours worth knowing before you publish:**
+
+- **A key without the `posts:publish` scope produces a draft, not a refusal.**
+  `posts:create` needs only `posts:draft`; without `posts:publish` the server
+  coerces `type` to `draft` and creates one. Read back the `type` in the
+  response rather than assuming the one you sent.
+- **One X channel per post.** A single post may not target two X channels,
+  whatever the content — X's Developer Policy forbids it and the developer
+  account at risk is Postemi's, shared by every customer. Any other combination
+  of channels is fine.
+
+---
+
+## X (Twitter) — `x`
+
+| Field | Required | Values |
+|---|---|---|
+| `who_can_reply_post` | **yes** | `everyone`, `following`, `mentionedUsers`, `subscribers`, `verified` |
+| `community` | no | A community URL matching `https://x.com/i/communities/<digits>`, or empty string |
+| `made_with_ai` | no | boolean |
+| `paid_partnership` | no | boolean |
+
+```bash
+postemi posts:create \
+  -c "Announcement" \
+  -s "2026-12-31T12:00:00Z" \
+  --settings '{"who_can_reply_post":"everyone"}' \
+  -i "$X_ID"
+```
+
+A malformed `community` fails validation with the expected format in the
+message. Anything other than the five reply values is a `400`.
+
+---
+
+## Facebook — `facebook`
+
+All fields optional.
+
+| Field | Values |
+|---|---|
+| `post_type` | `post`, `story` |
+| `url` | A URL to attach |
+| `text_format_preset_id` | A Facebook background preset id |
+
+`text_format_preset_id` applies to **text-only posts on Pages** and caps at
+about 130 characters. Facebook exposes no API to enumerate the presets, so the
+server carries a hardcoded catalogue; the ids are opaque strings.
+
+```bash
+IMG=$(postemi upload photo.jpg | jq -r '.path')
+postemi posts:create -c "Post text" -s "2026-12-31T12:00:00Z" \
+  --settings '{"post_type":"post"}' -m "$IMG" -i "$FB_ID"
+```
+
+---
+
+## Instagram — `instagram`
+
+| Field | Required | Values |
+|---|---|---|
+| `post_type` | **yes** | `post`, `story` |
+| `collaborators` | no | array of `{ "label": "<username>" }` |
+| `audio` | no | `{ id, title?, artist?, image?, audio_volume?, video_volume? }` — volumes 0–100 |
+| `is_trial_reel` | no | boolean |
+| `graduation_strategy` | no | `MANUAL`, `SS_PERFORMANCE` |
+
+`audio.id` comes from the `audioSearch` tool:
+
+```bash
+postemi integrations:trigger "$IG_ID" audioSearch -d '{"q":"lofi","type":"music"}'
+# type is "music" (default) or "original_sound"; an empty q returns trending audio
+```
+
+```bash
+STORY=$(postemi upload story.jpg | jq -r '.path')
+postemi posts:create -c "" -s "2026-12-31T12:00:00Z" \
+  --settings '{"post_type":"story"}' -m "$STORY" -i "$IG_ID"
+```
+
+---
+
+## Threads — `threads`
+
+**No settings.** Omit `--settings`. There are no fields to send and inventing
+one is a `400`.
+
+```bash
+postemi posts:create -c "Post text" -s "2026-12-31T12:00:00Z" -i "$THREADS_ID"
+```
+
+---
+
+## Bluesky — `bluesky`
+
+**No settings.** Same as Threads.
+
+---
+
+## YouTube — `youtube`
+
+| Field | Required | Values |
+|---|---|---|
+| `title` | **yes** | 2–100 characters |
+| `type` | **yes** | `public`, `private`, `unlisted` |
+| `selfDeclaredMadeForKids` | no | `yes`, `no` |
+| `thumbnail` | no | A media object from `postemi upload` |
+| `tags` | no | array of `{ value, label }` |
+
+The post's `-c` content becomes the **video description**. `title` is separate
+and is the video's title.
+
+**The tag budget is 500 characters in total across every tag**, not per tag.
+A tag containing whitespace costs two extra characters against that budget,
+because YouTube wraps it in quotes. Over the budget is a `400` naming the
+limit.
+
+There is **no `playlistId` field** and no way to add a video to a playlist
+through the API. Earlier documentation claimed otherwise.
+
+```bash
+VIDEO=$(postemi upload video.mp4 | jq -r '.path')
+postemi posts:create \
+  -c "Full video description…" \
+  -s "2026-12-31T12:00:00Z" \
+  --settings '{"title":"How to build a CLI","type":"public","selfDeclaredMadeForKids":"no","tags":[{"value":"tech","label":"Tech"},{"value":"tutorial","label":"Tutorial"}]}' \
+  -m "$VIDEO" \
+  -i "$YT_ID"
+```
+
+Only MP4 uploads. See [SUPPORTED_FILE_TYPES.md](./SUPPORTED_FILE_TYPES.md).
+
+---
+
+## LinkedIn — `linkedin`
+
+Both fields optional.
+
+| Field | Values |
+|---|---|
+| `post_as_images_carousel` | boolean |
+| `carousel_name` | string |
+
+There is **no `companyId`**. Posting as a company page is a separate connected
+channel with identifier `linkedin-page`, chosen at connect time — not a setting
+on a personal post.
+
+```bash
+postemi posts:create -c "Content" -s "2026-12-31T12:00:00Z" \
+  --settings '{"post_as_images_carousel":true,"carousel_name":"Product launch"}' \
+  -m "$A,$B,$C" -i "$LI_ID"
+```
+
+---
+
+## TikTok — `tiktok`
+
+| Field | Required | Values |
+|---|---|---|
+| `title` | no | ≤ 90 characters |
+| `privacy_level` | **yes for `DIRECT_POST`** | `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` |
+| `content_posting_method` | **yes** | `DIRECT_POST`, `UPLOAD` |
+| `duet` | yes | boolean — video only, `DIRECT_POST` only |
+| `stitch` | yes | boolean — video only, `DIRECT_POST` only |
+| `comment` | yes | boolean — `DIRECT_POST` only |
+| `autoAddMusic` | yes | `yes`, `no` — photo posts only, `DIRECT_POST` only |
+| `brand_content_toggle` | yes | boolean — `DIRECT_POST` only |
+| `brand_organic_toggle` | yes | boolean — `DIRECT_POST` only |
+| `video_made_with_ai` | no | boolean — video only, `DIRECT_POST` only |
+
+The field is `privacy_level`. Earlier documentation called it `privacy`; that
+name is silently ignored, which is worse than an error.
+
+**`UPLOAD` does not publish.** It sends the media to the user's TikTok app
+inbox as a draft, which they must finish and publish by hand within 24 hours or
+it is discarded — and TikTok ignores every setting above except `title`. Only
+use it when the user explicitly asks to finish the post inside the TikTok app.
+
+**`privacy_level` deliberately has no default.** TikTok's Content Sharing
+Guidelines require the person posting to choose it. Ask the user; do not pick
+one on their behalf.
+
+```bash
+VIDEO=$(postemi upload video.mp4 | jq -r '.path')
+postemi posts:create \
+  -c "Caption #fyp" \
+  -s "2026-12-31T12:00:00Z" \
+  --settings '{"title":"Caption","privacy_level":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true,"comment":true,"autoAddMusic":"no","brand_content_toggle":false,"brand_organic_toggle":false,"content_posting_method":"DIRECT_POST"}' \
+  -m "$VIDEO" \
+  -i "$TT_ID"
+```
+
+---
+
+## Telegram — `telegram`
+
+**No settings.** Same as Threads. The channel is fixed when the user connects
+it in Postemi (one shared bot posts into the channel or group they chose).
+
+---
+
+## Discord — `discord`
+
+| Field | Values |
+|---|---|
+| `channel` | **required** — a channel id from the `channels` tool |
+
+Get the id first; a channel name is a `400`:
+
+```bash
+postemi integrations:trigger "$DISCORD_ID" channels -d '{}' | jq '.output'
+postemi posts:create -c "Release notes are out" -s "2026-12-31T12:00:00Z" \
+  --settings '{"channel":"123456789012345678"}' -i "$DISCORD_ID"
+```
+
+---
+
+## Slack — `slack`
+
+| Field | Values |
+|---|---|
+| `channel` | **required** — a channel id from the `channels` tool |
+
+Same shape as Discord:
+
+```bash
+postemi integrations:trigger "$SLACK_ID" channels -d '{}' | jq '.output'
+postemi posts:create -c "Release notes are out" -s "2026-12-31T12:00:00Z" \
+  --settings '{"channel":"C0123456789"}' -i "$SLACK_ID"
+```
+
+---
+
+## Pinterest — `pinterest`
+
+**BETA.** Until Pinterest grants Postemi Standard access, a pin is visible only
+to the account that created it. Tell the user before you schedule one.
+
+| Field | Values |
+|---|---|
+| `board` | **required** — a board id from the `boards` tool |
+| `title` | optional, up to 100 characters |
+| `link` | optional, a URL the pin opens |
+
+A pin needs media: one image (up to 5 images in one pin), or a video with a
+cover picture as the second attachment. Get the board id first; a board name is
+refused:
+
+```bash
+postemi integrations:trigger "$PINTEREST_ID" boards | jq '.output'
+IMG=$(postemi upload ./pin.jpg | jq -r '.path')
+postemi posts:create -c "Autumn recipes" -m "$IMG" -s "2026-12-31T12:00:00Z" \
+  --settings '{"board":"1234567890123456789","title":"Autumn recipes","link":"https://example.com/recipes"}' \
+  -i "$PINTEREST_ID"
+```
+
+---
+
+## Finding your integration ids
+
+```bash
+postemi integrations:list
+# [{ "id": "…", "name": "…", "identifier": "instagram", … }]
+
+X_ID=$(postemi integrations:list  | jq -r '.[] | select(.identifier=="x")        | .id')
+IG_ID=$(postemi integrations:list | jq -r '.[] | select(.identifier=="instagram")| .id')
+YT_ID=$(postemi integrations:list | jq -r '.[] | select(.identifier=="youtube")  | .id')
+```
+
+`identifier` is the provider; `__type` in JSON mode is the same string.
+
+If a channel is not in `integrations:list`, the user cannot post to it. For
+Google Business Profile and LinkedIn company pages that is the expected state
+until those platforms approve the app (personal LinkedIn profiles work).
+Pinterest is live as a BETA channel. Say so rather than scheduling a post that will fail.
+
+---
+
+## Validating before you publish
+
+Post as a draft first. A draft goes through the same validation as a scheduled
+post, so a bad settings payload fails immediately instead of at publish time:
+
+```bash
+postemi posts:create -c "…" -s "2026-12-31T12:00:00Z" -t draft --settings '…' -i "$ID"
+```
+
+Then promote it, or delete it:
+
+```bash
+postemi posts:status <post-id> --status schedule
+postemi posts:delete <post-id>
+```

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# Postemi CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Social media scheduling from the command line, or from your AI agent.**
+
+Postemi (https://postemi.com) is a social media scheduler, and this is its
+command-line tool. It uses the same public API as the web app: what you
+schedule here shows up in your Postemi calendar, and what you schedule there
+you can see here too.
+
+Channels: 20 platforms, including Facebook, Instagram, X, LinkedIn, TikTok, YouTube, Threads, Bluesky, Pinterest and Mastodon.
+
+[`SKILL.md`](./SKILL.md) is the full command reference, written for AI agents.
+Show it to Claude, ChatGPT, Codex, OpenClaw or Hermes and they can use the
+whole CLI with no further explanation.
+
+## Install
+
+```bash
+npm install -g postemi
+postemi --help
+```
+
+Node.js 18 or newer.
+
+## Sign in
+
+```bash
+postemi auth:login     # device flow: opens postemi.com/app/device in the browser
+postemi auth:status    # checks the credential
+postemi auth:logout    # deletes the stored credential
+```
+
+You approve the login in the browser while signed in to Postemi, and choose
+there which workspace and which channels the key may reach. The CLI stores it
+in `~/.postemi/credentials.json` (mode `0600`).
+
+No account yet? Create one from the terminal:
+
+```bash
+postemi auth:signup --email anna@example.com    # e-mails a code, asks for it and for the terms
+postemi auth:signup --email anna@example.com --code 123456 --accept-terms --workspace-name "Anna's Cafe"
+```
+
+The person must agree to https://postemi.com/terms and
+https://postemi.com/privacy first. There is no free trial: next come
+`postemi billing:plans` and `postemi billing:subscribe`. You can also sign up
+at https://postemi.com/app/signup and then run `postemi auth:login`.
+
+For a server, CI or an agent without a browser, use an API key from
+Settings, Developers in the web app:
+
+```bash
+export POSTEMI_API_KEY=your_api_key
+```
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `POSTEMI_API_KEY` | none | API key, when you do not use `auth:login` |
+| `POSTEMI_API_URL` | `https://api.postemi.com` | API base |
+| `POSTEMI_WORKSPACE` | none | Workspace id for every command (same as `--workspace`) |
+| `POSTEMI_TIMEZONE` | none | IANA zone for dates written without an offset |
+| `POSTEMI_AUTH_SERVER` | `https://api.postemi.com` | Where `auth:login` runs the device flow |
+| `POSTEMI_CLIENT_NAME` | `Postemi CLI` | Name shown on the approval page |
+
+Stored credentials from `auth:login` take precedence over `POSTEMI_API_KEY`.
+
+## Quick start
+
+```bash
+postemi auth:status
+postemi integrations:list                        # your channels and their ids
+postemi config:set timezone Europe/London        # once: how to read dates without an offset
+
+IMG=$(postemi upload ./photo.jpg | jq -r '.path')
+postemi posts:create -c "Hello from the terminal" -m "$IMG" \
+  -s "2026-12-31 09:00" -i "<integration-id>"
+```
+
+Results are JSON on stdout; status lines and errors go to stderr, and every
+failure exits 1. Run `postemi <command> --help` for each command.
+
+## More
+
+- [`SKILL.md`](./SKILL.md): every command, flag and rule
+- [`PROVIDER_SETTINGS.md`](./PROVIDER_SETTINGS.md): per-channel settings
+- [`SUPPORTED_FILE_TYPES.md`](./SUPPORTED_FILE_TYPES.md): the eight accepted media types
+- [`examples/`](./examples): ready `--json` payloads
+- MCP server for chat clients: `https://mcp.postemi.com/mcp`
+- Help: https://postemi.com/help, support: norbert@postemi.com
+- Privacy: https://postemi.com/privacy, terms: https://postemi.com/terms
+
+## Plugins for AI agents
+
+This repository also holds the Postemi plugins, in [`plugins/`](./plugins):
+
+| Folder | For | What it is |
+|---|---|---|
+| [`plugins/postemi-mcp`](./plugins/postemi-mcp) | Claude (chat, desktop, Code) | The hosted MCP server `https://mcp.postemi.com/mcp` plus a skill |
+| [`plugins/postemi-cli`](./plugins/postemi-cli) | Claude Code | This CLI's skill; the agent runs `postemi` commands |
+| [`plugins/postemi-chatgpt`](./plugins/postemi-chatgpt) | ChatGPT | The ChatGPT app package |
+| [`plugins/postemi-cursor`](./plugins/postemi-cursor) | Cursor | MCP server, skill and commands |
+| [`plugins/postemi-grok`](./plugins/postemi-grok) | Grok Build | MCP server, skill and commands |
+
+In Claude Code:
+
+```bash
+claude plugin marketplace add norbertlevente/postemi-agent
+claude plugin install postemi@postemi-agent        # MCP server
+claude plugin install postemi-cli@postemi-agent    # CLI skill
+```
+
+The skill on its own (for OpenClaw and other agents) is
+[`skills/postemi/SKILL.md`](./skills/postemi/SKILL.md).
+
+## Development
+
+```bash
+pnpm install
+pnpm build        # dist/index.js
+pnpm test         # type check, build, and scripts/check.mjs (manifests, skill copies, no other-brand text)
+node dist/index.js --help
+```
+
+Release steps: [`PUBLISHING.md`](./PUBLISHING.md). Changes: [`CHANGELOG.md`](./CHANGELOG.md).
+
+License: AGPL-3.0, see [`LICENSE`](./LICENSE).
+Source: https://github.com/norbertlevente/postemi-agent