@heyputer/puter.js 2.2.4 → 2.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heyputer/puter.js",
-    "version": "2.2.4",
+    "version": "2.2.8",
     "description": "Puter.js - A JavaScript library for interacting with Puter services.",
     "homepage": "https://developer.puter.com",
     "main": "src/index.js",
@@ -42,6 +42,7 @@
         "webpack-cli": "^5.1.4"
     },
     "dependencies": {
-        "@heyputer/kv.js": "^0.2.1"
+        "@heyputer/kv.js": "^0.2.1",
+        "open": "^10.2.0"
     }
 }

package/src/index.js

@@ -54,7 +54,7 @@ class SimpleLogger {
 
     _prefix () {
         const entries = Object.entries(this.fieldsObj);
-        if ( !entries.length ) return [];
+        if ( ! entries.length ) return [];
         return [`[${ entries.map(([k, v]) => `${k}=${v}`).join(' ')}]`];
     }
 }
@@ -66,7 +66,7 @@ class Lock {
     }
 
     async acquire () {
-        if ( !this.locked ) {
+        if ( ! this.locked ) {
             this.locked = true;
             return;
         }
@@ -374,7 +374,7 @@ const puterInit = (function () {
                     }]`;
                     logger = logger.fields({ prefix });
                     this.logger = logger;
-                } catch (error) {
+                } catch ( error ) {
                     if ( this.debugMode ) {
                         console.error('Failed to initialize prefix logger', error);
                     }
@@ -536,6 +536,9 @@ const puterInit = (function () {
         };
 
         resetAuthToken = function () {
+            if ( this.env === 'worker' || this.env === 'service-worker' ) {
+                throw new Error('Sign out is not permitted from WebWorkers or ServiceWorkers');
+            }
             this.authToken = null;
             // If the SDK is running on a 3rd-party site or an app, then save the authToken in localStorage
             if ( this.env === 'web' || this.env === 'app' ) {

package/src/init.cjs

@@ -1,6 +1,8 @@
 const { readFileSync } = require('node:fs');
 const vm = require('node:vm');
 const { resolve } = require('node:path');
+const { IncomingMessage } = require('node:http');
+const open = require('open');
 /**
  * Method for loading puter.js in Node.js environment with auth token
  * @param {string} authToken - Optional auth token to initialize puter with
@@ -28,4 +30,22 @@ const init = (authToken) => {
     return goodContext.puter;
 };
 
-module.exports = { init };
+const getAuthToken = (guiOrigin = 'https://puter.com') => {
+    const http = require('http');
+
+    return new Promise((resolve) => {
+        const requestListener = function (/**@type {IncomingMessage} */ req, res) {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('Authentication Granted! You maty now close this window.');
+
+            resolve(new URL(req.url, 'http://localhost/').searchParams.get('token'));
+        };
+        const server = http.createServer(requestListener);
+        server.listen(0, function () {
+            const url = `${guiOrigin}/?action=authme&redirectURL=${encodeURIComponent('http://localhost:') + this.address().port}`;
+            open.default(url);
+        });
+    });
+};
+
+module.exports = { init, getAuthToken };

package/src/modules/AI.js

@@ -70,7 +70,7 @@ class AI {
 
         const tryFetchModels = async () => {
             const resp = await fetch(`${this.APIOrigin }/puterai/chat/models/details`, { headers });
-            if ( !resp.ok ) return null;
+            if ( ! resp.ok ) return null;
             const data = await resp.json();
             const models = Array.isArray(data?.models) ? data.models : [];
             return provider ? models.filter(model => model.provider === provider) : models;
@@ -298,13 +298,13 @@ class AI {
             if ( ! options.voice ) {
                 options.voice = '21m00Tcm4TlvDq8ikWAM';
             }
-            if ( ! options.model && typeof options.engine === 'string' ) {
+            if ( !options.model && typeof options.engine === 'string' ) {
                 options.model = options.engine;
             }
             if ( ! options.model ) {
                 options.model = 'eleven_multilingual_v2';
             }
-            if ( ! options.output_format && !options.response_format ) {
+            if ( !options.output_format && !options.response_format ) {
                 options.output_format = 'mp3_44100_128';
             }
             if ( options.response_format && !options.output_format ) {
@@ -736,6 +736,10 @@ class AI {
             requestParams.max_tokens = userParams.max_tokens;
         }
 
+        if ( userParams.provider ) {
+            requestParams.provider = userParams.provider;
+        }
+
         // convert undefined to empty string so that .startsWith works
         requestParams.model = requestParams.model ?? '';
 
@@ -745,11 +749,11 @@ class AI {
         }
 
         if ( userParams.driver ) {
-            driver = userParams.driver;
+            requestParams.provider = requestParams.provider || userParams.driver;
         }
 
         // Additional parameters to pass from userParams to requestParams
-        const PARAMS_TO_PASS = ['tools', 'response', 'reasoning', 'reasoning_effort', 'text', 'verbosity'];
+        const PARAMS_TO_PASS = ['tools', 'response', 'reasoning', 'reasoning_effort', 'text', 'verbosity', 'provider'];
         for ( const name of PARAMS_TO_PASS ) {
             if ( userParams[name] ) {
                 requestParams[name] = userParams[name];
@@ -835,8 +839,8 @@ class AI {
             options.model = 'gemini-2.5-flash-image-preview';
         }
 
-        if (options.model === "nano-banana-pro") {
-            options.model = "gemini-3-pro-image-preview";
+        if ( options.model === 'nano-banana-pro' ) {
+            options.model = 'gemini-3-pro-image-preview';
         }
 
         const driverHint = typeof options.driver === 'string' ? options.driver : undefined;
@@ -912,6 +916,7 @@ class AI {
             options.seconds = options.duration;
         }
 
+        // This sucks, should be backend's job like we do for chat models now
         let videoService = 'openai-video-generation';
         const driverHint = typeof options.driver === 'string' ? options.driver : undefined;
         const driverHintLower = driverHint ? driverHint.toLowerCase() : undefined;
@@ -922,7 +927,7 @@ class AI {
         const modelLower = typeof options.model === 'string' ? options.model.toLowerCase() : '';
 
         const looksLikeTogetherVideoModel = typeof options.model === 'string' &&
-            TOGETHER_VIDEO_MODEL_PREFIXES.some(prefix => modelLower.startsWith(prefix));
+            (TOGETHER_VIDEO_MODEL_PREFIXES.some(prefix => modelLower.startsWith(prefix)) || options.model.startsWith('togetherai:'));
 
         if ( driverHintLower === 'together' || driverHintLower === 'together-ai' ) {
             videoService = 'together-video-generation';
@@ -958,7 +963,8 @@ class AI {
                     return result;
                 }
 
-                const video = (globalThis.document?.createElement('video') || {setAttribute: ()=>{}});
+                const video = (globalThis.document?.createElement('video') || { setAttribute: () => {
+                } });
                 video.src = sourceUrl;
                 video.controls = true;
                 video.preload = 'metadata';

package/src/modules/Apps.js

@@ -217,7 +217,7 @@ class Apps {
             };
         }
 
-        return new Promise((resolve, reject) => {
+        return new Promise((resUpper, rejUpper) => {
             let options;
 
             // If first argument is an object, it's the options
@@ -235,7 +235,7 @@ class Apps {
                 const xhr = utils.initXhr('/get-dev-profile', puter.APIOrigin, puter.authToken, 'get');
 
                 // set up event handlers for load and error events
-                utils.setupXhrEventHandlers(xhr, options.success, options.error, resolve, reject);
+                utils.setupXhrEventHandlers(xhr, options.success ?? resUpper, options.error ?? rejUpper, resolve, reject);
 
                 xhr.send();
             });

package/src/modules/FileSystem/operations/upload.js

@@ -2,6 +2,98 @@ import path from '../../../lib/path.js';
 import * as utils from '../../../lib/utils.js';
 import getAbsolutePathForApp from '../utils/getAbsolutePathForApp.js';
 
+const MAX_THUMBNAIL_BYTES = 2 * 1024 * 1024;
+const DEFAULT_THUMBNAIL_DIMENSION = 128;
+const MIN_THUMBNAIL_DIMENSION = 32;
+
+const isLikelyImageFile = (file) => {
+    if ( ! file ) return false;
+    if ( file.type && file.type.startsWith('image/') ) return true;
+    const name = (file.name || '').toLowerCase();
+    return ['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp', '.tiff', '.avif', '.jfif'].some(ext => name.endsWith(ext));
+};
+
+const estimateDataUrlSize = (dataUrl) => {
+    if ( ! dataUrl ) return 0;
+    const commaIndex = dataUrl.indexOf(',');
+    const base64 = commaIndex === -1 ? dataUrl : dataUrl.slice(commaIndex + 1);
+    return Math.ceil(base64.length * 3 / 4);
+};
+
+const scaleDimensions = (width, height, maxDim) => {
+    const base = Math.max(width, height) || 1;
+    const scale = Math.min(1, maxDim / base);
+    const w = Math.max(1, Math.round(width * scale));
+    const h = Math.max(1, Math.round(height * scale));
+    return { width: w, height: h };
+};
+
+const loadImageFromFile = (file) => new Promise((resolve, reject) => {
+    if ( typeof document === 'undefined' || typeof URL === 'undefined' || typeof Image === 'undefined' ) return resolve(null);
+    const url = URL.createObjectURL(file);
+    const img = new Image();
+    img.onload = () => {
+        URL.revokeObjectURL(url);
+        resolve(img);
+    };
+    img.onerror = (e) => {
+        URL.revokeObjectURL(url);
+        reject(e);
+    };
+    img.src = url;
+});
+
+const renderThumbnail = (img, maxDim, type, quality) => {
+    if ( !img || typeof document === 'undefined' ) return null;
+    const { width, height } = scaleDimensions(img.naturalWidth || img.width, img.naturalHeight || img.height, maxDim);
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if ( ! ctx ) return null;
+    ctx.drawImage(img, 0, 0, width, height);
+    try {
+        return canvas.toDataURL(type, quality);
+    } catch (e) {
+        return null;
+    }
+};
+
+const defaultThumbnailGenerator = async (file) => {
+    try {
+        if ( typeof document === 'undefined' ) return undefined;
+        if ( typeof File === 'undefined' || !(file instanceof File) ) return undefined;
+        if ( ! isLikelyImageFile(file) ) return undefined;
+
+        const img = await loadImageFromFile(file);
+        if ( ! img ) return undefined;
+
+        let dimension = DEFAULT_THUMBNAIL_DIMENSION;
+        const formats = [
+            { type: 'image/webp', quality: 0.85 },
+            { type: 'image/jpeg', quality: 0.8 },
+            { type: 'image/png' },
+        ];
+
+        while ( dimension >= MIN_THUMBNAIL_DIMENSION ) {
+            for ( const { type, quality } of formats ) {
+                const dataUrl = renderThumbnail(img, dimension, type, quality);
+                if ( ! dataUrl ) continue;
+                if ( estimateDataUrlSize(dataUrl) <= MAX_THUMBNAIL_BYTES ) {
+                    return dataUrl;
+                }
+            }
+            dimension = Math.floor(dimension / 2);
+        }
+    } catch (e) {
+        // Ignore thumbnail errors; upload should proceed without them.
+        return undefined;
+    }
+
+    return undefined;
+};
+
+/* eslint-disable */
 const upload = async function (items, dirPath, options = {}) {
     return new Promise(async (resolve, reject) => {
         const DataTransferItem = globalThis.DataTransfer || (class DataTransferItem {
@@ -199,6 +291,19 @@ const upload = async function (items, dirPath, options = {}) {
             return error({ code: 'EMPTY_UPLOAD', message: 'No files or directories to upload.' });
         }
 
+        let thumbnails = [];
+        const shouldGenerateThumbnails = options.generateThumbnails || options.thumbnailGenerator;
+        if ( files.length && shouldGenerateThumbnails ) {
+            const generator = options.thumbnailGenerator || defaultThumbnailGenerator;
+            thumbnails = await Promise.all(files.map(async (file) => {
+                try {
+                    return await generator(file);
+                } catch (e) {
+                    return undefined;
+                }
+            }));
+        }
+
         // Check storage capacity.
         // We need to check the storage capacity before the upload starts because
         // we want to avoid uploading files in case there is not enough storage space.
@@ -286,19 +391,28 @@ const upload = async function (items, dirPath, options = {}) {
         // Append file metadata to upload request
         if ( ! options.shortcutTo ) {
             for ( let i = 0; i < files.length; i++ ) {
-                fd.append('fileinfo', JSON.stringify({
+                const thumbnail = thumbnails[i] ?? options.thumbnail ?? undefined;
+                const fileinfo_payload = {
                     name: files[i].name,
                     type: files[i].type,
                     size: files[i].size,
+                };
+                if ( thumbnail ) {
+                    fileinfo_payload.thumbnail = thumbnail;
+                }
+                fd.append('fileinfo', JSON.stringify({
+                    ...fileinfo_payload,
                 }));
             }
         }
         // Append write operations for each file
         for ( let i = 0; i < files.length; i++ ) {
-            fd.append('operation', JSON.stringify({
+            const thumbnail = thumbnails[i] ?? options.thumbnail ?? undefined;
+            const operation = {
                 op: options.shortcutTo ? 'shortcut' : 'write',
                 dedupe_name: options.dedupeName ?? true,
                 overwrite: options.overwrite ?? false,
+                thumbnail,
                 create_missing_ancestors: (options.createMissingAncestors || options.createMissingParents),
                 operation_id: operation_id,
                 path: (
@@ -313,7 +427,13 @@ const upload = async function (items, dirPath, options = {}) {
                 shortcut_to: options.shortcutTo,
                 shortcut_to_uid: options.shortcutTo,
                 app_uid: options.appUID,
-            }));
+            };
+
+            if ( thumbnail === undefined ) {
+                delete operation.thumbnail;
+            }
+
+            fd.append('operation', JSON.stringify(operation));
         }
 
         // Append files to upload
@@ -463,4 +583,4 @@ const upload = async function (items, dirPath, options = {}) {
     });
 };
 
-export default upload;
+export default upload;

package/src/modules/FileSystem/utils/getAbsolutePathForApp.js

@@ -1,12 +1,18 @@
 import path from '../../../lib/path.js';
 
 const getAbsolutePathForApp = (relativePath) => {
-    // if we are in the gui environment, return the relative path as is
-    if ( puter.env === 'gui' )
+    // preserve previous behavior for falsy values when env is gui
+    if ( puter.env === 'gui' && !relativePath )
     {
         return relativePath;
     }
 
+    const reLooksLikeUUID = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+    const isUUID = reLooksLikeUUID.test(relativePath);
+    if ( isUUID ) {
+        return relativePath;
+    }
+
     // if no relative path is provided, use the current working directory
     if ( ! relativePath )
     {
@@ -15,8 +21,12 @@ const getAbsolutePathForApp = (relativePath) => {
 
     // If relativePath is not provided, or it's not starting with a slash or tilde,
     // it means it's a relative path. In that case, prepend the app's root directory.
-    if ( !relativePath || (!relativePath.startsWith('/') && !relativePath.startsWith('~') && puter.appID) ) {
-        relativePath = path.join('~/AppData', puter.appID, relativePath);
+    if ( !relativePath || (!relativePath.startsWith('/') && !relativePath.startsWith('~')) ) {
+        if ( puter.appID ) {
+            relativePath = path.join('~/AppData', puter.appID, relativePath);
+        } else {
+            relativePath = path.join('~/', relativePath);
+        }
     }
 
     return relativePath;

package/src/modules/KV.js

@@ -233,6 +233,38 @@ class KV {
         return utils.make_driver_method(['key'], 'puter-kvstore', undefined, 'add').call(this, options);
     };
 
+    remove = async (...args) => {
+        if ( !args || args.length < 2 ) {
+            throw ({ message: 'At least one path is required', code: 'arguments_required' });
+        }
+
+        const key = args[0];
+        const paths = args.slice(1);
+
+        if ( Array.isArray(paths[0]) && paths.length === 1 ) {
+            throw ({ message: 'Paths must be provided as separate arguments', code: 'paths_invalid' });
+        }
+
+        if ( key === undefined || key === null ) {
+            throw ({ message: 'Key cannot be undefined', code: 'key_undefined' });
+        }
+
+        if ( key.length > this.MAX_KEY_SIZE ) {
+            throw ({ message: `Key size cannot be larger than ${this.MAX_KEY_SIZE}`, code: 'key_too_large' });
+        }
+
+        if ( paths.length === 0 ) {
+            throw ({ message: 'At least one path is required', code: 'arguments_required' });
+        }
+
+        if ( paths.some((path) => typeof path !== 'string') ) {
+            throw ({ message: 'All paths must be strings', code: 'paths_invalid' });
+        }
+
+        return utils.make_driver_method(['key', 'paths'], 'puter-kvstore', undefined, 'remove')
+            .call(this, { key, paths });
+    };
+
     update = utils.make_driver_method(['key', 'pathAndValueMap', 'ttl'], 'puter-kvstore', undefined, 'update', {
         preprocess: (args) => {
             if ( args.key === undefined || args.key === null ) {
@@ -318,43 +350,43 @@ class KV {
         let pattern;
         let returnValues = false;
 
-        // list(true) or list(pattern, true) will return the key-value pairs
-        if ( (args && args.length === 1 && args[0] === true) || (args && args.length === 2 && args[1] === true) ) {
-            options = {};
-            returnValues = true;
-        }
-        // return only the keys, default behavior
-        else {
-            options = { as: 'keys' };
+        const isOptionsObject = args.length === 1 && args[0] && typeof args[0] === 'object' && !Array.isArray(args[0]);
+
+        if ( isOptionsObject ) {
+            const input = args[0];
+            if ( typeof input.pattern === 'string' ) {
+                pattern = input.pattern;
+            }
+            returnValues = !!input.returnValues;
+            if ( input.limit !== undefined ) {
+                options.limit = input.limit;
+            }
+            if ( input.cursor !== undefined ) {
+                options.cursor = input.cursor;
+            }
+        } else {
+            // list(true) or list(pattern, true) will return the key-value pairs
+            if ( (args && args.length === 1 && args[0] === true) || (args && args.length === 2 && args[1] === true) ) {
+                returnValues = true;
+            }
+
+            // list(pattern)
+            // list(pattern, true)
+            if ( (args && args.length === 1 && typeof args[0] === 'string') || (args && args.length === 2 && typeof args[0] === 'string' && args[1] === true) ) {
+                pattern = args[0];
+            }
         }
 
-        // list(pattern)
-        // list(pattern, true)
-        if ( (args && args.length === 1 && typeof args[0] === 'string') || (args && args.length === 2 && typeof args[0] === 'string' && args[1] === true) ) {
-            pattern = args[0];
+        if ( ! returnValues ) {
+            options.as = 'keys';
         }
 
-        return utils.make_driver_method([], 'puter-kvstore', undefined, 'list', {
-            transform: (res) => {
-                // glob pattern was provided
-                if ( pattern ) {
-                    // consider both the key and the value
-                    if ( ! returnValues ) {
-                        let keys = res.filter((key) => {
-                            return globMatch(pattern, key);
-                        });
-                        return keys;
-                    } else {
-                        let keys = res.filter((key_value_pair) => {
-                            return globMatch(pattern, key_value_pair.key);
-                        });
-                        return keys;
-                    }
-                }
+        const normalizedPattern = normalizeListPattern(pattern);
+        if ( normalizedPattern ) {
+            options.pattern = normalizedPattern;
+        }
 
-                return res;
-            },
-        }).call(this, options);
+        return utils.make_driver_method([], 'puter-kvstore', undefined, 'list').call(this, options);
     };
 
     // resolve to 'true' on success, or rejects with an error on failure
@@ -365,18 +397,19 @@ class KV {
     clear = this.flush;
 }
 
-function globMatch (pattern, str) {
-    const escapeRegExp = (string) => string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-    let regexPattern = escapeRegExp(pattern)
-        .replace(/\\\*/g, '.*') // Replace * with .*
-        .replace(/\\\?/g, '.') // Replace ? with .
-        .replace(/\\\[/g, '[') // Replace [ with [
-        .replace(/\\\]/g, ']') // Replace ] with ]
-        .replace(/\\\^/g, '^'); // Replace ^ with ^
-
-    let re = new RegExp(`^${regexPattern}$`);
-    return re.test(str);
+function normalizeListPattern (pattern) {
+    if ( typeof pattern !== 'string' ) {
+        return undefined;
+    }
+    const trimmed = pattern.trim();
+    if ( trimmed === '' ) {
+        return undefined;
+    }
+    if ( trimmed.endsWith('*') ) {
+        const prefix = trimmed.slice(0, -1);
+        return prefix === '' ? undefined : prefix;
+    }
+    return trimmed;
 }
 
 export default KV;

package/types/modules/kv.d.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-unused-vars */
 export type KVValue = string | number | boolean | object | unknown;
 export type KVScalar = KVValue | KVValue[];
 
@@ -18,6 +19,22 @@ export interface KVAddPath {
     [path: string]: KVValue | KVValue[];
 }
 
+export interface KVListOptions {
+    pattern?: string;
+    returnValues?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+
+export type KVListPaginationOptions =
+    | { limit: number; cursor?: string }
+    | { cursor: string; limit?: number };
+
+export interface KVListPage<T = unknown> {
+    items: T[];
+    cursor?: string;
+}
+
 export class KV {
     readonly MAX_KEY_SIZE: number;
     readonly MAX_VALUE_SIZE: number;
@@ -28,12 +45,17 @@ export class KV {
     incr (key: string, amount?: number | KVIncrementPath): Promise<number>;
     decr (key: string, amount?: number | KVIncrementPath): Promise<number>;
     add (key: string, value?: KVValue | KVAddPath): Promise<KVValue>;
+    remove (key: string, ...paths: string[]): Promise<KVValue>;
     update (key: string, pathAndValueMap: KVUpdatePath, ttlSeconds?: number): Promise<KVValue>;
     expire (key: string, ttlSeconds: number): Promise<boolean>;
     expireAt (key: string, timestampSeconds: number): Promise<boolean>;
     list (pattern?: string, returnValues?: false): Promise<string[]>;
     list<T = unknown>(pattern: string, returnValues: true): Promise<KVPair<T>[]>;
     list<T = unknown>(returnValues: true): Promise<KVPair<T>[]>;
+    list (options: KVListOptions & KVListPaginationOptions & { returnValues?: false }): Promise<KVListPage<string>>;
+    list<T = unknown>(options: KVListOptions & KVListPaginationOptions & { returnValues: true }): Promise<KVListPage<KVPair<T>>>;
+    list (options: KVListOptions & { returnValues?: false }): Promise<string[]>;
+    list<T = unknown>(options: KVListOptions & { returnValues: true }): Promise<KVPair<T>[]>;
     flush (): Promise<boolean>;
     clear (): Promise<boolean>;
 }