@heyputer/puter.js 2.1.10 → 2.1.14

package/index.d.ts

@@ -4,7 +4,7 @@ import type { Apps, AppListOptions, AppRecord, CreateAppOptions, UpdateAppAttrib
 import type { Auth, APIUsage, AllowanceInfo, AppUsage, AuthUser, DetailedAppUsage, MonthlyUsage } from './types/modules/auth.d.ts';
 import type { Debug } from './types/modules/debug.d.ts';
 import type { Driver, DriverDescriptor, Drivers } from './types/modules/drivers.d.ts';
-import type { PuterJSFileSystemModule, CopyOptions, DeleteOptions, MkdirOptions, MoveOptions, ReadOptions, ReaddirOptions, SignResult, SpaceInfo, UploadOptions, WriteOptions } from './types/modules/filesystem.d.ts';
+import type { FS, CopyOptions, DeleteOptions, MkdirOptions, MoveOptions, ReadOptions, ReaddirOptions, SignResult, SpaceInfo, UploadOptions, WriteOptions } from './types/modules/filesystem.d.ts';
 import type { FSItem, FileSignatureInfo, InternalFSProperties } from './types/modules/fs-item.d.ts';
 import type { Hosting, Subdomain } from './types/modules/hosting.d.ts';
 import type { KV, KVIncrementPath, KVPair } from './types/modules/kv.d.ts';
@@ -83,7 +83,7 @@ export type {
     PTLSSocket,
     Puter,
     PuterEnvironment,
-    PuterJSFileSystemModule,
+    FS,
     ReadOptions,
     ReaddirOptions,
     RequestCallbacks,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heyputer/puter.js",
-    "version": "2.1.10",
+    "version": "2.1.14",
     "description": "Puter.js - A JavaScript library for interacting with Puter services.",
     "main": "src/index.js",
     "types": "./index.d.ts",

package/src/index.js

@@ -458,6 +458,7 @@ const puterInit = (function () {
 
         registerModule (name, cls, parameters = {}) {
             const instance = new cls(this.context, parameters);
+            instance.puter = this;
             this.modules_.push(name);
             this[name] = instance;
             if ( instance._init ) instance._init({ puter: this });

package/src/modules/Perms.js

@@ -111,4 +111,243 @@ export default class Perms {
     async listGroups () {
         return await this.req_('/group/list');
     }
+
+    /**
+     * @deprecated use .request() instead
+     */
+    requestPermission (...a) {
+        return this.request(...a);
+    };
+
+    /**
+     * Request a specific permission string to be granted. Note that some
+     * permission strings are not supported and will be denied silently.
+     * @param {string} permission - permission string to request
+     * @returns {boolean} true if permission was granted, false otherwise
+     */
+    async request (permission) {
+        // note: we cannot move this fully from "puter.ui" without
+        // a significant refactor because the UI module contains
+        // all of the IPC communication logic.
+        return await this.puter.ui.requestPermission({ permission });
+    };
+
+    // #region shorthand functions
+    /**
+     * Request to see a user's email. If the user has already granted this
+     * permission the user will not be prompted and their email address
+     * will be returned. If the user grants permission their email address will
+     * be returned. If the user does not allow access `undefined` will be
+     * returned. If the user does not have an email address, the value of their
+     * email address will be `null`.
+     *
+     * @return {string|null|undefined} An email address or undefined
+     */
+    async requestEmail () {
+        let whoami;
+        whoami = await this.puter.auth.whoami();
+        if ( whoami.email !== undefined ) return whoami.email;
+        const granted = await this.puter.ui.requestPermission({
+            permission: `user:${whoami.uuid}:email:read`,
+        });
+        if ( granted ) {
+            whoami = await this.puter.auth.whoami();
+        }
+        return whoami.email;
+    }
+
+    /**
+     * Request read access to the user's Desktop folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Desktop path or undefined
+     */
+    async requestReadDesktop () {
+        return this.requestFolder_('Desktop', 'read');
+    }
+
+    /**
+     * Request write access to the user's Desktop folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Desktop path or undefined
+     */
+    async requestWriteDesktop () {
+        return this.requestFolder_('Desktop', 'write');
+    }
+
+    /**
+     * Request read access to the user's Documents folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Documents path or undefined
+     */
+    async requestReadDocuments () {
+        return this.requestFolder_('Documents', 'read');
+    }
+
+    /**
+     * Request write access to the user's Documents folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Documents path or undefined
+     */
+    async requestWriteDocuments () {
+        return this.requestFolder_('Documents', 'write');
+    }
+
+    /**
+     * Request read access to the user's Pictures folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Pictures path or undefined
+     */
+    async requestReadPictures () {
+        return this.requestFolder_('Pictures', 'read');
+    }
+
+    /**
+     * Request write access to the user's Pictures folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Pictures path or undefined
+     */
+    async requestWritePictures () {
+        return this.requestFolder_('Pictures', 'write');
+    }
+
+    /**
+     * Request read access to the user's Videos folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Videos path or undefined
+     */
+    async requestReadVideos () {
+        return this.requestFolder_('Videos', 'read');
+    }
+
+    /**
+     * Request write access to the user's Videos folder. If the user has already
+     * granted this permission the user will not be prompted and the path will
+     * be returned. If the user grants permission the path will be returned.
+     * If the user does not allow access `undefined` will be returned.
+     *
+     * @return {string|undefined} The Videos path or undefined
+     */
+    async requestWriteVideos () {
+        return this.requestFolder_('Videos', 'write');
+    }
+
+    /**
+     * Request read access to the user's apps. If the user has already granted
+     * this permission the user will not be prompted and `true` will be returned.
+     * If the user grants permission `true` will be returned. If the user does
+     * not allow access `false` will be returned.
+     *
+     * @return {boolean} Whether read access to apps was granted
+     */
+    async requestReadApps () {
+        const whoami = await this.puter.auth.whoami();
+        const granted = await this.puter.ui.requestPermission({
+            permission: `apps-of-user:${whoami.uuid}:read`,
+        });
+        return granted;
+    }
+
+    /**
+     * Request write (manage) access to the user's apps. If the user has already
+     * granted this permission the user will not be prompted and `true` will be
+     * returned. If the user grants permission `true` will be returned. If the
+     * user does not allow access `false` will be returned.
+     *
+     * @return {boolean} Whether manage access to apps was granted
+     */
+    async requestManageApps () {
+        const whoami = await this.puter.auth.whoami();
+        const granted = await this.puter.ui.requestPermission({
+            permission: `apps-of-user:${whoami.uuid}:write`,
+        });
+        return granted;
+    }
+
+    /**
+     * Request read access to the user's subdomains. If the user has already
+     * granted this permission the user will not be prompted and `true` will be
+     * returned. If the user grants permission `true` will be returned. If the
+     * user does not allow access `false` will be returned.
+     *
+     * @return {boolean} Whether read access to subdomains was granted
+     */
+    async requestReadSubdomains () {
+        const whoami = await this.puter.auth.whoami();
+        const granted = await this.puter.ui.requestPermission({
+            permission: `subdomains-of-user:${whoami.uuid}:read`,
+        });
+        return granted;
+    }
+
+    /**
+     * Request write (manage) access to the user's subdomains. If the user has
+     * already granted this permission the user will not be prompted and `true`
+     * will be returned. If the user grants permission `true` will be returned.
+     * If the user does not allow access `false` will be returned.
+     *
+     * @return {boolean} Whether manage access to subdomains was granted
+     */
+    async requestManageSubdomains () {
+        const whoami = await this.puter.auth.whoami();
+        const granted = await this.puter.ui.requestPermission({
+            permission: `subdomains-of-user:${whoami.uuid}:write`,
+        });
+        return granted;
+    }
+
+    /**
+     * Internal helper to request access to a user's special folder.
+     * @private
+     * @param {string} folderName - The name of the folder (Desktop, Documents, Pictures, Videos)
+     * @param {string} accessLevel - The access level (read, write)
+     * @return {string|undefined} The folder path or undefined
+     */
+    async requestFolder_ (folderName, accessLevel) {
+        const whoami = await this.puter.auth.whoami();
+        const folderPath = `/${whoami.username}/${folderName}`;
+
+        // Check if we already have access by trying to stat the folder
+        try {
+            await this.puter.fs.stat({ path: folderPath });
+
+            // If we can stat the folder, we have at least read access
+            if ( accessLevel !== 'write' ) {
+                return folderPath;
+            }
+        } catch (e) {
+            // No access yet, need to request permission
+        }
+
+        const granted = await this.puter.ui.requestPermission({
+            permission: `fs:${folderPath}:${accessLevel}`,
+        });
+
+        if ( granted ) {
+            return folderPath;
+        }
+
+        return undefined;
+    }
+    // #endregion
 }

package/src/modules/UI.js

@@ -182,7 +182,15 @@ class UI extends EventListener {
             ...args,
         }, '*');
         //register callback
-        this.#callbackFunctions[msg_id] = resolve;
+        this.#callbackFunctions[msg_id] = (...a) => {
+            resolve(...a);
+        };
+    }
+
+    #postMessageAsync (name, args = {}) {
+        return new Promise(resolve => {
+            this.#postMessageWithCallback(name, resolve, args);
+        });
     }
 
     #postMessageWithObject (name, value) {
@@ -974,17 +982,14 @@ class UI extends EventListener {
         this.#postMessageWithObject('setMenubar', spec);
     };
 
-    requestPermission (options) {
-        return new Promise((resolve) => {
-            if ( this.env === 'app' ) {
-                return new Promise((resolve) => {
-                    this.#postMessageWithCallback('requestPermission', resolve, { options });
-                });
-            } else {
-                // TODO: Implement for web
-                resolve(false);
-            }
-        });
+    async requestPermission (options) {
+        if ( this.env === 'app' ) {
+            const result = await this.#postMessageAsync('requestPermission', { options });
+            return result.granted;
+        } else {
+            // TODO: Implement for web
+            return false;
+        }
     };
 
     disableMenuItem (item_id) {

package/types/modules/ai.d.ts

@@ -3,34 +3,53 @@ export type AIMessageContent = string | { image_url?: { url: string } } | Record
 export interface ChatMessage {
     role?: string;
     content: AIMessageContent | AIMessageContent[];
-    [key: string]: unknown;
+    tool_calls?: ToolCall[];
+}
+
+export interface ToolCall {
+    id: string;
+    function: { name: string, arguments: string };
 }
 
 export interface ChatOptions {
     model?: string;
     temperature?: number;
     max_tokens?: number;
-    stream?: boolean;
     vision?: boolean;
-    [key: string]: unknown;
+    driver?: string;
+    tools?: unknown;
+    response?: unknown;
+    reasoning?: unknown;
+    reasoning_effort?: string;
+    text?: unknown;
+    verbosity?: unknown;
+}
+
+export interface StreamingChatOptions extends ChatOptions {
+    stream: boolean;
 }
 
 export interface ChatResponse {
     message?: ChatMessage;
     choices?: unknown;
-    [key: string]: unknown;
 }
 
 export interface ChatResponseChunk {
     text?: string;
-    [key: string]: unknown;
+    reasoning?: string;
 }
 
 export interface Img2TxtOptions {
     source?: string | File | Blob;
     provider?: string;
     testMode?: boolean;
-    [key: string]: unknown;
+    model?: string;
+    pages?: number[];
+    includeImageBase64?: boolean;
+    imageLimit?: number;
+    imageMinSize?: number;
+    bboxAnnotationFormat?: string;
+    documentAnnotationFormat?: string;
 }
 
 export interface Txt2ImgOptions {
@@ -39,18 +58,52 @@ export interface Txt2ImgOptions {
     quality?: string;
     input_image?: string;
     input_image_mime_type?: string;
-    [key: string]: unknown;
+    driver?: string;
+    provider?: string;
+    service?: string;
+    ratio?: { w: number; h: number };
+    width?: number;
+    height?: number;
+    aspect_ratio?: string;
+    steps?: number;
+    seed?: number;
+    negative_prompt?: string;
+    n?: number;
+    image_url?: string;
+    image_base64?: string;
+    mask_image_url?: string;
+    mask_image_base64?: string;
+    prompt_strength?: number;
+    disable_safety_checker?: boolean;
+    response_format?: string;
+    test_mode?: boolean;
 }
 
 export interface Txt2VidOptions {
     prompt?: string;
+    provider?: string;
     model?: string;
-    duration?: number;
+    seconds?: number;
+    test_mode?: boolean;
+
+    // OpenAI options
+    size?: string;
+    resolution?: string;
+    input_reference?: File;
+
+    // TogetherAI options
     width?: number;
     height?: number;
     fps?: number;
     steps?: number;
-    [key: string]: unknown;
+    guidance_scale?: number;
+    seed?: number;
+    output_format?: string;
+    output_quality?: number;
+    negative_prompt?: string;
+    reference_images?: string[];
+    frame_images?: Array<{ input_image: string; frame: number }>;
+    metadata?: Record<string, unknown>;
 }
 
 export interface Txt2SpeechOptions {
@@ -61,26 +114,43 @@ export interface Txt2SpeechOptions {
     provider?: string;
     model?: string;
     response_format?: string;
-    [key: string]: unknown;
+    output_format?: string;
+    instructions?: string;
+    voice_settings?: Record<string, unknown>;
+    ssml?: boolean;
+    test_mode?: boolean;
 }
 
-export interface Txt2SpeechCallable {
-    (text: string, options?: Txt2SpeechOptions): Promise<HTMLAudioElement>;
-    (text: string, language?: string, voice?: string, engine?: string): Promise<HTMLAudioElement>;
-    listEngines: (options?: string | Record<string, unknown>) => Promise<unknown>;
-    listVoices: (options?: string | Record<string, unknown>) => Promise<unknown>;
+export interface Speech2TxtResult {
+    text: string;
+    language: string;
+    segments?: Record<string, unknown>[];
 }
 
-export interface Speech2TxtOptions {
+interface BaseSpeech2TxtOptions {
     file?: string | File | Blob;
     audio?: string | File | Blob;
     model?: string;
-    response_format?: string;
     language?: string;
     prompt?: string;
     stream?: boolean;
     translate?: boolean;
-    [key: string]: unknown;
+    temperature?: number;
+    logprobs?: boolean;
+    timestamp_granularities?: string[];
+    chunking_strategy?: string;
+    known_speaker_names?: string[];
+    known_speaker_references?: string[];
+    extra_body?: Record<string, unknown>;
+    test_mode?: boolean;
+}
+
+export interface TextFormatSpeech2TxtOptions extends BaseSpeech2TxtOptions {
+    response_format: "text";
+}
+
+export interface Speech2TxtOptions extends BaseSpeech2TxtOptions {
+    response_format?: Exclude<string, "text">;
 }
 
 export interface Speech2SpeechOptions {
@@ -88,36 +158,73 @@ export interface Speech2SpeechOptions {
     file?: string | File | Blob;
     provider?: string;
     model?: string;
+    modelId?: string;
+    model_id?: string;
     voice?: string;
-    [key: string]: unknown;
+    voiceId?: string;
+    voice_id?: string;
+    output_format?: string;
+    outputFormat?: string;
+    voice_settings?: Record<string, unknown>;
+    voiceSettings?: Record<string, unknown>;
+    seed?: number;
+    file_format?: string;
+    fileFormat?: string;
+    remove_background_noise?: boolean;
+    removeBackgroundNoise?: boolean;
+    optimize_streaming_latency?: number;
+    optimizeStreamingLatency?: number;
+    enable_logging?: boolean;
+    enableLogging?: boolean;
+    test_mode?: boolean;
 }
 
 export class AI {
-    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
-
-    setAuthToken (authToken: string): void;
-    setAPIOrigin (APIOrigin: string): void;
-
     listModels (provider?: string): Promise<Record<string, unknown>[]>;
     listModelProviders (): Promise<string[]>;
 
-    chat (prompt: string, options?: ChatOptions): Promise<ChatResponse>;
-    chat (prompt: string, imageURL: string | File, options?: ChatOptions): Promise<ChatResponse>;
-    chat (messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>;
-    chat (prompt: string, options: ChatOptions & { stream: true }): AsyncIterable<ChatResponseChunk>;
-    chat (prompt: string, imageURL: string | File, options: ChatOptions & { stream: true }): AsyncIterable<ChatResponseChunk>;
-    chat (messages: ChatMessage[], options: ChatOptions & { stream: true }): AsyncIterable<ChatResponseChunk>;
-    chat (...args: unknown[]): Promise<ChatResponse> | AsyncIterable<ChatResponseChunk>;
+    chat (prompt: string, testMode?: boolean): Promise<ChatResponse>;
+    chat (prompt: string, options: ChatOptions, testMode?: boolean): Promise<ChatResponse>;
+    chat (prompt: string, imageURL: string | File, testMode?: boolean): Promise<ChatResponse>;
+    chat (prompt: string, imageURLArray: string[], testMode?: boolean): Promise<ChatResponse>;
+    chat (prompt: string, imageURL: string | File, options: ChatOptions, testMode?: boolean): Promise<ChatResponse>;
+    chat (prompt: string, imageURLArray: string[], options: ChatOptions, testMode?: boolean): Promise<ChatResponse>;
+
+    chat (prompt: string, options: StreamingChatOptions, testMode?: boolean): AsyncIterable<ChatResponseChunk>;
+    chat (prompt: string, imageURL: string | File, options: StreamingChatOptions, testMode?: boolean): AsyncIterable<ChatResponseChunk>;
+    chat (prompt: string, imageURLArray: string[], options: StreamingChatOptions, testMode?: boolean): AsyncIterable<ChatResponseChunk>;
+
+    chat (messages: ChatMessage[], testMode?: boolean): Promise<ChatResponse>;
+    chat (messages: ChatMessage[], options: ChatOptions, testMode?: boolean): Promise<ChatResponse>;
+    chat (messages: ChatMessage[], options: StreamingChatOptions, testMode?: boolean): AsyncIterable<ChatResponseChunk>;
+
+    img2txt (source: string | File | Blob, testMode?: boolean): Promise<string>;
+    img2txt (source: string | File | Blob, options: Img2TxtOptions, testMode?: boolean): Promise<string>;
+    img2txt (options: Img2TxtOptions, testMode?: boolean): Promise<string>;
 
-    img2txt (source: string | File | Blob | Img2TxtOptions, testMode?: boolean): Promise<string>;
     txt2img (prompt: string, testMode?: boolean): Promise<HTMLImageElement>;
     txt2img (prompt: string, options: Txt2ImgOptions): Promise<HTMLImageElement>;
+    txt2img (options: Txt2ImgOptions, testMode?: boolean): Promise<HTMLImageElement>;
+
     txt2vid (prompt: string, testMode?: boolean): Promise<HTMLVideoElement>;
     txt2vid (prompt: string, options: Txt2VidOptions): Promise<HTMLVideoElement>;
-    speech2txt (source: string | File | Blob | Speech2TxtOptions, options?: Speech2TxtOptions): Promise<string | Record<string, unknown>>;
-    speech2speech (source: string | File | Blob | Speech2SpeechOptions, options?: Speech2SpeechOptions): Promise<Record<string, unknown>>;
-
-    txt2speech: Txt2SpeechCallable;
+    txt2vid (options: Txt2VidOptions, testMode?: boolean): Promise<HTMLVideoElement>;
+
+    speech2txt (source: string | File | Blob, testMode?: boolean): Promise<string>;
+    speech2txt (source: string | File | Blob, options: TextFormatSpeech2TxtOptions, testMode?: boolean): Promise<string>;
+    speech2txt (source: string | File | Blob, options: Speech2TxtOptions, testMode?: boolean): Promise<Speech2TxtResult>;
+    speech2txt (options: TextFormatSpeech2TxtOptions, testMode?: boolean): Promise<string>;
+    speech2txt (options: Speech2TxtOptions, testMode?: boolean): Promise<Speech2TxtResult>;
+
+    speech2speech (source: string | File | Blob, testMode?: boolean): Promise<HTMLAudioElement>;
+    speech2speech (source: string | File | Blob, options: Speech2SpeechOptions, testMode?: boolean): Promise<HTMLAudioElement>;
+    speech2speech (options: Speech2SpeechOptions, testMode?: boolean): Promise<HTMLAudioElement>;
+
+    txt2speech (text: string, testMode?: boolean): Promise<HTMLAudioElement>;
+    txt2speech (text: string, options: Txt2SpeechOptions, testMode?: boolean): Promise<HTMLAudioElement>;
+    txt2speech (text: string, language: string, testMode?: boolean): Promise<HTMLAudioElement>;
+    txt2speech (text: string, language: string, voice: string, testMode?: boolean): Promise<HTMLAudioElement>;
+    txt2speech (text: string, language: string, voice: string, engine: string, testMode?: boolean): Promise<HTMLAudioElement>;
 }
 
 // NOTE: AI responses contain provider-specific payloads that are not fully typed here because

package/types/modules/auth.d.ts

@@ -1,8 +1,18 @@
-export interface AuthUser {
+export interface User {
     uuid: string;
     username: string;
-    email_confirmed?: boolean;
-    [key: string]: unknown;
+    email_confirmed?: boolean | number;
+    actual_free_storage?: number;
+    app_name?: string;
+    feature_flags?: Record<string, unknown>;
+    hasDevAccountAccess?: boolean;
+    is_temp?: boolean;
+    last_activity_ts?: number;
+    otp?: boolean;
+    paid_storage?: number;
+    referral_code?: string;
+    requires_email_confirmation?: boolean | number;
+    subscribed?: boolean;
 }
 
 export interface AllowanceInfo {
@@ -32,17 +42,21 @@ export interface DetailedAppUsage {
     [key: string]: APIUsage;
 }
 
-export class Auth {
-    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
-
-    setAuthToken (authToken: string): void;
-    setAPIOrigin (APIOrigin: string): void;
+export interface SignInResult {
+    success: boolean;
+    token: string;
+    app_uid: string;
+    username: string;
+    error?: string;
+    msg?: string;
+}
 
-    signIn (options?: { attempt_temp_user_creation?: boolean }): Promise<AuthUser | { token?: string }>;
+export class Auth {
+    signIn (options?: { attempt_temp_user_creation?: boolean }): Promise<SignInResult>;
     signOut (): void;
     isSignedIn (): boolean;
-    getUser (): Promise<AuthUser>;
-    whoami (): Promise<AuthUser>;
+    getUser (): Promise<User>;
+    whoami (): Promise<User>;
     getMonthlyUsage (): Promise<MonthlyUsage>;
     getDetailedAppUsage (appId: string): Promise<DetailedAppUsage>;
 }