clipugc 0.2.0

package/dist/services/videos.service.d.ts

@@ -0,0 +1,100 @@
+import type { ApiClient } from './api.js';
+import type { Paginated, Pagination } from '../types/index.js';
+export declare const MAX_PROMPT_LENGTH = 1500;
+export declare const MAX_SCENE_PROMPT_LENGTH = 600;
+export declare const MAX_HOOK_TEXT_LENGTH = 150;
+export declare const MAX_PER_PAGE = 50;
+export declare const ALLOWED_DURATIONS: readonly [5, 10];
+/** A character video as returned by /character-videos endpoints. */
+export interface CharacterVideo {
+    id: number | string;
+    status: string;
+    kind?: string;
+    type?: string;
+    prompt?: string | null;
+    scene_prompt?: string | null;
+    duration?: number;
+    is_merged?: boolean;
+    /** processing | completed | failed | null (never merged). */
+    merge_status?: string | null;
+    created_at?: string;
+    [key: string]: unknown;
+}
+/** Payload of GET /character-videos/{id}/check-status. */
+export interface VideoStatusCheck {
+    status: string;
+    failure_reason?: string | null;
+    error_message?: string | null;
+    [key: string]: unknown;
+}
+export interface ImageToVideoInput {
+    /** Exactly one of characterReferenceImageId / sourceImageKey is required. */
+    characterReferenceImageId?: string;
+    sourceImageKey?: string;
+    prompt?: string;
+    /** Extra scene description — turns the clip into a scene-staged clip (9 credits). */
+    scenePrompt?: string;
+    /** 5 or 10 seconds (default 5). A 5s clip costs 7 credits, a 10s clip 13. */
+    duration?: number;
+    keepOriginalSound?: boolean;
+}
+export interface MotionControlInput extends Omit<ImageToVideoInput, 'scenePrompt' | 'duration'> {
+    /** Storage key of the uploaded driver video (purpose driver_video). */
+    referenceVideoKey: string;
+    scenePrompt?: string;
+    duration?: number;
+}
+export interface MergeInput {
+    /** Storage key of the uploaded app screen recording (purpose app_video). */
+    appVideoKey: string;
+    /** Hook text overlaid on the final video (required, max 150 chars). */
+    hookText: string;
+    /** Optional storage key of background music (purpose music). */
+    musicKey?: string;
+}
+/**
+ * Tolerant list extractor: the API may return the array raw or wrapped under
+ * a known key. Pagination, when present, lives at data.pagination.
+ */
+export declare function extractList<T>(data: unknown): Paginated<T>;
+export interface ListVideosOptions {
+    page?: number;
+    perPage?: number;
+    /** Only videos of this AI character (ai_character_id filter). */
+    aiCharacterId?: string;
+    /** Only completed, unmerged clips — ready for `videos merge` (mergeable=1). */
+    mergeable?: boolean;
+    /** Only merged final videos (finals=1). */
+    finals?: boolean;
+}
+/** GET /character-videos — paginated list. */
+export declare function listVideos(api: ApiClient, opts?: ListVideosOptions): Promise<{
+    items: CharacterVideo[];
+    pagination?: Pagination;
+    raw: unknown;
+}>;
+/** POST /character-videos/image-to-video — animate a still image into a talking clip. */
+export declare function createImageToVideo(api: ApiClient, input: ImageToVideoInput): Promise<CharacterVideo>;
+/** POST /character-videos/motion-control — drive the character with a reference video. */
+export declare function createMotionControl(api: ApiClient, input: MotionControlInput): Promise<CharacterVideo>;
+/** POST /character-videos/{id}/merge — merge app recording + hook text (+ music) into the final UGC video. */
+export declare function mergeVideo(api: ApiClient, id: string, input: MergeInput): Promise<CharacterVideo>;
+/** POST /character-videos/{id}/retry. */
+export declare function retryVideo(api: ApiClient, id: string): Promise<CharacterVideo>;
+/** GET /character-videos/{id}. */
+export declare function getVideo(api: ApiClient, id: string): Promise<CharacterVideo>;
+/** GET /character-videos/{id}/check-status. */
+export declare function checkVideoStatus(api: ApiClient, id: string): Promise<VideoStatusCheck>;
+/** DELETE /character-videos/{id}. Returns the envelope message when present. */
+export declare function deleteVideo(api: ApiClient, id: string): Promise<{
+    data: unknown;
+    message: string | null;
+}>;
+/**
+ * GET /character-videos/{id}/download → data.download_url, then fetch that URL
+ * and write the bytes to disk. Returns the destination path.
+ */
+export declare function downloadVideo(api: ApiClient, id: string, opts?: {
+    output?: string;
+    quiet?: boolean;
+}): Promise<string>;

package/dist/services/videos.service.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ora from 'ora';
+import { ApiError, NetworkError, ValidationError } from '../utils/errors.js';
+export const MAX_PROMPT_LENGTH = 1500;
+export const MAX_SCENE_PROMPT_LENGTH = 600;
+export const MAX_HOOK_TEXT_LENGTH = 150;
+export const MAX_PER_PAGE = 50;
+export const ALLOWED_DURATIONS = [5, 10];
+/**
+ * Tolerant list extractor: the API may return the array raw or wrapped under
+ * a known key. Pagination, when present, lives at data.pagination.
+ */
+export function extractList(data) {
+    if (Array.isArray(data)) {
+        return { items: data };
+    }
+    if (data && typeof data === 'object') {
+        const record = data;
+        const pagination = record.pagination ?? undefined;
+        for (const key of ['videos', 'character_videos', 'items', 'data', 'results']) {
+            if (Array.isArray(record[key])) {
+                return { items: record[key], pagination };
+            }
+        }
+    }
+    return { items: [] };
+}
+function validatePrompts(prompt, scenePrompt) {
+    if (prompt !== undefined && prompt.length > MAX_PROMPT_LENGTH) {
+        throw new ValidationError(`--prompt is too long (${prompt.length} chars, max ${MAX_PROMPT_LENGTH}).`);
+    }
+    if (scenePrompt !== undefined && scenePrompt.length > MAX_SCENE_PROMPT_LENGTH) {
+        throw new ValidationError(`--scene is too long (${scenePrompt.length} chars, max ${MAX_SCENE_PROMPT_LENGTH}).`);
+    }
+}
+function validateDuration(duration) {
+    if (!ALLOWED_DURATIONS.includes(duration)) {
+        throw new ValidationError(`--duration must be 5 or 10 (got ${duration}).`);
+    }
+}
+function validateImageSource(input) {
+    const hasLook = Boolean(input.characterReferenceImageId);
+    const hasKey = Boolean(input.sourceImageKey);
+    if (hasLook === hasKey) {
+        throw new ValidationError('Provide exactly one image source: --image <lookId> (a generated character look) or --photo <file> (your own photo).');
+    }
+}
+function baseVideoPayload(input) {
+    const payload = {};
+    if (input.characterReferenceImageId)
+        payload.character_reference_image_id = input.characterReferenceImageId;
+    if (input.sourceImageKey)
+        payload.source_image_key = input.sourceImageKey;
+    if (input.prompt !== undefined && input.prompt !== '')
+        payload.prompt = input.prompt;
+    if (input.scenePrompt !== undefined && input.scenePrompt !== '')
+        payload.scene_prompt = input.scenePrompt;
+    if (input.keepOriginalSound !== undefined)
+        payload.keep_original_sound = input.keepOriginalSound;
+    return payload;
+}
+/** GET /character-videos — paginated list. */
+export async function listVideos(api, opts = {}) {
+    if (opts.perPage !== undefined && (!Number.isInteger(opts.perPage) || opts.perPage < 1 || opts.perPage > MAX_PER_PAGE)) {
+        throw new ValidationError(`--per-page must be an integer between 1 and ${MAX_PER_PAGE}.`);
+    }
+    if (opts.page !== undefined && (!Number.isInteger(opts.page) || opts.page < 1)) {
+        throw new ValidationError('--page must be a positive integer.');
+    }
+    if (opts.mergeable && opts.finals) {
+        throw new ValidationError('--mergeable and --finals are mutually exclusive — pick one.');
+    }
+    const raw = await api.get('/character-videos', {
+        query: {
+            page: opts.page,
+            per_page: opts.perPage,
+            ai_character_id: opts.aiCharacterId,
+            mergeable: opts.mergeable ? 1 : undefined,
+            finals: opts.finals ? 1 : undefined,
+        },
+    });
+    const { items, pagination } = extractList(raw);
+    return { items, pagination, raw };
+}
+/** POST /character-videos/image-to-video — animate a still image into a talking clip. */
+export async function createImageToVideo(api, input) {
+    validateImageSource(input);
+    validatePrompts(input.prompt, input.scenePrompt);
+    const duration = input.duration ?? 5;
+    validateDuration(duration);
+    const payload = baseVideoPayload(input);
+    payload.duration = duration;
+    return api.post('/character-videos/image-to-video', { body: payload });
+}
+/** POST /character-videos/motion-control — drive the character with a reference video. */
+export async function createMotionControl(api, input) {
+    validateImageSource(input);
+    if (!input.referenceVideoKey) {
+        throw new ValidationError('A driver video is required (--driver <videoFile>).');
+    }
+    validatePrompts(input.prompt, input.scenePrompt);
+    const payload = baseVideoPayload(input);
+    payload.reference_video_key = input.referenceVideoKey;
+    if (input.duration !== undefined) {
+        validateDuration(input.duration);
+        payload.duration = input.duration;
+    }
+    return api.post('/character-videos/motion-control', { body: payload });
+}
+/** POST /character-videos/{id}/merge — merge app recording + hook text (+ music) into the final UGC video. */
+export async function mergeVideo(api, id, input) {
+    if (!input.appVideoKey) {
+        throw new ValidationError('An app screen recording is required (--app-video <file>).');
+    }
+    if (!input.hookText || input.hookText.trim() === '') {
+        throw new ValidationError('Hook text is required (--hook "your hook text").');
+    }
+    if (input.hookText.length > MAX_HOOK_TEXT_LENGTH) {
+        throw new ValidationError(`--hook is too long (${input.hookText.length} chars, max ${MAX_HOOK_TEXT_LENGTH}).`);
+    }
+    const payload = {
+        app_video_key: input.appVideoKey,
+        hook_text: input.hookText,
+    };
+    if (input.musicKey)
+        payload.music_key = input.musicKey;
+    return api.post(`/character-videos/${encodeURIComponent(id)}/merge`, { body: payload });
+}
+/** POST /character-videos/{id}/retry. */
+export async function retryVideo(api, id) {
+    return api.post(`/character-videos/${encodeURIComponent(id)}/retry`);
+}
+/** GET /character-videos/{id}. */
+export async function getVideo(api, id) {
+    return api.get(`/character-videos/${encodeURIComponent(id)}`);
+}
+/** GET /character-videos/{id}/check-status. */
+export async function checkVideoStatus(api, id) {
+    return api.get(`/character-videos/${encodeURIComponent(id)}/check-status`);
+}
+/** DELETE /character-videos/{id}. Returns the envelope message when present. */
+export async function deleteVideo(api, id) {
+    const result = await api.request('DELETE', `/character-videos/${encodeURIComponent(id)}`);
+    return { data: result.data, message: result.message };
+}
+/**
+ * GET /character-videos/{id}/download → data.download_url, then fetch that URL
+ * and write the bytes to disk. Returns the destination path.
+ */
+export async function downloadVideo(api, id, opts = {}) {
+    const data = await api.get(`/character-videos/${encodeURIComponent(id)}/download`);
+    const url = data?.download_url;
+    if (!url) {
+        throw new ApiError('The API did not return a download URL. Is the video completed? Check `clipugc videos status`.');
+    }
+    const dest = opts.output || `clipugc-video-${id}.mp4`;
+    const spinner = opts.quiet ? null : ora(`Downloading to ${dest}`).start();
+    try {
+        let response;
+        try {
+            response = await fetch(url);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new NetworkError(`Download failed: ${reason}`);
+        }
+        if (!response.ok) {
+            throw new NetworkError(`Download failed (HTTP ${response.status}). The link may have expired — try again.`);
+        }
+        const bytes = Buffer.from(await response.arrayBuffer());
+        // Create missing parent directories so -o can target workspace paths
+        // like clipugc/influencers/<id>/clips/… directly.
+        const dir = path.dirname(dest);
+        if (dir && dir !== '.')
+            await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(dest, bytes);
+        spinner?.succeed(`Saved ${dest} (${(bytes.length / (1024 * 1024)).toFixed(1)} MB)`);
+        return dest;
+    }
+    catch (err) {
+        if (spinner?.isSpinning)
+            spinner.fail(`Download to ${dest} failed`);
+        throw err;
+    }
+}
+//# sourceMappingURL=videos.service.js.map

package/dist/services/videos.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"videos.service.js","sourceRoot":"","sources":["../../src/services/videos.service.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared types for the ClipUGC CLI.
+ *
+ * NOTE (subagent contract): group-specific request/response types live in the
+ * corresponding service file (e.g. src/services/characters.service.ts).
+ * Only genuinely shared, cross-group types belong here.
+ */
+/** Persisted CLI configuration (~/.config/clipugc/config.json). */
+export interface ClipUgcConfig {
+    /** API base URL, e.g. https://clipugc.com/api/v1 */
+    apiBaseUrl: string;
+    /** Sanctum personal access token created from the ClipUGC dashboard. */
+    apiKey: string;
+    /** Email of the authenticated user (cached at login for `auth status`). */
+    email: string;
+}
+/** Standard ClipUGC API response envelope. Every response is HTTP 200. */
+export interface ApiEnvelope<T = unknown> {
+    statusCode: number;
+    errorMessage: string | null;
+    data: T;
+    message: string | null;
+}
+/** Pagination block returned inside `data.pagination`. */
+export interface Pagination {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    has_more_pages: boolean;
+}
+export interface Paginated<T> {
+    items: T[];
+    pagination?: Pagination;
+}
+/** Long-running resource statuses. */
+export type ResourceStatus = 'pending' | 'processing' | 'completed' | 'failed';
+/** App-level status codes used by the API envelope. */
+export declare const APP_CODES: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly VALIDATION: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly NOT_FOUND: 404;
+    readonly PREMIUM_REQUIRED: 1002;
+    readonly INSUFFICIENT_CREDITS: 1003;
+};

package/dist/types/index.js

@@ -0,0 +1,18 @@
+/**
+ * Shared types for the ClipUGC CLI.
+ *
+ * NOTE (subagent contract): group-specific request/response types live in the
+ * corresponding service file (e.g. src/services/characters.service.ts).
+ * Only genuinely shared, cross-group types belong here.
+ */
+/** App-level status codes used by the API envelope. */
+export const APP_CODES = {
+    OK: 200,
+    CREATED: 201,
+    VALIDATION: 400,
+    UNAUTHORIZED: 401,
+    NOT_FOUND: 404,
+    PREMIUM_REQUIRED: 1002,
+    INSUFFICIENT_CREDITS: 1003,
+};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqCH,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,GAAG;IACP,OAAO,EAAE,GAAG;IACZ,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,gBAAgB,EAAE,IAAI;IACtB,oBAAoB,EAAE,IAAI;CAClB,CAAC"}

package/dist/utils/config.d.ts

@@ -0,0 +1,18 @@
+import type { ClipUgcConfig } from '../types/index.js';
+export declare const DEFAULT_API_BASE_URL = "https://clipugc.com/api/v1";
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function getDefaultConfig(): ClipUgcConfig;
+export declare function loadConfig(): Promise<ClipUgcConfig>;
+export declare function saveConfig(config: ClipUgcConfig): Promise<void>;
+export declare function getConfigValue(key: keyof ClipUgcConfig): Promise<string>;
+export declare function setConfigValue(key: keyof ClipUgcConfig, value: string): Promise<void>;
+export declare function isValidConfigKey(key: string): key is keyof ClipUgcConfig;
+export declare function getConfigKeys(): (keyof ClipUgcConfig)[];
+/**
+ * Resolve the effective API key: env var CLIPUGC_API_KEY wins, else config file.
+ * Returns empty string when not set.
+ */
+export declare function resolveApiKey(): Promise<string>;
+/** Resolve the effective API base URL: env CLIPUGC_API_BASE_URL wins, else config. */
+export declare function resolveApiBaseUrl(): Promise<string>;

package/dist/utils/config.js

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'fs-extra';
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'clipugc');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+export const DEFAULT_API_BASE_URL = 'https://clipugc.com/api/v1';
+const DEFAULT_CONFIG = {
+    apiBaseUrl: DEFAULT_API_BASE_URL,
+    apiKey: '',
+    email: '',
+};
+export function getConfigDir() {
+    return CONFIG_DIR;
+}
+export function getConfigPath() {
+    return process.env.CLIPUGC_CONFIG_PATH ?? CONFIG_FILE;
+}
+export function getDefaultConfig() {
+    return { ...DEFAULT_CONFIG };
+}
+export async function loadConfig() {
+    try {
+        const file = getConfigPath();
+        if (await fs.pathExists(file)) {
+            const raw = await fs.readJson(file);
+            return { ...DEFAULT_CONFIG, ...raw };
+        }
+    }
+    catch {
+        // Corrupt or unreadable config — fall back to defaults
+    }
+    return { ...DEFAULT_CONFIG };
+}
+export async function saveConfig(config) {
+    const file = getConfigPath();
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeJson(file, config, { spaces: 2 });
+}
+export async function getConfigValue(key) {
+    const config = await loadConfig();
+    return config[key];
+}
+export async function setConfigValue(key, value) {
+    const config = await loadConfig();
+    config[key] = value;
+    await saveConfig(config);
+}
+export function isValidConfigKey(key) {
+    return key in DEFAULT_CONFIG;
+}
+export function getConfigKeys() {
+    return Object.keys(DEFAULT_CONFIG);
+}
+/**
+ * Resolve the effective API key: env var CLIPUGC_API_KEY wins, else config file.
+ * Returns empty string when not set.
+ */
+export async function resolveApiKey() {
+    return process.env.CLIPUGC_API_KEY || (await loadConfig()).apiKey || '';
+}
+/** Resolve the effective API base URL: env CLIPUGC_API_BASE_URL wins, else config. */
+export async function resolveApiBaseUrl() {
+    return process.env.CLIPUGC_API_BASE_URL || (await loadConfig()).apiBaseUrl || DEFAULT_API_BASE_URL;
+}
+//# sourceMappingURL=config.js.map

package/dist/utils/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,UAAU,CAAC;AAG1B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AACjE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAEzD,MAAM,CAAC,MAAM,oBAAoB,GAAG,4BAA4B,CAAC;AAEjE,MAAM,cAAc,GAAkB;IACpC,UAAU,EAAE,oBAAoB;IAChC,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,WAAW,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;QAC7B,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO,EAAE,GAAG,cAAc,EAAE,GAAG,GAAG,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;IACD,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAqB;IACpD,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAwB;IAC3D,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAwB,EAAE,KAAa;IAC1E,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACpB,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,IAAI,cAAc,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,cAAc,CAA4B,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;AAC1E,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,oBAAoB,CAAC;AACrG,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Typed errors thrown by services. Services NEVER call process.exit —
+ * only src/index.ts maps errors to exit codes.
+ */
+/** Exit codes used by the CLI entry point. */
+export declare const EXIT_CODES: {
+    readonly OK: 0;
+    readonly GENERIC: 1;
+    readonly VALIDATION: 2;
+    readonly AUTH: 3;
+    readonly NOT_FOUND: 4;
+    readonly PREMIUM_REQUIRED: 5;
+    readonly INSUFFICIENT_CREDITS: 6;
+    readonly NETWORK: 7;
+};
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** Generic API failure (unexpected status code or malformed response). */
+export declare class ApiError extends CliError {
+    readonly statusCode: number | undefined;
+    constructor(message: string, statusCode?: number, exitCode?: number);
+}
+/** 400 — request validation failed. */
+export declare class ValidationError extends ApiError {
+    constructor(message: string);
+}
+/** 401 — missing/invalid API key. */
+export declare class AuthError extends ApiError {
+    constructor(message?: string);
+}
+/** 404 — resource not found. */
+export declare class NotFoundError extends ApiError {
+    constructor(message?: string);
+}
+/** 1002 — premium subscription required. */
+export declare class PremiumRequiredError extends ApiError {
+    constructor(message?: string);
+}
+/** 1003 — insufficient credits. */
+export declare class InsufficientCreditsError extends ApiError {
+    constructor(message?: string);
+}
+/** Network-level failure (server unreachable, DNS, timeout). */
+export declare class NetworkError extends CliError {
+    constructor(message: string);
+}
+/** User aborted an interactive confirmation. */
+export declare class AbortedError extends CliError {
+    constructor(message?: string);
+}

package/dist/utils/errors.js

@@ -0,0 +1,74 @@
+/**
+ * Typed errors thrown by services. Services NEVER call process.exit —
+ * only src/index.ts maps errors to exit codes.
+ */
+/** Exit codes used by the CLI entry point. */
+export const EXIT_CODES = {
+    OK: 0,
+    GENERIC: 1,
+    VALIDATION: 2,
+    AUTH: 3,
+    NOT_FOUND: 4,
+    PREMIUM_REQUIRED: 5,
+    INSUFFICIENT_CREDITS: 6,
+    NETWORK: 7,
+};
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_CODES.GENERIC) {
+        super(message);
+        this.name = new.target.name;
+        this.exitCode = exitCode;
+    }
+}
+/** Generic API failure (unexpected status code or malformed response). */
+export class ApiError extends CliError {
+    statusCode;
+    constructor(message, statusCode, exitCode = EXIT_CODES.GENERIC) {
+        super(message, exitCode);
+        this.statusCode = statusCode;
+    }
+}
+/** 400 — request validation failed. */
+export class ValidationError extends ApiError {
+    constructor(message) {
+        super(message, 400, EXIT_CODES.VALIDATION);
+    }
+}
+/** 401 — missing/invalid API key. */
+export class AuthError extends ApiError {
+    constructor(message = 'Unauthorized. Run `clipugc auth login` with a valid API key.') {
+        super(message, 401, EXIT_CODES.AUTH);
+    }
+}
+/** 404 — resource not found. */
+export class NotFoundError extends ApiError {
+    constructor(message = 'Resource not found.') {
+        super(message, 404, EXIT_CODES.NOT_FOUND);
+    }
+}
+/** 1002 — premium subscription required. */
+export class PremiumRequiredError extends ApiError {
+    constructor(message = 'This feature requires a premium subscription. Upgrade at https://clipugc.com') {
+        super(message, 1002, EXIT_CODES.PREMIUM_REQUIRED);
+    }
+}
+/** 1003 — insufficient credits. */
+export class InsufficientCreditsError extends ApiError {
+    constructor(message = 'Insufficient credits. Top up at https://clipugc.com') {
+        super(message, 1003, EXIT_CODES.INSUFFICIENT_CREDITS);
+    }
+}
+/** Network-level failure (server unreachable, DNS, timeout). */
+export class NetworkError extends CliError {
+    constructor(message) {
+        super(message, EXIT_CODES.NETWORK);
+    }
+}
+/** User aborted an interactive confirmation. */
+export class AbortedError extends CliError {
+    constructor(message = 'Aborted.') {
+        super(message, EXIT_CODES.OK);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8CAA8C;AAC9C,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,CAAC;IACL,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,CAAC;IACP,SAAS,EAAE,CAAC;IACZ,gBAAgB,EAAE,CAAC;IACnB,oBAAoB,EAAE,CAAC;IACvB,OAAO,EAAE,CAAC;CACF,CAAC;AAEX,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,WAAmB,UAAU,CAAC,OAAO;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,QAAS,SAAQ,QAAQ;IAC3B,UAAU,CAAqB;IAExC,YAAY,OAAe,EAAE,UAAmB,EAAE,WAAmB,UAAU,CAAC,OAAO;QACrF,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,uCAAuC;AACvC,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC;CACF;AAED,qCAAqC;AACrC,MAAM,OAAO,SAAU,SAAQ,QAAQ;IACrC,YAAY,OAAO,GAAG,8DAA8D;QAClF,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;CACF;AAED,gCAAgC;AAChC,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,OAAO,GAAG,qBAAqB;QACzC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;CACF;AAED,4CAA4C;AAC5C,MAAM,OAAO,oBAAqB,SAAQ,QAAQ;IAChD,YAAY,OAAO,GAAG,8EAA8E;QAClG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC;IACpD,CAAC;CACF;AAED,mCAAmC;AACnC,MAAM,OAAO,wBAAyB,SAAQ,QAAQ;IACpD,YAAY,OAAO,GAAG,qDAAqD;QACzE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACxD,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;CACF;AAED,gDAAgD;AAChD,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAO,GAAG,UAAU;QAC9B,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,11 @@
+export declare const logger: {
+    success(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    plain(message: string): void;
+    /** Dim helper hint, e.g. next-command suggestions. */
+    hint(message: string): void;
+    /** Key/value detail line used in `show` commands. */
+    kv(key: string, value: string | number | boolean | null | undefined): void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+export const logger = {
+    success(message) {
+        console.log(chalk.green('✔ ') + message);
+    },
+    info(message) {
+        console.log(chalk.gray('- ') + message);
+    },
+    warn(message) {
+        console.log(chalk.yellow('! ') + message);
+    },
+    error(message) {
+        console.error(chalk.red('✖ ') + message);
+    },
+    plain(message) {
+        console.log(message);
+    },
+    /** Dim helper hint, e.g. next-command suggestions. */
+    hint(message) {
+        console.log(chalk.dim(message));
+    },
+    /** Key/value detail line used in `show` commands. */
+    kv(key, value) {
+        const v = value === null || value === undefined || value === '' ? chalk.dim('—') : String(value);
+        console.log(`  ${chalk.cyan(key.padEnd(18))} ${v}`);
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,OAAO,CAAC,OAAe;QACrB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,OAAe;QACnB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,OAAe;QACnB,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,sDAAsD;IACtD,IAAI,CAAC,OAAe;QAClB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,qDAAqD;IACrD,EAAE,CAAC,GAAW,EAAE,KAAmD;QACjE,MAAM,CAAC,GAAG,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjG,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;CACF,CAAC"}

package/dist/utils/output.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import type { Pagination } from '../types/index.js';
+/** True when the global --json flag is set (for scripting). */
+export declare function isJsonMode(command: Command): boolean;
+/** Print raw JSON data (the `data` part of the envelope) for --json mode. */
+export declare function printJson(data: unknown): void;
+export interface Column<T> {
+    header: string;
+    value: (row: T) => string | number | boolean | null | undefined;
+}
+/** Render a simple aligned text table for humans. */
+export declare function printTable<T>(rows: T[], columns: Column<T>[]): void;
+/** Print a "page X of Y (N total)" footer for paginated lists. */
+export declare function printPagination(pagination: Pagination | undefined): void;
+/** Colorize a pending|processing|completed|failed status. */
+export declare function formatStatus(status: string): string;