@heyputer/puter.js 2.1.8 → 2.1.10

package/index.d.ts

@@ -26,7 +26,7 @@ declare global {
 declare const puter: Puter;
 
 export default puter;
-export { puter, Puter };
+export { puter };
 
 export type {
     AI,
@@ -109,6 +109,7 @@ export type {
     WorkerInfo,
     WorkersHandler,
     WriteOptions,
+    Puter
 };
 
 // NOTE: Provider-specific response bodies (AI, drivers, workers logging stream) intentionally

package/package.json

@@ -1,14 +1,15 @@
 {
     "name": "@heyputer/puter.js",
-    "version": "2.1.8",
+    "version": "2.1.10",
     "description": "Puter.js - A JavaScript library for interacting with Puter services.",
     "main": "src/index.js",
-    "types": "index.d.ts",
-    "typings": "index.d.ts",
+    "types": "./index.d.ts",
+    "typings": "./index.d.ts",
     "type": "module",
     "files": [
         "dist/puter.cjs",
         "src/",
+        "types/",
         "index.d.ts"
     ],
     "publishConfig": {

package/src/modules/Perms.js

@@ -10,15 +10,22 @@ export default class Perms {
         this.APIOrigin = APIOrigin;
     }
     async req_ (route, body) {
-        const resp = await fetch(this.APIOrigin + route, {
-            method: body ? 'POST' : 'GET',
-            headers: {
-                Authorization: `Bearer ${this.authToken}`,
-                'Content-Type': 'application/json',
-            },
-            ...(body ? { body: JSON.stringify(body) } : {}),
-        });
-        return await resp.json();
+        try {
+            const resp = await fetch(this.APIOrigin + route, {
+                method: body ? 'POST' : 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.authToken}`,
+                    'Content-Type': 'application/json',
+                },
+                ...(body ? { body: JSON.stringify(body) } : {}),
+            });
+            if ( resp.headers.get('content-type')?.includes('application/json') ) {
+                return await resp.json();
+            }
+            return { message: await resp.text(), code: 'unknown_error' };
+        } catch (e) {
+            return { message: e.message, code: 'internal_error' };
+        }
     }
 
     // Grant Permissions

package/types/modules/ai.d.ts

@@ -0,0 +1,124 @@
+export type AIMessageContent = string | { image_url?: { url: string } } | Record<string, unknown>;
+
+export interface ChatMessage {
+    role?: string;
+    content: AIMessageContent | AIMessageContent[];
+    [key: string]: unknown;
+}
+
+export interface ChatOptions {
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    vision?: boolean;
+    [key: string]: unknown;
+}
+
+export interface ChatResponse {
+    message?: ChatMessage;
+    choices?: unknown;
+    [key: string]: unknown;
+}
+
+export interface ChatResponseChunk {
+    text?: string;
+    [key: string]: unknown;
+}
+
+export interface Img2TxtOptions {
+    source?: string | File | Blob;
+    provider?: string;
+    testMode?: boolean;
+    [key: string]: unknown;
+}
+
+export interface Txt2ImgOptions {
+    prompt?: string;
+    model?: string;
+    quality?: string;
+    input_image?: string;
+    input_image_mime_type?: string;
+    [key: string]: unknown;
+}
+
+export interface Txt2VidOptions {
+    prompt?: string;
+    model?: string;
+    duration?: number;
+    width?: number;
+    height?: number;
+    fps?: number;
+    steps?: number;
+    [key: string]: unknown;
+}
+
+export interface Txt2SpeechOptions {
+    text?: string;
+    language?: string;
+    voice?: string;
+    engine?: string;
+    provider?: string;
+    model?: string;
+    response_format?: string;
+    [key: string]: unknown;
+}
+
+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 Speech2TxtOptions {
+    file?: string | File | Blob;
+    audio?: string | File | Blob;
+    model?: string;
+    response_format?: string;
+    language?: string;
+    prompt?: string;
+    stream?: boolean;
+    translate?: boolean;
+    [key: string]: unknown;
+}
+
+export interface Speech2SpeechOptions {
+    audio?: string | File | Blob;
+    file?: string | File | Blob;
+    provider?: string;
+    model?: string;
+    voice?: string;
+    [key: string]: unknown;
+}
+
+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>;
+
+    img2txt (source: string | File | Blob | Img2TxtOptions, testMode?: boolean): Promise<string>;
+    txt2img (prompt: string, testMode?: boolean): Promise<HTMLImageElement>;
+    txt2img (prompt: string, options: Txt2ImgOptions): 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;
+}
+
+// NOTE: AI responses contain provider-specific payloads that are not fully typed here because
+// the SDK does not yet publish stable shapes for those fields.

package/types/modules/apps.d.ts

@@ -0,0 +1,62 @@
+import type { PaginationOptions, RequestCallbacks } from '../shared.d.ts';
+
+export interface AppRecord {
+    uid: string;
+    name: string;
+    index_url: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    maximize_on_start?: boolean;
+    background?: boolean;
+    filetype_associations?: string[];
+    metadata?: Record<string, unknown>;
+    created_at?: string;
+    open_count?: number;
+    user_count?: number;
+}
+
+export interface AppListOptions extends PaginationOptions {
+    stats_period?: string;
+    icon_size?: null | 16 | 32 | 64 | 128 | 256 | 512;
+}
+
+export interface CreateAppOptions extends RequestCallbacks<AppRecord> {
+    name: string;
+    indexURL: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    maximizeOnStart?: boolean;
+    background?: boolean;
+    filetypeAssociations?: string[];
+    metadata?: Record<string, unknown>;
+    dedupeName?: boolean;
+}
+
+export interface UpdateAppAttributes extends RequestCallbacks<AppRecord> {
+    name?: string;
+    indexURL?: string;
+    title?: string;
+    description?: string;
+    icon?: string;
+    maximizeOnStart?: boolean;
+    background?: boolean;
+    filetypeAssociations?: string[];
+    metadata?: Record<string, unknown>;
+}
+
+export class Apps {
+    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    list (options?: AppListOptions): Promise<AppRecord[]>;
+    create (name: string, indexURL: string, title?: string): Promise<AppRecord>;
+    create (options: CreateAppOptions): Promise<AppRecord>;
+    update (name: string, attributes: UpdateAppAttributes): Promise<AppRecord>;
+    get (name: string, options?: AppListOptions): Promise<AppRecord>;
+    delete (name: string): Promise<{ success?: boolean }>;
+    getDeveloperProfile (options?: RequestCallbacks<Record<string, unknown>>): Promise<Record<string, unknown>>;
+}

package/types/modules/auth.d.ts

@@ -0,0 +1,48 @@
+export interface AuthUser {
+    uuid: string;
+    username: string;
+    email_confirmed?: boolean;
+    [key: string]: unknown;
+}
+
+export interface AllowanceInfo {
+    monthUsageAllowance: number;
+    remaining: number;
+}
+
+export interface AppUsage {
+    count: number;
+    total: number;
+}
+
+export interface APIUsage {
+    cost: number;
+    count: number;
+    units: number;
+}
+
+export interface MonthlyUsage {
+    allowanceInfo: AllowanceInfo;
+    appTotals: Record<string, AppUsage>;
+    usage: Record<string, APIUsage>;
+}
+
+export interface DetailedAppUsage {
+    total: number;
+    [key: string]: APIUsage;
+}
+
+export class Auth {
+    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    signIn (options?: { attempt_temp_user_creation?: boolean }): Promise<AuthUser | { token?: string }>;
+    signOut (): void;
+    isSignedIn (): boolean;
+    getUser (): Promise<AuthUser>;
+    whoami (): Promise<AuthUser>;
+    getMonthlyUsage (): Promise<MonthlyUsage>;
+    getDetailedAppUsage (appId: string): Promise<DetailedAppUsage>;
+}

package/types/modules/debug.d.ts

@@ -0,0 +1,3 @@
+export class Debug {
+    constructor (context: Record<string, unknown>, parameters?: Record<string, unknown>);
+}

package/types/modules/drivers.d.ts

@@ -0,0 +1,21 @@
+export interface DriverDescriptor {
+    iface_name: string;
+    service_name?: string;
+}
+
+export class Driver {
+    constructor (config: DriverDescriptor & { call_backend: unknown });
+    call (methodName: string, parameters?: Record<string, unknown>): Promise<unknown>;
+}
+
+export class Drivers {
+    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    list (): Promise<Record<string, unknown>>;
+    get (iface_name: string, service_name?: string): Promise<Driver>;
+    call (iface_name: string, method_name: string, parameters?: Record<string, unknown>): Promise<unknown>;
+    call (iface_name: string, service_name: string, method_name: string, parameters?: Record<string, unknown>): Promise<unknown>;
+}

package/types/modules/filesystem.d.ts

@@ -0,0 +1,104 @@
+import type { RequestCallbacks } from '../shared.d.ts';
+import type { FSItem } from './fs-item.d.ts';
+
+export interface SpaceInfo {
+    capacity: number;
+    used: number;
+}
+
+export interface CopyOptions extends RequestCallbacks<FSItem> {
+    source: string;
+    destination: string;
+    overwrite?: boolean;
+    newName?: string;
+    createMissingParents?: boolean;
+    dedupeName?: boolean;
+    newMetadata?: Record<string, unknown>;
+    excludeSocketID?: string;
+}
+
+export interface MoveOptions extends RequestCallbacks<FSItem> {
+    source: string;
+    destination: string;
+    overwrite?: boolean;
+    newName?: string;
+    createMissingParents?: boolean;
+    newMetadata?: Record<string, unknown>;
+    excludeSocketID?: string;
+}
+
+export interface MkdirOptions extends RequestCallbacks<FSItem> {
+    path?: string;
+    overwrite?: boolean;
+    dedupeName?: boolean;
+    createMissingParents?: boolean;
+}
+
+export interface DeleteOptions extends RequestCallbacks<void> {
+    path?: string;
+    recursive?: boolean;
+    descendantsOnly?: boolean;
+}
+
+export interface ReadOptions extends RequestCallbacks<Blob> {
+    path?: string;
+    offset?: number;
+    byte_count?: number;
+}
+
+export interface ReaddirOptions extends RequestCallbacks<FSItem[]> {
+    path?: string;
+    uid?: string;
+    no_thumbs?: boolean;
+    no_assocs?: boolean;
+    consistency?: 'strong' | 'eventual';
+}
+
+export interface RenameOptions extends RequestCallbacks<FSItem> {
+    uid?: string;
+    path?: string;
+    newName: string;
+}
+
+export interface UploadOptions extends RequestCallbacks<FSItem[]> {
+    overwrite?: boolean;
+    dedupeName?: boolean;
+    name?: string;
+    parsedDataTransferItems?: boolean;
+    createFileParent?: boolean;
+    init?: (operationId: string, xhr: XMLHttpRequest) => void;
+    error?: (e: unknown) => void;
+}
+
+export interface WriteOptions extends RequestCallbacks<FSItem> {
+    overwrite?: boolean;
+    dedupeName?: boolean;
+    createMissingParents?: boolean;
+    name?: string;
+}
+
+export interface SignResult<T = Record<string, unknown>> {
+    token: string;
+    items: T | T[];
+}
+
+export class PuterJSFileSystemModule {
+    constructor (context: Record<string, unknown>);
+
+    space (options?: RequestCallbacks<SpaceInfo>): Promise<SpaceInfo>;
+    mkdir (pathOrOptions: string | MkdirOptions, options?: MkdirOptions): Promise<FSItem>;
+    copy (sourceOrOptions: string | CopyOptions, destination?: string, options?: CopyOptions): Promise<FSItem>;
+    rename (pathOrUid: string, newName: string, options?: RenameOptions): Promise<FSItem>;
+    upload (items: FileList | File[] | Blob[] | Blob | string | unknown[], dirPath?: string, options?: UploadOptions): Promise<FSItem[]>;
+    read (pathOrOptions: string | ReadOptions, options?: ReadOptions): Promise<Blob>;
+    delete (pathOrOptions: string | DeleteOptions, options?: DeleteOptions): Promise<void>;
+    move (sourceOrOptions: string | MoveOptions, destination?: string, options?: MoveOptions): Promise<FSItem>;
+    write (path: string, data?: string | File | Blob | ArrayBuffer | ArrayBufferView, options?: WriteOptions): Promise<FSItem>;
+    sign (appUid: string, items: unknown | unknown[], success?: (result: SignResult) => void, error?: (reason: unknown) => void): Promise<SignResult>;
+    symlink (targetPath: string, linkPath: string, options?: Record<string, unknown>): Promise<FSItem>;
+    getReadURL (path: string, expiresIn?: number): Promise<string>;
+    readdir (pathOrOptions?: string | ReaddirOptions, options?: ReaddirOptions): Promise<FSItem[]>;
+    stat (pathOrUid: string, options?: Record<string, unknown>): Promise<FSItem>;
+
+    FSItem: typeof FSItem;
+}

package/types/modules/fs-item.d.ts

@@ -0,0 +1,57 @@
+import type { ReaddirOptions, WriteOptions } from './filesystem.d.ts';
+
+export interface FileSignatureInfo {
+    read_url?: string;
+    write_url?: string;
+    metadata_url?: string;
+    fsentry_accessed?: number;
+    fsentry_modified?: number;
+    fsentry_created?: number;
+    fsentry_is_dir?: boolean;
+    fsentry_size?: number | null;
+    fsentry_name?: string;
+    path?: string;
+    uid?: string;
+}
+
+export interface InternalFSProperties {
+    signature?: string | null;
+    expires?: string | null;
+    file_signature: FileSignatureInfo;
+}
+
+export class FSItem {
+    constructor (options: Record<string, unknown>);
+
+    readURL?: string;
+    writeURL?: string;
+    metadataURL?: string;
+    name: string;
+    uid: string;
+    id: string;
+    uuid: string;
+    path: string;
+    size: number | null;
+    accessed?: number;
+    modified?: number;
+    created?: number;
+    isDirectory: boolean;
+    _internalProperties?: InternalFSProperties;
+
+    write (data: Blob | File | ArrayBuffer | ArrayBufferView | string): Promise<FSItem>;
+    rename (newName: string): Promise<FSItem>;
+    move (destination: string, overwrite?: boolean, newName?: string): Promise<FSItem>;
+    copy (destinationDirectory: string, autoRename?: boolean, overwrite?: boolean): Promise<FSItem>;
+    delete (): Promise<void>;
+    mkdir (name: string, autoRename?: boolean): Promise<FSItem>;
+    readdir (options?: ReaddirOptions): Promise<FSItem[]>;
+    read (): Promise<Blob>;
+
+    // Placeholders that are not implemented in the runtime SDK yet.
+    watch (callback: (item: FSItem) => void): void;
+    open (callback: (item: FSItem) => void): void;
+    setAsWallpaper (options?: Record<string, unknown>, callback?: () => void): void;
+    versions (): Promise<unknown>;
+    trash (): Promise<unknown>;
+    metadata (): Promise<unknown>;
+}

package/types/modules/hosting.d.ts

@@ -0,0 +1,23 @@
+import type { RequestCallbacks } from '../shared.d.ts';
+import type { FSItem } from './fs-item.d.ts';
+
+export interface Subdomain extends RequestCallbacks<Subdomain> {
+    uid: string;
+    subdomain: string;
+    root_dir?: FSItem | string | null;
+}
+
+export class Hosting {
+    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    list (): Promise<Subdomain[]>;
+    create (subdomain: string): Promise<Subdomain>;
+    create (subdomain: string, dirPath: string): Promise<Subdomain>;
+    create (options: { subdomain: string; root_dir?: string | FSItem }): Promise<Subdomain>;
+    update (subdomain: string, dirPath?: string | null): Promise<Subdomain>;
+    get (subdomain: string): Promise<Subdomain>;
+    delete (subdomain: string): Promise<boolean>;
+}

package/types/modules/kv.d.ts

@@ -0,0 +1,34 @@
+export type KVValue = string | number | boolean | object | unknown;
+export type KVScalar = KVValue | KVValue[];
+
+export interface KVPair<T = unknown> {
+    key: string;
+    value: T;
+}
+
+export interface KVIncrementPath {
+    [path: string]: number;
+}
+
+export class KV {
+    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
+
+    readonly MAX_KEY_SIZE: number;
+    readonly MAX_VALUE_SIZE: number;
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    set<T = KVScalar>(key: string, value: T, expireAt?: number): Promise<boolean>;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    del (key: string): Promise<boolean>;
+    incr (key: string, amount?: number | KVIncrementPath): Promise<number>;
+    decr (key: string, amount?: number | KVIncrementPath): Promise<number>;
+    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>[]>;
+    flush (): Promise<boolean>;
+    clear (): Promise<boolean>;
+}

package/types/modules/networking.d.ts

@@ -0,0 +1,33 @@
+export type SocketEvent =
+    | 'open'
+    | 'data'
+    | 'error'
+    | 'close'
+    | 'drain'
+    | 'tlsdata'
+    | 'tlsopen'
+    | 'tlsclose';
+
+export class PSocket {
+    constructor (host: string, port: number);
+    write (data: ArrayBuffer | ArrayBufferView | string, callback?: () => void): void;
+    close (): void;
+    on (event: 'open', handler: () => void): void;
+    on (event: 'data', handler: (buffer: Uint8Array) => void): void;
+    on (event: 'error', handler: (reason: unknown) => void): void;
+    on (event: 'close', handler: (hadError: boolean) => void): void;
+    addListener (event: SocketEvent, handler: (...args: unknown[]) => void): void;
+}
+
+export class PTLSSocket extends PSocket {
+    constructor (host: string, port: number);
+}
+
+export interface Networking {
+    generateWispV1URL(): Promise<string>;
+    Socket: typeof PSocket;
+    tls: {
+        TLSSocket: typeof PTLSSocket;
+    };
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}

package/types/modules/os.d.ts

@@ -0,0 +1,12 @@
+import type { RequestCallbacks } from '../shared.d.ts';
+import type { AuthUser } from './auth.d.ts';
+
+export class OS {
+    constructor (context: { authToken?: string; APIOrigin: string; appID?: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    user (options?: RequestCallbacks<AuthUser> & { query?: Record<string, string> }): Promise<AuthUser>;
+    version (options?: RequestCallbacks<Record<string, unknown>>): Promise<Record<string, unknown>>;
+}

package/types/modules/perms.d.ts

@@ -0,0 +1,23 @@
+export class Perms {
+    constructor (context: { authToken?: string; APIOrigin: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    grantUser (username: string, permission: string): Promise<Record<string, unknown>>;
+    grantGroup (groupUid: string, permission: string): Promise<Record<string, unknown>>;
+    grantApp (appUid: string, permission: string): Promise<Record<string, unknown>>;
+    grantAppAnyUser (appUid: string, permission: string): Promise<Record<string, unknown>>;
+    grantOrigin (origin: string, permission: string): Promise<Record<string, unknown>>;
+
+    revokeUser (username: string, permission: string): Promise<Record<string, unknown>>;
+    revokeGroup (groupUid: string, permission: string): Promise<Record<string, unknown>>;
+    revokeApp (appUid: string, permission: string): Promise<Record<string, unknown>>;
+    revokeAppAnyUser (appUid: string, permission: string): Promise<Record<string, unknown>>;
+    revokeOrigin (origin: string, permission: string): Promise<Record<string, unknown>>;
+
+    createGroup (metadata?: Record<string, unknown>, extra?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    addUsersToGroup (uid: string, usernames: string[]): Promise<Record<string, unknown>>;
+    removeUsersFromGroup (uid: string, usernames: string[]): Promise<Record<string, unknown>>;
+    listGroups (): Promise<Record<string, unknown>>;
+}

package/types/modules/threads.d.ts

@@ -0,0 +1,27 @@
+export interface ThreadPost {
+    uid?: string;
+    parent?: string;
+    text?: string;
+    [key: string]: unknown;
+}
+
+export interface ThreadListResult {
+    posts: ThreadPost[];
+    total?: number;
+    page?: number;
+}
+
+export type ThreadSubscriptionHandler = (event: string, data: Record<string, unknown>) => void;
+
+export default class Threads {
+    constructor (context: { authToken?: string; APIOrigin: string });
+
+    setAuthToken (authToken: string): void;
+    setAPIOrigin (APIOrigin: string): void;
+
+    create (spec: string | ThreadPost, parent?: string): Promise<ThreadPost>;
+    edit (uid: string, spec?: string | ThreadPost): Promise<void>;
+    delete (uid: string): Promise<void>;
+    list (uid: string, page?: number, options?: Record<string, unknown>): Promise<ThreadListResult>;
+    subscribe (uid: string, callback: ThreadSubscriptionHandler): Promise<void>;
+}