@inferencesh/app 0.1.3 → 0.1.5

package/dist/file.d.ts

@@ -22,22 +22,56 @@ export interface FileData {
  * A file in the inference.sh ecosystem.
  *
  * Accepts a URL, local path, or options object.
- * URLs are downloaded and cached locally on construction (via `await File.from()`).
+ * URLs are downloaded lazily when `getPath()` is called.
  * Local paths are resolved to absolute paths.
  *
+ * For API wrapper apps that only need to forward the URL, use `uri` directly
+ * without calling `getPath()` to avoid unnecessary downloads.
+ *
  * In JSON output, File serializes to `{ path, uri, content_type, size, filename }`
  * — the engine uploads local `path` files to CDN and replaces with `uri`.
  */
 export declare class File {
     uri?: string;
-    path?: string;
     contentType?: string;
     size?: number;
     filename?: string;
+    private _path?;
+    private _resolved;
+    private _downloading?;
     private constructor();
+    /**
+     * Get the local file path. Downloads the file lazily if needed.
+     * For sync access after download, use the `path` getter.
+     */
+    getPath(): Promise<string>;
+    /**
+     * Sync access to path. Returns undefined if not yet downloaded.
+     * Use `getPath()` for lazy downloading.
+     */
+    get path(): string | undefined;
+    /**
+     * Check if the file has been downloaded/resolved.
+     */
+    get isResolved(): boolean;
+    private _resolve;
+    /**
+     * Create a lazy File from a URL or path string.
+     * Does NOT download immediately — download happens when `getPath()` is called.
+     *
+     * @example
+     * ```js
+     * const file = File.lazy("https://example.com/image.jpg");
+     * console.log(file.uri);  // Available immediately
+     * const path = await file.getPath();  // Downloads here
+     * ```
+     */
+    static lazy(input: string): File;
     /**
      * Create a File from a URL, local path, or options object.
-     * URLs are downloaded and cached automatically.
+     * URLs are downloaded and cached automatically (eager loading).
+     *
+     * For lazy loading, use `File.lazy()` instead.
      *
      * @example
      * ```js
@@ -58,8 +92,14 @@ export declare class File {
     static fromPath(localPath: string): File;
     /**
      * Check if the file exists on disk.
+     * Note: This checks the current state without triggering download.
+     * Use `getPath()` first if you need to ensure the file is downloaded.
      */
     exists(): boolean;
+    /**
+     * Check if we have a local path (without triggering download).
+     */
+    isLocal(): boolean;
     /**
      * Re-read metadata (contentType, size, filename) from disk.
      */
@@ -67,10 +107,12 @@ export declare class File {
     /**
      * Serialize to a plain object for JSON output.
      * The engine reads `path` fields and uploads them to CDN.
+     * Note: Uses internal _path to avoid triggering download during serialization.
      */
     toJSON(): FileData;
     static getCacheDir(): string;
     private _getCachePath;
+    private _decodeDataUri;
     private _downloadUrl;
     private _populateMetadata;
 }

package/dist/file.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { createWriteStream, existsSync, mkdirSync, statSync, renameSync, unlinkSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, statSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { get as httpsGet } from "node:https";
@@ -9,28 +9,116 @@ import { URL } from "node:url";
  * A file in the inference.sh ecosystem.
  *
  * Accepts a URL, local path, or options object.
- * URLs are downloaded and cached locally on construction (via `await File.from()`).
+ * URLs are downloaded lazily when `getPath()` is called.
  * Local paths are resolved to absolute paths.
  *
+ * For API wrapper apps that only need to forward the URL, use `uri` directly
+ * without calling `getPath()` to avoid unnecessary downloads.
+ *
  * In JSON output, File serializes to `{ path, uri, content_type, size, filename }`
  * — the engine uploads local `path` files to CDN and replaces with `uri`.
  */
 export class File {
     uri;
-    path;
     contentType;
     size;
     filename;
+    _path;
+    _resolved = false;
+    _downloading;
     constructor(options) {
         this.uri = options.uri;
-        this.path = options.path;
+        this._path = options.path;
         this.contentType = options.contentType;
         this.size = options.size;
         this.filename = options.filename;
     }
+    /**
+     * Get the local file path. Downloads the file lazily if needed.
+     * For sync access after download, use the `path` getter.
+     */
+    async getPath() {
+        if (this._resolved && this._path) {
+            return this._path;
+        }
+        // Avoid concurrent downloads
+        if (this._downloading) {
+            return this._downloading;
+        }
+        this._downloading = this._resolve();
+        try {
+            const path = await this._downloading;
+            return path;
+        }
+        finally {
+            this._downloading = undefined;
+        }
+    }
+    /**
+     * Sync access to path. Returns undefined if not yet downloaded.
+     * Use `getPath()` for lazy downloading.
+     */
+    get path() {
+        return this._path;
+    }
+    /**
+     * Check if the file has been downloaded/resolved.
+     */
+    get isResolved() {
+        return this._resolved;
+    }
+    async _resolve() {
+        if (this._resolved && this._path) {
+            return this._path;
+        }
+        if (this.uri) {
+            if (isDataUri(this.uri)) {
+                this._decodeDataUri(this.uri);
+            }
+            else if (isUrl(this.uri)) {
+                await this._downloadUrl(this.uri);
+            }
+            else {
+                // Treat as local path
+                this._path = resolve(this.uri);
+            }
+        }
+        if (this._path) {
+            this._path = resolve(this._path);
+            this._populateMetadata();
+        }
+        this._resolved = true;
+        if (!this._path) {
+            throw new Error("Failed to resolve file path");
+        }
+        return this._path;
+    }
+    /**
+     * Create a lazy File from a URL or path string.
+     * Does NOT download immediately — download happens when `getPath()` is called.
+     *
+     * @example
+     * ```js
+     * const file = File.lazy("https://example.com/image.jpg");
+     * console.log(file.uri);  // Available immediately
+     * const path = await file.getPath();  // Downloads here
+     * ```
+     */
+    static lazy(input) {
+        const file = new File({ uri: input });
+        // If it's a local path (not URL or data URI), resolve immediately
+        if (!isUrl(input) && !isDataUri(input)) {
+            file._path = resolve(input);
+            file._resolved = true;
+            file._populateMetadata();
+        }
+        return file;
+    }
     /**
      * Create a File from a URL, local path, or options object.
-     * URLs are downloaded and cached automatically.
+     * URLs are downloaded and cached automatically (eager loading).
+     *
+     * For lazy loading, use `File.lazy()` instead.
      *
      * @example
      * ```js
@@ -48,7 +136,7 @@ export class File {
         if (input instanceof File) {
             return new File({
                 uri: input.uri,
-                path: input.path,
+                path: input._path,
                 contentType: input.contentType,
                 size: input.size,
                 filename: input.filename,
@@ -72,23 +160,8 @@ export class File {
             throw new Error("Either 'uri' or 'path' must be provided");
         }
         const file = new File(options);
-        // Resolve URI
-        if (file.uri) {
-            if (isUrl(file.uri)) {
-                await file._downloadUrl(file.uri);
-            }
-            else {
-                // Treat as local path
-                file.path = resolve(file.uri);
-            }
-        }
-        if (file.path) {
-            file.path = resolve(file.path);
-            file._populateMetadata();
-        }
-        else {
-            throw new Error("Either 'uri' or 'path' must be provided and be valid");
-        }
+        // Eagerly resolve
+        await file.getPath();
         return file;
     }
     /**
@@ -97,14 +170,23 @@ export class File {
     static fromPath(localPath) {
         const absPath = resolve(localPath);
         const file = new File({ path: absPath });
+        file._resolved = true;
         file._populateMetadata();
         return file;
     }
     /**
      * Check if the file exists on disk.
+     * Note: This checks the current state without triggering download.
+     * Use `getPath()` first if you need to ensure the file is downloaded.
      */
     exists() {
-        return this.path != null && existsSync(this.path);
+        return this._path != null && existsSync(this._path);
+    }
+    /**
+     * Check if we have a local path (without triggering download).
+     */
+    isLocal() {
+        return this._path != null;
     }
     /**
      * Re-read metadata (contentType, size, filename) from disk.
@@ -115,13 +197,14 @@ export class File {
     /**
      * Serialize to a plain object for JSON output.
      * The engine reads `path` fields and uploads them to CDN.
+     * Note: Uses internal _path to avoid triggering download during serialization.
      */
     toJSON() {
         const result = {};
         if (this.uri != null)
             result.uri = this.uri;
-        if (this.path != null)
-            result.path = this.path;
+        if (this._path != null)
+            result.path = this._path;
         if (this.contentType != null)
             result.content_type = this.contentType;
         if (this.size != null)
@@ -148,18 +231,48 @@ export class File {
         mkdirSync(hashDir, { recursive: true });
         return join(hashDir, fname);
     }
+    // --- Data URI ---
+    _decodeDataUri(uri) {
+        const parsed = parseDataUri(uri);
+        // Create cache path based on hash
+        const hash = createHash("sha256").update(uri).digest("hex").slice(0, 16);
+        const cacheDir = join(File.getCacheDir(), "data_uri", hash);
+        // Check for existing cached file
+        if (existsSync(cacheDir)) {
+            const files = require("node:fs").readdirSync(cacheDir);
+            if (files.length > 0) {
+                this._path = join(cacheDir, files[0]);
+                this._populateMetadata();
+                return;
+            }
+        }
+        // Set content type from data URI
+        if (!this.contentType) {
+            this.contentType = parsed.mediaType;
+        }
+        // Write to cache
+        mkdirSync(cacheDir, { recursive: true });
+        const ext = getExtensionForMimeType(parsed.mediaType);
+        const filename = `file${ext}`;
+        const cachePath = join(cacheDir, filename);
+        writeFileSync(cachePath, parsed.data);
+        this._path = cachePath;
+        this._populateMetadata();
+    }
     // --- Download ---
     async _downloadUrl(url) {
         const cachePath = this._getCachePath(url);
         if (existsSync(cachePath)) {
-            this.path = cachePath;
+            this._path = cachePath;
+            this._populateMetadata();
             return;
         }
         const tmpPath = cachePath + ".tmp";
         try {
             await downloadToFile(url, tmpPath);
             renameSync(tmpPath, cachePath);
-            this.path = cachePath;
+            this._path = cachePath;
+            this._populateMetadata();
         }
         catch (err) {
             try {
@@ -171,19 +284,19 @@ export class File {
     }
     // --- Metadata ---
     _populateMetadata() {
-        if (!this.path || !existsSync(this.path))
+        if (!this._path || !existsSync(this._path))
             return;
         if (!this.contentType) {
-            this.contentType = guessContentType(this.path);
+            this.contentType = guessContentType(this._path);
         }
         if (this.size == null) {
             try {
-                this.size = statSync(this.path).size;
+                this.size = statSync(this._path).size;
             }
             catch { /* ignore */ }
         }
         if (!this.filename) {
-            this.filename = basename(this.path);
+            this.filename = basename(this._path);
         }
     }
 }
@@ -191,6 +304,60 @@ export class File {
 function isUrl(s) {
     return s.startsWith("http://") || s.startsWith("https://");
 }
+function isDataUri(s) {
+    return s.startsWith("data:");
+}
+/**
+ * Parse a data URI and return the media type and decoded data.
+ *
+ * Supports formats:
+ * - data:image/jpeg;base64,/9j/4AAQ...
+ * - data:text/plain,Hello%20World
+ * - data:;base64,SGVsbG8= (defaults to text/plain)
+ */
+function parseDataUri(uri) {
+    const match = uri.match(/^data:([^;,]*)?(?:;(base64))?,(.*)$/s);
+    if (!match) {
+        throw new Error("Invalid data URI format");
+    }
+    const mediaType = match[1] || "text/plain";
+    const isBase64 = match[2] === "base64";
+    let dataStr = match[3];
+    if (isBase64) {
+        // Handle URL-safe base64 (- and _ instead of + and /)
+        dataStr = dataStr.replace(/-/g, "+").replace(/_/g, "/");
+        // Add padding if needed
+        const padding = 4 - (dataStr.length % 4);
+        if (padding !== 4) {
+            dataStr += "=".repeat(padding);
+        }
+        return { mediaType, data: Buffer.from(dataStr, "base64") };
+    }
+    else {
+        // URL-encoded data
+        return { mediaType, data: Buffer.from(decodeURIComponent(dataStr), "utf-8") };
+    }
+}
+const EXTENSION_MAP = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/svg+xml": ".svg",
+    "video/mp4": ".mp4",
+    "video/webm": ".webm",
+    "audio/mpeg": ".mp3",
+    "audio/wav": ".wav",
+    "audio/ogg": ".ogg",
+    "application/pdf": ".pdf",
+    "application/json": ".json",
+    "text/plain": ".txt",
+    "text/html": ".html",
+    "text/csv": ".csv",
+};
+function getExtensionForMimeType(mimeType) {
+    return EXTENSION_MAP[mimeType] || "";
+}
 function downloadToFile(url, destPath) {
     return new Promise((resolve, reject) => {
         const parsed = new URL(url);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { File } from "./file.js";
 export type { FileOptions, FileData } from "./file.js";
+export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 export { StorageDir, ensureDir } from "./storage.js";
 export type { StorageDirValue } from "./storage.js";
 export { download } from "./download.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 // File handling
 export { File } from "./file.js";
+// Zod schema utilities
+export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Zod schema utilities for inference.sh apps.
+ *
+ * Provides a `fileSchema` that:
+ * - Accepts URL strings as input
+ * - Transforms to lazy File objects (no download until getPath() called)
+ * - Generates JSON Schema with format: "file"
+ */
+/**
+ * Symbol to mark a schema as a file schema.
+ * The kernel's zodToJsonSchema will detect this and output format: "file".
+ */
+export declare const FILE_SCHEMA_MARKER: unique symbol;
+/**
+ * Create a file schema using the app's Zod instance.
+ *
+ * @example
+ * ```js
+ * import { z } from "zod";
+ * import { createFileSchema } from "@inferencesh/app";
+ *
+ * const fileSchema = createFileSchema(z);
+ *
+ * const InputSchema = z.object({
+ *   image: fileSchema.describe("Input image"),
+ * });
+ * ```
+ */
+export declare function createFileSchema(z: any): any;
+/**
+ * Check if a Zod schema is a file schema (created by createFileSchema).
+ */
+export declare function isFileSchema(schema: any): boolean;

package/dist/schema.js

@@ -0,0 +1,52 @@
+/**
+ * Zod schema utilities for inference.sh apps.
+ *
+ * Provides a `fileSchema` that:
+ * - Accepts URL strings as input
+ * - Transforms to lazy File objects (no download until getPath() called)
+ * - Generates JSON Schema with format: "file"
+ */
+import { File } from "./file.js";
+// We don't import zod directly to avoid version conflicts.
+// Instead, apps provide their own zod and we work with the schema structure.
+/**
+ * Symbol to mark a schema as a file schema.
+ * The kernel's zodToJsonSchema will detect this and output format: "file".
+ */
+export const FILE_SCHEMA_MARKER = Symbol.for("inferencesh.fileSchema");
+/**
+ * Create a file schema using the app's Zod instance.
+ *
+ * @example
+ * ```js
+ * import { z } from "zod";
+ * import { createFileSchema } from "@inferencesh/app";
+ *
+ * const fileSchema = createFileSchema(z);
+ *
+ * const InputSchema = z.object({
+ *   image: fileSchema.describe("Input image"),
+ * });
+ * ```
+ */
+export function createFileSchema(z) {
+    const schema = z.string().transform((uri) => File.lazy(uri));
+    // Mark as file schema for JSON schema generation
+    schema._def[FILE_SCHEMA_MARKER] = true;
+    return schema;
+}
+/**
+ * Check if a Zod schema is a file schema (created by createFileSchema).
+ */
+export function isFileSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    // Check for our marker
+    if (schema._def && schema._def[FILE_SCHEMA_MARKER])
+        return true;
+    // Check inner type for transforms/effects
+    if (schema._def?.typeName === "ZodEffects" && schema._def.schema) {
+        return isFileSchema(schema._def.schema);
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/app",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "rimraf": "^6.0.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "zod": "^4.3.6"
   },
   "files": [
     "dist",