chirpie 1.0.47 → 1.0.49

package/README.md

@@ -30,12 +30,13 @@ 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, `--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 post <text>` | Create a post. `-a` account (repeat it for several accounts), `-m` media files or URLs, `--alt` descriptions, `--config` per-account overrides, `--first-comment` a comment published under the post as soon as it goes out, `-s` schedule, `--timezone` the IANA zone a `-s` with no offset is read in, `--idempotency-key` to make a retry safe, `--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, `--first-comment` posts a comment under the last part, `--timezone` and `--idempotency-key` work as they do on a post, `-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, 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 update <id>` | Edit a post that has not published yet, or finish a draft. `--text`, `--media`, `--alt`, `--clear-media`, `--first-comment` (`""` removes it), `--schedule-at`, `--timezone`, `--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 first-comment <id>` | Post a first comment that failed, again. It re-sends the text the post already carries. `--idempotency-key` makes a retry safe |
 | `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 |
@@ -48,8 +49,8 @@ export CHIRPIE_API_KEY=chirpie_sk_...
 | `chirpie accounts connect-linkedin --pages` | Connect the LinkedIn Pages you administer, each as its own account (coming soon) |
 | `chirpie accounts connect-telegram` | Connect a Telegram bot to a channel or group |
 | `chirpie accounts x-keys set` / `status` / `remove` | Use your own X developer app |
-| `chirpie analytics <post_id>` | Engagement metrics for a published post |
-| `chirpie keys` / `keys create` / `keys revoke <id>` | Manage API keys |
+| `chirpie analytics <post_id>` | Engagement metrics for a published post. `--refresh` asks the platform now instead of reading the stored snapshot, once per post every 30 minutes |
+| `chirpie keys` / `keys create` / `keys revoke <id>` | Manage API keys. `keys create --scope posts:write --scope media:write` mints a key that can do less than yours; `chirpie keys` prints each key's scopes |
 
 Run `chirpie <command> --help` for the full option list. Threads, Instagram, Facebook, Pinterest, TikTok, YouTube and Google Business Profile are coming soon. Accounts already connected keep posting and scheduling as normal.
 
@@ -65,11 +66,26 @@ chirpie post "Look at this" -a 550e8400-e29b-41d4-a716-446655440000 -m ./shot.pn
 # Schedule. Any ISO 8601 timestamp that carries a timezone.
 chirpie post "Later" -s 2026-04-01T14:00:00Z
 
+# Or a local time, with the zone named separately. Daylight saving is worked
+# out for the date, which an offset computed today gets wrong.
+chirpie post "Half nine, my time" -s 2026-11-01T09:30 --timezone America/New_York
+
+# Make a retry safe: the same key replays the first answer for 24 hours.
+chirpie post "Shipped" --idempotency-key release-2026-11-01
+
 # A thread
 chirpie thread "One" "Two" "Three" -a 550e8400-e29b-41d4-a716-446655440000
 
 # What is queued
 chirpie posts --status scheduled
+
+# Put the link in the first comment. X, Threads, Instagram and Facebook only,
+# and it counts as one post against your monthly quota.
+chirpie post "We rebuilt scheduling this week." \
+  --first-comment "Full write-up: https://example.com/blog/scheduling"
+
+# A first comment never fails its post. Send one that did not go out again.
+chirpie posts first-comment "$POST_ID"
 ```
 
 ## Drafts

package/dist/index.js

@@ -168,6 +168,15 @@ function getClient() {
   });
 }
 
+// src/lib/flags.ts
+function wantsJson(opts, cmd) {
+  if (opts?.json) return true;
+  return Boolean(cmd?.optsWithGlobals?.().json);
+}
+function idempotency(opts) {
+  return opts?.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : void 0;
+}
+
 // src/lib/media.ts
 import { readFile } from "fs/promises";
 import { basename, resolve } from "path";
@@ -274,12 +283,18 @@ var postCommand = new Command3("post").description("Create a post").argument("<t
   "-a, --account <id>",
   "Account ID. Repeat it to publish the same post to several accounts at once (up to 25)",
   collect
-).option("-m, --media <files...>", MEDIA_OPTION_HELP).option("--alt <text...>", ALT_OPTION_HELP).option(
+).option("-m, --media <files...>", MEDIA_OPTION_HELP).option("--first-comment <text>", "Post this as a comment under the post, as soon as it goes out. X, Threads, Instagram and Facebook only. It counts as one post against your monthly quota").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(
+  'Per-account overrides as JSON, or a path to a JSON file holding them: { "<account id>": { "text": "...", "media_urls": ["..."], "first_comment": "..." } }. Every key must be an account named with --account, and "first_comment": "" publishes that account without the first comment the call is sending'
+).option("-s, --schedule <datetime>", "Schedule for later. An ISO 8601 timestamp carrying a timezone (2026-04-01T14:00:00Z or 2026-04-01T16:00:00+02:00), or a local time with no offset (2026-11-01T09:30) read in --timezone or the timezone saved on your account. 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(
+  "--timezone <iana>",
+  "The IANA timezone a --schedule with no offset is read in, such as America/New_York. Daylight saving is worked out for the date you name"
+).option(
+  "--idempotency-key <key>",
+  "Make a retry safe. The same key with the same request replays the first answer instead of sending it again, for 24 hours. One is generated per call when you do not pass one"
 ).option("--json", "Output raw JSON").action(async (text, opts) => {
   const client = getClient();
   const named = opts.account ?? [];
@@ -296,14 +311,16 @@ var postCommand = new Command3("post").description("Create a post").argument("<t
         account_ids: accountIds,
         text,
         ...media ? { media } : {},
+        ...opts.firstComment ? { first_comment: opts.firstComment } : {},
         ...opts.config ? {
           account_configurations: parseAccountConfigurations(
             opts.config
           )
         } : {},
         schedule_at: opts.schedule,
+        ...opts.timezone ? { timezone: opts.timezone } : {},
         ...opts.draft ? { draft: true } : {}
-      });
+      }, idempotency(opts));
       if (opts.json) {
         json(result);
         if (result.results.some((r) => !r.success)) process.exit(1);
@@ -329,9 +346,11 @@ var postCommand = new Command3("post").description("Create a post").argument("<t
       account_id: accountIds[0],
       text,
       ...media ? { media } : {},
+      ...opts.firstComment ? { first_comment: opts.firstComment } : {},
       schedule_at: opts.schedule,
+      ...opts.timezone ? { timezone: opts.timezone } : {},
       ...opts.draft ? { draft: true } : {}
-    });
+    }, idempotency(opts));
     if (opts.json) {
       json(post);
     } else if (post.status === "draft") {
@@ -366,7 +385,7 @@ function parseAltSpec(spec) {
     alts: m[2].split(",").map((a) => a.trim())
   };
 }
-var threadCommand = new Command4("thread").description("Create a thread").argument("[posts...]", "Thread posts (each argument is one post). Omit when using --file.").option(
+var threadCommand = new Command4("thread").description("Create a thread").argument("[posts...]", "Thread posts (each argument is one post). Omit when using --file.").option("--first-comment <text>", "Post this as a comment under the thread's last post, as soon as it goes out. X, Threads, Instagram and Facebook only. It counts as one post against your monthly quota").option(
   "-a, --account <id>",
   "Account ID. Repeat it to publish the same thread to several accounts at once (up to 25)",
   collect
@@ -381,10 +400,16 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
   "JSON file with a full thread payload: { posts: [{ text, media_urls? }, ...], schedule_at?: string }. It may also carry account_ids and account_configurations."
 ).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(
+  `Per-account overrides as JSON, or a path to a JSON file holding them: { "<account id>": { "posts": [{ "text": "one" }, { "text": "two" }], "first_comment": "..." } }. An account's posts replace the whole thread for that account, and "first_comment": "" publishes that account without the first comment the call is sending`
+).option("-s, --schedule <datetime>", "Schedule for later. An ISO 8601 timestamp carrying a timezone (2026-04-01T14:00:00Z or 2026-04-01T16:00:00+02:00), or a local time with no offset (2026-11-01T09:30) read in --timezone or the timezone saved on your account. 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(
+  "--timezone <iana>",
+  "The IANA timezone a --schedule with no offset is read in, such as America/New_York. Daylight saving is worked out for the date you name"
+).option(
+  "--idempotency-key <key>",
+  "Make a retry safe. The same key with the same request replays the first answer instead of sending it again, for 24 hours. One is generated per call when you do not pass one"
 ).option("--json", "Output raw JSON").action(async (posts, opts) => {
   const client = getClient();
   let postPayload;
@@ -459,10 +484,12 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
       const result = await client.createThread({
         account_ids: accountIds,
         posts: postPayload,
+        ...opts.firstComment ? { first_comment: opts.firstComment } : {},
         ...configurations ? { account_configurations: configurations } : {},
         schedule_at: scheduleAt,
+        ...opts.timezone ? { timezone: opts.timezone } : {},
         ...opts.draft ? { draft: true } : {}
-      });
+      }, idempotency(opts));
       if (opts.json) {
         json(result);
         if (result.results.some((r) => !r.success)) process.exit(1);
@@ -487,9 +514,11 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
     const thread = await client.createThread({
       account_id: accountIds[0],
       posts: postPayload,
+      ...opts.firstComment ? { first_comment: opts.firstComment } : {},
       schedule_at: scheduleAt,
+      ...opts.timezone ? { timezone: opts.timezone } : {},
       ...opts.draft ? { draft: true } : {}
-    });
+    }, idempotency(opts));
     if (opts.json) {
       json(thread);
     } else if (thread.status === "draft") {
@@ -507,14 +536,6 @@ var threadCommand = new Command4("thread").description("Create a thread").argume
 // src/commands/posts.ts
 import { Command as Command5 } from "commander";
 import { postFailureReason } from "@chirpie/sdk";
-
-// src/lib/flags.ts
-function wantsJson(opts, cmd) {
-  if (opts?.json) return true;
-  return Boolean(cmd?.optsWithGlobals?.().json);
-}
-
-// src/commands/posts.ts
 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"
@@ -583,7 +604,13 @@ postsCommand.command("update <id>").description(
   "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. On a draft this queues it, unless you also pass --keep-draft."
+  "New publish time. An ISO 8601 timestamp carrying a timezone (2027-04-01T14:00:00Z or 2027-04-01T16:00:00+02:00), or a local time with no offset (2027-04-01T09:30) read in --timezone or the timezone saved on your account. 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(
+  "--timezone <iana>",
+  "The IANA timezone a --schedule-at with no offset is read in, such as America/New_York"
+).option(
+  "--first-comment <text>",
+  'The comment to post under this one once it publishes. Pass "" to remove the one it has'
 ).option(
   "--keep-draft",
   "Keep a draft a draft, so --schedule-at only changes the time it remembers"
@@ -592,9 +619,9 @@ postsCommand.command("update <id>").description(
     error("Pass either --media or --clear-media, not both");
     process.exit(1);
   }
-  if (!opts.text && !opts.media && !opts.clearMedia && !opts.scheduleAt && !opts.keepDraft) {
+  if (!opts.text && !opts.media && !opts.clearMedia && opts.firstComment === void 0 && !opts.scheduleAt && !opts.keepDraft) {
     error(
-      "Nothing to change. Pass --text, --media, --clear-media, --schedule-at or --keep-draft"
+      "Nothing to change. Pass --text, --media, --clear-media, --first-comment, --schedule-at or --keep-draft"
     );
     process.exit(1);
   }
@@ -605,7 +632,9 @@ postsCommand.command("update <id>").description(
       ...opts.text !== void 0 ? { text: opts.text } : {},
       ...opts.clearMedia ? { media: [] } : {},
       ...media ? { media } : {},
+      ...opts.firstComment !== void 0 ? { first_comment: opts.firstComment } : {},
       ...opts.scheduleAt ? { schedule_at: opts.scheduleAt } : {},
+      ...opts.timezone ? { timezone: opts.timezone } : {},
       ...opts.keepDraft ? { draft: true } : {}
     });
     if (wantsJson(opts, cmd)) {
@@ -664,6 +693,25 @@ postsCommand.command("delete <id>").description(
     process.exit(1);
   }
 });
+postsCommand.command("first-comment <id>").description(
+  "Post a first comment that failed, again. Re-sends the text the post already carries"
+).option(
+  "--idempotency-key <key>",
+  "Make a retry safe. The same key replays the first answer instead of sending the comment again, for 24 hours"
+).option("--json", "Output raw JSON").action(async (id, opts, cmd) => {
+  const client = getClient();
+  try {
+    const post = await client.retryFirstComment(id, idempotency(opts));
+    if (wantsJson(opts, cmd)) {
+      json(post);
+    } else {
+      success(`First comment posted on ${post.id}`);
+    }
+  } catch (err) {
+    apiError(err, "Failed to post the first comment");
+    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) => {
@@ -1196,10 +1244,18 @@ commentsCommand.command("list").description("List the comments on a post you pub
     process.exit(1);
   }
 });
-commentsCommand.command("reply").description("Reply to a comment (counts as one post against your quota)").argument("<post_id>", "Post ID").argument("<comment_id>", "Comment ID from `chirpie comments list`").requiredOption("--text <text>", "The reply text").option("--json", "Output raw JSON").action(async (postId, commentId, opts, cmd) => {
+commentsCommand.command("reply").description("Reply to a comment (counts as one post against your quota)").argument("<post_id>", "Post ID").argument("<comment_id>", "Comment ID from `chirpie comments list`").requiredOption("--text <text>", "The reply text").option(
+  "--idempotency-key <key>",
+  "Make a retry safe. The same key with the same reply replays the first answer instead of sending it again, for 24 hours"
+).option("--json", "Output raw JSON").action(async (postId, commentId, opts, cmd) => {
   const client = getClient();
   try {
-    const reply = await client.replyToComment(postId, commentId, opts.text);
+    const reply = await client.replyToComment(
+      postId,
+      commentId,
+      opts.text,
+      idempotency(opts)
+    );
     if (wantsJson(opts, cmd)) {
       json(reply);
     } else {
@@ -1259,10 +1315,15 @@ async function confirm2(question) {
 
 // src/commands/analytics.ts
 import { Command as Command8 } from "commander";
-var analyticsCommand = new Command8("analytics").description("Get analytics for a post").argument("<post_id>", "Post ID").option("--json", "Output raw JSON").action(async (postId, opts) => {
+var analyticsCommand = new Command8("analytics").description("Get analytics for a post").argument("<post_id>", "Post ID").option(
+  "--refresh",
+  "Ask the platform now instead of reading the stored numbers. Allowed once per post every 30 minutes"
+).option("--json", "Output raw JSON").action(async (postId, opts) => {
   const client = getClient();
   try {
-    const analytics = await client.getPostAnalytics(postId);
+    const analytics = await client.getPostAnalytics(postId, {
+      refresh: Boolean(opts.refresh)
+    });
     if (opts.json) {
       json(analytics);
     } else {
@@ -1284,6 +1345,7 @@ var analyticsCommand = new Command8("analytics").description("Get analytics for
 
 // src/commands/keys.ts
 import { Command as Command9 } from "commander";
+import { API_SCOPES } from "@chirpie/sdk";
 var keysCommand = new Command9("keys").description("Manage API keys").option("--json", "Output raw JSON").action(async (opts, cmd) => {
   const client = getClient();
   try {
@@ -1296,6 +1358,9 @@ var keysCommand = new Command9("keys").description("Manage API keys").option("--
           id: k.id.slice(0, 8),
           name: k.name,
           prefix: k.key_prefix,
+          // Null scopes mean full access, which is not the same as every
+          // scope listed: it also covers anything added later.
+          scopes: k.scopes === null ? "all" : k.scopes.join(" "),
           // GET /v1/keys only ever returns live keys, so there is no
           // revoked column to show.
           expires: k.expires_at?.slice(0, 10) ?? "never",
@@ -1308,10 +1373,27 @@ var keysCommand = new Command9("keys").description("Manage API keys").option("--
     process.exit(1);
   }
 });
-keysCommand.command("create").description("Create a new API key").option("-n, --name <name>", "Key name").option("--json", "Output raw JSON").action(async (opts, cmd) => {
+keysCommand.command("create").description("Create a new API key").option("-n, --name <name>", "Key name").option(
+  "--scope <scope>",
+  `Limit what the new key can do. Repeat it for each one: ${API_SCOPES.join(", ")}. Leave it out and the key can do everything this one can`,
+  collect
+).option("--json", "Output raw JSON").action(async (opts, cmd) => {
   const client = getClient();
+  const scopes = opts.scope;
+  const unknown = (scopes ?? []).filter(
+    (scope) => !API_SCOPES.includes(scope)
+  );
+  if (unknown.length > 0) {
+    error(
+      `Not a scope: ${unknown.join(", ")}. Allowed values: ${API_SCOPES.join(", ")}`
+    );
+    process.exit(1);
+  }
   try {
-    const key = await client.createKey(opts.name);
+    const key = await client.createKey({
+      ...opts.name ? { name: opts.name } : {},
+      ...scopes ? { scopes } : {}
+    });
     if (wantsJson(opts, cmd)) {
       json(key);
     } else {
@@ -1319,6 +1401,10 @@ keysCommand.command("create").description("Create a new API key").option("-n, --
       console.log(`
   ${key.key}
 `);
+      console.log(
+        `  Scopes: ${key.scopes === null ? "all" : key.scopes.join(" ")}
+`
+      );
     }
   } catch (err) {
     error(err instanceof Error ? err.message : "Failed to create key");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chirpie",
-  "version": "1.0.47",
+  "version": "1.0.49",
   "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.44",
+    "@chirpie/sdk": "^1.0.46",
     "commander": "^13"
   },
   "devDependencies": {