clipugc 1.0.0 → 1.1.0

package/dist/cli.js

@@ -9,6 +9,7 @@ import { registerImagesCommands } from './commands/images.js';
 import { registerAdsCommands } from './commands/ads.js';
 import { registerVideosCommands } from './commands/videos.js';
 import { registerHooksCommands } from './commands/hooks.js';
+import { registerStoriesCommands } from './commands/stories.js';
 export function createCli() {
     const program = new Command();
     program
@@ -28,6 +29,7 @@ export function createCli() {
     registerVideosCommands(program);
     registerAdsCommands(program);
     registerHooksCommands(program);
+    registerStoriesCommands(program);
     return program;
 }
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,UAAU,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CACV,yGAAyG;QACzG,2FAA2F,CAC5F;SACA,OAAO,CAAC,UAAU,EAAE,EAAE,eAAe,EAAE,uBAAuB,CAAC;SAC/D,MAAM,CAAC,QAAQ,EAAE,iCAAiC,CAAC;SACnD,kBAAkB,CAAC,wBAAwB,CAAC;SAC5C,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAElC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,MAAM,UAAU,SAAS;IACvB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CACV,yGAAyG;QACzG,2FAA2F,CAC5F;SACA,OAAO,CAAC,UAAU,EAAE,EAAE,eAAe,EAAE,uBAAuB,CAAC;SAC/D,MAAM,CAAC,QAAQ,EAAE,iCAAiC,CAAC;SACnD,kBAAkB,CAAC,wBAAwB,CAAC;SAC5C,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAElC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAEjC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/commands/stories.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { ValidationError } from '../utils/errors.js';
+/**
+ * `clipugc stories` — ongoing episodic videos of an AI character's life. Each episode's
+ * script is drafted for free and only generated after `episodes approve` (charged).
+ * Every episode continues the story — and starts on the previous episode's last frame.
+ */
+export declare function registerStoriesCommands(program: Command): void;
+export { ValidationError };

package/dist/commands/stories.js

@@ -0,0 +1,165 @@
+import { createApiClient } from '../services/api.js';
+import { approveEpisode, createStory, downloadEpisode, draftEpisode, getEpisode, getStory, listStories, STORY_RESOLUTIONS, } from '../services/stories.service.js';
+import { formatStatus, isJsonMode, printJson, printTable } from '../utils/output.js';
+import { waitForCompletion } from '../utils/poll.js';
+import { ValidationError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+const SERIES_COLUMNS = [
+    { header: 'STORY ID', value: (s) => s.id },
+    { header: 'Title', value: (s) => s.title },
+    { header: 'Character', value: (s) => s.character?.name },
+    { header: 'Episodes', value: (s) => s.episode_count },
+    { header: 'Quality', value: (s) => (s.resolution === '768P' ? 'HD' : 'Standard') },
+];
+const EPISODE_COLUMNS = [
+    { header: 'EPISODE ID', value: (e) => e.id },
+    { header: '#', value: (e) => e.episode_number },
+    { header: 'Title', value: (e) => e.title },
+    { header: 'Status', value: (e) => formatStatus(e.status) },
+    { header: 'Length', value: (e) => (e.duration_seconds ? `${e.duration_seconds}s` : undefined) },
+];
+function printScript(episode) {
+    logger.info('');
+    logger.info(`Episode ${episode.episode_number ?? '?'} — ${episode.title ?? 'Untitled'}`);
+    (episode.script ?? []).forEach((scene, index) => {
+        logger.info(`  Scene ${index + 1}: ${scene.action}`);
+        if (scene.dialogue)
+            logger.info(`    She says: "${scene.dialogue}"`);
+    });
+    logger.info('');
+}
+/**
+ * `clipugc stories` — ongoing episodic videos of an AI character's life. Each episode's
+ * script is drafted for free and only generated after `episodes approve` (charged).
+ * Every episode continues the story — and starts on the previous episode's last frame.
+ */
+export function registerStoriesCommands(program) {
+    const stories = program
+        .command('stories')
+        .description("Ongoing story series: your AI character's life, one talking episode at a time");
+    stories
+        .command('list')
+        .description('List your story series')
+        .action(async (_opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const { stories: items, raw } = await listStories(api);
+        if (json)
+            return printJson(raw);
+        printTable(items, SERIES_COLUMNS);
+    });
+    stories
+        .command('create')
+        .description('Start a new story series for one of your characters')
+        .requiredOption('--character <id>', 'The character the story is about')
+        .requiredOption('--title <title>', 'Story title')
+        .requiredOption('--premise <premise>', "What her life is about (drives every episode's script)")
+        .option('--tone <tone>', 'Optional tone, e.g. "dry humor, cliffhangers"')
+        .option('--resolution <res>', `Video quality: ${STORY_RESOLUTIONS.join(' or ')} (default 480P)`)
+        .action(async (opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const series = await createStory(api, {
+            characterId: opts.character,
+            title: opts.title,
+            premise: opts.premise,
+            tone: opts.tone,
+            resolution: opts.resolution,
+        });
+        if (json)
+            return printJson(series);
+        logger.success(`Story ${series.id} created: ${series.title}`);
+        logger.info(`Draft the first episode: clipugc stories draft ${series.id}`);
+    });
+    stories
+        .command('show <id>')
+        .description('Show a story and its episodes')
+        .action(async (id, _opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const { story, episodes } = await getStory(api, id);
+        if (json)
+            return printJson({ story, episodes });
+        printTable([story], SERIES_COLUMNS);
+        if (story.story_summary)
+            logger.info(`\nStory so far:\n${story.story_summary}\n`);
+        printTable(episodes, EPISODE_COLUMNS);
+    });
+    stories
+        .command('draft <id>')
+        .description("Draft the next episode's script (free — nothing is generated yet)")
+        .option('--minutes <n>', 'Episode length in minutes: 1, 2 or 5 (default 1)', (v) => Number.parseInt(v, 10))
+        .option('--direction <text>', 'Write the plot yourself; omit to let the AI continue the story')
+        .action(async (id, opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const { episode, cost_credits } = await draftEpisode(api, id, {
+            minutes: opts.minutes,
+            direction: opts.direction,
+        });
+        if (json)
+            return printJson({ episode, cost_credits });
+        printScript(episode);
+        logger.info(`Generating this episode costs ${cost_credits ?? '?'} credits.`);
+        logger.info(`Approve it: clipugc stories approve ${id} ${episode.id} [--wait]`);
+    });
+    stories
+        .command('approve <id> <episodeId>')
+        .description('Approve a drafted episode: charges credits and generates it scene by scene')
+        .option('--wait', 'Wait until the episode finishes rendering')
+        .option('--output <path>', 'With --wait: also download the finished episode here')
+        .action(async (id, episodeId, opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const episode = await approveEpisode(api, id, episodeId);
+        if (!opts.wait) {
+            if (json)
+                return printJson(episode);
+            logger.success(`Episode ${episode.episode_number ?? episodeId} is generating.`);
+            logger.info(`Check progress: clipugc stories status ${id} ${episodeId}`);
+            return;
+        }
+        const finished = await waitForCompletion(() => getEpisode(api, id, episodeId), {
+            label: `Episode ${episode.episode_number ?? episodeId}`,
+            intervalMs: 10_000,
+            quiet: json,
+        });
+        if (opts.output || !json) {
+            const path = await downloadEpisode(api, id, episodeId, opts.output);
+            if (!json)
+                logger.success(`Saved to ${path}`);
+        }
+        if (json)
+            printJson(finished);
+    });
+    stories
+        .command('status <id> <episodeId>')
+        .description("Check an episode's generation progress")
+        .action(async (id, episodeId, _opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const episode = await getEpisode(api, id, episodeId);
+        if (json)
+            return printJson(episode);
+        printTable([episode], EPISODE_COLUMNS);
+        if (episode.status === 'processing') {
+            logger.info(`Scenes completed: ${episode.scenes_completed ?? 0}/${episode.scene_count ?? '?'}`);
+        }
+        if (episode.error)
+            logger.warn(`Error: ${episode.error}`);
+    });
+    stories
+        .command('download <id> <episodeId>')
+        .description('Download a completed episode')
+        .option('--output <path>', 'Where to save the .mp4')
+        .action(async (id, episodeId, opts, cmd) => {
+        const json = isJsonMode(cmd);
+        const api = await createApiClient();
+        const path = await downloadEpisode(api, id, episodeId, opts.output);
+        if (json)
+            return printJson({ saved_to: path });
+        logger.success(`Saved to ${path}`);
+    });
+}
+export { ValidationError };
+//# sourceMappingURL=stories.js.map

package/dist/commands/stories.js.map

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

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

@@ -0,0 +1,84 @@
+import type { ApiClient } from './api.js';
+/**
+ * Stories — ongoing episodic videos of an AI character's life (`/stories` endpoints).
+ *
+ * Flow: create a series → draft an episode script (free) → approve it (charges credits,
+ * generates scene-by-scene with native speech) → poll status → download the episode.
+ */
+export interface StorySeries {
+    id: number | string;
+    title: string;
+    premise?: string;
+    tone?: string | null;
+    /** 480P (standard) | 768P (HD) */
+    resolution?: string;
+    status?: string;
+    episode_count?: number;
+    story_summary?: string | null;
+    character?: {
+        id?: number | string;
+        name?: string;
+    };
+    created_at?: string;
+    [key: string]: unknown;
+}
+export interface StoryScene {
+    action: string;
+    dialogue?: string | null;
+    location?: string | null;
+}
+export interface StoryEpisode {
+    id: number | string;
+    story_series_id?: number | string;
+    episode_number?: number;
+    title?: string | null;
+    /** draft | script_ready | processing | stitching | completed | failed */
+    status: string;
+    script?: StoryScene[];
+    summary?: string | null;
+    scene_count?: number;
+    scenes_completed?: number;
+    duration_seconds?: number;
+    credits_charged?: number | null;
+    video_url?: string | null;
+    thumbnail_url?: string | null;
+    error?: string | null;
+    created_at?: string;
+    [key: string]: unknown;
+}
+export declare const STORY_RESOLUTIONS: string[];
+/** GET /stories */
+export declare function listStories(api: ApiClient): Promise<{
+    stories: StorySeries[];
+    raw: unknown;
+}>;
+/** POST /stories */
+export declare function createStory(api: ApiClient, input: {
+    characterId: string;
+    title: string;
+    premise: string;
+    tone?: string;
+    resolution?: string;
+}): Promise<StorySeries>;
+/** GET /stories/{id} — the series plus all its episodes. */
+export declare function getStory(api: ApiClient, id: string): Promise<{
+    story: StorySeries;
+    episodes: StoryEpisode[];
+}>;
+/**
+ * POST /stories/{id}/episodes — draft the next episode's script. Free. Pass `direction`
+ * to write the plot yourself; leave it out and the AI continues the story.
+ */
+export declare function draftEpisode(api: ApiClient, id: string, opts?: {
+    minutes?: number;
+    direction?: string;
+}): Promise<{
+    episode: StoryEpisode;
+    cost_credits?: number;
+}>;
+/** POST /stories/{id}/episodes/{episodeId}/approve — charges credits, starts generation. */
+export declare function approveEpisode(api: ApiClient, id: string, episodeId: string, scenes?: StoryScene[]): Promise<StoryEpisode>;
+/** GET /stories/{id}/episodes/{episodeId} — status; also nudges a lost-webhook scene along. */
+export declare function getEpisode(api: ApiClient, id: string, episodeId: string): Promise<StoryEpisode>;
+/** Save a completed episode's video to disk (the URL is short-lived — fetch fresh first). */
+export declare function downloadEpisode(api: ApiClient, id: string, episodeId: string, outPath?: string): Promise<string>;

package/dist/services/stories.service.js

@@ -0,0 +1,55 @@
+import { ValidationError } from '../utils/errors.js';
+import { saveUrlToFile } from '../utils/download.js';
+export const STORY_RESOLUTIONS = ['480P', '768P'];
+/** GET /stories */
+export async function listStories(api) {
+    const raw = await api.get('/stories');
+    return { stories: raw?.stories ?? [], raw };
+}
+/** POST /stories */
+export async function createStory(api, input) {
+    if (input.resolution !== undefined && !STORY_RESOLUTIONS.includes(input.resolution)) {
+        throw new ValidationError(`--resolution must be one of: ${STORY_RESOLUTIONS.join(', ')} (got "${input.resolution}").`);
+    }
+    return api.post('/stories', {
+        body: {
+            character_id: Number(input.characterId),
+            title: input.title,
+            premise: input.premise,
+            tone: input.tone,
+            resolution: input.resolution,
+        },
+    });
+}
+/** GET /stories/{id} — the series plus all its episodes. */
+export async function getStory(api, id) {
+    const data = await api.get(`/stories/${encodeURIComponent(id)}`);
+    return { story: data.story, episodes: data.episodes ?? [] };
+}
+/**
+ * POST /stories/{id}/episodes — draft the next episode's script. Free. Pass `direction`
+ * to write the plot yourself; leave it out and the AI continues the story.
+ */
+export async function draftEpisode(api, id, opts = {}) {
+    if (opts.minutes !== undefined && (!Number.isInteger(opts.minutes) || opts.minutes < 1 || opts.minutes > 5)) {
+        throw new ValidationError('--minutes must be an integer between 1 and 5.');
+    }
+    return api.post(`/stories/${encodeURIComponent(id)}/episodes`, { body: { minutes: opts.minutes, direction: opts.direction } });
+}
+/** POST /stories/{id}/episodes/{episodeId}/approve — charges credits, starts generation. */
+export async function approveEpisode(api, id, episodeId, scenes) {
+    return api.post(`/stories/${encodeURIComponent(id)}/episodes/${encodeURIComponent(episodeId)}/approve`, scenes && scenes.length > 0 ? { body: { scenes } } : undefined);
+}
+/** GET /stories/{id}/episodes/{episodeId} — status; also nudges a lost-webhook scene along. */
+export async function getEpisode(api, id, episodeId) {
+    return api.get(`/stories/${encodeURIComponent(id)}/episodes/${encodeURIComponent(episodeId)}`);
+}
+/** Save a completed episode's video to disk (the URL is short-lived — fetch fresh first). */
+export async function downloadEpisode(api, id, episodeId, outPath) {
+    const episode = await getEpisode(api, id, episodeId);
+    if (episode.status !== 'completed' || !episode.video_url) {
+        throw new ValidationError(`Episode ${episodeId} has no downloadable video yet (status: ${episode.status}).`);
+    }
+    return saveUrlToFile(episode.video_url, outPath ?? `story_${id}_episode_${episode.episode_number ?? episodeId}.mp4`);
+}
+//# sourceMappingURL=stories.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stories.service.js","sourceRoot":"","sources":["../../src/services/stories.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiDrD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD,mBAAmB;AACnB,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAc;IAC9C,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,GAAG,CAA8B,UAAU,CAAC,CAAC;IACnE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC;AAC9C,CAAC;AAED,oBAAoB;AACpB,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAc,EACd,KAAkG;IAElG,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,eAAe,CAAC,gCAAgC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,UAAU,KAAK,CAAC,CAAC;IACzH,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAc,UAAU,EAAE;QACvC,IAAI,EAAE;YACJ,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC;YACvC,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B;KACF,CAAC,CAAC;AACL,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAc,EACd,EAAU;IAEV,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,GAAG,CACxB,YAAY,kBAAkB,CAAC,EAAE,CAAC,EAAE,CACrC,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAc,EACd,EAAU,EACV,OAAiD,EAAE;IAEnD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5G,MAAM,IAAI,eAAe,CAAC,+CAA+C,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CACb,YAAY,kBAAkB,CAAC,EAAE,CAAC,WAAW,EAC7C,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,CAC/D,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAc,EACd,EAAU,EACV,SAAiB,EACjB,MAAqB;IAErB,OAAO,GAAG,CAAC,IAAI,CACb,YAAY,kBAAkB,CAAC,EAAE,CAAC,aAAa,kBAAkB,CAAC,SAAS,CAAC,UAAU,EACtF,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAC/D,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAc,EAAE,EAAU,EAAE,SAAiB;IAC5E,OAAO,GAAG,CAAC,GAAG,CACZ,YAAY,kBAAkB,CAAC,EAAE,CAAC,aAAa,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAC/E,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAc,EACd,EAAU,EACV,SAAiB,EACjB,OAAgB;IAEhB,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACzD,MAAM,IAAI,eAAe,CAAC,WAAW,SAAS,2CAA2C,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,IAAI,SAAS,EAAE,YAAY,OAAO,CAAC,cAAc,IAAI,SAAS,MAAM,CAAC,CAAC;AACvH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clipugc",
-  "version": "1.0.0",
-  "description": "Official CLI for ClipUGC \u2014 create AI characters, generate looks, and produce UGC-style videos for your mobile app from the terminal.",
+  "version": "1.1.0",
+  "description": "Official CLI for ClipUGC — create AI characters, generate looks, and produce UGC-style videos for your mobile app from the terminal.",
   "type": "module",
   "bin": {
     "clipugc": "./dist/index.js"