agnes-ai-cli 0.1.0 → 0.1.2

package/README.md

@@ -4,28 +4,16 @@ CLI and JS API for Agnes text, image, and video workflows.
 
 ## Install
 
-Current verified distribution path:
+Install globally:
 
 ```bash
-npm install -g github:jomeswang/agnes-ai-cli
-```
-
-Ad hoc execution without a global install:
-
-```bash
-npx -y github:jomeswang/agnes-ai-cli --help
-```
-
-Planned npm package name:
-
-```bash
-agnes-ai-cli
+npm install -g agnes-ai-cli
 ```
 
-Once the npm publish path is cleared, the package will also be installable as:
+Run without installing:
 
 ```bash
-npm install -g agnes-ai-cli
+npx -y agnes-ai-cli --help
 ```
 
 ## CLI
@@ -44,6 +32,8 @@ agnes video keyframes --image ./frame-a.png --image ./frame-b.png --prompt "morp
 agnes video poll <task-id>
 ```
 
+Local media inputs are uploaded to a temporary public URL automatically. The default bridge tries x0.at first, then falls back to tmpfiles, Uguu, and Litterbox.
+
 ## JS API
 
 ```js

package/dist/cli.js

@@ -72,7 +72,7 @@ Use this group when Agnes requires a public image URL and your source asset is a
         .command("url")
         .description("Return a public URL for a local file or pass through an existing URL")
         .argument("<file-or-url>", "Local file path or http(s) URL")
-        .option("--ttl <ttl>", "Litterbox TTL (1h, 12h, 24h, 72h)", "1h")
+        .option("--ttl <ttl>", "Temporary upload TTL (1h, 12h, 24h, 72h)", "1h")
         .option("--json", "Output JSON")
         .action(async (input, options) => {
         const result = await client.media.toPublicUrl(input, { ttl: ttlSchema.parse(options.ttl) });

package/dist/config.d.ts

@@ -40,7 +40,7 @@ export interface AuthCheckResult {
 export interface PublicUrlResult {
     ok: true;
     url: string;
-    source: "passthrough" | "litterbox" | "provider";
+    source: "passthrough" | "litterbox" | "temporary" | "provider";
 }
 export type AgnesStatus = "queued" | "in_progress" | "completed" | "failed" | "timed_out";
 export interface NormalizedVideoTask {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { AgnesClientConfig } from "./config.js";
 export { checkAuth } from "./auth/check.js";
 export { toPublicUrl } from "./media/toPublicUrl.js";
 export { LitterboxMediaUrlProvider } from "./media/litterbox.js";
+export { TemporaryMediaUrlProvider, TmpfilesMediaUrlProvider, UguuMediaUrlProvider, X0MediaUrlProvider } from "./media/temporary-upload.js";
 export type { AgnesClientConfig, AuthCheckResult, PublicUrlResult, ImageGenerationResult, NormalizedVideoTask, NormalizedVideoResult, Ttl, } from "./config.js";
 export type { ImageGenerateOptions } from "./image/normalizeImageRequest.js";
 export type { TextCompleteOptions, TextCompletionResult } from "./text/complete.js";

package/dist/index.js

@@ -7,6 +7,7 @@ import { pollVideo } from "./video/pollVideo.js";
 export { checkAuth } from "./auth/check.js";
 export { toPublicUrl } from "./media/toPublicUrl.js";
 export { LitterboxMediaUrlProvider } from "./media/litterbox.js";
+export { TemporaryMediaUrlProvider, TmpfilesMediaUrlProvider, UguuMediaUrlProvider, X0MediaUrlProvider } from "./media/temporary-upload.js";
 export function createAgnesClient(config = {}) {
     return {
         auth: {

package/dist/media/litterbox.d.ts

@@ -1,9 +1,15 @@
 import type { FetchLike, Ttl } from "../config.js";
+type LitterboxMediaUrlProviderOptions = {
+    maxAttempts?: number;
+    retryDelayMs?: number;
+};
 export declare class LitterboxMediaUrlProvider {
     private readonly fetchImpl;
-    constructor(fetchImpl?: FetchLike);
+    private readonly options;
+    constructor(fetchImpl?: FetchLike, options?: LitterboxMediaUrlProviderOptions);
     upload(localPath: string, options?: {
         ttl?: Ttl;
     }): Promise<string>;
     private postFormWithRetry;
 }
+export {};

package/dist/media/litterbox.js

@@ -14,8 +14,10 @@ const MIME_TYPES = {
 };
 export class LitterboxMediaUrlProvider {
     fetchImpl;
-    constructor(fetchImpl = fetch) {
+    options;
+    constructor(fetchImpl = fetch, options = {}) {
         this.fetchImpl = fetchImpl;
+        this.options = options;
     }
     async upload(localPath, options = {}) {
         const ttl = options.ttl ?? "1h";
@@ -40,7 +42,9 @@ export class LitterboxMediaUrlProvider {
     }
     async postFormWithRetry(form) {
         let lastError;
-        for (let attempt = 0; attempt <= 2; attempt += 1) {
+        const maxAttempts = this.options.maxAttempts ?? 3;
+        const retryDelayMs = this.options.retryDelayMs ?? 500;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
             try {
                 const response = await this.fetchImpl(LITTERBOX_ENDPOINT, {
                     method: "POST",
@@ -51,12 +55,12 @@ export class LitterboxMediaUrlProvider {
             }
             catch (error) {
                 lastError = error;
-                if (attempt === 2) {
+                if (attempt === maxAttempts) {
                     throw new AgnesCliError("UPLOAD_FAILED", "Litterbox upload failed before a response was received.", {
                         cause: error instanceof Error ? error.message : String(error),
                     });
                 }
-                await sleep(500);
+                await sleep(retryDelayMs);
             }
         }
         throw new AgnesCliError("UPLOAD_FAILED", "Litterbox upload failed before a response was received.", {

package/dist/media/temporary-upload.d.ts

@@ -0,0 +1,25 @@
+import type { FetchLike, MediaUrlProvider, Ttl } from "../config.js";
+export declare class TemporaryMediaUrlProvider implements MediaUrlProvider {
+    private readonly providers;
+    constructor(fetchImpl?: FetchLike);
+    upload(localPath: string, options?: {
+        ttl?: Ttl;
+    }): Promise<string>;
+}
+export declare class X0MediaUrlProvider implements MediaUrlProvider {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: FetchLike);
+    upload(localPath: string): Promise<string>;
+}
+export declare class UguuMediaUrlProvider implements MediaUrlProvider {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: FetchLike);
+    upload(localPath: string): Promise<string>;
+}
+export declare class TmpfilesMediaUrlProvider implements MediaUrlProvider {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: FetchLike);
+    upload(localPath: string, options?: {
+        ttl?: Ttl;
+    }): Promise<string>;
+}

package/dist/media/temporary-upload.js

@@ -0,0 +1,176 @@
+import { promises as fs } from "node:fs";
+import { basename, extname } from "node:path";
+import { AgnesCliError } from "../errors.js";
+import { LitterboxMediaUrlProvider } from "./litterbox.js";
+const X0_ENDPOINT = "https://x0.at/";
+const UGUU_ENDPOINT = "https://uguu.se/upload";
+const TMPFILES_ENDPOINT = "https://tmpfiles.org/api/v1/upload";
+const MIME_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+};
+const TTL_SECONDS = {
+    "1h": "3600",
+    "12h": "43200",
+    "24h": "86400",
+    "72h": "259200",
+};
+export class TemporaryMediaUrlProvider {
+    providers;
+    constructor(fetchImpl = fetch) {
+        this.providers = [
+            { name: "x0.at", provider: new X0MediaUrlProvider(fetchImpl) },
+            { name: "tmpfiles", provider: new TmpfilesMediaUrlProvider(fetchImpl) },
+            { name: "Uguu", provider: new UguuMediaUrlProvider(fetchImpl) },
+            { name: "Litterbox", provider: new LitterboxMediaUrlProvider(fetchImpl, { maxAttempts: 1 }) },
+        ];
+    }
+    async upload(localPath, options = {}) {
+        const failures = [];
+        for (const { name, provider } of this.providers) {
+            try {
+                return await provider.upload(localPath, options);
+            }
+            catch (error) {
+                failures.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new AgnesCliError("UPLOAD_FAILED", "Temporary upload failed after trying x0.at, tmpfiles, Uguu, and Litterbox.", {
+            failures,
+        });
+    }
+}
+export class X0MediaUrlProvider {
+    fetchImpl;
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async upload(localPath) {
+        const form = await createFileForm(localPath, "file");
+        const { response, text } = await postForm(this.fetchImpl, X0_ENDPOINT, form);
+        if (!response.ok) {
+            throw new AgnesCliError("UPLOAD_FAILED", `x0.at upload failed with HTTP ${response.status}.`, {
+                status: response.status,
+                body: text,
+            });
+        }
+        const url = extractPlainTextUrl(text);
+        if (!url) {
+            throw new AgnesCliError("UPLOAD_FAILED", `x0.at did not return a public URL: ${text}`);
+        }
+        return url;
+    }
+}
+export class UguuMediaUrlProvider {
+    fetchImpl;
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async upload(localPath) {
+        const form = await createFileForm(localPath, "files[]");
+        const { response, text } = await postForm(this.fetchImpl, UGUU_ENDPOINT, form);
+        if (!response.ok) {
+            throw new AgnesCliError("UPLOAD_FAILED", `Uguu upload failed with HTTP ${response.status}.`, {
+                status: response.status,
+                body: text,
+            });
+        }
+        const raw = parseUploadJson(text, "Uguu");
+        const url = extractUguuUrl(raw);
+        if (!url) {
+            throw new AgnesCliError("UPLOAD_FAILED", `Uguu did not return a public URL: ${text}`);
+        }
+        return url;
+    }
+}
+export class TmpfilesMediaUrlProvider {
+    fetchImpl;
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async upload(localPath, options = {}) {
+        const form = await createFileForm(localPath, "file");
+        form.set("expire", TTL_SECONDS[options.ttl ?? "1h"]);
+        const { response, text } = await postForm(this.fetchImpl, TMPFILES_ENDPOINT, form);
+        if (!response.ok) {
+            throw new AgnesCliError("UPLOAD_FAILED", `tmpfiles upload failed with HTTP ${response.status}.`, {
+                status: response.status,
+                body: text,
+            });
+        }
+        const raw = parseUploadJson(text, "tmpfiles");
+        const url = extractTmpfilesUrl(raw);
+        if (!url) {
+            throw new AgnesCliError("UPLOAD_FAILED", `tmpfiles did not return a public URL: ${text}`);
+        }
+        return toTmpfilesDirectUrl(url);
+    }
+}
+async function createFileForm(localPath, fieldName) {
+    const file = await fs.readFile(localPath);
+    const form = new FormData();
+    const mimeType = MIME_TYPES[extname(localPath).toLowerCase()] ?? "application/octet-stream";
+    form.set(fieldName, new Blob([file], { type: mimeType }), basename(localPath));
+    return form;
+}
+async function postForm(fetchImpl, endpoint, form) {
+    try {
+        const response = await fetchImpl(endpoint, {
+            method: "POST",
+            body: form,
+        });
+        return { response, text: (await response.text()).trim() };
+    }
+    catch (error) {
+        throw new AgnesCliError("UPLOAD_FAILED", `${new URL(endpoint).hostname} upload failed before a response was received.`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function parseUploadJson(text, providerName) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new AgnesCliError("UPLOAD_FAILED", `${providerName} did not return JSON: ${text}`);
+    }
+}
+function extractPlainTextUrl(text) {
+    const url = text.match(/https?:\/\/[^\s"'<>]+/)?.[0];
+    return url && /^https?:\/\//.test(url) ? url : undefined;
+}
+function extractUguuUrl(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const files = raw.files;
+    if (!Array.isArray(files))
+        return undefined;
+    const first = files[0];
+    if (!first || typeof first !== "object")
+        return undefined;
+    const url = first.url;
+    return typeof url === "string" && /^https?:\/\//.test(url) ? url : undefined;
+}
+function extractTmpfilesUrl(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const data = raw.data;
+    if (!data || typeof data !== "object")
+        return undefined;
+    const url = data.url;
+    return typeof url === "string" && /^https?:\/\//.test(url) ? url : undefined;
+}
+function toTmpfilesDirectUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.hostname !== "tmpfiles.org" || parsed.pathname.startsWith("/dl/")) {
+        return url;
+    }
+    parsed.pathname = `/dl${parsed.pathname}`;
+    return parsed.toString();
+}

package/dist/media/toPublicUrl.js

@@ -1,21 +1,112 @@
-import { access } from "node:fs/promises";
+import { access, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
-import { LitterboxMediaUrlProvider } from "./litterbox.js";
+import { tmpdir } from "node:os";
+import { extname, join } from "node:path";
+import { TemporaryMediaUrlProvider } from "./temporary-upload.js";
 import { resolveConfig } from "../config.js";
 import { AgnesCliError } from "../errors.js";
+const MIME_EXTENSIONS = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "video/mp4": ".mp4",
+    "video/quicktime": ".mov",
+    "video/webm": ".webm",
+};
 export async function toPublicUrl(input, options = {}, config = {}) {
-    if (/^https?:\/\//.test(input)) {
+    if (isPublicHttpUrl(input)) {
         return { ok: true, url: input, source: "passthrough" };
     }
+    const resolved = resolveConfig(config);
+    const provider = resolved.mediaProvider ??
+        new TemporaryMediaUrlProvider(resolved.fetchImpl);
+    const materialized = await materializeUploadInput(input, resolved.fetchImpl);
+    try {
+        const url = await provider.upload(materialized.path, { ttl: options.ttl ?? resolved.defaultMediaTtl });
+        return { ok: true, url, source: resolved.mediaProvider ? "provider" : "temporary" };
+    }
+    finally {
+        if (materialized.cleanupDir) {
+            await rm(materialized.cleanupDir, { recursive: true, force: true });
+        }
+    }
+}
+function isPublicHttpUrl(input) {
+    if (!/^https?:\/\//.test(input))
+        return false;
+    const url = new URL(input);
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return !isPrivateHost(host);
+}
+function isPrivateHost(host) {
+    if (host === "localhost" || host.endsWith(".localhost") || host === "::1") {
+        return true;
+    }
+    if (/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) || /^169\.254\./.test(host)) {
+        return true;
+    }
+    const match = host.match(/^172\.(\d{1,3})\./);
+    if (match) {
+        const secondOctet = Number(match[1]);
+        return secondOctet >= 16 && secondOctet <= 31;
+    }
+    return host === "0.0.0.0" || (host.includes(":") && (host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80:")));
+}
+async function materializeUploadInput(input, fetchImpl) {
+    if (input.startsWith("data:")) {
+        return writeTempMedia(await decodeDataUrl(input));
+    }
+    if (/^https?:\/\//.test(input)) {
+        return writeTempMedia(await fetchPrivateUrl(input, fetchImpl));
+    }
     try {
         await access(input, constants.R_OK);
     }
     catch {
-        throw new AgnesCliError("INPUT_NOT_FOUND", `Input must be an existing file path or an http(s) URL: ${input}`);
+        throw new AgnesCliError("INPUT_NOT_FOUND", `Input must be an existing file path, a data URL, or an http(s) URL: ${input}`);
     }
-    const resolved = resolveConfig(config);
-    const provider = resolved.mediaProvider ??
-        new LitterboxMediaUrlProvider(resolved.fetchImpl);
-    const url = await provider.upload(input, { ttl: options.ttl ?? resolved.defaultMediaTtl });
-    return { ok: true, url, source: resolved.mediaProvider ? "provider" : "litterbox" };
+    return { path: input };
+}
+async function fetchPrivateUrl(input, fetchImpl) {
+    const response = await fetchImpl(input);
+    if (!response.ok) {
+        throw new AgnesCliError("INPUT_FETCH_FAILED", `Input URL fetch failed with HTTP ${response.status}: ${input}`, {
+            status: response.status,
+            url: input,
+        });
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const mimeType = normalizeMimeType(response.headers.get("content-type") ?? undefined);
+    const extension = extname(new URL(input).pathname);
+    return { bytes, mimeType, extension };
+}
+function decodeDataUrl(input) {
+    const match = input.match(/^data:([^;,]+)?((?:;[^,]+)*?),(.*)$/s);
+    if (!match) {
+        throw new AgnesCliError("INPUT_INVALID", "Data URL input is malformed.");
+    }
+    const mimeType = normalizeMimeType(match[1]);
+    const metadata = match[2] ?? "";
+    const body = match[3] ?? "";
+    const bytes = metadata.includes(";base64")
+        ? Buffer.from(body, "base64")
+        : Buffer.from(decodeURIComponent(body));
+    return { bytes, mimeType };
+}
+async function writeTempMedia(input) {
+    const cleanupDir = await mkdtemp(join(tmpdir(), "agnes-media-"));
+    const extension = normalizeExtension(input.extension) ?? (input.mimeType ? MIME_EXTENSIONS[input.mimeType] : undefined) ?? ".bin";
+    const path = join(cleanupDir, `input${extension}`);
+    await writeFile(path, input.bytes);
+    return { path, cleanupDir };
+}
+function normalizeMimeType(value) {
+    return value?.split(";")[0]?.trim().toLowerCase() || undefined;
+}
+function normalizeExtension(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.toLowerCase();
+    return /^\.[a-z0-9]+$/.test(normalized) ? normalized : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agnes-ai-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI and JS API for Agnes text, image, and video workflows.",
   "type": "module",
   "bin": {