@heyputer/puter.js 2.0.4 → 2.0.6

package/index.d.ts

@@ -0,0 +1,496 @@
+// index.d.ts
+
+declare global {
+    interface Window {
+        puter: Puter;
+    }
+}
+
+declare class Puter {
+    // Properties
+    appID: string;
+    env: 'app' | 'web' | 'gui';
+
+    // Utility methods
+    print(text: string, options?: { code?: boolean }): void;
+    randName(separator?: string): string;
+    exit(statusCode?: number): void;
+
+    // Sub-modules
+    ai: AI;
+    apps: Apps;
+    auth: Auth;
+    drivers: Drivers;
+    fs: FileSystem;
+    hosting: Hosting;
+    kv: KV;
+    net: Networking;
+    perms: Permissions;
+    ui: UI;
+    workers: Workers;
+}
+
+// AI Module
+interface AI {
+    chat(prompt: string, options?: ChatOptions): Promise<ChatResponse>;
+    chat(prompt: string, testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
+    chat(prompt: string, imageURL?: string, testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
+    chat(prompt: string, imageURLArray?: string[], testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
+    chat(messages: ChatMessage[], testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
+
+    img2txt(image: string | File | Blob, testMode?: boolean): Promise<string>;
+
+    txt2img(prompt: string, testMode?: boolean): Promise<HTMLImageElement>;
+    txt2img(prompt: string, options?: Txt2ImgOptions): Promise<HTMLImageElement>;
+
+    txt2speech(text: string): Promise<HTMLAudioElement>;
+    txt2speech(text: string, options?: Txt2SpeechOptions): Promise<HTMLAudioElement>;
+    txt2speech(text: string, language?: string): Promise<HTMLAudioElement>;
+    txt2speech(text: string, language?: string, voice?: string): Promise<HTMLAudioElement>;
+    txt2speech(text: string, language?: string, voice?: string, engine?: string): Promise<HTMLAudioElement>;
+}
+
+interface ChatOptions {
+    model?: string;
+    stream?: boolean;
+    max_tokens?: number;
+    temperature?: number;
+    tools?: ToolDefinition[];
+}
+
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+        strict?: boolean;
+    };
+}
+
+interface ChatMessage {
+    role: 'system' | 'assistant' | 'user' | 'function' | 'tool';
+    content: string | ContentObject[];
+    tool_call_id?: string;
+}
+
+interface ContentObject {
+    type: 'text' | 'file';
+    text?: string;
+    puter_path?: string;
+}
+
+interface ChatResponse {
+    message: {
+        role: string;
+        content: string;
+        tool_calls?: ToolCall[];
+    };
+}
+
+interface ToolCall {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+
+interface Txt2ImgOptions {
+    model?: 'gpt-image-1' | 'gemini-2.5-flash-image-preview' | 'dall-e-3';
+    quality?: 'high' | 'medium' | 'low' | 'hd' | 'standard';
+    input_image?: string;
+    input_image_mime_type?: string;
+}
+
+interface Txt2SpeechOptions {
+    language?: string;
+    voice?: string;
+    engine?: 'standard' | 'neural' | 'generative';
+}
+
+// Apps Module
+interface Apps {
+    create(name: string, indexURL: string): Promise<App>;
+    create(name: string, indexURL: string, title?: string): Promise<App>;
+    create(name: string, indexURL: string, title?: string, description?: string): Promise<App>;
+    create(options: CreateAppOptions): Promise<App>;
+
+    delete(name: string): Promise<App>;
+    get(name: string, options?: GetAppOptions): Promise<App>;
+    list(options?: ListAppOptions): Promise<App[]>;
+    update(name: string, attributes: UpdateAppAttributes): Promise<App>;
+}
+
+interface CreateAppOptions {
+    name: string;
+    indexURL: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    maximizeOnStart?: boolean;
+    filetypeAssociations?: string[];
+}
+
+interface GetAppOptions {
+    stats_period?: StatsPeriod;
+    icon_size?: null | 16 | 32 | 64 | 128 | 256 | 512;
+}
+
+interface ListAppOptions extends GetAppOptions { }
+
+interface UpdateAppAttributes {
+    name?: string;
+    indexURL?: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    maximizeOnStart?: boolean;
+    filetypeAssociations?: string[];
+}
+
+type StatsPeriod = 'all' | 'today' | 'yesterday' | '7d' | '30d' | 'this_month' | 'last_month' | 'this_year' | 'last_year' | 'month_to_date' | 'year_to_date' | 'last_12_months';
+
+interface App {
+    uid: string;
+    name: string;
+    icon: string;
+    description: string;
+    title: string;
+    maximize_on_start: boolean;
+    index_url: string;
+    created_at: string;
+    background: boolean;
+    filetype_associations: string[];
+    open_count: number;
+    user_count: number;
+}
+
+// Auth Module
+interface Auth {
+    signIn(options?: { attempt_temp_user_creation?: boolean }): Promise<boolean>;
+    signOut(): void;
+    isSignedIn(): boolean;
+    getUser(): Promise<User>;
+}
+
+interface User {
+    uuid: string;
+    username: string;
+    email_confirmed: boolean;
+}
+
+// Drivers Module
+interface Drivers {
+    call(interface: string, driver: string, method: string, args?: object): Promise<any>;
+}
+
+// FileSystem Module
+interface FileSystem {
+    copy(source: string, destination: string, options?: CopyOptions): Promise<FSItem>;
+    delete(path: string, options?: DeleteOptions): Promise<void>;
+    getReadURL(path: string, expiresIn?: number): Promise<string>;
+    mkdir(path: string, options?: MkdirOptions): Promise<FSItem>;
+    move(source: string, destination: string, options?: MoveOptions): Promise<FSItem>;
+    read(path: string, options?: ReadOptions): Promise<Blob>;
+    readdir(path: string, options?: ReaddirOptions): Promise<FSItem[]>;
+    readdir(options?: ReaddirOptions): Promise<FSItem[]>;
+    rename(path: string, newName: string): Promise<FSItem>;
+    space(): Promise<SpaceInfo>;
+    stat(path: string): Promise<FSItem>;
+    upload(items: FileList | File[] | Blob[], dirPath?: string, options?: object): Promise<FSItem[]>;
+    write(path: string, data?: string | File | Blob, options?: WriteOptions): Promise<FSItem>;
+}
+
+interface CopyOptions {
+    overwrite?: boolean;
+    dedupeName?: boolean;
+    newName?: string;
+}
+
+interface DeleteOptions {
+    recursive?: boolean;
+    descendantsOnly?: boolean;
+}
+
+interface MkdirOptions {
+    overwrite?: boolean;
+    dedupeName?: boolean;
+    createMissingParents?: boolean;
+}
+
+interface MoveOptions extends CopyOptions {
+    createMissingParents?: boolean;
+}
+
+interface ReadOptions {
+    offset?: number;
+    byte_count?: number;
+}
+
+interface ReaddirOptions {
+    path?: string;
+    uid?: string;
+}
+
+interface WriteOptions {
+    overwrite?: boolean;
+    dedupeName?: boolean;
+    createMissingParents?: boolean;
+}
+
+interface SpaceInfo {
+    capacity: number;
+    used: number;
+}
+
+interface FSItem {
+    id: string;
+    uid: string;
+    name: string;
+    path: string;
+    is_dir: boolean;
+    parent_id: string;
+    parent_uid: string;
+    created: number;
+    modified: number;
+    accessed: number;
+    size: number | null;
+    writable: boolean;
+    read(): Promise<Blob>;
+    readdir(): Promise<FSItem[]>;
+}
+
+// Hosting Module
+interface Hosting {
+    create(subdomain: string, dirPath?: string): Promise<Subdomain>;
+    delete(subdomain: string): Promise<boolean>;
+    get(subdomain: string): Promise<Subdomain>;
+    list(): Promise<Subdomain[]>;
+    update(subdomain: string, dirPath?: string): Promise<Subdomain>;
+}
+
+interface Subdomain {
+    uid: string;
+    subdomain: string;
+    root_dir: FSItem;
+}
+
+// Key-Value Store Module
+interface KV {
+    set(key: string, value: string | number | boolean | object | any[]): Promise<boolean>;
+    get(key: string): Promise<any>;
+    del(key: string): Promise<boolean>;
+    incr(key: string, amount?: number): Promise<number>;
+    decr(key: string, amount?: number): Promise<number>;
+    list(pattern?: string, returnValues?: boolean): Promise<string[] | KVPair[]>;
+    list(returnValues?: boolean): Promise<string[] | KVPair[]>;
+    flush(): Promise<boolean>;
+}
+
+interface KVPair {
+    key: string;
+    value: any;
+}
+
+// Networking Module
+interface Networking {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+    Socket: typeof Socket;
+    tls: {
+        TLSSocket: typeof TLSSocket;
+    };
+}
+
+declare class Socket {
+    constructor(hostname: string, port: number);
+    write(data: ArrayBuffer | Uint8Array | string): void;
+    close(): void;
+    on(event: 'open', callback: () => void): void;
+    on(event: 'data', callback: (buffer: Uint8Array) => void): void;
+    on(event: 'error', callback: (reason: string) => void): void;
+    on(event: 'close', callback: (hadError: boolean) => void): void;
+}
+
+declare class TLSSocket extends Socket {
+    constructor(hostname: string, port: number);
+}
+
+// Permissions Module
+interface Permissions {
+    grantApp(app_uid: string, permissionString: string): Promise<object>;
+    grantAppAnyUser(app_uid: string, permissionString: string): Promise<object>;
+    grantGroup(group_uid: string, permissionString: string): Promise<object>;
+    grantOrigin(origin: string, permissionString: string): Promise<object>;
+    grantUser(username: string, permissionString: string): Promise<object>;
+    revokeApp(app_uid: string, permissionString: string): Promise<object>;
+    revokeAppAnyUser(app_uid: string, permissionString: string): Promise<object>;
+    revokeGroup(group_uid: string, permissionString: string): Promise<object>;
+    revokeOrigin(origin: string, permissionString: string): Promise<object>;
+    revokeUser(username: string, permissionString: string): Promise<object>;
+}
+
+// UI Module
+interface UI {
+    alert(message?: string, buttons?: AlertButton[]): Promise<string>;
+    prompt(message?: string, defaultValue?: string): Promise<string | null>;
+    authenticateWithPuter(): Promise<boolean>;
+    contextMenu(options: ContextMenuOptions): void;
+    createWindow(options?: WindowOptions): void;
+    exit(statusCode?: number): void;
+    getLanguage(): Promise<string>;
+    hideSpinner(): void;
+    launchApp(appName?: string, args?: object): Promise<AppConnection>;
+    launchApp(options: LaunchAppOptions): Promise<AppConnection>;
+    on(eventName: 'localeChanged', handler: (data: { language: string }) => void): void;
+    on(eventName: 'themeChanged', handler: (data: ThemeData) => void): void;
+    onItemsOpened(handler: (items: FSItem[]) => void): void;
+    onLaunchedWithItems(handler: (items: FSItem[]) => void): void;
+    onWindowClose(handler: () => void): void;
+    parentApp(): AppConnection | null;
+    setMenubar(options: MenubarOptions): void;
+    setWindowHeight(height: number): void;
+    setWindowPosition(x: number, y: number): void;
+    setWindowSize(width: number, height: number): void;
+    setWindowTitle(title: string): void;
+    setWindowWidth(width: number): void;
+    setWindowX(x: number): void;
+    setWindowY(y: number): void;
+    showColorPicker(defaultColor?: string): Promise<string>;
+    showColorPicker(options?: object): Promise<string>;
+    showDirectoryPicker(options?: { multiple?: boolean }): Promise<FSItem | FSItem[]>;
+    showFontPicker(defaultFont?: string): Promise<{ fontFamily: string }>;
+    showFontPicker(options?: object): Promise<{ fontFamily: string }>;
+    showOpenFilePicker(options?: FilePickerOptions): Promise<FSItem | FSItem[]>;
+    showSaveFilePicker(data?: any, defaultFileName?: string): Promise<FSItem>;
+    showSpinner(): void;
+    socialShare(url: string, message?: string, options?: { left?: number; top?: number }): void;
+    wasLaunchedWithItems(): boolean;
+}
+
+interface AlertButton {
+    label: string;
+    value?: string;
+    type?: 'primary' | 'success' | 'info' | 'warning' | 'danger';
+}
+
+interface ContextMenuOptions {
+    items: (ContextMenuItem | '-')[];
+}
+
+interface ContextMenuItem {
+    label: string;
+    action?: () => void;
+    icon?: string;
+    icon_active?: string;
+    disabled?: boolean;
+    items?: (ContextMenuItem | '-')[];
+}
+
+interface WindowOptions {
+    center?: boolean;
+    content?: string;
+    disable_parent_window?: boolean;
+    has_head?: boolean;
+    height?: number;
+    is_resizable?: boolean;
+    show_in_taskbar?: boolean;
+    title?: string;
+    width?: number;
+}
+
+interface LaunchAppOptions {
+    name?: string;
+    args?: object;
+}
+
+interface ThemeData {
+    palette: {
+        primaryHue: number;
+        primarySaturation: string;
+        primaryLightness: string;
+        primaryAlpha: number;
+        primaryColor: string;
+    };
+}
+
+interface MenubarOptions {
+    items: MenuItem[];
+}
+
+interface MenuItem {
+    label: string;
+    action?: () => void;
+    items?: MenuItem[];
+}
+
+interface FilePickerOptions {
+    multiple?: boolean;
+    accept?: string | string[];
+}
+
+interface AppConnection {
+    usesSDK: boolean;
+    on(eventName: 'message', handler: (message: any) => void): void;
+    on(eventName: 'close', handler: (data: { appInstanceID: string }) => void): void;
+    off(eventName: string, handler: Function): void;
+    postMessage(message: any): void;
+    close(): void;
+}
+
+// Workers Module
+interface Workers {
+    create(workerName: string, filePath: string): Promise<WorkerDeployment>;
+    delete(workerName: string): Promise<boolean>;
+    exec(workerURL: string, options?: WorkerExecOptions): Promise<Response>;
+    get(workerName: string): Promise<WorkerInfo>;
+    list(): Promise<WorkerInfo[]>;
+}
+
+interface WorkerDeployment {
+    success: boolean;
+    url: string;
+    errors: any[];
+}
+
+interface WorkerExecOptions extends RequestInit {
+    method?: string;
+    headers?: object;
+    body?: string | object;
+    cache?: RequestCache;
+    credentials?: RequestCredentials;
+    mode?: RequestMode;
+    redirect?: RequestRedirect;
+    referrer?: string;
+    signal?: AbortSignal;
+}
+
+interface WorkerInfo {
+    name: string;
+    url: string;
+    file_path: string;
+    file_uid: string;
+    created_at: string;
+}
+
+// Global puter instance
+declare const puter: Puter;
+
+// Export the Puter class as both default and named export
+export default puter;
+export { puter };
+
+// Also export all the interfaces for users who want to use them
+export {
+    AI, AlertButton, App, AppConnection, Apps,
+    Auth, ChatMessage, ChatOptions, ChatResponse, ContentObject, ContextMenuItem, ContextMenuOptions, CopyOptions, CreateAppOptions, DeleteOptions, Drivers, FilePickerOptions, FileSystem, FSItem, GetAppOptions, Hosting,
+    KV,
+    KVPair, LaunchAppOptions, MenubarOptions,
+    MenuItem, MkdirOptions,
+    MoveOptions, Networking,
+    Permissions, Puter, ReaddirOptions, ReadOptions, SpaceInfo, StatsPeriod, Subdomain, ThemeData, ToolCall, ToolDefinition, Txt2ImgOptions,
+    Txt2SpeechOptions, UI, UpdateAppAttributes, User, WindowOptions, WorkerDeployment,
+    WorkerExecOptions,
+    WorkerInfo, Workers, WriteOptions
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heyputer/puter.js",
-    "version": "2.0.4",
+    "version": "2.0.6",
     "description": "Puter.js - A JavaScript library for interacting with Puter services.",
     "main": "src/index.js",
     "types": "index.d.ts",
@@ -8,7 +8,8 @@
     "type": "module",
     "files": [
         "dist/puter.js",
-        "src/"
+        "src/",
+        "index.d.ts"
     ],
     "publishConfig": {
         "registry": "https://registry.npmjs.org/"

package/src/modules/FileSystem/index.js

@@ -1,23 +1,23 @@
 import io from '../../lib/socket.io/socket.io.esm.min.js';
 
 // Operations
-import space from "./operations/space.js";
-import mkdir from "./operations/mkdir.js";
-import copy from "./operations/copy.js";
-import rename from "./operations/rename.js";
-import upload from "./operations/upload.js";
-import read from "./operations/read.js";
-import move from "./operations/move.js";
-import write from "./operations/write.js";
-import sign from "./operations/sign.js";
-import symlink from './operations/symlink.js';
+import copy from './operations/copy.js';
+import mkdir from './operations/mkdir.js';
+import move from './operations/move.js';
+import read from './operations/read.js';
 import readdir from './operations/readdir.js';
+import rename from './operations/rename.js';
+import sign from './operations/sign.js';
+import space from './operations/space.js';
 import stat from './operations/stat.js';
-// Why is this called deleteFSEntry instead of just delete? because delete is 
+import symlink from './operations/symlink.js';
+import upload from './operations/upload.js';
+import write from './operations/write.js';
+// Why is this called deleteFSEntry instead of just delete? because delete is
 // a reserved keyword in javascript
-import deleteFSEntry from "./operations/deleteFSEntry.js";
 import { AdvancedBase } from '../../../../putility/index.js';
 import FSItem from '../FSItem.js';
+import deleteFSEntry from './operations/deleteFSEntry.js';
 import getReadURL from './operations/getReadUrl.js';
 
 export class PuterJSFileSystemModule extends AdvancedBase {
@@ -39,7 +39,7 @@ export class PuterJSFileSystemModule extends AdvancedBase {
     readdir = readdir;
     stat = stat;
 
-    FSItem = FSItem
+    FSItem = FSItem;
 
     static NARI_METHODS = {
         // stat: {
@@ -50,7 +50,7 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         //         return svc_fs.filesystem.stat(parameters);
         //     }
         // },
-    }
+    };
 
     /**
      * Creates a new instance with the given authentication token, API origin, and app ID,
@@ -61,7 +61,7 @@ export class PuterJSFileSystemModule extends AdvancedBase {
      * @param {string} APIOrigin - Origin of the API server. Used to build the API endpoint URLs.
      * @param {string} appID - ID of the app to use.
      */
-    constructor (context) {
+    constructor(context) {
         super();
         this.authToken = context.authToken;
         this.APIOrigin = context.APIOrigin;
@@ -81,7 +81,6 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         });
     }
 
-
     /**
      * Initializes the socket connection to the server using the current API origin.
      * If a socket connection already exists, it disconnects it before creating a new one.
@@ -92,17 +91,21 @@ export class PuterJSFileSystemModule extends AdvancedBase {
      * @returns {void}
      */
     initializeSocket() {
-        if (this.socket) {
+        if ( globalThis.puter.env === 'nodejs' ){
+            return;
+        }
+        if ( this.socket ) {
             this.socket.disconnect();
         }
 
         this.socket = io(this.APIOrigin, {
             auth: {
                 auth_token: this.authToken,
-            }
+            },
         });
 
         this.bindSocketEvents();
+
     }
 
     bindSocketEvents() {
@@ -117,16 +120,20 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         this.socket.on('item.moved', (item) => {
             // todo: NAIVE PURGE
             puter._cache.flushall();
-        }); 
+        });
 
         this.socket.on('connect', () => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.log('FileSystem Socket: Connected', this.socket.id);
+            }
         });
 
         this.socket.on('disconnect', () => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.log('FileSystem Socket: Disconnected');
+            }
 
             // todo: NAIVE PURGE
             // purge cache on disconnect since we may have become out of sync
@@ -134,28 +141,38 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         });
 
         this.socket.on('reconnect', (attempt) => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.log('FileSystem Socket: Reconnected', this.socket.id);
+            }
         });
 
         this.socket.on('reconnect_attempt', (attempt) => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.log('FileSystem Socket: Reconnection Attemps', attempt);
+            }
         });
 
         this.socket.on('reconnect_error', (error) => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.log('FileSystem Socket: Reconnection Error', error);
+            }
         });
 
         this.socket.on('reconnect_failed', () => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.log('FileSystem Socket: Reconnection Failed');
+            }
         });
 
         this.socket.on('error', (error) => {
-            if(puter.debugMode)
+            if ( puter.debugMode )
+            {
                 console.error('FileSystem Socket Error:', error);
+            }
         });
     }
 
@@ -166,7 +183,7 @@ export class PuterJSFileSystemModule extends AdvancedBase {
      * @memberof [FileSystem]
      * @returns {void}
      */
-    setAuthToken (authToken) {
+    setAuthToken(authToken) {
         this.authToken = authToken;
         // reset socket
         this.initializeSocket();
@@ -174,12 +191,12 @@ export class PuterJSFileSystemModule extends AdvancedBase {
 
     /**
      * Sets the API origin and resets the socket connection with the updated API origin.
-     * 
+     *
      * @param {string} APIOrigin - The new API origin.
      * @memberof [Apps]
      * @returns {void}
      */
-    setAPIOrigin (APIOrigin) {
+    setAPIOrigin(APIOrigin) {
         this.APIOrigin = APIOrigin;
         // reset socket
         this.initializeSocket();