juzpost-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiiva Durai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# juzpost-cli
+
+CLI for [JuzPost](https://www.juzpost.com) — login and smart-schedule clips from the terminal.
+Shells out from the ASMR clipper: `queue draft → juzpost schedule --group <name> --min-per-day <N>`.
+
+> **Skeleton.** Command tree is wired; backend endpoints under `/api/cli/v1/*` are not built
+> yet (see the prerequisite milestone in the JuzPost repo). Commands will 404 until they land.
+
+## Setup
+
+```bash
+npm install
+npm run dev -- --help     # run from source (Node 22 type-stripping via tsx)
+npm test                  # config store self-check
+npm run build && node dist/index.js --help
+```
+
+## Auth model
+
+- `juzpost auth login` — browser device-code flow; stores a revocable CLI token.
+  Single login method by design (no paste-token path).
+- Tokens are tagged (`type=cli` + browser/device) and **revocable in JuzPost settings**
+  (hard delete → next request 401). Manual API keys stay in the dashboard, unchanged.
+- The CLI only talks to the **token-only** `/api/cli/v1/*` namespace.
+
+## Commands (skeleton)
+
+| Command | Purpose | Backend |
+|---|---|---|
+| `auth login` / `logout [--revoke]` / `whoami` | device-code login, identity | NEW |
+| `account status` | plan + paid-tier entitlements | NEW (`/me`) |
+| `accounts [--platform/--group-id]` | list connected social accounts | reuse |
+| `groups [--name]` | list channel groups (account presets) | reuse |
+| `workspace` | timezone + default times | reuse |
+| `posts list [--status/--account-id/--from/--to]` | list posts (cursor pagination) | NEW (list route) |
+| `posts create [--file/--content/--title/--hashtags…]` | upload media + create draft | NEW |
+| `posts schedule <id> --account [--at]` | schedule one draft (low-level) | reuse `/posts/:id/schedule` |
+| `schedule --group --min-per-day [--dry-run]` | smart-spread drafts across days | NEW + reuse `/posts/schedule` |
+
+List commands share `--limit/--cursor/--sort/--order/--all` (cursor pagination, spec §3).
+
+Config lives at `$XDG_CONFIG_HOME/juzpost/config.json` (`~/.config/juzpost`).
+Override base url with `--base <url>` or `JUZPOST_URL`.

package/dist/api.js

@@ -0,0 +1,64 @@
+// Thin HTTP client for the token-only /api/cli/v1/* namespace.
+// ponytail: native fetch (Node 22), no axios. Token from config, Bearer auth.
+import { baseUrl, loadConfig } from './config.js';
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export async function api(path, opts = {}) {
+    const { method = 'GET', body, query, auth = true } = opts;
+    const url = new URL(path.replace(/^\//, ''), baseUrl().replace(/\/?$/, '/'));
+    for (const [k, v] of Object.entries(query ?? {})) {
+        if (v !== undefined)
+            url.searchParams.set(k, String(v));
+    }
+    const headers = { 'content-type': 'application/json' };
+    if (auth) {
+        const token = loadConfig().token;
+        if (!token)
+            throw new ApiError(401, 'Not logged in. Run `juzpost auth login`.');
+        headers.authorization = `Bearer ${token}`;
+    }
+    const res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+    const text = await res.text();
+    const data = text ? safeJson(text) : undefined;
+    if (!res.ok) {
+        // /api/cli/v1/* returns { error: { code, message } }; the forwarded schedule routes
+        // return { error: "string" }. Handle both shapes.
+        const errField = data?.error;
+        const msg = typeof errField === 'string'
+            ? errField
+            : errField?.message || res.statusText || 'request failed';
+        throw new ApiError(res.status, `${msg} (HTTP ${res.status})`);
+    }
+    return data;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+/** Fetch a single page of a list endpoint. */
+export function apiList(path, params = {}) {
+    return api(path, { query: params });
+}
+/**
+ * Follow `nextCursor` until exhausted or `max` rows collected.
+ * ponytail: hard cap (default 1000) so a runaway server can't loop us forever.
+ */
+export async function apiListAll(path, params = {}, max = 1000) {
+    const out = [];
+    let cursor = params.cursor;
+    do {
+        const page = await apiList(path, { ...params, cursor });
+        out.push(...page.data);
+        cursor = page.pagination.hasMore ? page.pagination.nextCursor ?? undefined : undefined;
+    } while (cursor && out.length < max);
+    return out.slice(0, max);
+}

package/dist/auth.js

@@ -0,0 +1,58 @@
+// Auth flows: device-code login, logout, whoami. Logic lives here (not in the command
+// wiring) so it's unit-testable with a mocked fetch + injectable sleep.
+import { api, ApiError } from './api.js';
+import { saveConfig, clearToken, loadConfig } from './config.js';
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Device-code login: start → print verify URL → poll auth/token until approved.
+ * Polls handle `428 pending` (keep waiting) and `410 gone` (expired). Stores the token.
+ */
+export async function login(opts = {}) {
+    const sleep = opts.sleep ?? realSleep;
+    const start = await api('/api/cli/v1/auth/start', { method: 'POST', auth: false, body: { deviceName: opts.deviceName } });
+    opts.onPrompt?.(start.verifyUrl);
+    const interval = start.interval ?? 3;
+    const maxWait = opts.maxWaitSec ?? start.expiresIn ?? 600;
+    let waited = 0;
+    while (waited < maxWait) {
+        await sleep(interval * 1000);
+        waited += interval;
+        try {
+            const r = await api('/api/cli/v1/auth/token', {
+                method: 'POST',
+                auth: false,
+                body: { deviceCode: start.deviceCode },
+            });
+            if (r.token) {
+                saveConfig({ token: r.token });
+                return { token: r.token };
+            }
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 428)
+                continue; // pending approval
+            if (e instanceof ApiError && e.status === 410)
+                throw new Error('Login code expired. Run `juzpost auth login` again.');
+            throw e;
+        }
+    }
+    throw new Error('Login timed out waiting for browser approval.');
+}
+/** Clear the local token; with `revoke`, also hard-delete the server-side row first. */
+export async function logout(opts = {}) {
+    if (opts.revoke && loadConfig().token) {
+        try {
+            await api('/api/cli/v1/auth/token', { method: 'DELETE' });
+        }
+        catch {
+            // best-effort: a revoked/expired token still gets cleared locally below
+        }
+    }
+    clearToken();
+}
+/** Identity behind the stored token, or null if logged out. */
+export function whoami() {
+    if (!loadConfig().token)
+        return null;
+    return api('/api/cli/v1/me');
+}

package/dist/config.js

@@ -0,0 +1,39 @@
+// Token + base-url store. Plain JSON at $XDG_CONFIG_HOME/juzpost/config.json
+// (defaults to ~/.config/juzpost). ponytail: fs + JSON, not a config library.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+const DEFAULT_BASE = 'https://www.juzpost.com';
+function dir() {
+    return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'juzpost');
+}
+export function configPath() {
+    return join(dir(), 'config.json');
+}
+export function loadConfig() {
+    const p = configPath();
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return {}; // ponytail: corrupt file = treat as empty, login rewrites it
+    }
+}
+export function saveConfig(patch) {
+    const next = { ...loadConfig(), ...patch };
+    mkdirSync(dir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+    return next;
+}
+export function clearToken() {
+    const cfg = loadConfig();
+    delete cfg.token;
+    mkdirSync(dir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+}
+/** Resolution order: --base flag (via env we set) > config file > prod default. */
+export function baseUrl() {
+    return process.env.JUZPOST_URL || loadConfig().baseUrl || DEFAULT_BASE;
+}

package/dist/index.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// JuzPost CLI — command tree mirrors the Higgsfield CLI shape (subcommand groups,
+// global --json, --wait-style polling). Talks to the token-only /api/cli/v1/* namespace.
+// Backend endpoints live in the JuzPost repo's /api/cli/v1/* namespace.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { Command } from 'commander';
+import { api, ApiError } from './api.js';
+import { saveConfig } from './config.js';
+import { render } from './output.js';
+import * as auth from './auth.js';
+import { runList } from './list.js';
+import { uploadMedia } from './upload.js';
+// Single source of truth for the version — ../package.json (resolves from both dist/ and src/).
+const { version } = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '../package.json'), 'utf8'));
+const program = new Command();
+program
+    .name('juzpost')
+    .description('Schedule clips to JuzPost from the terminal')
+    .version(version)
+    .option('--json', 'print raw JSON responses')
+    .option('--base <url>', 'override API base url (persists to config)');
+// --base is sugar for persisting baseUrl before any command runs.
+program.hook('preAction', (thisCmd) => {
+    const base = thisCmd.opts().base;
+    if (base)
+        saveConfig({ baseUrl: base });
+});
+const out = (data) => console.log(render(data, !!program.opts().json));
+// Attach the shared cursor-pagination flags to a list command.
+const withListOpts = (c) => c
+    .option('--limit <n>', 'page size (1–100)')
+    .option('--cursor <c>', 'pagination cursor from a previous page')
+    .option('--sort <field>', 'sort field')
+    .option('--order <dir>', 'asc | desc')
+    .option('--all', 'follow cursors and return everything');
+const printList = (r) => {
+    if (program.opts().json)
+        return console.log(JSON.stringify(r, null, 2));
+    console.log(render(r.data, false));
+    if (r.hasMore && r.nextCursor)
+        console.log(`\n… more — pass --cursor ${r.nextCursor} (or --all)`);
+};
+// ── auth ─────────────────────────────────────────────────────────────────────
+const authCmd = program.command('auth').description('Login, logout, identity');
+authCmd
+    .command('login')
+    .description('Browser device-code login; stores a revocable CLI token')
+    .option('--device-name <name>', 'label this token in JuzPost settings')
+    .action(async (opts) => {
+    // Single login method by design — no paste-token path. Manual tokens stay in the dashboard.
+    await auth.login({
+        deviceName: opts.deviceName,
+        onPrompt: (url) => console.log(`Open this URL in your browser to approve:\n  ${url}\n`),
+    });
+    out('Logged in. Token stored (revoke anytime in JuzPost settings).');
+});
+authCmd
+    .command('logout')
+    .description('Clear the stored token locally')
+    .option('--revoke', 'also hard-delete the token server-side')
+    .action(async (opts) => {
+    await auth.logout({ revoke: opts.revoke });
+    out(opts.revoke ? 'Logged out and token revoked.' : 'Logged out (token still valid server-side until deleted in settings).');
+});
+authCmd
+    .command('whoami')
+    .description('Show the identity behind the stored token')
+    .action(async () => {
+    const me = auth.whoami();
+    out(me === null ? 'Not logged in.' : await me);
+});
+// ── account ──────────────────────────────────────────────────────────────────
+program
+    .command('account')
+    .description('Plan, entitlements, status')
+    .command('status')
+    .description('Show plan + paid-tier entitlements')
+    .action(async () => {
+    out(await api('/api/cli/v1/me')); // TODO(api): GET /api/cli/v1/me (plan + entitlement gate)
+});
+// ── accounts (list) ───────────────────────────────────────────────────────────
+withListOpts(program
+    .command('accounts')
+    .description('List connected social accounts')
+    .option('--platform <p>', 'filter: tiktok | youtube | instagram | x')
+    .option('--group-id <id>', 'filter: only accounts in this channel group')).action(async (opts) => printList(await runList('/api/cli/v1/accounts', opts, ['platform', 'groupId'])));
+// ── groups (list) ─────────────────────────────────────────────────────────────
+withListOpts(program
+    .command('groups')
+    .description('List channel groups (account presets)')
+    .option('--name <q>', 'filter: name contains')).action(async (opts) => printList(await runList('/api/cli/v1/groups', opts, ['name'])));
+// ── workspace (single object) ─────────────────────────────────────────────────
+program
+    .command('workspace')
+    .description('Show workspace timezone + default times')
+    .action(async () => out(await api('/api/cli/v1/workspace')));
+// ── posts (group: list | create | schedule) ──────────────────────────────────
+const posts = program.command('posts').description('List, create, and schedule posts');
+withListOpts(posts
+    .command('list')
+    .description('List posts')
+    .option('--status <s>', 'filter: draft | scheduled | posted | failed')
+    .option('--account-id <id>', 'filter: posts targeting this account')
+    .option('--from <date>', 'filter: ISO date lower bound')
+    .option('--to <date>', 'filter: ISO date upper bound')).action(async (opts) => printList(await runList('/api/cli/v1/posts', opts, ['status', 'accountId', 'from', 'to'])));
+posts
+    .command('create')
+    .description('Create a draft post (optionally uploading media)')
+    .option('--file <path>', 'media file to upload (presign → R2)')
+    .option('--content <text>', 'post body / caption')
+    .option('--title <title>', 'title')
+    .option('--description <desc>', 'description')
+    .option('--hashtags <tag...>', 'hashtags (no # prefix)')
+    .option('--type <type>', 'text | image | video | story')
+    .option('--cover-key <key>', 'R2 key of an already-uploaded cover')
+    .action(async (opts) => {
+    const mediaUrls = opts.file ? [await uploadMedia(opts.file)] : undefined;
+    const res = await api('/api/cli/v1/posts', {
+        method: 'POST',
+        body: {
+            content: opts.content,
+            mediaUrls,
+            title: opts.title,
+            description: opts.description,
+            hashtags: opts.hashtags,
+            type: opts.type,
+            coverR2Key: opts.coverKey,
+        },
+    });
+    out(res);
+});
+posts
+    .command('schedule <postId>')
+    .description('Schedule one draft (low-level)')
+    .requiredOption('--account <id...>', 'social account id(s), 1–10')
+    .option('--at <iso>', 'publish time, ISO 8601 UTC; omit = post now')
+    .action(async (postId, opts) => {
+    const res = await api(`/api/cli/v1/posts/${postId}/schedule`, {
+        method: 'POST',
+        body: { publishAt: opts.at, socialAccountIds: opts.account },
+    });
+    out(res);
+});
+// ── schedule (the headline) ───────────────────────────────────────────────────
+program
+    .command('schedule')
+    .description('Smart-schedule draft posts across a group at preset times')
+    .requiredOption('--group <name>', 'account group (channel group) name')
+    .requiredOption('--min-per-day <n>', 'minimum posts per day', (v) => parseInt(v, 10))
+    .option('--post-id <id...>', 'specific draft post id(s); default = all drafts')
+    .option('--start-date <date>', 'first day to schedule (ISO date); default = tomorrow')
+    .option('--times <hh:mm...>', 'override workspace default times')
+    .option('--dry-run', 'compute and print the plan without scheduling')
+    .action(async (opts) => {
+    const res = await api('/api/cli/v1/schedule', {
+        method: 'POST',
+        body: {
+            group: opts.group,
+            minPerDay: opts.minPerDay,
+            postIds: opts.postId,
+            startDate: opts.startDate,
+            times: opts.times,
+            dryRun: opts.dryRun,
+        },
+    });
+    if (program.opts().json)
+        return out(res);
+    if (opts.dryRun)
+        console.log('DRY RUN — nothing scheduled\n');
+    if (res.plan)
+        console.log(render(res.plan, false) + '\n');
+    console.log(render(res.scheduled ?? [], false));
+    if (res.skipped?.length)
+        console.log('\nSkipped:\n' + render(res.skipped, false));
+});
+program.parseAsync().catch((e) => {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`Error: ${msg}`);
+    process.exitCode = e instanceof ApiError && e.status >= 400 && e.status < 500 ? 1 : 3;
+});

package/dist/list.js

@@ -0,0 +1,28 @@
+// Shared plumbing for list commands: map commander options → ListParams and run a
+// single cursor page (default) or follow all pages (--all). Normalizes both to one shape.
+import { apiList, apiListAll } from './api.js';
+export function toParams(opts, filterKeys) {
+    const p = {};
+    if (opts.limit)
+        p.limit = parseInt(opts.limit, 10);
+    if (opts.cursor)
+        p.cursor = opts.cursor;
+    if (opts.sort)
+        p.sort = opts.sort;
+    if (opts.order)
+        p.order = opts.order;
+    for (const k of filterKeys) {
+        const v = opts[k];
+        if (v != null)
+            p[k] = v;
+    }
+    return p;
+}
+export async function runList(path, opts, filterKeys = []) {
+    const params = toParams(opts, filterKeys);
+    if (opts.all) {
+        return { data: await apiListAll(path, params), nextCursor: null, hasMore: false };
+    }
+    const page = await apiList(path, params);
+    return { data: page.data, nextCursor: page.pagination.nextCursor, hasMore: page.pagination.hasMore };
+}

package/dist/output.js

@@ -0,0 +1,22 @@
+// Output rendering: --json (pretty JSON) or a human table for list data.
+// ponytail: hand-rolled fixed-width table, no cli-table dep — values are short.
+export function render(data, json) {
+    if (json)
+        return JSON.stringify(data, null, 2);
+    if (typeof data === 'string')
+        return data;
+    if (Array.isArray(data))
+        return data.length ? table(data) : '(none)';
+    return JSON.stringify(data, null, 2); // single object → JSON is the clearest plain view
+}
+/** Render an array of flat objects as an aligned table. Columns = keys of the first row. */
+export function table(rows, columns) {
+    const objs = rows.filter((r) => !!r && typeof r === 'object');
+    if (!objs.length)
+        return '(none)';
+    const cols = columns ?? Object.keys(objs[0]);
+    const cell = (v) => v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+    const widths = cols.map((c) => Math.max(c.length, ...objs.map((o) => cell(o[c]).length)));
+    const line = (cells) => cells.map((s, i) => s.padEnd(widths[i])).join('  ').trimEnd();
+    return [line(cols), line(cols.map((_, i) => '-'.repeat(widths[i]))), ...objs.map((o) => line(cols.map((c) => cell(o[c]))))].join('\n');
+}

package/dist/upload.js

@@ -0,0 +1,28 @@
+// Media upload: presign → PUT raw bytes to R2 → return the workspace-scoped key.
+// The PUT goes to the signed URL directly (absolute, no auth header — the signature IS the auth).
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { api, ApiError } from './api.js';
+const CONTENT_TYPES = {
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+};
+export function contentTypeFor(file) {
+    return CONTENT_TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream';
+}
+/** Upload a local file to R2 via presign+PUT; returns the resolved (workspace-scoped) key. */
+export async function uploadMedia(filePath, opts = {}) {
+    const contentType = contentTypeFor(filePath);
+    const relativeKey = opts.relativeKey ?? `media/${basename(filePath)}`;
+    const { signedUrl, resolvedKey } = await api('/api/cli/v1/storage/presign', { method: 'POST', body: { relativeKey, contentType, operation: 'upload' } });
+    const bytes = readFileSync(filePath);
+    const res = await fetch(signedUrl, { method: 'PUT', headers: { 'content-type': contentType }, body: bytes });
+    if (!res.ok)
+        throw new ApiError(res.status, `R2 upload failed (HTTP ${res.status})`);
+    return resolvedKey;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "juzpost-cli",
+  "version": "0.1.0",
+  "description": "CLI for JuzPost — login + smart-schedule short-form clips from the terminal",
+  "keywords": ["juzpost", "cli", "social", "scheduler", "tiktok", "youtube", "shorts", "clips"],
+  "license": "MIT",
+  "author": "Jiiva Durai <jackstiffer1@gmail.com>",
+  "type": "module",
+  "bin": { "juzpost": "dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}