chirpie 1.0.45 → 1.0.47

package/README.md

@@ -30,12 +30,14 @@ export CHIRPIE_API_KEY=chirpie_sk_...
 | Command | What it does |
 |---------|--------------|
 | `chirpie login` / `logout` / `auth` / `whoami` | Manage credentials |
-| `chirpie post <text>` | Create a post. `-a` account (repeat it for several accounts), `-m` media files or URLs, `--alt` descriptions, `--config` per-account overrides, `-s` schedule |
-| `chirpie thread <post> <post> ...` | Create a 2 to 25 post thread. `-a` is repeatable, `--config` takes per-account posts, `-f` takes a JSON payload file |
-| `chirpie posts` | List posts. `--status`, `--account`, `--group`, `--limit` |
+| `chirpie post <text>` | Create a post. `-a` account (repeat it for several accounts), `-m` media files or URLs, `--alt` descriptions, `--config` per-account overrides, `-s` schedule, `--draft` save without sending |
+| `chirpie thread <post> <post> ...` | Create a 2 to 25 post thread, or 1 to 25 with `--draft`. `-a` is repeatable, `--config` takes per-account posts, `-f` takes a JSON payload file |
+| `chirpie posts` | List posts. `--status`, `--account`, `--group`, `--limit`, `--include-hidden` |
 | `chirpie posts get <id>` | Fetch one post |
-| `chirpie posts update <id>` | Edit a post that has not published yet. `--text`, `--media`, `--alt`, `--clear-media`, `--schedule-at`. Leaving `--schedule-at` out keeps the time it already has |
-| `chirpie posts delete <id>` | Delete a post. Deleting any post of a scheduled thread cancels the thread |
+| `chirpie posts update <id>` | Edit a post that has not published yet, or finish a draft. `--text`, `--media`, `--alt`, `--clear-media`, `--schedule-at`, `--keep-draft`. Leaving `--schedule-at` out keeps the time it already has |
+| `chirpie posts publish <id>` | Send a saved draft now. `-t` sets the final text first |
+| `chirpie posts delete <id>` | Take a post down from the platform. Chirpie keeps it, marked deleted. Deleting any post of a scheduled thread cancels the thread. Instagram and TikTok offer no delete API and refuse with `delete_unsupported` |
+| `chirpie posts hide <id>` / `unhide <id>` | Hide a post from your Chirpie listings, or show it again. Nothing reaches the platform |
 | `chirpie accounts` | List connected accounts, active and inactive |
 | `chirpie accounts activate <id>` / `deactivate <id>` | Choose which accounts publish. Deactivating cancels that account's scheduled posts |
 | `chirpie accounts disconnect <id>` | End a connection. Cancels that account's scheduled posts, frees a plan slot, and removes the stored credential, so reconnecting means authorizing again. Asks first; `-y` skips the prompt |
@@ -70,6 +72,25 @@ chirpie thread "One" "Two" "Three" -a 550e8400-e29b-41d4-a716-446655440000
 chirpie posts --status scheduled
 ```
 
+## Drafts
+
+`--draft` saves a post or a thread without sending it. Nothing reaches the platform and nothing counts against your quota until you promote it. Anything that would go wrong is printed back, one warning per line.
+
+```bash
+chirpie post "Half an idea" --draft
+chirpie thread "Opening line" --draft     # a draft thread may be one post
+chirpie posts --status draft              # what is saved
+
+# Change only the time it remembers
+chirpie posts update "$POST_ID" --schedule-at 2027-04-02T09:00:00Z --keep-draft
+
+# Promote it: queue it, or send it now
+chirpie posts update "$POST_ID" --schedule-at 2027-04-02T09:00:00Z
+chirpie posts publish "$POST_ID"
+```
+
+Promoting runs every rule a normal post runs and takes the quota, so a draft that would be refused stays a draft, unchanged. A draft thread is promoted whole.
+
 ## Several accounts at once
 
 Repeat `-a` to publish the same post to up to 25 accounts in one call.

package/dist/index.js

@@ -31,10 +31,22 @@ function apiError(err, fallback) {
   const maybe = err;
   if (typeof maybe?.code === "string" && typeof maybe?.message === "string") {
     error(`${maybe.code}: ${maybe.message}`);
+    printThreadRollback(err);
     return;
   }
   error(err instanceof Error ? err.message : fallback);
 }
+function printThreadRollback(err) {
+  const rollback = err?.details?.thread_rollback;
+  const live = rollback?.still_live ?? [];
+  if (live.length === 0) return;
+  error("Still live on the platform, delete these yourself:");
+  for (const part of live) {
+    error(
+      `  post ${part.thread_order + 1}: ${part.platform_post_url ?? part.platform_post_id}`
+    );
+  }
+}
 function info(msg) {
   console.log(`\x1B[36m\u2139\x1B[0m ${msg}`);
 }
@@ -227,6 +239,14 @@ function parseAccountConfigurations(value) {
   }
   return parsed;
 }
+function printDraftWarnings(warnings) {
+  if (!Array.isArray(warnings)) return;
+  for (const warning of warnings) {
+    const entry = warning;
+    if (typeof entry?.message !== "string") continue;
+    info(`${entry.platform} ${entry.account_id}: ${entry.message}`);
+  }
+}
 function printFanOut(groupId, lines) {
   const failed = lines.filter((line) => !line.success);
   console.log(`Group ${groupId}`);
@@ -257,7 +277,10 @@ var postCommand = new Command3("post").description("Create a post").argument("<t
 ).option("-m, --media <files...>", MEDIA_OPTION_HELP).option("--alt <text...>", ALT_OPTION_HELP).option(
   "--config <json-or-file>",
   'Per-account overrides as JSON, or a path to a JSON file holding them: { "<account id>": { "text": "...", "media_urls": ["..."] } }. Every key must be an account named with --account'
-).option("-s, --schedule <datetime>", "Schedule for later. Any ISO 8601 timestamp with a timezone (2026-04-01T14:00:00Z or 2026-04-01T16:00:00+02:00). Posts publish within ~5 minutes of the scheduled time.").option("--json", "Output raw JSON").action(async (text, opts) => {
+).option("-s, --schedule <datetime>", "Schedule for later. Any ISO 8601 timestamp with a timezone (2026-04-01T14:00:00Z or 2026-04-01T16:00:00+02:00). Posts publish within ~5 minutes of the scheduled time.").option(
+  "--draft",
+  "Save without publishing. Nothing is sent, nothing counts against your quota, and any problems are listed back"
+).option("--json", "Output raw JSON").action(async (text, opts) => {
   const client = getClient();
   const named = opts.account ?? [];
   if (opts.config && named.length === 0) {
@@ -278,13 +301,15 @@ var postCommand = new Command3("post").description("Create a post").argument("<t
             opts.config
           )
         } : {},
-        schedule_at: opts.schedule
+        schedule_at: opts.schedule,
+        ...opts.draft ? { draft: true } : {}
       });
       if (opts.json) {
         json(result);
         if (result.results.some((r) => !r.success)) process.exit(1);
         return;
       }
+      if ("warnings" in result) printDraftWarnings(result.warnings);
       const failed = printFanOut(
         result.group_id,
         result.results.map((r) => ({
@@ -304,10 +329,14 @@ var postCommand = new Command3("post").description("Create a post").argument("<t
       account_id: accountIds[0],
       text,
       ...media ? { media } : {},
-      schedule_at: opts.schedule
+      schedule_at: opts.schedule,
+      ...opts.draft ? { draft: true } : {}
     });
     if (opts.json) {
       json(post);
+    } else if (post.status === "draft") {
+      success(`Draft saved (${post.id})`);
+      if ("warnings" in post) printDraftWarnings(post.warnings);
     } else if (post.status === "scheduled") {
       success(`Post scheduled for ${post.scheduled_at} (${post.id})`);
     } else {
@@ -353,7 +382,10 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
 ).option(
   "--config <json-or-file>",
   `Per-account overrides as JSON, or a path to a JSON file holding them: { "<account id>": { "posts": [{ "text": "one" }, { "text": "two" }] } }. An account's posts replace the whole thread for that account`
-).option("-s, --schedule <datetime>", "Schedule for later. Any ISO 8601 timestamp with a timezone (2026-04-01T14:00:00Z or 2026-04-01T16:00:00+02:00). Threads publish within ~5 minutes of the scheduled time.").option("--json", "Output raw JSON").action(async (posts, opts) => {
+).option("-s, --schedule <datetime>", "Schedule for later. Any ISO 8601 timestamp with a timezone (2026-04-01T14:00:00Z or 2026-04-01T16:00:00+02:00). Threads publish within ~5 minutes of the scheduled time.").option(
+  "--draft",
+  "Save without publishing. Nothing is sent, nothing counts against your quota, and any problems are listed back"
+).option("--json", "Output raw JSON").action(async (posts, opts) => {
   const client = getClient();
   let postPayload;
   let scheduleAt = opts.schedule;
@@ -375,8 +407,10 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
       process.exit(1);
     }
   } else {
-    if (posts.length < 2) {
-      error("Thread must have at least 2 posts (or use --file)");
+    if (posts.length < (opts.draft ? 1 : 2)) {
+      error(
+        opts.draft ? "Pass at least one post (or use --file)" : "Thread must have at least 2 posts (or use --file)"
+      );
       process.exit(1);
     }
     postPayload = posts.map((text) => ({ text }));
@@ -426,13 +460,15 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
         account_ids: accountIds,
         posts: postPayload,
         ...configurations ? { account_configurations: configurations } : {},
-        schedule_at: scheduleAt
+        schedule_at: scheduleAt,
+        ...opts.draft ? { draft: true } : {}
       });
       if (opts.json) {
         json(result);
         if (result.results.some((r) => !r.success)) process.exit(1);
         return;
       }
+      if ("warnings" in result) printDraftWarnings(result.warnings);
       const failed = printFanOut(
         result.group_id,
         result.results.map((r) => ({
@@ -451,10 +487,14 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
     const thread = await client.createThread({
       account_id: accountIds[0],
       posts: postPayload,
-      schedule_at: scheduleAt
+      schedule_at: scheduleAt,
+      ...opts.draft ? { draft: true } : {}
     });
     if (opts.json) {
       json(thread);
+    } else if (thread.status === "draft") {
+      success(`Draft thread saved with ${thread.posts.length} posts (${thread.id})`);
+      if ("warnings" in thread) printDraftWarnings(thread.warnings);
     } else {
       success(`Thread created with ${thread.posts.length} posts (${thread.id})`);
     }
@@ -475,17 +515,21 @@ function wantsJson(opts, cmd) {
 }
 
 // src/commands/posts.ts
-var postsCommand = new Command5("posts").description("List, get, update, or delete posts").option("--status <status>", "Filter by status").option("--account <id>", "Filter by account").option(
+var postsCommand = new Command5("posts").description("List, get, update, delete, hide or unhide posts").option(
+  "--status <status>",
+  "Filter by status: draft, scheduled, publishing, published, failed, deleted"
+).option("--account <id>", "Filter by account").option(
   "--group <id>",
   "Only the posts of one fan-out, from the group ID a multi-account post returned"
-).option("--limit <n>", "Limit results", "20").option("--json", "Output raw JSON").action(async (opts, cmd) => {
+).option("--limit <n>", "Limit results", "20").option("--include-hidden", "Include posts you have hidden").option("--json", "Output raw JSON").action(async (opts, cmd) => {
   const client = getClient();
   try {
     const posts = await client.listPosts({
       status: opts.status,
       account_id: opts.account,
       group_id: opts.group,
-      limit: parseInt(opts.limit)
+      limit: parseInt(opts.limit),
+      include_hidden: opts.includeHidden
     });
     if (wantsJson(opts, cmd)) {
       json(posts);
@@ -496,6 +540,7 @@ var postsCommand = new Command5("posts").description("List, get, update, or dele
           status: p.status,
           text: p.text.length > 50 ? p.text.slice(0, 50) + "..." : p.text,
           created: p.created_at.slice(0, 10),
+          hidden: p.hidden ? "yes" : "",
           // Why a post is not where you expected it. Empty for the ones
           // that are exactly where you left them.
           issue: postFailureReason(p) ?? ""
@@ -532,20 +577,25 @@ postsCommand.command("get <id>").description("Get a post by ID").option("--json"
   }
 });
 postsCommand.command("update <id>").description(
-  "Edit a post that has not published yet. Leaving --schedule-at out keeps the time it already has"
+  "Edit a post that has not published yet, or finish a draft. Leaving --schedule-at out keeps the time a queued post already has"
 ).option("-t, --text <text>", "Replacement post text").option(
   "-m, --media <files...>",
   "Replacement image or video files on this machine, or public URLs, following the same per-platform rules as creating a post. Pass --clear-media to remove the media instead."
 ).option("--alt <text...>", ALT_OPTION_HELP).option("--clear-media", "Remove the media from the post").option(
   "-s, --schedule-at <datetime>",
-  "New publish time. Any ISO 8601 timestamp with a timezone (2027-04-01T14:00:00Z or 2027-04-01T16:00:00+02:00). Omit it to keep the time the post already has. Rescheduling one part of a thread moves the whole thread."
+  "New publish time. Any ISO 8601 timestamp with a timezone (2027-04-01T14:00:00Z or 2027-04-01T16:00:00+02:00). Omit it to keep the time the post already has. Rescheduling one part of a thread moves the whole thread. On a draft this queues it, unless you also pass --keep-draft."
+).option(
+  "--keep-draft",
+  "Keep a draft a draft, so --schedule-at only changes the time it remembers"
 ).option("--json", "Output raw JSON").action(async (id, opts, cmd) => {
   if (opts.media && opts.clearMedia) {
     error("Pass either --media or --clear-media, not both");
     process.exit(1);
   }
-  if (!opts.text && !opts.media && !opts.clearMedia && !opts.scheduleAt) {
-    error("Nothing to change. Pass --text, --media, --clear-media or --schedule-at");
+  if (!opts.text && !opts.media && !opts.clearMedia && !opts.scheduleAt && !opts.keepDraft) {
+    error(
+      "Nothing to change. Pass --text, --media, --clear-media, --schedule-at or --keep-draft"
+    );
     process.exit(1);
   }
   const client = getClient();
@@ -555,26 +605,46 @@ postsCommand.command("update <id>").description(
       ...opts.text !== void 0 ? { text: opts.text } : {},
       ...opts.clearMedia ? { media: [] } : {},
       ...media ? { media } : {},
-      ...opts.scheduleAt ? { schedule_at: opts.scheduleAt } : {}
+      ...opts.scheduleAt ? { schedule_at: opts.scheduleAt } : {},
+      ...opts.keepDraft ? { draft: true } : {}
     });
     if (wantsJson(opts, cmd)) {
       json(post);
     } else {
       const moved = post.rescheduled_post_ids ?? [];
-      success(`Post ${post.id} updated`);
+      const promoted = post.promoted_from_draft_id ?? post.promoted_from_draft_ids?.[0];
+      success(promoted ? `Draft ${promoted} is now ${post.status}` : `Post ${post.id} updated`);
       if (opts.scheduleAt) {
         success(
           moved.length > 1 ? `Thread rescheduled for ${post.scheduled_at} (${moved.length} posts)` : `Scheduled for ${post.scheduled_at}`
         );
       }
+      if (post.warnings?.length) printDraftWarnings(post.warnings);
     }
   } catch (err) {
     apiError(err, "Failed to update post");
     process.exit(1);
   }
 });
+postsCommand.command("publish <id>").description("Publish a draft now. Every rule and the monthly quota apply").option("-t, --text <text>", "Final post text, saved before publishing").option("--json", "Output raw JSON").action(async (id, opts, cmd) => {
+  const client = getClient();
+  try {
+    const post = await client.updatePost(id, {
+      publish: true,
+      ...opts.text !== void 0 ? { text: opts.text } : {}
+    });
+    if (wantsJson(opts, cmd)) {
+      json(post);
+    } else {
+      success(`Draft ${id} published (${post.id})`);
+    }
+  } catch (err) {
+    apiError(err, "Failed to publish draft");
+    process.exit(1);
+  }
+});
 postsCommand.command("delete <id>").description(
-  "Delete a post (deleting any post of a scheduled thread cancels the thread)"
+  "Delete a post from the platform (a scheduled thread is cancelled whole; the post stays in Chirpie marked deleted)"
 ).option("--json", "Output raw JSON").action(async (id, opts, cmd) => {
   const client = getClient();
   try {
@@ -594,6 +664,42 @@ postsCommand.command("delete <id>").description(
     process.exit(1);
   }
 });
+postsCommand.command("hide <id>").description(
+  "Hide a post from your Chirpie listings (nothing reaches the platform)"
+).option("--json", "Output raw JSON").action(async (id, opts, cmd) => {
+  const client = getClient();
+  try {
+    const result = await client.hidePost(id);
+    if (wantsJson(opts, cmd)) {
+      json(result);
+    } else {
+      const n = result.hidden_ids.length;
+      success(
+        n > 1 ? `Hidden from Chirpie (${n} posts): ${result.hidden_ids.join(", ")}` : `Post ${id} hidden from Chirpie. It is unchanged on the platform.`
+      );
+    }
+  } catch (err) {
+    error(err instanceof Error ? err.message : "Failed to hide post");
+    process.exit(1);
+  }
+});
+postsCommand.command("unhide <id>").description("Put a hidden post back in your Chirpie listings").option("--json", "Output raw JSON").action(async (id, opts, cmd) => {
+  const client = getClient();
+  try {
+    const result = await client.unhidePost(id);
+    if (wantsJson(opts, cmd)) {
+      json(result);
+    } else {
+      const n = result.hidden_ids.length;
+      success(
+        n > 1 ? `Showing again (${n} posts): ${result.hidden_ids.join(", ")}` : `Post ${id} is showing again`
+      );
+    }
+  } catch (err) {
+    error(err instanceof Error ? err.message : "Failed to unhide post");
+    process.exit(1);
+  }
+});
 
 // src/commands/accounts.ts
 import { Command as Command6 } from "commander";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chirpie",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "description": "Chirpie CLI: post to social media from the command line",
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@chirpie/sdk": "^1.0.42",
+    "@chirpie/sdk": "^1.0.44",
     "commander": "^13"
   },
   "devDependencies": {