@inferencesh/app 0.1.0

package/README.md

@@ -0,0 +1,236 @@
+# @inferencesh/app — build inference.sh apps in node.js
+
+[![npm version](https://img.shields.io/npm/v/@inferencesh/app.svg)](https://www.npmjs.com/package/@inferencesh/app)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+app framework for building [inference.sh](https://inference.sh) apps in node.js — file handling, output metadata, and storage utilities.
+
+this is the **app-side** sdk. for the **client-side** sdk (calling apps, agents, file uploads), see [@inferencesh/sdk](https://www.npmjs.com/package/@inferencesh/sdk).
+
+## installation
+
+```bash
+npm install @inferencesh/app
+```
+
+## what's included
+
+| export | description |
+|--------|-------------|
+| `File` | smart file reference — downloads urls, caches locally, resolves paths, serializes for the engine |
+| `StorageDir` | standard storage directory constants (`DATA`, `TEMP`, `CACHE`) |
+| `download()` | download a url to a directory with caching |
+| `textMeta`, `imageMeta`, `videoMeta`, `audioMeta`, `rawMeta` | output metadata factories for usage-based pricing |
+
+## file handling
+
+the `File` class handles downloading, caching, and path resolution — the node.js equivalent of the python sdk's `File` class.
+
+### reading input files
+
+```javascript
+import { File } from "@inferencesh/app";
+
+async run(inputData) {
+  // Input files come as URLs — File downloads and caches them
+  const file = await File.from(inputData.image);
+  console.log(file.path);        // /home/.cache/inferencesh/files/abc123/image.jpg
+  console.log(file.contentType);  // image/jpeg
+  console.log(file.size);        // 102400
+}
+```
+
+### returning output files
+
+```javascript
+import { File } from "@inferencesh/app";
+
+async run(inputData) {
+  const outputPath = "/tmp/result.png";
+  await generateImage(inputData.prompt, outputPath);
+
+  // File.fromPath is sync — no download needed for local files
+  return { image: File.fromPath(outputPath) };
+}
+```
+
+the engine reads `path` from the serialized output and uploads it to cdn automatically.
+
+### how File serializes
+
+`File` implements `toJSON()` so it works seamlessly with `JSON.stringify`:
+
+```javascript
+const file = File.fromPath("/tmp/output.png");
+JSON.stringify(file);
+// {"path":"/tmp/output.png","content_type":"image/png","size":102400,"filename":"output.png"}
+```
+
+### construction options
+
+```javascript
+// From URL (downloads and caches)
+const file = await File.from("https://example.com/image.jpg");
+
+// From local path
+const file = await File.from("/tmp/output.png");
+
+// From options object
+const file = await File.from({ path: "/tmp/output.png", contentType: "image/png" });
+
+// From engine-style data (snake_case)
+const file = await File.from({ uri: "https://...", content_type: "image/jpeg" });
+
+// Sync from local path (no download)
+const file = File.fromPath("/tmp/output.png");
+```
+
+### caching
+
+downloaded files are cached at `~/.cache/inferencesh/files/{url_hash}/{filename}`. set `FILE_CACHE_DIR` to override.
+
+## storage directories
+
+```javascript
+import { StorageDir, ensureDir } from "@inferencesh/app";
+
+// Standard directories available on inference.sh workers
+StorageDir.DATA   // "/app/data"  — persistent storage
+StorageDir.TEMP   // "/app/tmp"   — cleaned between runs
+StorageDir.CACHE  // "/app/cache" — persists, may be evicted
+
+// Ensure directory exists
+const dataDir = ensureDir(StorageDir.DATA);
+```
+
+## download utility
+
+```javascript
+import { download, StorageDir } from "@inferencesh/app";
+
+// Download to a specific directory with caching
+const modelPath = await download(
+  "https://huggingface.co/org/model/resolve/main/weights.bin",
+  StorageDir.CACHE
+);
+// Returns: /app/cache/{hash}/weights.bin
+```
+
+skips download if the file already exists in the target directory (except for `TEMP`).
+
+## output metadata
+
+report what your app processes and generates for usage-based pricing:
+
+```javascript
+import { textMeta, imageMeta, videoMeta, audioMeta } from "@inferencesh/app";
+
+// LLM app
+async run(inputData) {
+  const result = await this.llm.generate(inputData.prompt);
+  return {
+    response: result.text,
+    output_meta: {
+      inputs: [textMeta({ tokens: result.promptTokens })],
+      outputs: [textMeta({ tokens: result.completionTokens })],
+    },
+  };
+}
+
+// Image generation app
+async run(inputData) {
+  const image = await this.model.generate(inputData.prompt);
+  return {
+    image: File.fromPath(image.path),
+    output_meta: {
+      outputs: [imageMeta({ width: 1024, height: 1024, steps: 20 })],
+    },
+  };
+}
+
+// Video generation app
+async run(inputData) {
+  return {
+    video: File.fromPath(videoPath),
+    output_meta: {
+      outputs: [videoMeta({ resolution: "1080p", seconds: 5.0, fps: 30 })],
+    },
+  };
+}
+```
+
+### meta types
+
+| factory | key fields |
+|---------|-----------|
+| `textMeta` | `tokens` |
+| `imageMeta` | `width`, `height`, `resolution_mp`, `steps`, `count` |
+| `videoMeta` | `width`, `height`, `resolution`, `seconds`, `fps` |
+| `audioMeta` | `seconds`, `sample_rate` |
+| `rawMeta` | `cost` (dollar cents) |
+
+all meta types support an optional `extra` field for app-specific pricing factors.
+
+## full app example
+
+```javascript
+import { z } from "zod";
+import { File, textMeta } from "@inferencesh/app";
+
+export const RunInput = z.object({
+  prompt: z.string().describe("Input prompt"),
+  image: z.string().optional().describe("Optional image URL"),
+});
+
+export const RunOutput = z.object({
+  result: z.string(),
+  processedImage: z.any().optional(),
+});
+
+export class App {
+  async setup(config) {
+    this.model = await loadModel();
+  }
+
+  async run(inputData) {
+    // Handle input files
+    let imageFile;
+    if (inputData.image) {
+      imageFile = await File.from(inputData.image);
+    }
+
+    const result = await this.model.process({
+      prompt: inputData.prompt,
+      imagePath: imageFile?.path,
+    });
+
+    return {
+      result: result.text,
+      processedImage: result.outputPath
+        ? File.fromPath(result.outputPath)
+        : undefined,
+      output_meta: {
+        inputs: [textMeta({ tokens: result.inputTokens })],
+        outputs: [textMeta({ tokens: result.outputTokens })],
+      },
+    };
+  }
+}
+```
+
+## requirements
+
+- node.js 18.0.0 or higher
+- zero runtime dependencies
+
+## resources
+
+- [documentation](https://inference.sh/docs) — getting started guides
+- [app development guide](https://inference.sh/docs/extend/app-code) — writing app logic
+- [client sdk](https://www.npmjs.com/package/@inferencesh/sdk) — calling apps from your code
+- [discord](https://discord.gg/RM77SWSbyT) — community support
+
+## license
+
+MIT © [inference.sh](https://inference.sh)

package/dist/download.d.ts

@@ -0,0 +1,15 @@
+import { type StorageDirValue } from "./storage.js";
+/**
+ * Download a file to a directory and return its local path.
+ *
+ * Uses the same cache as `File.from()`. If the file already exists in the
+ * target directory (and it's not TEMP), returns the cached copy.
+ *
+ * @example
+ * ```js
+ * import { download, StorageDir } from "@inferencesh/app";
+ *
+ * const path = await download("https://example.com/model.bin", StorageDir.CACHE);
+ * ```
+ */
+export declare function download(url: string, directory: StorageDirValue | string): Promise<string>;

package/dist/download.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { File } from "./file.js";
+import { StorageDir } from "./storage.js";
+/**
+ * Download a file to a directory and return its local path.
+ *
+ * Uses the same cache as `File.from()`. If the file already exists in the
+ * target directory (and it's not TEMP), returns the cached copy.
+ *
+ * @example
+ * ```js
+ * import { download, StorageDir } from "@inferencesh/app";
+ *
+ * const path = await download("https://example.com/model.bin", StorageDir.CACHE);
+ * ```
+ */
+export async function download(url, directory) {
+    const dirPath = directory;
+    mkdirSync(dirPath, { recursive: true });
+    // Build output path with hash subdirectory (matches Python SDK)
+    const parsed = new URL(url);
+    let components = parsed.host + parsed.pathname;
+    if (parsed.search)
+        components += parsed.search;
+    const hash = createHash("sha256").update(components).digest("hex").slice(0, 12);
+    const filename = basename(parsed.pathname) || "download";
+    const hashDir = join(dirPath, hash);
+    mkdirSync(hashDir, { recursive: true });
+    const outputPath = join(hashDir, filename);
+    // Skip download if already in target directory (unless TEMP)
+    if (existsSync(outputPath) && directory !== StorageDir.TEMP) {
+        return outputPath;
+    }
+    // Download via File (uses File's own cache)
+    const file = await File.from(url);
+    if (file.path) {
+        copyFileSync(file.path, outputPath);
+        return outputPath;
+    }
+    throw new Error(`Failed to download ${url}`);
+}

package/dist/file.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Options for constructing a File.
+ */
+export interface FileOptions {
+    uri?: string;
+    path?: string;
+    contentType?: string;
+    size?: number;
+    filename?: string;
+}
+/**
+ * Serialized File representation — what the engine sees in task output.
+ */
+export interface FileData {
+    uri?: string;
+    path?: string;
+    content_type?: string;
+    size?: number;
+    filename?: string;
+}
+/**
+ * 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()`).
+ * Local paths are resolved to absolute paths.
+ *
+ * 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 constructor();
+    /**
+     * Create a File from a URL, local path, or options object.
+     * URLs are downloaded and cached automatically.
+     *
+     * @example
+     * ```js
+     * // From local path
+     * const file = await File.from("/tmp/output.png");
+     *
+     * // From URL (downloads and caches)
+     * const file = await File.from("https://example.com/image.jpg");
+     *
+     * // From options
+     * const file = await File.from({ path: "/tmp/output.png", contentType: "image/png" });
+     * ```
+     */
+    static from(input: string | FileData | FileOptions | File): Promise<File>;
+    /**
+     * Create a File from a local path (sync, no download).
+     */
+    static fromPath(localPath: string): File;
+    /**
+     * Check if the file exists on disk.
+     */
+    exists(): boolean;
+    /**
+     * Re-read metadata (contentType, size, filename) from disk.
+     */
+    refreshMetadata(): void;
+    /**
+     * Serialize to a plain object for JSON output.
+     * The engine reads `path` fields and uploads them to CDN.
+     */
+    toJSON(): FileData;
+    static getCacheDir(): string;
+    private _getCachePath;
+    private _downloadUrl;
+    private _populateMetadata;
+}

package/dist/file.js

@@ -0,0 +1,235 @@
+import { createHash } from "node:crypto";
+import { createWriteStream, existsSync, mkdirSync, statSync, renameSync, unlinkSync } from "node:fs";
+import { basename, resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { get as httpsGet } from "node:https";
+import { get as httpGet } from "node:http";
+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()`).
+ * Local paths are resolved to absolute paths.
+ *
+ * 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;
+    constructor(options) {
+        this.uri = options.uri;
+        this.path = options.path;
+        this.contentType = options.contentType;
+        this.size = options.size;
+        this.filename = options.filename;
+    }
+    /**
+     * Create a File from a URL, local path, or options object.
+     * URLs are downloaded and cached automatically.
+     *
+     * @example
+     * ```js
+     * // From local path
+     * const file = await File.from("/tmp/output.png");
+     *
+     * // From URL (downloads and caches)
+     * const file = await File.from("https://example.com/image.jpg");
+     *
+     * // From options
+     * const file = await File.from({ path: "/tmp/output.png", contentType: "image/png" });
+     * ```
+     */
+    static async from(input) {
+        if (input instanceof File) {
+            return new File({
+                uri: input.uri,
+                path: input.path,
+                contentType: input.contentType,
+                size: input.size,
+                filename: input.filename,
+            });
+        }
+        let options;
+        if (typeof input === "string") {
+            options = { uri: input };
+        }
+        else {
+            const data = input;
+            options = {
+                uri: data.uri,
+                path: data.path,
+                contentType: data.content_type ?? data.contentType,
+                size: data.size,
+                filename: data.filename,
+            };
+        }
+        if (!options.uri && !options.path) {
+            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");
+        }
+        return file;
+    }
+    /**
+     * Create a File from a local path (sync, no download).
+     */
+    static fromPath(localPath) {
+        const absPath = resolve(localPath);
+        const file = new File({ path: absPath });
+        file._populateMetadata();
+        return file;
+    }
+    /**
+     * Check if the file exists on disk.
+     */
+    exists() {
+        return this.path != null && existsSync(this.path);
+    }
+    /**
+     * Re-read metadata (contentType, size, filename) from disk.
+     */
+    refreshMetadata() {
+        this._populateMetadata();
+    }
+    /**
+     * Serialize to a plain object for JSON output.
+     * The engine reads `path` fields and uploads them to CDN.
+     */
+    toJSON() {
+        const result = {};
+        if (this.uri != null)
+            result.uri = this.uri;
+        if (this.path != null)
+            result.path = this.path;
+        if (this.contentType != null)
+            result.content_type = this.contentType;
+        if (this.size != null)
+            result.size = this.size;
+        if (this.filename != null)
+            result.filename = this.filename;
+        return result;
+    }
+    // --- Cache ---
+    static getCacheDir() {
+        const envDir = process.env.FILE_CACHE_DIR;
+        const dir = envDir || join(homedir(), ".cache", "inferencesh", "files");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    _getCachePath(url) {
+        const parsed = new URL(url);
+        let components = parsed.host + parsed.pathname;
+        if (parsed.search)
+            components += parsed.search;
+        const hash = createHash("sha256").update(components).digest("hex").slice(0, 12);
+        const fname = basename(parsed.pathname) || "download";
+        const hashDir = join(File.getCacheDir(), hash);
+        mkdirSync(hashDir, { recursive: true });
+        return join(hashDir, fname);
+    }
+    // --- Download ---
+    async _downloadUrl(url) {
+        const cachePath = this._getCachePath(url);
+        if (existsSync(cachePath)) {
+            this.path = cachePath;
+            return;
+        }
+        const tmpPath = cachePath + ".tmp";
+        try {
+            await downloadToFile(url, tmpPath);
+            renameSync(tmpPath, cachePath);
+            this.path = cachePath;
+        }
+        catch (err) {
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch { /* ignore */ }
+            throw new Error(`Failed to download ${url}: ${err.message}`);
+        }
+    }
+    // --- Metadata ---
+    _populateMetadata() {
+        if (!this.path || !existsSync(this.path))
+            return;
+        if (!this.contentType) {
+            this.contentType = guessContentType(this.path);
+        }
+        if (this.size == null) {
+            try {
+                this.size = statSync(this.path).size;
+            }
+            catch { /* ignore */ }
+        }
+        if (!this.filename) {
+            this.filename = basename(this.path);
+        }
+    }
+}
+// --- Helpers ---
+function isUrl(s) {
+    return s.startsWith("http://") || s.startsWith("https://");
+}
+function downloadToFile(url, destPath) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const getter = parsed.protocol === "https:" ? httpsGet : httpGet;
+        const request = getter(url, (response) => {
+            // Follow redirects
+            if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+                downloadToFile(response.headers.location, destPath).then(resolve, reject);
+                return;
+            }
+            if (response.statusCode && response.statusCode >= 400) {
+                reject(new Error(`HTTP ${response.statusCode}`));
+                return;
+            }
+            const dir = join(destPath, "..");
+            mkdirSync(dir, { recursive: true });
+            const stream = createWriteStream(destPath);
+            response.pipe(stream);
+            stream.on("finish", () => {
+                stream.close();
+                resolve();
+            });
+            stream.on("error", reject);
+        });
+        request.on("error", reject);
+    });
+}
+const MIME_TYPES = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png",
+    ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+    ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg",
+    ".flac": "audio/flac", ".aac": "audio/aac",
+    ".pdf": "application/pdf", ".json": "application/json",
+    ".txt": "text/plain", ".csv": "text/csv", ".html": "text/html",
+    ".zip": "application/zip", ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+};
+function guessContentType(filePath) {
+    const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+    return MIME_TYPES[ext];
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { File } from "./file.js";
+export type { FileOptions, FileData } from "./file.js";
+export { StorageDir, ensureDir } from "./storage.js";
+export type { StorageDirValue } from "./storage.js";
+export { download } from "./download.js";
+export { textMeta, imageMeta, videoMeta, audioMeta, rawMeta } from "./output-meta.js";
+export type { OutputMeta, MetaItem, MetaItemBase, TextMeta, ImageMeta, VideoMeta, AudioMeta, RawMeta, } from "./output-meta.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// File handling
+export { File } from "./file.js";
+// Storage directories
+export { StorageDir, ensureDir } from "./storage.js";
+// Download utility
+export { download } from "./download.js";
+// Output metadata for usage-based pricing
+export { textMeta, imageMeta, videoMeta, audioMeta, rawMeta } from "./output-meta.js";

package/dist/output-meta.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Output metadata types for usage-based pricing.
+ *
+ * Apps include OutputMeta in their run output to report what was consumed
+ * (inputs) and what was produced (outputs). The backend uses this for
+ * pricing calculation.
+ *
+ * @example
+ * ```js
+ * import { textMeta, imageMeta } from "@inferencesh/app";
+ *
+ * return {
+ *   result: generatedText,
+ *   output_meta: {
+ *     inputs: [textMeta({ tokens: promptTokens })],
+ *     outputs: [textMeta({ tokens: completionTokens })],
+ *   },
+ * };
+ * ```
+ */
+export interface MetaItemBase {
+    type: string;
+    extra?: Record<string, unknown>;
+}
+export interface TextMeta extends MetaItemBase {
+    type: "text";
+    tokens: number;
+}
+export interface ImageMeta extends MetaItemBase {
+    type: "image";
+    width?: number;
+    height?: number;
+    resolution_mp?: number;
+    steps?: number;
+    count?: number;
+}
+export interface VideoMeta extends MetaItemBase {
+    type: "video";
+    width?: number;
+    height?: number;
+    resolution_mp?: number;
+    resolution?: "480p" | "720p" | "1080p" | "1440p" | "4k";
+    seconds?: number;
+    fps?: number;
+}
+export interface AudioMeta extends MetaItemBase {
+    type: "audio";
+    seconds?: number;
+    sample_rate?: number;
+}
+export interface RawMeta extends MetaItemBase {
+    type: "raw";
+    cost?: number;
+}
+export type MetaItem = TextMeta | ImageMeta | VideoMeta | AudioMeta | RawMeta;
+export interface OutputMeta {
+    inputs?: MetaItem[];
+    outputs?: MetaItem[];
+}
+/** Create a text metadata item. */
+export declare function textMeta(opts: Omit<TextMeta, "type">): TextMeta;
+/** Create an image metadata item. */
+export declare function imageMeta(opts?: Omit<ImageMeta, "type">): ImageMeta;
+/** Create a video metadata item. */
+export declare function videoMeta(opts?: Omit<VideoMeta, "type">): VideoMeta;
+/** Create an audio metadata item. */
+export declare function audioMeta(opts?: Omit<AudioMeta, "type">): AudioMeta;
+/** Create a raw metadata item (custom pricing). */
+export declare function rawMeta(opts?: Omit<RawMeta, "type">): RawMeta;

package/dist/output-meta.js

@@ -0,0 +1,41 @@
+/**
+ * Output metadata types for usage-based pricing.
+ *
+ * Apps include OutputMeta in their run output to report what was consumed
+ * (inputs) and what was produced (outputs). The backend uses this for
+ * pricing calculation.
+ *
+ * @example
+ * ```js
+ * import { textMeta, imageMeta } from "@inferencesh/app";
+ *
+ * return {
+ *   result: generatedText,
+ *   output_meta: {
+ *     inputs: [textMeta({ tokens: promptTokens })],
+ *     outputs: [textMeta({ tokens: completionTokens })],
+ *   },
+ * };
+ * ```
+ */
+// --- Factories ---
+/** Create a text metadata item. */
+export function textMeta(opts) {
+    return { type: "text", ...opts };
+}
+/** Create an image metadata item. */
+export function imageMeta(opts = {}) {
+    return { type: "image", ...opts };
+}
+/** Create a video metadata item. */
+export function videoMeta(opts = {}) {
+    return { type: "video", ...opts };
+}
+/** Create an audio metadata item. */
+export function audioMeta(opts = {}) {
+    return { type: "audio", ...opts };
+}
+/** Create a raw metadata item (custom pricing). */
+export function rawMeta(opts = {}) {
+    return { type: "raw", ...opts };
+}

package/dist/storage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Standard storage directories available to inference.sh apps at runtime.
+ */
+export declare const StorageDir: {
+    /** Persistent storage — survives across runs */
+    readonly DATA: "/app/data";
+    /** Temporary storage — cleaned between runs */
+    readonly TEMP: "/app/tmp";
+    /** Cache storage — persists across runs, may be evicted */
+    readonly CACHE: "/app/cache";
+};
+export type StorageDirValue = (typeof StorageDir)[keyof typeof StorageDir];
+/**
+ * Ensure a storage directory exists and return its path.
+ *
+ * @example
+ * ```js
+ * import { ensureDir, StorageDir } from "@inferencesh/app";
+ *
+ * const dataDir = ensureDir(StorageDir.DATA);
+ * ```
+ */
+export declare function ensureDir(dir: StorageDirValue | string): string;

package/dist/storage.js

@@ -0,0 +1,26 @@
+import { mkdirSync } from "node:fs";
+/**
+ * Standard storage directories available to inference.sh apps at runtime.
+ */
+export const StorageDir = {
+    /** Persistent storage — survives across runs */
+    DATA: "/app/data",
+    /** Temporary storage — cleaned between runs */
+    TEMP: "/app/tmp",
+    /** Cache storage — persists across runs, may be evicted */
+    CACHE: "/app/cache",
+};
+/**
+ * Ensure a storage directory exists and return its path.
+ *
+ * @example
+ * ```js
+ * import { ensureDir, StorageDir } from "@inferencesh/app";
+ *
+ * const dataDir = ensureDir(StorageDir.DATA);
+ * ```
+ */
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}

package/dist/test/file.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/file.test.js

@@ -0,0 +1,70 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert";
+import { writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { File } from "../file.js";
+const TEST_DIR = join(tmpdir(), "inferencesh-app-test-" + Date.now());
+let testFile;
+describe("File", () => {
+    before(() => {
+        mkdirSync(TEST_DIR, { recursive: true });
+        testFile = join(TEST_DIR, "hello.txt");
+        writeFileSync(testFile, "hello world");
+    });
+    after(() => {
+        rmSync(TEST_DIR, { recursive: true, force: true });
+    });
+    it("creates from local path", () => {
+        const file = File.fromPath(testFile);
+        assert.ok(file.path);
+        assert.ok(file.exists());
+        assert.strictEqual(file.filename, "hello.txt");
+        assert.strictEqual(file.contentType, "text/plain");
+        assert.strictEqual(file.size, 11);
+    });
+    it("creates from path via async from()", async () => {
+        const file = await File.from(testFile);
+        assert.ok(file.path);
+        assert.ok(file.exists());
+        assert.strictEqual(file.filename, "hello.txt");
+    });
+    it("creates from options object", async () => {
+        const file = await File.from({ path: testFile, contentType: "text/plain" });
+        assert.ok(file.exists());
+        assert.strictEqual(file.contentType, "text/plain");
+    });
+    it("creates from FileData with content_type (snake_case)", async () => {
+        const file = await File.from({ path: testFile, content_type: "application/octet-stream" });
+        assert.strictEqual(file.contentType, "application/octet-stream");
+    });
+    it("creates from another File", async () => {
+        const original = File.fromPath(testFile);
+        const copy = await File.from(original);
+        assert.strictEqual(copy.path, original.path);
+        assert.strictEqual(copy.filename, original.filename);
+    });
+    it("serializes to JSON with snake_case", () => {
+        const file = File.fromPath(testFile);
+        const json = file.toJSON();
+        assert.ok(json.path);
+        assert.strictEqual(json.content_type, "text/plain");
+        assert.strictEqual(json.size, 11);
+        assert.strictEqual(json.filename, "hello.txt");
+        assert.strictEqual(json.uri, undefined);
+    });
+    it("works with JSON.stringify", () => {
+        const file = File.fromPath(testFile);
+        const str = JSON.stringify({ image: file });
+        const parsed = JSON.parse(str);
+        assert.ok(parsed.image.path);
+        assert.strictEqual(parsed.image.content_type, "text/plain");
+    });
+    it("resolves relative paths to absolute", () => {
+        const file = File.fromPath("./package.json");
+        assert.ok(file.path.startsWith("/"));
+    });
+    it("throws on missing path and uri", async () => {
+        await assert.rejects(() => File.from({}), /Either 'uri' or 'path' must be provided/);
+    });
+});

package/dist/test/output-meta.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/output-meta.test.js

@@ -0,0 +1,48 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { textMeta, imageMeta, videoMeta, audioMeta, rawMeta } from "../output-meta.js";
+describe("OutputMeta", () => {
+    it("creates text meta", () => {
+        const meta = textMeta({ tokens: 150 });
+        assert.strictEqual(meta.type, "text");
+        assert.strictEqual(meta.tokens, 150);
+    });
+    it("creates image meta", () => {
+        const meta = imageMeta({ width: 1024, height: 1024, steps: 20, count: 1 });
+        assert.strictEqual(meta.type, "image");
+        assert.strictEqual(meta.width, 1024);
+        assert.strictEqual(meta.steps, 20);
+    });
+    it("creates video meta", () => {
+        const meta = videoMeta({ resolution: "1080p", seconds: 5.0 });
+        assert.strictEqual(meta.type, "video");
+        assert.strictEqual(meta.resolution, "1080p");
+    });
+    it("creates audio meta", () => {
+        const meta = audioMeta({ seconds: 30.0 });
+        assert.strictEqual(meta.type, "audio");
+        assert.strictEqual(meta.seconds, 30.0);
+    });
+    it("creates raw meta", () => {
+        const meta = rawMeta({ cost: 0.5 });
+        assert.strictEqual(meta.type, "raw");
+        assert.strictEqual(meta.cost, 0.5);
+    });
+    it("supports extra data", () => {
+        const meta = imageMeta({ width: 512, height: 512, extra: { model: "sdxl" } });
+        assert.strictEqual(meta.extra?.model, "sdxl");
+    });
+    it("composes into OutputMeta", () => {
+        const output = {
+            inputs: [textMeta({ tokens: 100 })],
+            outputs: [textMeta({ tokens: 500 }), imageMeta({ width: 1024, height: 1024 })],
+        };
+        assert.strictEqual(output.inputs.length, 1);
+        assert.strictEqual(output.outputs.length, 2);
+        // Serializes cleanly
+        const json = JSON.stringify(output);
+        const parsed = JSON.parse(json);
+        assert.strictEqual(parsed.inputs[0].type, "text");
+        assert.strictEqual(parsed.outputs[1].type, "image");
+    });
+});

package/dist/test/storage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/storage.test.js

@@ -0,0 +1,10 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { StorageDir } from "../storage.js";
+describe("StorageDir", () => {
+    it("has correct paths", () => {
+        assert.strictEqual(StorageDir.DATA, "/app/data");
+        assert.strictEqual(StorageDir.TEMP, "/app/tmp");
+        assert.strictEqual(StorageDir.CACHE, "/app/cache");
+    });
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@inferencesh/app",
+  "version": "0.1.0",
+  "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/test/*.test.js",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "inference",
+    "ai",
+    "ml",
+    "app",
+    "sdk",
+    "file",
+    "typescript"
+  ],
+  "author": "Okaris <hello@inference.sh>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inference-sh/sdk-js-app.git"
+  },
+  "homepage": "https://inference.sh",
+  "bugs": {
+    "url": "https://github.com/inference-sh/sdk-js-app/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}