zernio-cli 0.4.0 → 0.5.0

package/dist/utils/posts-create-platform-data.js

@@ -0,0 +1,103 @@
+import { parseThreadItems } from './posts-create-thread-items.js';
+import { PostsCreateValidationError } from './posts-create-validation-error.js';
+export { PostsCreateValidationError } from './posts-create-validation-error.js';
+const REPLY_SETTINGS = new Set(['following', 'mentionedUsers', 'subscribers', 'verified']);
+export function buildMediaItems(media) {
+    const urls = commaList(media);
+    if (!urls.length)
+        return undefined;
+    return urls.map((url) => ({
+        type: /\.(mp4|mov|avi|webm|m4v)$/i.test(url) ? 'video' : 'image',
+        url,
+    }));
+}
+export function buildTwitterPlatformSpecificData(options) {
+    const data = parsePlatformSpecificData(options.platformSpecificData);
+    const quoteTweetId = stringOption(options.quoteTweetId);
+    const replyToTweetId = stringOption(options.replyToTweetId);
+    const replySettings = stringOption(options.replySettings);
+    if (quoteTweetId)
+        data.quoteTweetId = quoteTweetId;
+    if (replyToTweetId)
+        data.replyToTweetId = replyToTweetId;
+    if (replySettings) {
+        if (!REPLY_SETTINGS.has(replySettings)) {
+            throw new PostsCreateValidationError('replySettings must be one of: following, mentionedUsers, subscribers, verified.', 'INVALID_REPLY_SETTINGS');
+        }
+        data.replySettings = replySettings;
+    }
+    const threadItems = parseThreadItems(options.threadJson, options.threadFile);
+    if (threadItems)
+        data.threadItems = threadItems;
+    return Object.keys(data).length ? { hasData: true, data } : { hasData: false };
+}
+export function validateTwitterPlatformSpecificData(result, platforms, mediaItems = []) {
+    if (!result.hasData || !result.data)
+        return;
+    const invalidTargets = platforms.filter((target) => !isTwitterPlatform(target.platform));
+    if (invalidTargets.length) {
+        throw new PostsCreateValidationError('X/Twitter-specific options require only twitter/x accounts.', 'TWITTER_PLATFORM_DATA_REQUIRES_TWITTER');
+    }
+    if (result.data.quoteTweetId && mediaItems.length) {
+        throw new PostsCreateValidationError('quoteTweetId cannot be combined with --media.', 'TWITTER_QUOTE_REJECTS_MEDIA');
+    }
+    if (result.data.quoteTweetId && result.data.poll) {
+        throw new PostsCreateValidationError('quoteTweetId cannot be combined with poll.', 'TWITTER_QUOTE_REJECTS_POLL');
+    }
+    if (result.data.replyToTweetId && result.data.replySettings) {
+        throw new PostsCreateValidationError('replyToTweetId cannot be combined with replySettings.', 'TWITTER_REPLY_REJECTS_REPLY_SETTINGS');
+    }
+    if (result.data.poll && mediaItems.length) {
+        throw new PostsCreateValidationError('poll cannot be combined with --media.', 'TWITTER_POLL_REJECTS_MEDIA');
+    }
+    if (result.data.threadItems && result.data.poll) {
+        throw new PostsCreateValidationError('threadItems cannot be combined with poll.', 'TWITTER_THREAD_REJECTS_POLL');
+    }
+}
+export function applyTwitterPlatformSpecificData(platforms, result) {
+    if (!result.hasData || !result.data)
+        return platforms;
+    return platforms.map((target) => ({
+        ...target,
+        platformSpecificData: {
+            ...(target.platformSpecificData || {}),
+            ...result.data,
+        },
+    }));
+}
+function parsePlatformSpecificData(input) {
+    const raw = stringOption(input);
+    if (!raw)
+        return {};
+    const parsed = parseJson(raw, '--platformSpecificData');
+    if (!isRecord(parsed) || Array.isArray(parsed)) {
+        throw new PostsCreateValidationError('--platformSpecificData must be a JSON object.', 'INVALID_PLATFORM_SPECIFIC_DATA');
+    }
+    return { ...parsed };
+}
+function parseJson(raw, optionName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new PostsCreateValidationError(`${optionName} must contain valid JSON: ${error.message}`, 'INVALID_JSON');
+    }
+}
+function stringOption(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text || undefined;
+}
+function commaList(value) {
+    const raw = stringOption(value);
+    if (!raw)
+        return [];
+    return raw.split(',').map((item) => item.trim()).filter(Boolean);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isTwitterPlatform(platform) {
+    return platform === 'twitter' || platform === 'x';
+}

package/dist/utils/posts-create-thread-items.d.ts

@@ -0,0 +1 @@
+export declare function parseThreadItems(threadJson?: unknown, threadFile?: unknown): Record<string, unknown>[] | undefined;

package/dist/utils/posts-create-thread-items.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { PostsCreateValidationError } from './posts-create-validation-error.js';
+export function parseThreadItems(threadJson, threadFile) {
+    const inline = stringOption(threadJson);
+    const file = stringOption(threadFile);
+    if (inline && file) {
+        throw new PostsCreateValidationError('Use either --threadJson or --threadFile, not both.', 'AMBIGUOUS_THREAD_INPUT');
+    }
+    if (inline)
+        return normalizeThreadItems(parseJson(inline, '--threadJson'));
+    if (!file)
+        return undefined;
+    const raw = readFileSync(file, 'utf8');
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('['))
+        return normalizeThreadItems(parseJson(trimmed, '--threadFile'));
+    return normalizeThreadItems(splitThreadFile(raw));
+}
+function normalizeThreadItems(input) {
+    if (!Array.isArray(input)) {
+        throw new PostsCreateValidationError('threadItems must be a JSON array.', 'INVALID_THREAD_ITEMS');
+    }
+    if (!input.length)
+        throw new PostsCreateValidationError('threadItems cannot be empty.', 'INVALID_THREAD_ITEMS');
+    return input.map((item, index) => {
+        if (typeof item === 'string') {
+            if (!item.trim()) {
+                throw new PostsCreateValidationError(`threadItems[${index}] content cannot be empty.`, 'INVALID_THREAD_ITEMS');
+            }
+            return { content: item };
+        }
+        if (!isRecord(item) || Array.isArray(item)) {
+            throw new PostsCreateValidationError(`threadItems[${index}] must be a string or object.`, 'INVALID_THREAD_ITEMS');
+        }
+        if (item.content !== undefined && typeof item.content !== 'string') {
+            throw new PostsCreateValidationError(`threadItems[${index}].content must be a string.`, 'INVALID_THREAD_ITEMS');
+        }
+        if (item.mediaItems !== undefined && !Array.isArray(item.mediaItems)) {
+            throw new PostsCreateValidationError(`threadItems[${index}].mediaItems must be an array.`, 'INVALID_THREAD_ITEMS');
+        }
+        if (!item.content && !item.mediaItems) {
+            throw new PostsCreateValidationError(`threadItems[${index}] must include content or mediaItems.`, 'INVALID_THREAD_ITEMS');
+        }
+        return { ...item };
+    });
+}
+function splitThreadFile(raw) {
+    const items = [];
+    let current = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === '---') {
+            pushThreadFileItem(items, current);
+            current = [];
+        }
+        else {
+            current.push(line);
+        }
+    }
+    pushThreadFileItem(items, current);
+    return items;
+}
+function pushThreadFileItem(items, lines) {
+    const content = lines.join('\n').trim();
+    if (content)
+        items.push(content);
+}
+function parseJson(raw, optionName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new PostsCreateValidationError(`${optionName} must contain valid JSON: ${error.message}`, 'INVALID_JSON');
+    }
+}
+function stringOption(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text || undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/utils/posts-create-validation-error.d.ts

@@ -0,0 +1,5 @@
+export declare class PostsCreateValidationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status?: number);
+}

package/dist/utils/posts-create-validation-error.js

@@ -0,0 +1,10 @@
+export class PostsCreateValidationError extends Error {
+    code;
+    status;
+    constructor(message, code, status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'PostsCreateValidationError';
+    }
+}

package/docs/cli.md

@@ -88,6 +88,63 @@ zernio media:upload ./photo.jpg
 
 The command implements Zernio's two-step upload: presign, direct PUT, then return public URL. Use that URL in `posts:create` or `api:call createPost`.
 
+## Posts
+
+Generic post creation:
+
+```bash
+zernio posts:create --text "Hello" --accounts <accountId>
+zernio posts:create --text "Draft" --accounts <accountId> --draft
+zernio posts:create --text "Launch" --accounts <accountId> --scheduledAt "2026-06-20T09:00:00Z"
+```
+
+Native X/Twitter fields are available on `posts:create`:
+
+```bash
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadJson '["tweet 1","tweet 2"]'
+
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadFile ./thread.txt
+
+zernio posts:create \
+  --text "my take" \
+  --accounts <twitterAccountId> \
+  --quoteTweetId "https://x.com/user/status/2061975910467698972"
+
+zernio posts:create \
+  --text "reply text" \
+  --accounts <twitterAccountId> \
+  --replyToTweetId "2061975910467698972"
+```
+
+`--threadJson` accepts a JSON array of strings or objects. Object items can include `mediaItems`, so per-tweet media stays inside the relevant thread item. `--threadFile` accepts either a JSON array or plain text separated by lines containing only `---`.
+
+When `threadItems` are present, top-level `--text` is only for Zernio display/search. It is not published as the root tweet; include the root tweet as `threadItems[0]`.
+
+Advanced X/Twitter passthrough:
+
+```bash
+zernio posts:create \
+  --text "custom x data" \
+  --accounts <twitterAccountId> \
+  --platformSpecificData '{"replySettings":"following"}'
+```
+
+X/Twitter-specific options reject non-X targets. `quoteTweetId` cannot be combined with top-level `--media`, and `replyToTweetId` cannot be combined with `replySettings`.
+
+For safe diagnostics on publish failures:
+
+```bash
+zernio posts:create --text "Draft" --accounts <accountId> --draft --debug-safe --pretty
+```
+
+`--debug-safe` includes resolved platform/account context and recovery hints without printing API keys or social tokens.
+
 ## Queue Scheduling
 
 Use `queuedFromProfile` and optional `queueId` in create-post payloads. Do not use `queue/next-slot` as the scheduled time; it is preview-only.

package/docs/development-roadmap.md

@@ -24,9 +24,10 @@ Status: Complete
 - Semantic-release stable/beta workflow.
 - NPM token based publish.
 
-## Phase 4 - Follow-Up
+## Phase 4 - Curated Command Follow-Up
 
-Status: Planned
+Status: In Progress
 
-- Enable GitHub Issues if `ck:vibe` issue tracking is required.
+- Enable GitHub Issues if `ck:vibe` issue tracking is required. Complete.
 - Add more curated commands for high-use endpoints discovered through real usage.
+- Add native X/Twitter `posts:create` support for quote, reply, threadItems, and safe publish diagnostics. Complete.

package/docs/project-changelog.md

@@ -13,3 +13,7 @@
 - Fixed `doctor --connection` so failed API checks exit non-zero for CI and scripts.
 - Added coverage-gated tests for critical agent CLI paths: `api:*`, `doctor`, `platforms`, config, request construction, parsing, output, and error handling.
 - Updated docs and skill guidance for media uploads, queue scheduling, errors, rate limits, and platforms.
+- Expanded the bundled `zernio` skill to cover all shipped curated commands, full OpenAPI fallback usage, and end-to-end agent workflows.
+- Added native X/Twitter `posts:create` options for quote tweets, replies, reply settings, thread JSON/files, and advanced `platformSpecificData`.
+- Added safe `posts:create --debug-safe` diagnostics for failed publish attempts without exposing secrets.
+- Added focused tests for X platform-specific payload mapping, validation, thread parsing, and safe 401 diagnostics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zernio-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Unofficial agent-friendly CLI for the Zernio API",
   "type": "module",
   "bin": {