zernio-cli 0.4.0 → 0.5.0

package/claude/skills/zernio/references/zernio-workflows.md

@@ -1,58 +1,287 @@
 # Zernio Workflows
 
-## Auth
+Use these flows as recipes. Replace IDs with values from discovery commands.
 
-Use browser login for local human sessions:
+## Setup and Health
 
 ```bash
-zernio auth:login
+zernio auth:login --device-name "$(hostname)"
 zernio auth:check --pretty
+zernio doctor --connection --pretty
+zernio platforms:list --pretty
 ```
 
-Use env for agents and CI:
+For CI/agents:
 
 ```bash
 export ZERNIO_API_KEY="sk_..."
 zernio doctor --connection --pretty
 ```
 
-## Post With Media
+## Discover Workspace IDs
+
+```bash
+zernio profiles:list --pretty
+zernio accounts:list --profileId <profileId> --pretty
+zernio accounts:health --profileId <profileId> --pretty
+```
+
+When ambiguous, always ask the user which profile/account to use. Do not guess between client brands.
+
+## Profile Lifecycle
+
+```bash
+zernio profiles:create --name "Client A" --description "Launch workspace" --color "#2563eb"
+zernio profiles:update <profileId> --name "Client A Social" --isDefault false
+zernio profiles:get <profileId> --pretty
+zernio profiles:delete <profileId>
+```
+
+Delete only after explicit confirmation.
+
+## Create Posts
+
+Publish now:
+
+```bash
+zernio posts:create --text "Hello from Zernio" --accounts <accountId>
+```
+
+Schedule:
+
+```bash
+zernio posts:create \
+  --text "Launch update" \
+  --accounts <accountId1>,<accountId2> \
+  --scheduledAt "2026-06-20T09:00:00Z" \
+  --timezone "America/New_York"
+```
+
+Draft:
+
+```bash
+zernio posts:create --text "Draft copy" --accounts <accountId> --draft
+```
+
+Native X/Twitter thread:
+
+```bash
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadJson '["tweet 1","tweet 2","tweet 3"]'
+```
+
+Thread from file:
+
+```bash
+zernio posts:create \
+  --text "Thread display title" \
+  --accounts <twitterAccountId> \
+  --threadFile ./thread.txt
+```
+
+`thread.txt` can be a JSON array or plain text separated by lines containing only `---`. When thread items are present, `--text` is only for Zernio display/search; put the first published tweet in `threadItems[0]`.
+
+Native X/Twitter quote or reply:
+
+```bash
+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"
+```
+
+Use `--platformSpecificData '{"replySettings":"following"}'` for advanced X passthrough. X-specific options require only `twitter`/`x` targets.
+
+Track/retry:
+
+```bash
+zernio posts:list --status failed --limit 20 --pretty
+zernio posts:get <postId> --pretty
+zernio posts:retry <postId> --pretty
+```
+
+Debug failed post creation without exposing secrets:
+
+```bash
+zernio posts:create --text "Draft copy" --accounts <accountId> --draft --debug-safe --pretty
+```
+
+## Upload Media Then Post
 
 ```bash
 zernio media:upload ./image.jpg --pretty
 zernio posts:create \
   --text "Launch update" \
   --accounts <accountId> \
-  --media "<url-from-upload>"
+  --media "<public-url-from-upload>"
 ```
 
-Media upload is a two-step server workflow: presign, upload direct to returned URL, then use returned public URL in post payload.
+For non-post upload endpoints or raw binary endpoints, use `api:call --raw-body-file`.
 
 ## Queue Scheduling
 
-Use:
+Let Zernio assign the queue slot:
 
 ```bash
 zernio api:call createPost \
-  --body-json '{"content":"Queued","platforms":[{"platform":"twitter","accountId":"acc_123"}],"queuedFromProfile":"profile_123"}'
+  --body-json '{"content":"Queued post","platforms":[{"platform":"twitter","accountId":"acc_123"}],"queuedFromProfile":"profile_123"}' \
+  --request-id req_queue_001 \
+  --pretty
+```
+
+Optional `queueId` targets a queue. Do not feed `queue/next-slot` into `scheduledFor`; that endpoint is preview-only.
+
+## Analytics
+
+```bash
+zernio analytics:posts --profileId <profileId> --from "2026-06-01" --to "2026-06-14" --pretty
+zernio analytics:daily --platform instagram --pretty
+zernio analytics:best-time --profileId <profileId> --platform linkedin --pretty
+```
+
+For endpoint-specific metrics such as demographics or ad analytics:
+
+```bash
+zernio api:catalog --tag Analytics --search demographics --pretty
+zernio api:describe getInstagramDemographics --pretty
+zernio api:call getInstagramDemographics --query accountId=<accountId> --pretty
 ```
 
-Optional `queueId` targets a specific queue. Do not use `next-slot` as `scheduledFor`; it is preview-only.
+## Inbox, Comments, Reviews
 
-## Full API Calls
+```bash
+zernio inbox:conversations --platform instagram --limit 20 --pretty
+zernio inbox:messages <conversationId> --accountId <accountId> --pretty
+zernio inbox:send <conversationId> --accountId <accountId> --message "Thanks for reaching out"
+```
 
 ```bash
-zernio api:catalog --tag Posts --pretty
-zernio api:describe createPost --pretty
-zernio api:call createPost --body-file ./post.json --pretty
+zernio inbox:comments --accountId <accountId> --limit 20 --pretty
+zernio inbox:post-comments <postId> --accountId <accountId> --pretty
+zernio inbox:reply <postId> --accountId <accountId> --commentId <commentId> --message "Thank you"
 ```
 
-Use `--dry-run` before mutating calls when building automation.
+```bash
+zernio inbox:reviews --platform googlebusiness --minRating 1 --maxRating 3 --pretty
+zernio inbox:review-reply <reviewId> --accountId <accountId> --message "Thanks for the feedback"
+```
 
-## Common Checks
+## Contacts and CRM
 
 ```bash
-zernio platforms:list --pretty
-zernio accounts:health --pretty
-zernio api:catalog --search webhook --pretty
+zernio contacts:list --search "john" --tag vip --pretty
+zernio contacts:create --profileId <profileId> --name "John Doe" --email john@example.com
+zernio contacts:update <contactId> --tags "vip,lead" --isSubscribed true
+zernio contacts:channels <contactId> --pretty
+zernio contacts:set-field <contactId> lifecycle_stage --value lead
+zernio contacts:clear-field <contactId> lifecycle_stage
+```
+
+Bulk import:
+
+```bash
+zernio contacts:bulk-create --profileId <profileId> --accountId <accountId> --platform instagram --file ./contacts.json
+```
+
+## Broadcasts
+
+Direct message broadcast:
+
+```bash
+zernio broadcasts:create \
+  --profileId <profileId> \
+  --accountId <accountId> \
+  --platform instagram \
+  --name "Launch" \
+  --message "We just launched"
+zernio broadcasts:add-recipients <broadcastId> --contactIds <id1>,<id2>
+zernio broadcasts:send <broadcastId>
 ```
+
+WhatsApp template broadcast:
+
+```bash
+zernio broadcasts:create \
+  --profileId <profileId> \
+  --accountId <accountId> \
+  --platform whatsapp \
+  --name "Order update" \
+  --templateName order_confirmation \
+  --templateLanguage en
+zernio broadcasts:schedule <broadcastId> --scheduledAt "2026-06-20T10:00:00Z"
+zernio broadcasts:recipients <broadcastId> --status delivered --pretty
+```
+
+## Sequences
+
+```bash
+zernio sequences:create \
+  --profileId <profileId> \
+  --accountId <accountId> \
+  --platform instagram \
+  --name "Welcome Series" \
+  --stepsFile ./steps.json
+zernio sequences:activate <sequenceId>
+zernio sequences:enroll <sequenceId> --contactIds <contactId1>,<contactId2>
+zernio sequences:enrollments <sequenceId> --status active --pretty
+zernio sequences:pause <sequenceId>
+```
+
+Use `stepsFile` for multi-step JSON. Prefer `api:call updateSequence --body-file` for complex edits.
+
+## Comment-to-DM Automations
+
+```bash
+zernio automations:create \
+  --profileId <profileId> \
+  --accountId <accountId> \
+  --platformPostId <platformPostId> \
+  --name "Lead Magnet" \
+  --keywords "info,details,link" \
+  --matchMode contains \
+  --dmMessage "Here is the link you asked for" \
+  --commentReply "Check your DMs"
+```
+
+```bash
+zernio automations:update <automationId> --isActive false
+zernio automations:logs <automationId> --status sent --pretty
+```
+
+Omit `--keywords` only when the user explicitly wants every comment to trigger.
+
+## Advanced API Use Cases
+
+Use `api:*` for ads, webhooks, WhatsApp phone numbers/templates/flows/calling, workflows, usage, API keys, account groups, GMB, Discord, validation, and any endpoint not wrapped by curated commands.
+
+```bash
+zernio api:catalog --tag Ads --search campaign --pretty
+zernio api:describe createStandaloneAd --pretty
+zernio api:call createStandaloneAd --body-file ./ad.json --idempotency-key ad_req_123 --pretty
+```
+
+```bash
+zernio api:catalog --tag Webhooks --pretty
+zernio api:describe createWebhookSettings --pretty
+zernio api:call createWebhookSettings --body-file ./webhook.json --pretty
+```
+
+```bash
+zernio api:catalog --tag Workflows --pretty
+zernio api:call triggerWorkflow --path workflowId=<workflowId> --body-file ./workflow-trigger.json --pretty
+```
+
+## Dry Run Before Mutation
+
+```bash
+zernio api:call createPost --body-file ./post.json --dry-run --pretty
+```
+
+Confirm method, URL, path params, and body presence before removing `--dry-run`.

package/dist/commands/posts-create.d.ts

@@ -0,0 +1,2 @@
+import type { Argv } from 'yargs';
+export declare function registerPostCreateCommand(yargs: Argv): Argv;

package/dist/commands/posts-create.js

@@ -0,0 +1,110 @@
+import { createClient } from '../client.js';
+import { addAccountHealthDiagnostics, handlePostCreateError } from '../utils/posts-create-diagnostics.js';
+import { applyTwitterPlatformSpecificData, buildMediaItems, buildTwitterPlatformSpecificData, PostsCreateValidationError, validateTwitterPlatformSpecificData, } from '../utils/posts-create-platform-data.js';
+import { output, outputError } from '../utils/output.js';
+export function registerPostCreateCommand(yargs) {
+    return yargs.command('posts:create', 'Create or schedule a post', (y) => y
+        .option('text', { type: 'string', describe: 'Post content text', demandOption: true })
+        .option('accounts', { type: 'string', describe: 'Comma-separated account IDs', demandOption: true })
+        .option('scheduledAt', { type: 'string', describe: 'ISO 8601 date to schedule (omit to publish now)' })
+        .option('draft', { type: 'boolean', describe: 'Save as draft', default: false })
+        .option('media', { type: 'string', describe: 'Comma-separated media URLs' })
+        .option('title', { type: 'string', describe: 'Post title (YouTube, Reddit, etc.)' })
+        .option('tags', { type: 'string', describe: 'Comma-separated tags' })
+        .option('hashtags', { type: 'string', describe: 'Comma-separated hashtags' })
+        .option('timezone', { type: 'string', describe: 'Timezone (e.g. America/New_York)' })
+        .option('quoteTweetId', { type: 'string', describe: 'X/Twitter tweet ID or status URL to quote' })
+        .option('replyToTweetId', { type: 'string', describe: 'X/Twitter tweet ID to reply to' })
+        .option('replySettings', {
+        type: 'string',
+        describe: 'X/Twitter reply settings: following, mentionedUsers, subscribers, verified',
+    })
+        .option('threadJson', { type: 'string', describe: 'X/Twitter threadItems as a JSON array' })
+        .option('threadFile', { type: 'string', describe: 'X/Twitter thread file, JSON array or --- separated text' })
+        .option('platformSpecificData', {
+        type: 'string',
+        describe: 'Advanced platformSpecificData JSON object for X/Twitter targets',
+    })
+        .option('debug-safe', {
+        type: 'boolean',
+        describe: 'Include non-secret post/account diagnostics when create fails',
+        default: false,
+    }), async (argv) => {
+        let platforms = [];
+        let selectedAccounts = [];
+        try {
+            const late = createClient();
+            const { data: accountsData } = await late.accounts.listAccounts();
+            const accountIds = argv.accounts.split(',').map((s) => s.trim()).filter(Boolean);
+            const allAccounts = accountsData?.accounts || [];
+            selectedAccounts = accountIds.map((id) => {
+                const account = allAccounts.find((a) => (a._id || a.id) === id);
+                if (!account) {
+                    throw new PostsCreateValidationError(`Account ${id} not found. Run "zernio accounts:list" to see available accounts.`, 'ACCOUNT_NOT_FOUND', 404);
+                }
+                return account;
+            });
+            platforms = selectedAccounts.map((account, index) => ({
+                platform: String(account.platform),
+                accountId: accountIds[index],
+            }));
+            const mediaItems = buildMediaItems(argv.media);
+            const twitterData = buildTwitterPlatformSpecificData({
+                quoteTweetId: argv.quoteTweetId,
+                replyToTweetId: argv.replyToTweetId,
+                replySettings: argv.replySettings,
+                threadJson: argv.threadJson,
+                threadFile: argv.threadFile,
+                platformSpecificData: argv.platformSpecificData,
+            });
+            validateTwitterPlatformSpecificData(twitterData, platforms, mediaItems);
+            platforms = applyTwitterPlatformSpecificData(platforms, twitterData);
+            if (argv.debugSafe) {
+                selectedAccounts = await addAccountHealthDiagnostics(late, accountIds, selectedAccounts);
+            }
+            const body = buildCreatePostBody(argv, platforms, mediaItems);
+            const { data } = await late.posts.createPost({ body });
+            output(data, argv.pretty);
+        }
+        catch (err) {
+            if (err instanceof PostsCreateValidationError) {
+                outputError(err.message, err.status, { code: err.code }, argv.pretty);
+            }
+            handlePostCreateError(err, {
+                debugSafe: argv.debugSafe,
+                pretty: argv.pretty,
+                platforms,
+                accounts: selectedAccounts,
+            });
+        }
+    });
+}
+function buildCreatePostBody(argv, platforms, mediaItems) {
+    const body = {
+        content: argv.text,
+        platforms,
+    };
+    if (mediaItems?.length)
+        body.mediaItems = mediaItems;
+    if (argv.title)
+        body.title = argv.title;
+    if (argv.timezone)
+        body.timezone = argv.timezone;
+    if (argv.tags)
+        body.tags = csv(argv.tags);
+    if (argv.hashtags)
+        body.hashtags = csv(argv.hashtags);
+    if (argv.draft) {
+        body.isDraft = true;
+    }
+    else if (argv.scheduledAt) {
+        body.scheduledFor = argv.scheduledAt;
+    }
+    else {
+        body.publishNow = true;
+    }
+    return body;
+}
+function csv(value) {
+    return value.split(',').map((s) => s.trim()).filter(Boolean);
+}

package/dist/commands/posts.js

@@ -1,70 +1,10 @@
 import { createClient } from '../client.js';
-import { output, outputError } from '../utils/output.js';
+import { output } from '../utils/output.js';
 import { handleError } from '../utils/errors.js';
+import { registerPostCreateCommand } from './posts-create.js';
 /** Register post commands: posts:create, posts:list, posts:get, posts:delete, posts:retry */
 export function registerPostCommands(yargs) {
-    return yargs
-        .command('posts:create', 'Create or schedule a post', (y) => y
-        .option('text', { type: 'string', describe: 'Post content text', demandOption: true })
-        .option('accounts', { type: 'string', describe: 'Comma-separated account IDs', demandOption: true })
-        .option('scheduledAt', { type: 'string', describe: 'ISO 8601 date to schedule (omit to publish now)' })
-        .option('draft', { type: 'boolean', describe: 'Save as draft', default: false })
-        .option('media', { type: 'string', describe: 'Comma-separated media URLs' })
-        .option('title', { type: 'string', describe: 'Post title (YouTube, Reddit, etc.)' })
-        .option('tags', { type: 'string', describe: 'Comma-separated tags' })
-        .option('hashtags', { type: 'string', describe: 'Comma-separated hashtags' })
-        .option('timezone', { type: 'string', describe: 'Timezone (e.g. America/New_York)' }), async (argv) => {
-        try {
-            const late = createClient();
-            // Look up accounts to resolve platform types
-            const { data: accountsData } = await late.accounts.listAccounts();
-            const allAccounts = accountsData?.accounts || [];
-            const accountIds = argv.accounts.split(',').map((s) => s.trim()).filter(Boolean);
-            const platforms = accountIds.map((id) => {
-                const account = allAccounts.find((a) => (a._id || a.id) === id);
-                if (!account) {
-                    outputError(`Account ${id} not found. Run "late accounts:list" to see available accounts.`, 404);
-                }
-                return { platform: account.platform, accountId: id };
-            });
-            // Build media items
-            const mediaItems = argv.media
-                ? argv.media.split(',').map((url) => {
-                    const trimmed = url.trim();
-                    const isVideo = /\.(mp4|mov|avi|webm|m4v)$/i.test(trimmed);
-                    return { type: (isVideo ? 'video' : 'image'), url: trimmed };
-                })
-                : undefined;
-            const body = {
-                content: argv.text,
-                platforms,
-            };
-            if (mediaItems?.length)
-                body.mediaItems = mediaItems;
-            if (argv.title)
-                body.title = argv.title;
-            if (argv.timezone)
-                body.timezone = argv.timezone;
-            if (argv.tags)
-                body.tags = argv.tags.split(',').map((s) => s.trim());
-            if (argv.hashtags)
-                body.hashtags = argv.hashtags.split(',').map((s) => s.trim());
-            if (argv.draft) {
-                body.isDraft = true;
-            }
-            else if (argv.scheduledAt) {
-                body.scheduledFor = argv.scheduledAt;
-            }
-            else {
-                body.publishNow = true;
-            }
-            const { data } = await late.posts.createPost({ body });
-            output(data, argv.pretty);
-        }
-        catch (err) {
-            handleError(err);
-        }
-    })
+    return registerPostCreateCommand(yargs)
         .command('posts:list', 'List posts', (y) => y
         .option('profileId', { type: 'string', describe: 'Filter by profile ID' })
         .option('status', { type: 'string', describe: 'Filter by status (scheduled, published, failed, draft)' })

package/dist/utils/posts-create-diagnostics.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformTarget } from './posts-create-platform-data.js';
+type AccountRecord = Record<string, unknown>;
+type PostCreateErrorContext = {
+    debugSafe: boolean;
+    pretty: boolean;
+    platforms: PlatformTarget[];
+    accounts: AccountRecord[];
+};
+export declare function handlePostCreateError(err: unknown, context: PostCreateErrorContext): never;
+export declare function buildPostCreateDiagnostic(context: PostCreateErrorContext, status?: number): Record<string, unknown>;
+export declare function addAccountHealthDiagnostics(late: {
+    accounts?: {
+        getAccountHealth?: (args: {
+            path: {
+                accountId: string;
+            };
+        }) => Promise<{
+            data: unknown;
+        }>;
+    };
+}, accountIds: string[], accounts: AccountRecord[]): Promise<AccountRecord[]>;
+export {};

package/dist/utils/posts-create-diagnostics.js

@@ -0,0 +1,83 @@
+import { LateApiError } from '@zernio/node';
+import { handleError } from './errors.js';
+import { outputError } from './output.js';
+const SAFE_ACCOUNT_FIELDS = [
+    'profileId',
+    'profileName',
+    'platform',
+    'username',
+    'displayName',
+    'status',
+    'canPost',
+    'tokenValid',
+    'needsReconnect',
+    'issues',
+];
+export function handlePostCreateError(err, context) {
+    if (!context.debugSafe)
+        handleError(err);
+    const status = err instanceof LateApiError ? err.statusCode : undefined;
+    const message = err instanceof Error ? err.message : String(err);
+    outputError(message, status, {
+        code: status === 401 ? 'POST_CREATE_UNAUTHORIZED' : 'POST_CREATE_FAILED',
+        diagnostic: buildPostCreateDiagnostic(context, status),
+    }, context.pretty);
+}
+export function buildPostCreateDiagnostic(context, status) {
+    return {
+        command: 'posts:create',
+        resolvedPlatforms: context.platforms,
+        targetAccounts: context.platforms.map((target) => summarizeAccount(target, context.accounts)),
+        suggestions: suggestionsForStatus(status),
+    };
+}
+export async function addAccountHealthDiagnostics(late, accountIds, accounts) {
+    if (!late.accounts?.getAccountHealth)
+        return accounts;
+    const healthEntries = await Promise.all(accountIds.map(async (id) => {
+        try {
+            const { data } = await late.accounts.getAccountHealth({ path: { accountId: id } });
+            return [id, data];
+        }
+        catch {
+            return [id, undefined];
+        }
+    }));
+    const healthById = new Map(healthEntries.filter((entry) => isRecord(entry[1])));
+    return accounts.map((account) => {
+        const id = accountId(account);
+        return id && healthById.has(id) ? { ...account, ...healthById.get(id) } : account;
+    });
+}
+function summarizeAccount(target, accounts) {
+    const account = accounts.find((candidate) => accountId(candidate) === target.accountId) || {};
+    const summary = {
+        accountId: target.accountId,
+        platform: target.platform,
+    };
+    for (const field of SAFE_ACCOUNT_FIELDS) {
+        if (account[field] !== undefined && field !== 'platform')
+            summary[field] = account[field];
+    }
+    return summary;
+}
+function accountId(account) {
+    const id = account.id || account._id || account.accountId;
+    return id === undefined ? undefined : String(id);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function suggestionsForStatus(status) {
+    if (status === 401) {
+        return [
+            'Run zernio auth:check --pretty to verify the API key.',
+            'Run zernio accounts:health --pretty and compare the target account status.',
+            'If health is valid but create still returns 401, reconnect the account or report a backend authorization mismatch.',
+        ];
+    }
+    return [
+        'Run zernio doctor --connection --pretty to verify API connectivity.',
+        'Run the same payload with zernio api:call createPost --dry-run to inspect request shape.',
+    ];
+}

package/dist/utils/posts-create-platform-data.d.ts

@@ -0,0 +1,27 @@
+export { PostsCreateValidationError } from './posts-create-validation-error.js';
+export type MediaItem = {
+    type: 'image' | 'video';
+    url: string;
+    [key: string]: unknown;
+};
+export type PlatformTarget = {
+    platform: string;
+    accountId: string;
+    platformSpecificData?: Record<string, unknown>;
+};
+export type TwitterPlatformSpecificDataResult = {
+    hasData: boolean;
+    data?: Record<string, unknown>;
+};
+type TwitterPlatformOptions = {
+    quoteTweetId?: unknown;
+    replyToTweetId?: unknown;
+    replySettings?: unknown;
+    threadJson?: unknown;
+    threadFile?: unknown;
+    platformSpecificData?: unknown;
+};
+export declare function buildMediaItems(media?: unknown): MediaItem[] | undefined;
+export declare function buildTwitterPlatformSpecificData(options: TwitterPlatformOptions): TwitterPlatformSpecificDataResult;
+export declare function validateTwitterPlatformSpecificData(result: TwitterPlatformSpecificDataResult, platforms: PlatformTarget[], mediaItems?: MediaItem[]): void;
+export declare function applyTwitterPlatformSpecificData(platforms: PlatformTarget[], result: TwitterPlatformSpecificDataResult): PlatformTarget[];