@heyputer/puter.js 2.1.7 → 2.1.9

package/types/modules/ui.d.ts

@@ -0,0 +1,146 @@
+import type { RequestCallbacks } from '../shared.d.ts';
+import type { FSItem } from './fs-item.d.ts';
+
+export interface AlertButton {
+    label: string;
+    value?: string;
+    type?: 'primary' | 'success' | 'info' | 'warning' | 'danger';
+}
+
+export interface ContextMenuItem {
+    label: string;
+    action?: () => void;
+    icon?: string;
+    icon_active?: string;
+    disabled?: boolean;
+    items?: (ContextMenuItem | '-')[];
+}
+
+export interface ContextMenuOptions {
+    items: (ContextMenuItem | '-')[];
+}
+
+export 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;
+    x?: number;
+    y?: number;
+}
+
+export interface LaunchAppOptions {
+    name?: string;
+    args?: Record<string, unknown>;
+    appInstanceID?: string;
+}
+
+export interface ThemeData {
+    palette: {
+        primaryHue: number;
+        primarySaturation: string;
+        primaryLightness: string;
+        primaryAlpha: number;
+        primaryColor: string;
+    };
+}
+
+export interface MenubarOptions {
+    items: MenuItem[];
+}
+
+export interface MenuItem {
+    label: string;
+    action?: () => void;
+    items?: MenuItem[];
+    icon?: string;
+    checked?: boolean;
+}
+
+export interface FilePickerOptions {
+    multiple?: boolean;
+    accept?: string | string[];
+}
+
+export interface DirectoryPickerOptions {
+    multiple?: boolean;
+}
+
+export interface AppConnectionCloseEvent {
+    appInstanceID: string;
+    statusCode?: number;
+}
+
+export type CancelAwarePromise<T> = Promise<T> & { undefinedOnCancel?: Promise<T | undefined> };
+
+export class AppConnection {
+    readonly usesSDK: boolean;
+    readonly response?: Record<string, unknown>;
+
+    on (eventName: 'message', handler: (message: unknown) => void): void;
+    on (eventName: 'close', handler: (data: AppConnectionCloseEvent) => void): void;
+    off (eventName: string, handler: (...args: unknown[]) => void): void;
+    postMessage (message: unknown): void;
+    close (): void;
+}
+
+export class UI {
+    constructor (context: Record<string, unknown>, parameters: { appInstanceID?: string; parentInstanceID?: string });
+
+    alert (message?: string, buttons?: AlertButton[]): Promise<string>;
+    prompt (message?: string, defaultValue?: string): Promise<string | null>;
+    authenticateWithPuter (): Promise<unknown>;
+    contextMenu (options: ContextMenuOptions): void;
+    createWindow (options?: WindowOptions): void;
+    exit (statusCode?: number): void;
+    getLanguage (): Promise<string>;
+    hideSpinner (): void;
+    showSpinner (): void;
+    showColorPicker (defaultColor?: string | Record<string, unknown>): Promise<string>;
+    showDirectoryPicker (options?: DirectoryPickerOptions): Promise<FSItem | FSItem[]>;
+    showFontPicker (defaultFont?: string | Record<string, unknown>): Promise<{ fontFamily: string }>;
+    showOpenFilePicker (options?: FilePickerOptions): CancelAwarePromise<FSItem | FSItem[]>;
+    showSaveFilePicker (data?: unknown, defaultFileName?: string): CancelAwarePromise<FSItem>;
+    socialShare (url: string, message?: string, options?: { left?: number; top?: number }): void;
+    setMenubar (options: MenubarOptions): void;
+    setMenuItemIcon (itemId: string, icon: string): void;
+    setMenuItemIconActive (itemId: string, icon: string): void;
+    setMenuItemChecked (itemId: string, checked: boolean): 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 (options?: Record<string, unknown>): Promise<string>;
+    showSaveFilePicker (data?: unknown, defaultFileName?: string): Promise<FSItem>;
+    wasLaunchedWithItems (): boolean;
+    onItemsOpened (handler: (items: FSItem[]) => void): void;
+    onLaunchedWithItems (handler: (items: FSItem[]) => void): void;
+    onWindowClose (handler: () => void): void;
+    on (eventName: 'localeChanged', handler: (data: { language: string }) => void): void;
+    on (eventName: 'themeChanged', handler: (data: ThemeData) => void): void;
+    parentApp (): AppConnection | null;
+    launchApp (appName?: string, args?: Record<string, unknown>): Promise<AppConnection>;
+    launchApp (options: LaunchAppOptions): Promise<AppConnection>;
+
+    getEntriesFromDataTransferItems (dataTransferItems: DataTransferItemList, options?: { raw?: boolean }): Promise<Array<File | FileSystemEntry>>;
+
+    // Broadcast helpers are only partially typed because the payloads are app-defined.
+    broadcast (name: string, data: unknown): void;
+    listenForBroadcast (name: string, handler: (data: unknown) => void): void;
+
+    get FILE_SAVE_CANCELLED (): symbol;
+    get FILE_OPEN_CANCELLED (): symbol;
+
+    requestUpgrade (): Promise<unknown>;
+}
+
+// NOTE: UI contains additional internal helpers that are not surfaced here because they are not
+// part of the stable app-facing API.

package/types/modules/util.d.ts

@@ -0,0 +1,12 @@
+export class UtilRPC {
+    callbackManager: unknown;
+    getDehydrator (): { dehydrate(value: unknown): unknown };
+    getHydrator (config: { target: Window | Worker | MessagePort }): { hydrate(value: unknown): unknown };
+    registerCallback (resolve: (value: unknown) => void): string;
+    send (target: Window | Worker | MessagePort, id: string, ...args: unknown[]): void;
+}
+
+export default class Util {
+    constructor ();
+    rpc: UtilRPC;
+}

package/types/modules/workers.d.ts

@@ -0,0 +1,26 @@
+export interface WorkerInfo {
+    name: string;
+    url: string;
+    file_path?: string;
+    file_uid?: string;
+    created_at?: string;
+    [key: string]: unknown;
+}
+
+export interface WorkerDeployment {
+    success: boolean;
+    url: string;
+    errors?: unknown[];
+    [key: string]: unknown;
+}
+
+export class WorkersHandler {
+    constructor (authToken?: string);
+
+    create (workerName: string, filePath: string, appName?: string): Promise<WorkerDeployment>;
+    delete (workerName: string): Promise<boolean>;
+    exec (request: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    get (workerName: string): Promise<WorkerInfo>;
+    list (): Promise<WorkerInfo[]>;
+    getLoggingHandle (workerName: string): Promise<EventTarget & { close: () => void }>;
+}

package/types/puter.d.ts

@@ -0,0 +1,101 @@
+import type { AI } from './modules/ai.d.ts';
+import type { Apps } from './modules/apps.d.ts';
+import type { Auth } from './modules/auth.d.ts';
+import type { Debug } from './modules/debug.d.ts';
+import type { Drivers } from './modules/drivers.d.ts';
+import type { PuterJSFileSystemModule, SpaceInfo } from './modules/filesystem.d.ts';
+import type { FSItem } from './modules/fs-item.d.ts';
+import type { Hosting } from './modules/hosting.d.ts';
+import type { KV } from './modules/kv.d.ts';
+import type { Networking } from './modules/networking.d.ts';
+import type { OS } from './modules/os.d.ts';
+import type { Perms } from './modules/perms.d.ts';
+import type Threads from './modules/threads.d.ts';
+import type { UI } from './modules/ui.d.ts';
+import type Util from './modules/util.d.ts';
+import type { WorkersHandler } from './modules/workers.d.ts';
+import type { APICallLogger, APILoggingConfig, PuterEnvironment, ToolSchema } from './shared.d.ts';
+
+export interface NetAPI extends Networking {}
+
+export interface PuterArgs {
+    [key: string]: unknown;
+}
+
+export interface PuterUser extends Record<string, unknown> {
+    username?: string;
+}
+
+export class Puter {
+    env: PuterEnvironment;
+    appID?: string;
+    appName?: string;
+    appDataPath?: string;
+    appInstanceID?: string;
+    parentInstanceID?: string;
+    args: PuterArgs;
+    onAuth?: (user: PuterUser) => void;
+    authToken?: string | null;
+    APIOrigin: string;
+    logger: unknown;
+    apiCallLogger?: APICallLogger;
+    puterAuthState: {
+        isPromptOpen: boolean;
+        authGranted: boolean | null;
+        resolver: { resolve: () => void; reject: (reason?: unknown) => void } | null;
+    };
+
+    // Core modules
+    util: Util;
+    ai: AI;
+    apps: Apps;
+    auth: Auth;
+    os: OS;
+    fs: PuterJSFileSystemModule;
+    ui: UI;
+    hosting: Hosting;
+    kv: KV;
+    threads: Threads;
+    perms: Perms;
+    drivers: Drivers;
+    debug: Debug;
+    path: {
+        join: (...parts: string[]) => string;
+        dirname: (p: string) => string;
+        basename: (p: string) => string;
+        normalize?: (p: string) => string;
+        [key: string]: unknown;
+    };
+
+    net: NetAPI;
+    workers: WorkersHandler;
+
+    static FSItem: typeof FSItem;
+
+    constructor();
+
+    setAuthToken(authToken: string): void;
+    resetAuthToken(): void;
+    setAPIOrigin(APIOrigin: string): void;
+    setAppID(appID: string): void;
+
+    get defaultAPIOrigin(): string;
+    set defaultAPIOrigin(value: string);
+    get defaultGUIOrigin(): string;
+    set defaultGUIOrigin(value: string);
+
+    print(text: string, options?: { code?: boolean; escapeHTML?: boolean }): void;
+    randName(separator?: string): string;
+    exit(statusCode?: number): void;
+
+    getUser(options?: { success?: (user: PuterUser) => void; error?: (reason: unknown) => void }): Promise<PuterUser>;
+    configureAPILogging(config?: APILoggingConfig): this;
+    enableAPILogging(config?: APILoggingConfig): this;
+    disableAPILogging(): this;
+
+    // Utilities for caches and network; exposed but not all internals are typed.
+    checkAndUpdateGUIFScache(): void;
+    initNetworkMonitoring(): void;
+
+    tools: ToolSchema[];
+}

package/types/shared.d.ts

@@ -0,0 +1,39 @@
+export type PuterEnvironment = 'app' | 'gui' | 'web' | 'web-worker' | 'service-worker' | 'nodejs';
+
+export interface RequestCallbacks<T = unknown> {
+    success?: (value: T) => void;
+    error?: (reason: unknown) => void;
+}
+
+export interface APILoggingConfig {
+    enabled?: boolean;
+    [key: string]: unknown;
+}
+
+export interface APICallLogger {
+    isEnabled(): boolean;
+    logRequest(entry: Record<string, unknown>): void;
+    updateConfig(config: APILoggingConfig): void;
+    disable(): void;
+}
+
+export interface PaginationOptions {
+    page?: number;
+    per_page?: number;
+}
+
+export interface PaginatedResult<T> {
+    data: T[];
+    page?: number;
+    pages?: number;
+}
+
+export interface ToolSchema {
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        strict?: boolean;
+    };
+    exec: (parameters: Record<string, unknown>) => unknown | Promise<unknown>;
+}