@thesethrose/socialspool-cli 1.0.0

package/README.md

@@ -0,0 +1,169 @@
+# @thesethrose/socialspool-cli
+
+Agent-friendly CLI for the [SocialSpool](https://socialspool.com/) Public API.
+
+SocialSpool is a social scheduling tool for creating posts, scheduling them
+across connected publishing accounts, and checking final publish status. This
+CLI is designed for humans and coding agents that need a safe, scriptable way
+to work through the public API without using dashboard session routes.
+
+## What You Can Do
+
+- Inspect the authenticated workspace and API key scopes.
+- List connected publishing accounts.
+- Validate post content against account and platform constraints.
+- Create drafts.
+- Schedule posts for future publishing.
+- Publish posts immediately.
+- Wait for terminal publish status.
+- Inspect timelines and failure details.
+- Upload media assets when media support is enabled.
+- Manage public API webhooks when the API key has webhook scopes.
+
+## Install
+
+```bash
+npm install -g @thesethrose/socialspool-cli
+```
+
+Or run without a global install:
+
+```bash
+npx @thesethrose/socialspool-cli doctor --json
+```
+
+Requires Node.js 20.19 or newer.
+
+## Authentication
+
+Create a SocialSpool API key in the dashboard, then set it in your shell or
+agent runtime:
+
+```bash
+export SOCIALSPOOL_API_KEY=ssp_live_...
+```
+
+For scheduling agents, use these scopes:
+
+```text
+posts:read
+posts:write
+accounts:read
+```
+
+Add `webhooks:read` and `webhooks:write` only when the agent should manage
+webhooks.
+
+The default API base URL is:
+
+```text
+https://socialspool.com/api/v1
+```
+
+Override it with:
+
+```bash
+export SOCIALSPOOL_API_BASE_URL=https://socialspool.com/api/v1
+```
+
+or pass `--base-url`.
+
+Never paste API keys into prompts, logs, tickets, or generated files. Configure
+them through the runtime environment.
+
+## Verify Setup
+
+```bash
+spool me --json
+spool accounts list --json
+spool capabilities --json
+spool doctor --json
+```
+
+`doctor` checks authentication and core API reachability. If it fails, the JSON
+output includes the structured error message and request id when the API
+returned one.
+
+## Common commands
+
+List connected accounts:
+
+```bash
+spool accounts list --json
+```
+
+Validate content before scheduling:
+
+```bash
+spool posts validate \
+  --content "Hello from SocialSpool" \
+  --account acct_123 \
+  --json
+```
+
+Create and schedule a post:
+
+```bash
+spool posts create \
+  --content "Hello from SocialSpool" \
+  --account acct_123 \
+  --publish-at 2026-06-12T15:00:00.000Z \
+  --idempotency-key schedule-launch-post-20260612 \
+  --json
+```
+
+Wait for final status:
+
+```bash
+spool posts wait post_123 --json
+```
+
+Publish an existing draft now:
+
+```bash
+spool posts publish-now post_123 \
+  --account acct_123 \
+  --idempotency-key publish-now-post-123 \
+  --json
+```
+
+Cancel a scheduled post:
+
+```bash
+spool posts cancel post_123 --json
+```
+
+Inspect a post timeline:
+
+```bash
+spool posts timeline post_123 --json
+```
+
+## Status Semantics
+
+Do not treat a successful request as a successful platform publish.
+
+- `draft`: saved but not scheduled.
+- `scheduled`: accepted for future publishing.
+- `publishing`: worker is attempting to publish.
+- `published`: confirmed by the platform adapter.
+- `failed`: terminal failure with an error code/message.
+- `canceled`: scheduled publish was canceled.
+
+Only report a post as published when SocialSpool returns `published` and
+platform result data such as a platform post id or URL.
+
+## Agent skill
+
+This package includes `SKILL.md`, the SocialSpool Public API Agent skill. Give
+that file to compatible coding agents along with an API key configured in their
+runtime environment.
+
+The skill intentionally excludes admin/customer-support operations. It uses the
+public `spool` CLI only.
+
+## Links
+
+- Website: [https://socialspool.com/](https://socialspool.com/)
+- API base URL: `https://socialspool.com/api/v1`
+- OpenAPI contract: `https://socialspool.com/api/docs/openapi`

package/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: socialspool-public-api-agent
+description: Use SocialSpool to inspect a workspace, list connected publishing accounts, create drafts, schedule posts, publish immediately, cancel scheduled posts, and verify post status through the public API and spool CLI.
+version: 2.0.0
+author: SocialSpool
+metadata:
+  hermes:
+    tags: [socialspool, spool, cli, social-media, api, scheduling, agents]
+---
+
+# Skill: SocialSpool Public API Agent
+
+## Purpose
+
+Use SocialSpool to inspect a workspace, list connected publishing accounts, create drafts, schedule posts, publish immediately, cancel scheduled posts, and verify post status.
+
+## When to use
+
+Use this skill when a user asks an agent to create, schedule, publish, cancel, or inspect SocialSpool posts through the public API.
+
+## Do not use this skill for
+
+- Admin/customer-support operations, audit inspection, operations queues, or billing diagnostics (use `spool-admin` and `src/cli/spool-admin/SKILL.md` instead)
+- User suspension/reactivation
+- Workspace deletion
+- Billing repair
+- API key creation/revocation
+- Direct database access
+- Dashboard session-only routes
+- Social OAuth connection flows
+- Reading or handling social platform tokens
+- Claiming platform publish success before SocialSpool reports confirmed platform result data
+
+## Authentication
+
+- Use `SOCIALSPOOL_API_KEY`.
+- Optional override: `SOCIALSPOOL_API_BASE_URL` or `--base-url`.
+- Never print, log, summarize, or echo the API key.
+- If authentication fails, report the structured API error code and request id if present.
+
+## Required first checks
+
+Every agent workflow must start with:
+
+```bash
+spool me --json
+spool accounts list --json
+spool capabilities --json
+```
+
+## Core workflow: schedule a post
+
+1. Inspect workspace and scopes.
+2. List connected accounts.
+3. Validate content against selected account/platform constraints.
+4. Create a draft or schedule directly.
+5. Use an idempotency key for every write.
+6. Verify returned post/target status.
+7. Poll/wait until status is terminal when the user asked for confirmation.
+
+Example:
+
+```bash
+spool accounts list --json
+
+spool posts validate \
+  --content "Post content here" \
+  --account acct_123 \
+  --publish-at 2026-06-12T15:00:00.000Z \
+  --json
+
+spool posts create \
+  --content "Post content here" \
+  --account acct_123 \
+  --publish-at 2026-06-12T15:00:00.000Z \
+  --idempotency-key schedule-<stable-operation-id> \
+  --json
+
+spool posts wait post_123 --json
+```
+
+## Core workflow: publish now
+
+```bash
+spool posts create --content "Post content here" --json
+
+spool posts publish-now post_123 \
+  --account acct_123 \
+  --idempotency-key publish-now-<stable-operation-id> \
+  --json
+
+spool posts wait post_123 --json
+```
+
+## Core workflow: cancel scheduled post
+
+```bash
+spool posts cancel post_123 --json
+spool posts get post_123 --json
+```
+
+## Media workflow
+
+When attaching media, upload first, then reference returned media asset ids:
+
+```bash
+spool media config --json
+spool media upload ./image.png --json
+spool posts create --post-style text_media --content "Caption" --media-asset-ids media_123 --json
+```
+
+## Status semantics
+
+- `draft`: not scheduled, not published.
+- `scheduled`: accepted for future publishing.
+- `publishing`: worker is attempting to publish.
+- `published`: confirmed by platform adapter. Only this may be reported as published.
+- `failed`: terminal failure. Report error code/message.
+- `canceled`: no platform publish should occur.
+
+## Hard rules
+
+- Never claim publish success from a 200/202 response alone.
+- Never claim success from `scheduled`, `queued`, or `publishing`.
+- A post is published only when SocialSpool returns `published` plus platform result data such as platform post id or URL.
+- Use idempotency keys for every POST/PATCH/DELETE.
+- Retry only through public API/CLI commands.
+- Do not call admin routes.
+- Do not ask the user for social tokens.
+- Do not use dashboard-only endpoints.
+- Prefer JSON output.
+
+## Troubleshooting
+
+- Use `spool posts get <postId> --json`.
+- Use `spool posts timeline <postId> --json`.
+- For cross-workspace audit, billing, or operations investigation, use `spool-admin` instead of `spool`.
+
+## Expected agent response
+
+Return:
+
+- command(s) run
+- post id
+- selected account ids/platforms
+- idempotency key used
+- final status
+- platform URL/id when published
+- error code/message when failed
+- next required action if blocked
+
+## CLI reference
+
+```bash
+spool me --json
+spool capabilities --json
+spool doctor --json
+spool openapi --json
+spool accounts list --json
+spool posts validate --content "..." --account acct_1 --json
+spool posts list --json
+spool posts get post_123 --json
+spool posts create --content "..." --json
+spool posts schedule post_123 --account acct_1 --publish-at 2026-06-12T15:00:00.000Z --json
+spool posts publish-now post_123 --account acct_1 --json
+spool posts cancel post_123 --json
+spool posts wait post_123 --json
+spool posts timeline post_123 --json
+spool media config --json
+spool media upload ./image.png --json
+spool media delete media_123 --json
+spool webhooks list --json
+```
+
+## API base URL
+
+Default production API:
+
+```text
+https://socialspool.com/api/v1
+```
+
+OpenAPI machine contract:
+
+```text
+https://socialspool.com/api/docs/openapi
+```

package/dist/spool.js

@@ -0,0 +1,886 @@
+#!/usr/bin/env node
+
+// src/cli/spool/socialspool.ts
+import { writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// src/cli/spool/errors.ts
+class SocialSpoolApiError extends Error {
+  status;
+  body;
+  meta;
+  constructor(status, body, meta = {}) {
+    super(body.error?.message ?? `SocialSpool API request failed with HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+    this.meta = meta;
+    this.name = "SocialSpoolApiError";
+  }
+  get code() {
+    return this.body.error?.code;
+  }
+  get requestId() {
+    return this.body.error?.requestId ?? this.meta.requestId;
+  }
+  get retryAfter() {
+    return this.meta.rateLimit?.retryAfter;
+  }
+}
+
+class SocialSpoolNetworkError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SocialSpoolNetworkError";
+  }
+}
+
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+function exitCodeForError(error) {
+  if (error instanceof UsageError)
+    return 2;
+  if (error instanceof SocialSpoolNetworkError)
+    return 7;
+  if (error instanceof SocialSpoolApiError) {
+    if (error.status === 401 || error.status === 403)
+      return 4;
+    if (error.status === 400)
+      return 5;
+    if (error.status === 409)
+      return 6;
+    if (error.status === 429)
+      return 8;
+  }
+  if (error instanceof Error && error.name === "MissingApiKeyError")
+    return 3;
+  return 1;
+}
+
+// src/cli/spool/client.ts
+class SocialSpoolClient {
+  config;
+  fetchImpl;
+  constructor(config, fetchImpl = fetch) {
+    this.config = config;
+    this.fetchImpl = fetchImpl;
+  }
+  async request(path, options = {}) {
+    const url = new URL(`${this.config.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== undefined && value !== null && value !== "")
+        url.searchParams.set(key, String(value));
+    }
+    const headers = new Headers({
+      Authorization: `Bearer ${this.config.apiKey}`
+    });
+    if (options.body !== undefined)
+      headers.set("Content-Type", "application/json");
+    if (options.idempotencyKey)
+      headers.set("Idempotency-Key", options.idempotencyKey);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: options.method ?? "GET",
+        headers,
+        body: options.body === undefined ? undefined : JSON.stringify(options.body)
+      });
+    } catch (error) {
+      throw new SocialSpoolNetworkError(error instanceof Error ? error.message : "Network request failed");
+    }
+    const meta = readResponseMeta(response);
+    const parsed = await parseJson(response);
+    if (!response.ok) {
+      throw new SocialSpoolApiError(response.status, parsed && typeof parsed === "object" ? parsed : {}, meta);
+    }
+    return { data: parsed, ...meta };
+  }
+}
+async function parseJson(response) {
+  const text = await response.text();
+  if (!text.trim())
+    return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    if (!response.ok) {
+      return {
+        error: {
+          code: "INVALID_JSON",
+          message: text,
+          statusCode: response.status
+        }
+      };
+    }
+    throw new SocialSpoolNetworkError("SocialSpool API returned invalid JSON");
+  }
+}
+function readResponseMeta(response) {
+  return {
+    requestId: response.headers.get("X-Request-Id") ?? undefined,
+    rateLimit: {
+      limit: response.headers.get("X-RateLimit-Limit") ?? undefined,
+      remaining: response.headers.get("X-RateLimit-Remaining") ?? undefined,
+      reset: response.headers.get("X-RateLimit-Reset") ?? undefined,
+      retryAfter: response.headers.get("Retry-After") ?? undefined
+    }
+  };
+}
+
+// src/cli/spool/config.ts
+var DEFAULT_API_BASE_URL = "https://socialspool.com/api/v1";
+var DEFAULT_API_DOCS_URL = "https://socialspool.com/api/docs/openapi";
+
+class MissingApiKeyError extends Error {
+  constructor() {
+    super("Missing SocialSpool API key. Pass --api-key or set SOCIALSPOOL_API_KEY.");
+    this.name = "MissingApiKeyError";
+  }
+}
+function resolveConfig(options, env = process.env) {
+  const apiKey = firstNonEmpty(options.apiKey, env.SOCIALSPOOL_API_KEY);
+  if (!apiKey)
+    throw new MissingApiKeyError;
+  return {
+    apiKey,
+    baseUrl: normalizeBaseUrl(firstNonEmpty(options.baseUrl, env.SOCIALSPOOL_API_BASE_URL) ?? DEFAULT_API_BASE_URL)
+  };
+}
+function normalizeBaseUrl(value) {
+  const trimmed = value.trim();
+  if (!trimmed)
+    return DEFAULT_API_BASE_URL;
+  return trimmed.replace(/\/+$/, "");
+}
+function firstNonEmpty(...values) {
+  return values.find((value) => value?.trim())?.trim();
+}
+
+// src/cli/spool/commands.ts
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+
+// src/cli/spool/idempotency.ts
+import { createHash } from "node:crypto";
+function resolveIdempotencyKey(input) {
+  if (input.explicitKey?.trim())
+    return input.explicitKey.trim();
+  const stable = [input.command, ...input.parts.filter(Boolean)].join("|");
+  if (stable === input.command) {
+    throw new Error("Idempotency key required");
+  }
+  return `spool-${createHash("sha256").update(stable).digest("hex").slice(0, 32)}`;
+}
+
+// src/cli/spool/commands.ts
+var POST_STYLES = ["text", "text_media", "media_only", "video_only"];
+var TERMINAL_POST_STATUSES = new Set(["published", "failed", "canceled", "draft"]);
+function parseArgs(args) {
+  const command = [];
+  const options = { accounts: [], mediaAssetIds: [], eventTypes: [] };
+  for (let i = 0;i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("-")) {
+      command.push(arg);
+      continue;
+    }
+    switch (arg) {
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      case "--version":
+        options.version = true;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      case "--yes":
+      case "-y":
+        options.yes = true;
+        break;
+      case "--api-key":
+        options.apiKey = requireValue(args, ++i, arg);
+        break;
+      case "--base-url":
+        options.baseUrl = requireValue(args, ++i, arg);
+        break;
+      case "--idempotency-key":
+        options.idempotencyKey = requireValue(args, ++i, arg);
+        break;
+      case "--title":
+        options.title = requireValue(args, ++i, arg);
+        break;
+      case "--content":
+        options.content = requireValue(args, ++i, arg);
+        break;
+      case "--status":
+        options.status = requireValue(args, ++i, arg);
+        break;
+      case "--limit":
+        options.limit = parsePositiveInt(requireValue(args, ++i, arg), arg);
+        break;
+      case "--offset":
+        options.offset = parseNonNegativeInt(requireValue(args, ++i, arg), arg);
+        break;
+      case "--account":
+        options.accounts.push(requireValue(args, ++i, arg));
+        break;
+      case "--post-style":
+        options.postStyle = parsePostStyle(requireValue(args, ++i, arg), arg);
+        break;
+      case "--media-asset-id":
+        options.mediaAssetIds.push(requireValue(args, ++i, arg));
+        break;
+      case "--media-asset-ids":
+        options.mediaAssetIds.push(...parseCommaSeparatedValues(requireValue(args, ++i, arg), arg));
+        break;
+      case "--publish-at":
+        options.publishAt = requireValue(args, ++i, arg);
+        break;
+      case "--output":
+      case "-o":
+        options.output = requireValue(args, ++i, arg);
+        break;
+      case "--event-type":
+        options.eventType = requireValue(args, ++i, arg);
+        break;
+      case "--event-types":
+        options.eventTypes.push(...parseCommaSeparatedValues(requireValue(args, ++i, arg), arg));
+        break;
+      case "--q":
+        options.q = requireValue(args, ++i, arg);
+        break;
+      case "--timeout":
+        options.timeout = parsePositiveInt(requireValue(args, ++i, arg), arg);
+        break;
+      case "--interval":
+        options.interval = parsePositiveInt(requireValue(args, ++i, arg), arg);
+        break;
+      case "--url":
+        options.url = requireValue(args, ++i, arg);
+        break;
+      default:
+        throw new UsageError(`Unknown option: ${arg}`);
+    }
+  }
+  return { command, options };
+}
+async function executeCommand(client, parsed) {
+  const [root, action, id] = parsed.command;
+  const { options } = parsed;
+  if (root === "me") {
+    const response = await client.request("/me");
+    return { command: "me", response };
+  }
+  if (root === "capabilities") {
+    const response = await client.request("/capabilities");
+    return { command: "capabilities", response };
+  }
+  if (root === "doctor") {
+    const response = await runDoctor(client);
+    return { command: "doctor", response };
+  }
+  if (root === "accounts" && action === "list") {
+    const response = await client.request("/social-accounts");
+    return { command: "accounts.list", response };
+  }
+  if (root === "media") {
+    if (action === "config") {
+      const response = await client.request("/media/config");
+      return { command: "media.config", response };
+    }
+    if (action === "upload") {
+      const filePath = requireCommandValue(id, "media upload requires <path>");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "media.upload",
+        explicitKey: options.idempotencyKey,
+        parts: [filePath]
+      });
+      const response = await uploadMediaFile(client, filePath, idempotencyKey);
+      return { command: "media.upload", idempotencyKey, response };
+    }
+    if (action === "delete") {
+      const mediaAssetId = requireCommandValue(id, "media delete requires <mediaAssetId>");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "media.delete",
+        explicitKey: options.idempotencyKey,
+        parts: [mediaAssetId]
+      });
+      const response = await client.request(`/media/${encodeURIComponent(mediaAssetId)}`, {
+        method: "DELETE",
+        idempotencyKey
+      });
+      return { command: "media.delete", idempotencyKey, response };
+    }
+  }
+  if (root === "webhooks") {
+    if (action === "list") {
+      const response = await client.request("/webhooks");
+      return { command: "webhooks.list", response };
+    }
+    if (action === "create") {
+      if (!options.url)
+        throw new UsageError("webhooks create requires --url");
+      const eventTypes = options.eventTypes.length > 0 ? options.eventTypes : options.eventType ? [options.eventType] : [];
+      if (eventTypes.length === 0)
+        throw new UsageError("webhooks create requires --event-type or --event-types");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "webhooks.create",
+        explicitKey: options.idempotencyKey,
+        parts: [options.url, ...eventTypes]
+      });
+      const response = await client.request("/webhooks", {
+        method: "POST",
+        body: { url: options.url, event_types: eventTypes },
+        idempotencyKey
+      });
+      return { command: "webhooks.create", idempotencyKey, response };
+    }
+    if (action === "test") {
+      const webhookId = requireCommandValue(id, "webhooks test requires <webhookId>");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "webhooks.test",
+        explicitKey: options.idempotencyKey,
+        parts: [webhookId]
+      });
+      const response = await client.request(`/webhooks/${encodeURIComponent(webhookId)}/test`, {
+        method: "POST",
+        idempotencyKey
+      });
+      return { command: "webhooks.test", idempotencyKey, response };
+    }
+    if (action === "rotate-secret") {
+      const webhookId = requireCommandValue(id, "webhooks rotate-secret requires <webhookId>");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "webhooks.rotate-secret",
+        explicitKey: options.idempotencyKey,
+        parts: [webhookId]
+      });
+      const response = await client.request(`/webhooks/${encodeURIComponent(webhookId)}/rotate-secret`, {
+        method: "POST",
+        idempotencyKey
+      });
+      return { command: "webhooks.rotate-secret", idempotencyKey, response };
+    }
+    if (action === "delete") {
+      const webhookId = requireCommandValue(id, "webhooks delete requires <webhookId>");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "webhooks.delete",
+        explicitKey: options.idempotencyKey,
+        parts: [webhookId]
+      });
+      const response = await client.request(`/webhooks/${encodeURIComponent(webhookId)}`, {
+        method: "DELETE",
+        idempotencyKey
+      });
+      return { command: "webhooks.delete", idempotencyKey, response };
+    }
+  }
+  if (root === "posts") {
+    if (action === "list") {
+      const response = await client.request("/posts", {
+        query: {
+          status: options.status,
+          limit: options.limit,
+          offset: options.offset
+        }
+      });
+      return { command: "posts.list", response };
+    }
+    if (action === "get") {
+      const postId = requireCommandValue(id, "posts get requires <postId>");
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}`);
+      return { command: "posts.get", response };
+    }
+    if (action === "timeline") {
+      const postId = requireCommandValue(id, "posts timeline requires <postId>");
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}/timeline`);
+      return { command: "posts.timeline", response };
+    }
+    if (action === "wait") {
+      const postId = requireCommandValue(id, "posts wait requires <postId>");
+      const response = await waitForPost(client, postId, options.timeout ?? 300, options.interval ?? 5);
+      return { command: "posts.wait", response };
+    }
+    if (action === "validate") {
+      if (!options.content && options.mediaAssetIds.length === 0) {
+        throw new UsageError("posts validate requires --content or --media-asset-ids");
+      }
+      if (options.accounts.length === 0)
+        throw new UsageError("posts validate requires --account");
+      const body = {
+        content: options.content ?? "",
+        social_account_ids: options.accounts
+      };
+      if (options.postStyle !== undefined)
+        body.post_style = options.postStyle;
+      if (options.mediaAssetIds.length > 0)
+        body.media_asset_ids = options.mediaAssetIds;
+      if (options.publishAt !== undefined) {
+        rejectReservedPublishAt(options.publishAt);
+        body.publish_at = options.publishAt;
+      }
+      const response = await client.request("/posts/validate", { method: "POST", body });
+      return { command: "posts.validate", response };
+    }
+    if (action === "create") {
+      if (!options.content && options.mediaAssetIds.length === 0) {
+        throw new UsageError("posts create requires --content or --media-asset-ids");
+      }
+      const body = { content: options.content ?? "" };
+      if (options.title !== undefined)
+        body.title = options.title;
+      if (options.postStyle !== undefined)
+        body.post_style = options.postStyle;
+      if (options.mediaAssetIds.length > 0)
+        body.media_asset_ids = options.mediaAssetIds;
+      if (options.accounts.length > 0)
+        body.social_account_ids = options.accounts;
+      if (options.publishAt !== undefined) {
+        rejectReservedPublishAt(options.publishAt);
+        if (options.accounts.length === 0) {
+          throw new UsageError("--account is required when --publish-at is provided");
+        }
+        body.publish_at = options.publishAt;
+      }
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "posts.create",
+        explicitKey: options.idempotencyKey,
+        parts: [
+          String(body.content),
+          String(body.post_style ?? ""),
+          JSON.stringify(body.social_account_ids ?? []),
+          String(body.publish_at ?? ""),
+          JSON.stringify(body.media_asset_ids ?? [])
+        ]
+      });
+      const response = await client.request("/posts", {
+        method: "POST",
+        body,
+        idempotencyKey
+      });
+      return { command: "posts.create", idempotencyKey, response };
+    }
+    if (action === "update") {
+      const postId = requireCommandValue(id, "posts update requires <postId>");
+      const body = {};
+      if (options.content !== undefined)
+        body.content = options.content;
+      if (options.title !== undefined)
+        body.title = options.title;
+      if (options.postStyle !== undefined)
+        body.post_style = options.postStyle;
+      if (Object.keys(body).length === 0)
+        throw new UsageError("posts update requires --content, --title, or --post-style");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "posts.update",
+        explicitKey: options.idempotencyKey,
+        parts: [postId, JSON.stringify(body)]
+      });
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}`, {
+        method: "PATCH",
+        body,
+        idempotencyKey
+      });
+      return { command: "posts.update", idempotencyKey, response };
+    }
+    if (action === "delete") {
+      const postId = requireCommandValue(id, "posts delete requires <postId>");
+      if (!options.yes)
+        throw new UsageError("posts delete requires --yes");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "posts.delete",
+        explicitKey: options.idempotencyKey,
+        parts: [postId]
+      });
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}`, {
+        method: "DELETE",
+        idempotencyKey
+      });
+      return { command: "posts.delete", idempotencyKey, response };
+    }
+    if (action === "schedule") {
+      const postId = requireCommandValue(id, "posts schedule requires <postId>");
+      if (options.accounts.length === 0)
+        throw new UsageError("posts schedule requires --account");
+      if (!options.publishAt)
+        throw new UsageError("posts schedule requires --publish-at");
+      rejectReservedPublishAt(options.publishAt);
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "posts.schedule",
+        explicitKey: options.idempotencyKey,
+        parts: [postId, ...options.accounts, options.publishAt]
+      });
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}/schedule`, {
+        method: "POST",
+        body: { social_account_ids: options.accounts, publish_at: options.publishAt },
+        idempotencyKey
+      });
+      return { command: "posts.schedule", idempotencyKey, response };
+    }
+    if (action === "publish-now") {
+      const postId = requireCommandValue(id, "posts publish-now requires <postId>");
+      if (options.accounts.length === 0)
+        throw new UsageError("posts publish-now requires --account");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "posts.publish-now",
+        explicitKey: options.idempotencyKey,
+        parts: [postId, ...options.accounts]
+      });
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}/publish-now`, {
+        method: "POST",
+        body: { social_account_ids: options.accounts },
+        idempotencyKey
+      });
+      return { command: "posts.publish-now", idempotencyKey, response };
+    }
+    if (action === "cancel") {
+      const postId = requireCommandValue(id, "posts cancel requires <postId>");
+      const idempotencyKey = resolveIdempotencyKey({
+        command: "posts.cancel",
+        explicitKey: options.idempotencyKey,
+        parts: [postId]
+      });
+      const response = await client.request(`/posts/${encodeURIComponent(postId)}/cancel`, {
+        method: "POST",
+        idempotencyKey
+      });
+      return { command: "posts.cancel", idempotencyKey, response };
+    }
+  }
+  throw new UsageError(parsed.command.length ? `Unknown command: ${parsed.command.join(" ")}` : "Missing command");
+}
+async function runDoctor(client) {
+  const checks = [];
+  try {
+    const me = await client.request("/me");
+    checks.push({ name: "auth", ok: true, scopes: me.data.api_key?.scopes ?? [] });
+  } catch (error) {
+    checks.push({ name: "auth", ok: false, error: error instanceof Error ? error.message : String(error) });
+    return { data: { ok: false, checks } };
+  }
+  try {
+    const capabilities = await client.request("/capabilities");
+    checks.push({ name: "capabilities", ok: true, features: capabilities.data.features });
+  } catch (error) {
+    checks.push({ name: "capabilities", ok: false, error: error instanceof Error ? error.message : String(error) });
+  }
+  return { data: { ok: checks.every((check) => check.ok), checks } };
+}
+async function waitForPost(client, postId, timeoutSeconds, intervalSeconds) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let latest = await client.request(`/posts/${encodeURIComponent(postId)}`);
+  while (Date.now() < deadline) {
+    const post = latest.data.post;
+    const statuses = [post?.status, ...post?.targets?.map((target) => target.status) ?? []].filter(Boolean);
+    if (statuses.every((status) => TERMINAL_POST_STATUSES.has(String(status)))) {
+      return latest;
+    }
+    await sleep(intervalSeconds * 1000);
+    latest = await client.request(`/posts/${encodeURIComponent(postId)}`);
+  }
+  return latest;
+}
+async function uploadMediaFile(client, filePath, idempotencyKey) {
+  const fileStats = await stat(filePath);
+  if (!fileStats.isFile())
+    throw new UsageError(`Not a file: ${filePath}`);
+  const fileBytes = await readFile(filePath);
+  const fileName = basename(filePath);
+  const mimeType = guessMimeType(fileName);
+  const created = await client.request("/media/uploads", {
+    method: "POST",
+    body: {
+      file_name: fileName,
+      mime_type: mimeType,
+      size_bytes: fileStats.size
+    },
+    idempotencyKey
+  });
+  const upload = created.data.upload;
+  const putResponse = await fetch(upload.url, {
+    method: upload.method,
+    headers: upload.headers,
+    body: new Blob([fileBytes], { type: mimeType })
+  });
+  if (!putResponse.ok) {
+    await client.request(`/media/${encodeURIComponent(created.data.media_asset.id)}/upload-failure`, {
+      method: "POST",
+      idempotencyKey: `${idempotencyKey}-failure`
+    });
+    throw new UsageError(`Media upload failed with HTTP ${putResponse.status}`);
+  }
+  return client.request(`/media/${encodeURIComponent(created.data.media_asset.id)}/confirm-upload`, {
+    method: "POST",
+    idempotencyKey: `${idempotencyKey}-confirm`
+  });
+}
+function guessMimeType(fileName) {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith(".png"))
+    return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg"))
+    return "image/jpeg";
+  if (lower.endsWith(".gif"))
+    return "image/gif";
+  if (lower.endsWith(".webp"))
+    return "image/webp";
+  if (lower.endsWith(".mp4"))
+    return "video/mp4";
+  if (lower.endsWith(".mov"))
+    return "video/quicktime";
+  return "application/octet-stream";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchOpenApi(options, fetchImpl = fetch) {
+  const docsUrl = options.baseUrl ? `${new URL(normalizeBaseUrl(options.baseUrl)).origin}/api/docs/openapi` : DEFAULT_API_DOCS_URL;
+  const response = await fetchImpl(docsUrl);
+  return response.json();
+}
+function requireValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith("-"))
+    throw new UsageError(`${flag} requires a value`);
+  return value;
+}
+function requireCommandValue(value, message) {
+  if (!value)
+    throw new UsageError(message);
+  return value;
+}
+function parsePositiveInt(value, flag) {
+  const numberValue = Number(value);
+  if (!Number.isInteger(numberValue) || numberValue < 1)
+    throw new UsageError(`${flag} must be a positive integer`);
+  return numberValue;
+}
+function parseNonNegativeInt(value, flag) {
+  const numberValue = Number(value);
+  if (!Number.isInteger(numberValue) || numberValue < 0)
+    throw new UsageError(`${flag} must be a non-negative integer`);
+  return numberValue;
+}
+function parsePostStyle(value, flag) {
+  if (POST_STYLES.includes(value))
+    return value;
+  throw new UsageError(`${flag} must be one of: ${POST_STYLES.join(", ")}`);
+}
+function parseCommaSeparatedValues(value, flag) {
+  const values = value.split(",").map((item) => item.trim()).filter(Boolean);
+  if (values.length === 0)
+    throw new UsageError(`${flag} requires at least one id`);
+  return values;
+}
+function rejectReservedPublishAt(value) {
+  if (value === "next-free-slot") {
+    throw new UsageError("--publish-at next-free-slot is reserved and currently rejected by the API");
+  }
+}
+
+// src/cli/spool/format.ts
+function formatSuccess(payload, json = false) {
+  if (json) {
+    return `${JSON.stringify({
+      ok: true,
+      command: payload.command,
+      ...payload.idempotencyKey ? { idempotency_key: payload.idempotencyKey } : {},
+      ...payload.requestId ? { request_id: payload.requestId } : {},
+      ...payload.rateLimit ? { rate_limit: payload.rateLimit } : {},
+      result: payload.result
+    }, null, 2)}
+`;
+  }
+  return `${formatHuman(payload.result)}
+`;
+}
+function formatError(error, status, json = false) {
+  if (json) {
+    if (error instanceof SocialSpoolApiError) {
+      return `${JSON.stringify({
+        ok: false,
+        status: error.status,
+        error: error.body.error,
+        ...error.requestId ? { request_id: error.requestId } : {},
+        ...error.retryAfter ? { retry_after: error.retryAfter } : {}
+      }, null, 2)}
+`;
+    }
+    return `${JSON.stringify({
+      ok: false,
+      status,
+      error: { message: error instanceof Error ? error.message : String(error) }
+    }, null, 2)}
+`;
+  }
+  if (error instanceof SocialSpoolApiError) {
+    const requestId = error.requestId ? ` (${error.requestId})` : "";
+    const retryAfter = error.retryAfter ? ` retry-after=${error.retryAfter}s` : "";
+    return `${error.body.error?.code ?? "API_ERROR"}: ${error.message}${requestId}${retryAfter}
+`;
+  }
+  return `${error instanceof Error ? error.message : String(error)}
+`;
+}
+function formatHuman(data) {
+  if (data && typeof data === "object") {
+    if ("workspace" in data && "api_key" in data) {
+      const value = data;
+      return [
+        `Workspace: ${value.workspace.name} (${value.workspace.plan})`,
+        `Workspace ID: ${value.workspace.id}`,
+        `API key: ${value.api_key.name} (${value.api_key.id})`,
+        `Scopes: ${value.api_key.scopes.join(", ")}`
+      ].join(`
+`);
+    }
+    if ("features" in data && "limits" in data && "workspace" in data) {
+      const value = data;
+      const enabled = Object.entries(value.features).filter(([, on]) => on).map(([name]) => name).join(", ");
+      return [`Workspace: ${value.workspace.name} (${value.workspace.plan})`, `Features: ${enabled}`].join(`
+`);
+    }
+    if ("results" in data && Array.isArray(data.results)) {
+      const value = data;
+      if (value.results.length === 0)
+        return "No results.";
+      return value.results.map((item) => {
+        const id = item.id ? ` ${item.id}` : "";
+        const label = item.username ?? item.title ?? item.content ?? item.platform ?? "item";
+        const status = item.status ? ` [${item.status}]` : "";
+        return `- ${String(label)}${id}${status}`;
+      }).join(`
+`);
+    }
+    if ("post" in data) {
+      const post = data.post;
+      return [
+        `Post: ${String(post.id)}`,
+        `Status: ${String(post.status)}`,
+        post.title ? `Title: ${String(post.title)}` : undefined,
+        `Content: ${String(post.content)}`
+      ].filter(Boolean).join(`
+`);
+    }
+  }
+  return JSON.stringify(data, null, 2);
+}
+
+// src/cli/spool/socialspool.ts
+var VERSION = "1.0.0";
+async function runSpoolCli(args, env = process.env, fetchImpl = fetch) {
+  const parsed = parseArgs(args);
+  if (parsed.options.help)
+    return { exitCode: 0, stdout: helpText() };
+  if (parsed.options.version)
+    return { exitCode: 0, stdout: `spool ${VERSION}
+` };
+  try {
+    if (parsed.command[0] === "openapi") {
+      const data = await fetchOpenApi({ baseUrl: parsed.options.baseUrl }, fetchImpl);
+      if (parsed.options.output) {
+        await writeFile(parsed.options.output, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+        return { exitCode: 0, stdout: `Wrote OpenAPI docs to ${parsed.options.output}
+` };
+      }
+      return {
+        exitCode: 0,
+        stdout: formatSuccess({ command: "openapi", result: data }, parsed.options.json)
+      };
+    }
+    const config = resolveConfig(parsed.options, env);
+    const client = new SocialSpoolClient(config, fetchImpl);
+    const executed = await executeCommand(client, parsed);
+    return {
+      exitCode: 0,
+      stdout: formatSuccess({
+        command: executed.command,
+        idempotencyKey: executed.idempotencyKey,
+        requestId: executed.response.requestId,
+        rateLimit: executed.response.rateLimit,
+        result: executed.response.data
+      }, parsed.options.json)
+    };
+  } catch (error) {
+    return {
+      exitCode: exitCodeForError(error),
+      stderr: formatError(error, undefined, parsed.options.json)
+    };
+  }
+}
+function helpText() {
+  return `spool ${VERSION}
+
+Agent-friendly CLI for the SocialSpool Public API.
+
+Usage:
+  spool [global options] <command> [command options]
+
+Global options:
+  --api-key <key>          SocialSpool API key. Defaults to SOCIALSPOOL_API_KEY.
+  --base-url <url>         API base URL. Defaults to https://socialspool.com/api/v1.
+  --json                   Emit machine-readable JSON.
+  --idempotency-key <key>  Override auto-generated idempotency key for writes.
+  --help, -h               Show this help.
+  --version                Show CLI version.
+
+Core commands:
+  me
+  capabilities
+  doctor
+  openapi [--output openapi.json]
+  accounts list
+  posts list [--status status] [--limit 20] [--offset 0]
+  posts get <postId>
+  posts validate --content <text> --account <id> [--publish-at ISO|now] [--post-style style] [--media-asset-ids ids] --json
+  posts create [--content <text>] [--title <title>] [--post-style text|text_media|media_only|video_only] [--media-asset-ids <id,id>] [--account <id>...] [--publish-at now|ISO] [--idempotency-key <key>]
+  posts update <postId> [--content <text>] [--title <title>] [--post-style style]
+  posts delete <postId> --yes
+  posts schedule <postId> --account <id>... --publish-at <ISO> [--idempotency-key <key>]
+  posts publish-now <postId> --account <id>... [--idempotency-key <key>]
+  posts cancel <postId>
+  posts wait <postId> [--timeout 300] [--interval 5]
+  posts timeline <postId>
+  media config
+  media upload <path>
+  media delete <mediaAssetId>
+  webhooks list
+  webhooks create --url <url> --event-type <type>|--event-types <a,b>
+  webhooks test <webhookId>
+  webhooks rotate-secret <webhookId>
+  webhooks delete <webhookId>
+
+Examples:
+  SOCIALSPOOL_API_KEY=ssp_live_xxx spool me --json
+  SOCIALSPOOL_API_KEY=ssp_live_xxx spool capabilities --json
+  SOCIALSPOOL_API_KEY=ssp_live_xxx spool accounts list --json
+  SOCIALSPOOL_API_KEY=ssp_live_xxx spool posts validate --content "Hello" --account acct_1 --json
+  SOCIALSPOOL_API_KEY=ssp_live_xxx spool posts create --content "Hello from an agent" --json
+  SOCIALSPOOL_API_KEY=ssp_live_xxx spool posts wait post_123 --json
+`;
+}
+function isMainModule(metaUrl) {
+  const entrypoint = process.argv[1];
+  if (!entrypoint)
+    return false;
+  return realpathSync(entrypoint) === realpathSync(fileURLToPath(metaUrl));
+}
+if (isMainModule(import.meta.url)) {
+  const result = await runSpoolCli(process.argv.slice(2));
+  if (result.stdout)
+    process.stdout.write(result.stdout);
+  if (result.stderr)
+    process.stderr.write(result.stderr);
+  process.exit(result.exitCode);
+}
+export {
+  runSpoolCli,
+  helpText
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@thesethrose/socialspool-cli",
+  "version": "1.0.0",
+  "description": "Agent-friendly CLI for the SocialSpool Public API.",
+  "type": "module",
+  "bin": {
+    "spool": "dist/spool.js"
+  },
+  "exports": {
+    ".": "./dist/spool.js",
+    "./package.json": "./package.json",
+    "./SKILL.md": "./SKILL.md"
+  },
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}