IMPORTANT: This file contains the concatenated documentation for puter.js, a JavaScript SDK for the Puter Web OS. Use this documentation to answer questions about puter.js, its features, usage, and APIs. WAIT FOR MY QUESTIONS BEFORE PROVIDING ANY INFORMATION. DO NOT SAY ANYTHING UNTIL I START ASKING QUESTIONS. -------------------------------------------- -------------------------------------------- The following document is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. -------------------------------------------- -------------------------------------------- Given a prompt returns the completion that best matches the prompt. ## Syntax ```js puter.ai.chat(prompt, testMode = false) puter.ai.chat(prompt, imageURL, testMode = false) puter.ai.chat(prompt, [imageURLArray], testMode = false) puter.ai.chat([messages], testMode = false) ``` ## Parameters #### `prompt` (String) (Required) A string containing the prompt you want to complete. #### `testMode` (Boolean) (Optional) A boolean indicating whether you want to use the test API. Defaults to `false`. This is useful for testing your code without using up API credits. #### `imageURL` (String) A string containing the URL of an image you want to provide as context for the completion. Also known as "GPT Vision". #### `imageURLArray` (Array) An array of strings containing the URLs of images you want to provide as context for the completion. #### `messages` (Array) An array of objects containing the messages you want to complete. Each object must have a `role` and a `content` property. The `role` property must be one of `system`, `assistant`, `user`, or `function`. The `content` property must be a string containing the message. An example of a valid `messages` parameter is: ```js [ { role: 'system', content: 'Hello, how are you?' }, { role: 'user', content: 'I am doing well, how are you?' }, ] ``` Providing a messages array is especially useful for building chatbots where you want to provide context to the completion. ## Return value Will resolve to a string containing the completion that best matches the prompt. In case of an error, the `Promise` will reject with an error message. ## Examples Ask GPT-3.5 Turbo a question ```html;ai-chatgpt ``` GPT-4 Vision ```html;ai-gpt-vision ``` Given an image will return the text contained in the image. ## Syntax ```js puter.ai.img2txt(image, testMode = false) ``` ## Parameters #### `image` (String|File|Blob) (required) A string containing the URL, or path (on Puter) of the image you want to recognize, or a `File` or `Blob` object containing the image. #### `testMode` (Boolean) (Optional) A boolean indicating whether you want to use the test API. Defaults to `false`. This is useful for testing your code without using up API credits. ## Return value A `Promise` that will resolve to a string containing the text contained in the image. In case of an error, the `Promise` will reject with an error message. ## Examples Extract the text contained in an image ```html;ai-img2txt ``` Given a prompt, generate an image using AI. ## Syntax ```js puter.ai.txt2img(prompt, testMode = false) ``` ## Parameters #### `prompt` (String) (required) A string containing the prompt you want to generate an image from. #### `testMode` (Boolean) (Optional) A boolean indicating whether you want to use the test API. Defaults to `false`. This is useful for testing your code without using up API credits. ## Return value A `Promise` that will resolve to an image data URL when the image has been generated. ## Examples Generate an image of a cat using DALL·E 3 ```html;ai-txt2img ``` Converts text into speech using AI. Supports multiple languages and voices. ## Syntax ```js puter.ai.txt2speech(text, language = 'en-US', testMode = false) ``` ## Parameters #### `text` (String) (required) A string containing the text you want to convert to speech. The text must be less than 3000 characters long. #### `language` (String) (optional) The language to use for speech synthesis. Defaults to `en-US`. #### `testMode` (Boolean) (Optional) A boolean indicating whether you want to use the test API. Defaults to `false`. This is useful for testing your code without using up API credits. ## Return value A `Promise` that will resolve to an MP3 stream when the speech has been synthesized. ## Examples Convert text to speech ```html;ai-txt2speech ``` Creates an app with the given name. The app will be created in the user's apps, and will be accessible to this app. The app will be created with no permissions, and will not be able to access any data until permissions are granted to it. ## Syntax ```js puter.apps.create(name, indexURL) puter.apps.create(name, indexURL, title) puter.apps.create(name, indexURL, title, description) puter.apps.create(options) ``` ## Parameters #### `name` (required) The name of the app to create. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected. #### `indexURL` (required) The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the app will be created with no index page. #### `title` (required) The title of the app. If this parameter is not provided, the app will be created with `name` as its title. #### `description` (optional) The description of the app aimed at the end user. If this parameter is not provided, the app will be created with no description. #### `options` (required) An object containing the options for the app to create. The object can contain the following properties: - `name` (required): The name of the app to create. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected. - `indexURL` (required): The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the app will be created with no index page. - `title` (optional): The human-readable title of the app. If this parameter is not provided, the app will be created with `name` as its title. - `description` (optional): The description of the app aimed at the end user. If this parameter is not provided, the app will be created with no description. - `icon` (optional): The new icon of the app. - `maximizeOnStart` (optional): Whether the app should be maximized when it is started. Defaults to `false`. - `filetypeAssociations` (optional): An array of strings representing the filetypes that the app can open. Defaults to `[]`. File extentions and MIME types are supported; For example, `[".txt", ".md", "application/pdf"]` would allow the app to open `.txt`, `.md`, and PDF files. ## Return value A `Promise` that will resolve to the [`app`](/Objects/app/) that was created. ## Examples Create an app pointing to https://example.com ```html ``` Deletes an app with the given name. ## Syntax ```js puter.apps.delete(name) ``` ## Parameters #### `name` (required) The name of the app to delete. ## Return value A `Promise` that will resolve to the app that was deleted. ## Examples Create a random app then delete it ```html ``` Returns an app with the given name. If the app does not exist, the promise will be rejected. ## Syntax ```js puter.apps.get(name) ``` ## Parameters #### `name` (required) The name of the app to get. ## Return value A `Promise` that will resolve to the [`app`](/Objects/app/) with the given name. ## Examples Create a random app then get it ```html ``` Returns an array of all appa belonging to the user and that this app has access to. If the user has no apps, the array will be empty. ## Syntax ```js puter.apps.list() ``` ## Parameters None ## Return value A `Promise` that will resolve to an array of all [`app`s](/Objects/app/) belonging to the user that this app has access to. ## Examples Create 3 random apps and then list them ```html ``` Updates attributes of the app with the given name. ## Syntax ```js puter.apps.update(name, attributes) ``` ## Parameters #### `name` (required) The name of the app to update. #### `attributes` (required) An object containing the attributes to update. The object can contain the following properties: - `name` (optional): The new name of the app. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected. - `indexURL` (optional): The new URL of the app's index page. This URL must be accessible to the user. - `title` (optional): The new title of the app. - `description` (optional): The new description of the app aimed at the end user. - `icon` (optional): The new icon of the app. - `maximizeOnStart` (optional): Whether the app should be maximized when it is started. Defaults to `false`. - `filetypeAssociations` (optional): An array of strings representing the filetypes that the app can open. Defaults to `[]`. File extentions and MIME types are supported; For example, `[".txt", ".md", "application/pdf"]` would allow the app to open `.txt`, `.md`, and PDF files. ## Return value A `Promise` that will resolve to the [`app`](/Objects/app/) that was updated. ## Examples Create a random app then change its title ```html ``` Returns the user's basic information. ## Syntax ```js puter.auth.getUser(); ``` ## Parameters None ## Return value A promise that resolves to an object containing the user's basic information. The user's basic information is an object with the following properties: - `uuid` - The user's UUID. This is a unique identifier that can be used to identify the user. - `username` - The user's username. - `email_confirmed` - Whether the user has confirmed their email address. ## Example ```html ``` Checks whether the user is signed into the application. ## Syntax ```js puter.auth.isSignedIn(); ``` ## Parameters None ## Return value Returns `true` if the user is signed in, `false` otherwise. ## Example ```html ``` Initiates the sign in process for the user. This will open a popup window with the appropriate authentication method. Puter automatically handles the authentication process and will resolve the promise when the user has signed in. It is important to note that all essential methods in Puter handle authentication automatically. This method is only necessary if you want to handle authentication manually, for example if you want to build your own custom authentication flow. ## Syntax ```js puter.auth.signIn(); ``` ## Parameters None ## Return value A `Promise` that will resolve to `true` when the user has signed in. The promise will never reject. ## Example ```html ``` Signs the user out of the application. ## Syntx ```js puter.auth.signOut(); ``` ## Parameters None ## Return value None ## Example ```html ``` Copies a file or directory from one location to another. ## Syntax ```js puter.fs.copy(source, destination) puter.fs.copy(source, destination, options) ``` ## Parameters #### `source` (String) (Required) The path to the file or directory to copy. #### `destination` (String) (Required) The path to the destination directory. If destination is a directory then the file or directory will be copied into that directory using the same name as the source file or directory. If the destination is a file, we overwrite if overwrite is `true`, otherwise we error. #### `options` (Object) (Optional) The options for the `copy` operation. The following options are supported: - `overwrite` (Boolean) - Whether to overwrite the destination file or directory if it already exists. Defaults to `false`. - `dedupeName` (Boolean) - Whether to deduplicate the file or directory name if it already exists. Defaults to `false`. - `newName` (String) - The new name to use for the copied file or directory. Defaults to `undefined`. ## Return value A `Promise` that will resolve to the copied file or directory. If the source file or directory does not exist, the promise will be rejected with an error. ## Examples Copy a file ```html;fs-copy ``` Deletes a file or directory. ## Syntax ```js puter.fs.delete(path) puter.fs.delete(path, options) ``` ## Parameters #### `path` (String) (required) Path of the file or directory to delete. If `path` is not absolute, it will be resolved relative to the app's root directory. #### `options` (Object) (optional) The options for the `delete` operation. The following options are supported: - `recursive` (Boolean) - Whether to delete the directory recursively. Defaults to `true`. - `descendantsOnly` (Boolean) - Whether to delete only the descendants of the directory and not the directory itself. Defaults to `false`. ## Return value A `Promise` that will resolve when the file or directory is deleted. ## Examples Delete a file ```html;fs-delete ``` Delete a directory ```html ``` Allows you to create a directory. ## Syntax ```js puter.fs.mkdir(path) puter.fs.mkdir(path, options) ``` ## Parameters #### `path` (string) (required) The path to the directory to create. If path is not absolute, it will be resolved relative to the app's root directory. #### `options` (object) The options for the `mkdir` operation. The following options are supported: - `overwrite` (boolean) - Whether to overwrite the directory if it already exists. Defaults to `false`. - `dedupeName` (boolean) - Whether to deduplicate the directory name if it already exists. Defaults to `false`. - `createMissingParents` (boolean) - Whether to create missing parent directories. Defaults to `false`. ## Return value Returns a promise that resolves to the directory object of the created directory. ## Examples Create a new directory ```html;fs-mkdir ``` Demonstrate the use of `dedupeName` ```html ``` Demonstrate the use of `createMissingParents` ```html ``` Moves a file or a directory from one location to another. ## Syntax ```js puter.fs.move(source, destination) puter.fs.move(source, destination, options) ``` ## Parameters #### `source` (String) (Required) The path to the file or directory to move. #### `destination` (String) (Required) The path to the destination directory. If destination is a directory then the file or directory will be moved into that directory using the same name as the source file or directory. If the destination is a file, we overwrite if overwrite is `true`, otherwise we error. #### `options` (Object) (Optional) The options for the `move` operation. The following options are supported: - `overwrite` (Boolean) - Whether to overwrite the destination file or directory if it already exists. Defaults to `false`. - `dedupeName` (Boolean) - Whether to deduplicate the file or directory name if it already exists. Defaults to `false`. - `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`. ## Return value A `Promise` that will resolve to the moved file or directory. If the source file or directory does not exist, the promise will be rejected with an error. ## Examples Move a file ```html;fs-move ``` Demonstrate the `createMissingParents` option ```html ``` Reads data from a file. ## Syntax ```js puter.fs.read(path) ``` ## Parameters #### `path` (String) (required) Path of the file to read. If `path` is not absolute, it will be resolved relative to the app's root directory. ## Return value A `Promise` that will resolve to the contents of the file. ## Examples Read a file ```html;fs-read ``` Reads the contents of a directory, returning an array of items (files and directories) within it. This method is useful for listing all items in a specified directory in the Puter cloud storage. ## Syntax ```js puter.fs.readdir(path) ``` ## Parameters `path` (string) The path to the directory to read. If `path` is not absolute, it will be resolved relative to the app's root directory. ## Return value A `Promise` that resolves to an array of [`fsitem`s](/Objects/fsitem/) (files and directories) within the specified directory. ## Examples Read a directory ```html;fs-readdir ``` Renames a file or directory to a new name. This method allows you to change the name of a file or directory in the Puter cloud storage. ## Syntax ```js puter.fs.rename(path, newName) ``` ## Parameters #### `path` (string) The path to the file or directory to rename. If `path` is not absolute, it will be resolved relative to the app's root directory. #### `newName` (string) The new name of the file or directory. ## Return value Returns a promise that resolves to the file or directory object of the renamed file or directory. ## Examples Rename a file ```html;fs-rename ``` Returns the storage space capacity and usage for the current user.
This method requires permission to access the user's storage space. If the user has not granted permission, the method will return an error.
## Syntax ```js puter.fs.space() ``` ## Parameters None. ## Return value A `Promise` that will resolve to an object with the following properties: - `capacity` (Number): The total amount of storage capacity available to the user, in bytes. - `used` (Number): The amount of storage space used by the user, in bytes. ## Examples ```html ``` This method allows you to get information about a file or directory. ## Syntax ```js puter.fs.stat(path) ``` ## Parameters #### `path` (string) (required) The path to the file or directory to get information about. If `path` is not absolute, it will be resolved relative to the app's root directory. ## Return value A `Promise` that resolves to the [`fsitem`](/Objects/fsitem/) of the specified file or directory. ## Examples Get information about a file ```html;fs-stat ``` Given a number of local items, upload them to the Puter filesystem. ## Syntax ```js puter.fs.upload(items) puter.fs.upload(items, dirPath) puter.fs.upload(items, dirPath, options) ``` ## Parameters #### `items` (Array) (required) The items to upload to the Puter filesystem. `items` can be an `InputFileList`, `FileList`, `Array` of `File` objects, or an `Array` of `Blob` objects. #### `dirPath` (String) (optional) The path of the directory to upload the items to. If not set, the items will be uploaded to the app's root directory. #### `options` (Object) (optional) A set of key/value pairs that configure the upload process. ## Return value Returns a promise that resolves to an array of file objects of the uploaded files. ## Examples Upload a file from a file input ```html;fs-upload ``` Writes data to a specified file path. This method is useful for creating new files or modifying existing ones in the Puter cloud storage. ## Syntax ```js puter.fs.write(path) puter.fs.write(path, data) puter.fs.write(path, data, options) ``` ## Parameters #### `path` (string) (required) The path to the file to write to. If path is not absolute, it will be resolved relative to the app's root directory. #### `data` (string|File|Blob) The data to write to the file. #### `options` (object) The options for the `write` operation. The following options are supported: - `overwrite` (boolean) - Whether to overwrite the file if it already exists. Defaults to `true`. - `dedupeName` (boolean) - Whether to deduplicate the file name if it already exists. Defaults to `false`. - `createMissingParents` (boolean) - Whether to create missing parent directories. Defaults to `false`. ## Return value Returns a promise that resolves to the file object of the written file. ## Examples Create a new file containing "Hello, world!" ```html;fs-write ``` Create a new file with input coming from a file input ```html ``` Demonstrate the use of `dedupeName` ```html ``` Demonstrate the use of `createMissingParents` ```html ``` Will create a new subdomain that will be served by the hosting service. Optionally, you can specify a path to a directory that will be served by the subdomain. ## Syntax ```js puter.hosting.create(subdomain, dirPath) ``` ## Parameters #### `subdomain` (String) (required) A string containing the name of the subdomain you want to create. #### `dirPath` (String) (optional) A string containing the path to the directory you want to serve. If not specified, the subdomain will be created without a directory. ## Return value A `Promise` that will resolve to a [`subdomain`](/Objects/subdomain/) object when the subdomain has been created. If a subdomain with the given name already exists, the promise will be rejected with an error. If the path does not exist, the promise will be rejected with an error. ## Examples Create a simple website displaying "Hello world!" ```html;hosting-create ``` Deletes a subdomain from your account. The subdomain will no longer be served by the hosting service. If the subdomain has a directory, it will be disconnected from the subdomain. The associated directory will not be deleted. ## Syntax ```js puter.hosting.delete(subdomain) ``` ## Parameters #### `subdomain` (String) (required) A string containing the name of the subdomain you want to delete. ## Return value A `Promise` that will resolve to `true` when the subdomain has been deleted. If a subdomain with the given name does not exist, the promise will be rejected with an error. ## Examples Create a random website then delete it ```html;hosting-delete ``` Returns a subdomain. If the subdomain does not exist, the promise will be rejected with an error. ## Syntax ```js puter.hosting.get(subdomain) ``` ## Parameters #### `subdomain` (String) (required) A string containing the name of the subdomain you want to retrieve. ## Return value A `Promise` that will resolve to a [`subdomain`](/Objects/subdomain/) object when the subdomain has been retrieved. If a subdomain with the given name does not exist, the promise will be rejected with an error. ## Examples Get a subdomain ```html;hosting-get ``` Returns an array of all subdomains in the user's subdomains that this app has access to. If the user has no subdomains, the array will be empty. ## Syntax ```js puter.hosting.list() ``` ## Parameters None ## Return value A `Promise` that will resolve to an array of all [`subdomain`s](/Objects/subdomain/) belonging to the user that this app has access to. ## Examples Create 3 random websites and then list them ```html;hosting-list ``` Updates a subdomain to point to a new directory. If directory is not specified, the subdomain will be disconnected from its directory. ## Syntax ```js puter.hosting.update(subdomain, dirPath) ``` ## Parameters #### `subdomain` (String) (required) A string containing the name of the subdomain you want to update. #### `dirPath` (String) (optional) A string containing the path to the directory you want to serve. If not specified, the subdomain will be disconnected from its directory. ## Return value A `Promise` that will resolve to a [`subdomain`](/Objects/subdomain/) object when the subdomain has been updated. If a subdomain with the given name does not exist, the promise will be rejected with an error. If the path does not exist, the promise will be rejected with an error. ## Examples Update a subdomain to point to a new directory ```html;hosting-update ``` Decrements the value of a key. If the key does not exist, it is initialized with 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. ## Syntax ```js puter.kv.decr(key) puter.kv.decr(key, amount) ``` ## Parameters #### `key` (string) (required) The key of the value to decrement. #### `amount` (integer) (optional) The amount to decrement the value by. Defaults to 1. ## Return Value Returns the new value of the key after the decrement operation. ## Examples Decrement the value of a key ```html;kv-decr ``` When passed a key, will remove that key from the key-value storage. If there is no key with the given name in the key-value storage, nothing will happen. ## Syntax ```js puter.kv.del(key) ``` ## Parameters #### `key` (String) (required) A string containing the name of the key you want to remove. ## Return value A `Promise` that will resolve to `true` when the key has been removed. ## Examples Delete the key 'name' ```html;kv-del ``` Will remove all key-value pairs from the user's key-value store for the current app. ## Syntax ```js puter.kv.flush() ``` ## Parameters None ## Return value A `Promise` that will resolve to `true` when the key-value store has been flushed (emptied). The promise will never reject. ## Examples ```html;kv-flush ``` When passed a key, will return that key's value, or `null` if the key does not exist. ## Syntax ```js puter.kv.get(key) ``` ## Parameters #### `key` (String) (required) A string containing the name of the key you want to retrieve the value of. ## Return value A `Promise` that will resolve to a string containing the value of the key. If the key does not exist, it will resolve to `null`. ## Examples Retrieve the value of key 'name' ```html;kv-get ``` Increments the value of a key. If the key does not exist, it is initialized with 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers. ## Syntax ```js puter.kv.incr(key) puter.kv.incr(key, amount) ``` ## Parameters #### `key` (string) (required) The key of the value to increment. #### `amount` (integer) (optional) The amount to increment the value by. Defaults to 1. ## Return Value Returns the new value of the key after the increment operation. ## Examples Increment the value of a key ```html;kv-incr ``` Returns an array of all keys in the user's key-value store for the current app. If the user has no keys, the array will be empty. ## Syntax ```js puter.kv.list() puter.kv.list(pattern) puter.kv.list(returnValues = false) puter.kv.list(pattern, returnValues = false) ``` ## Parameters #### `pattern` (String) (optional) If set, only keys that match the given pattern will be returned. The pattern can contain the `*` wildcard character, which matches any number of characters. For example, `abc*` will match all keys that start with `abc`, such as `abc`, `abc123`, `abc123xyz`, etc. Default is `*`, which matches all keys. #### `returnValues` (Boolean) (optional) If set to `true`, the returned array will contain objects with both `key` and `value` properties. If set to `false`, the returned array will contain only the keys. Default is `false`. ## Return value A `Promise` that will resolve to an array of all keys (and values, if `returnValues` is set to `true`) the user's key-value store for the current app. If the user has no keys, the array will be empty. ## Examples Retrieve all keys in the user's key-value store for the current app ```html;kv-list ``` When passed a key and a value, will add it to the user's key-value store, or update that key's value if it already exists.
Each app gets its own sandboxed key-value store in each user's account. Apps cannot access each other's key-value stores.
## Syntax ```js puter.kv.set(key, value) ``` ## Parameters #### `key` (String) (required) A string containing the name of the key you want to create/update. The maximum allowed `key` size is **1 KB**. #### `value` (String | Number | Boolean) A string containing the value you want to give the key you are creating/updating. The maximum allowed `value` size is **400 KB**. ## Return value A `Promise` that will resolves to `true` when the key-value pair has been created or the existing key's value has been updated. ## Examples Create a new key-value pair ```html;kv-set ``` Provides an interface for interaction with another app. ## Attributes #### `usesSDK` (Boolean) Whether the target app is using Puter.js. If not, then some features of `AppConnection` will not be available. ## Methods #### `on(eventName, handler)` Listen to an event from the target app. Possible events are: - `message` - The target app sent us a message with `postMessage()`. The handler receives the message. - `close` - The target app has closed. The handler receives an object with an `appInstanceID` field of the closed app. #### `off(eventName, handler)` Remove an event listener added with `on(eventName, handler)`. #### `postMessage(message)` Send a message to the target app. Think of it as a more limited version of [`window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). `message` can be anything that [`window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) would accept for its `message` parameter. If the target app is not using the SDK, or the connection is not open, then nothing will happen. #### `close()` Attempt to close the target app. If you do not have permission to close it, or the target app is already closed, then nothing will happen. An app has permission to close apps that it has launched with [`puter.ui.launchApp()`](/UI/launchApp). ## Examples ### Interacting with another app This example demonstrates two apps, `parent` and `child`, communicating with each other over using `AppConnection`. In order: 1. `parent` launches `child` 2. `parent` sends a message, `"Hello!"`, to `child` 3. `child` shows that message in an alert dialog. 4. `child` sends a message back. 5. `parent` receives the message and logs it. 6. `parent` closes the child app. ```html Parent app Child app ``` ### Single app with multiple windows Multi-window applications can also be implemented with a single app, by launching copies of itself that check if they have a parent and wait for instructions from it. In this example, a parent app (with the name `traffic-light`) launches three children that display the different colors of a traffic light. ```html Traffic light ``` ## Attributes #### `uid` (String) A string containing the unique identifier of the app. This is a unique identifier generated by Puter when the app is created. #### `name` (String) A string containing the name of the app. #### `icon` (String) A string containing the Data URL of the icon of the app. This is a base64 encoded image. #### `description` (String) A string containing the description of the app. #### `title` (String) A string containing the title of the app. #### `maximize_on_start` (Boolean) (default: `false`) A boolean value indicating whether the app should be maximized when it is started. #### `index_url` (String) A string containing the URL of the index file of the app. This is the file that will be loaded when the app is started. #### `created_at` (String) A string containing the date and time when the app was created. The format of the date and time is `YYYY-MM-DDTHH:MM:SSZ`. #### `background` (Boolean) (default: `false`) A boolean value indicating whether the app should run in the background. If this is set to `true`. #### `filetype_associations` (Array) An array of strings containing the file types that the app can open. Each string should be in the format `"."` or `"mime/type"`. e.g. `[".txt", "image/png"]`. For a directory association, the string should be `.directory`. An fsitem object represents a file or a directory in the file system of a Puter. ## Attributes #### `id` (String) A string containing the unique identifier of the item. This is a unique identifier generated by Puter when the item is created. #### `uid` (String) This is an alias for `id`. #### `name` (String) A string containing the name of the item. #### `path` (String) A string containing the path of the item. This is the path of the item relative to the root directory of the file system. #### `is_dir` (Boolean) A boolean value indicating whether the item is a directory. If this is set to `true`, the item is a directory. If this is set to `false`, the item is a file. #### `parent_id` (String) A string containing the unique identifier of the parent directory of the item. #### `parent_uid` (String) This is an alias for `parent_id`. #### `created` (Integer) An integer containing the Unix timestamp of the date and time when the item was created. #### `modified` (Integer) An integer containing the Unix timestamp of the date and time when the item was last modified. #### `accessed` (Integer) An integer containing the Unix timestamp of the date and time when the item was last accessed. #### `size` (Integer) An integer containing the size of the item in bytes. If the item is a directory, this will be `null`. ## Attributes #### `uid` (String) A string containing the unique identifier of the subdomain. #### `subdomain` (String) A string containing the name of the subdomain. This is the part of the domain that comes before the main domain name. e.g. in `example.puter.site`, `example` is the subdomain. #### `root_dir` (FSItem) An FSItem object representing the root directory of the subdomain. This is the directory where the files of the subdomain are stored. Displays an alert dialog by Puter. Puter improves upon the traditional browser alerts by providing more flexibility. For example, you can customize the buttons displayed. `puter.ui.alert()` will block the parent window until user responds by pressing a button. ## Syntax ```js puter.ui.alert(message) puter.ui.alert(message, buttons) ``` ## Parameters #### `message` (optional) A string to be displayed in the alert dialog. If not set, the dialog will be empty. #### `buttons` (optional) An array of objects that define the buttons to be displayed in the alert dialog. Each object must have a `label` property. The `value` property is optional. If it is not set, the `label` property will be used as the value. The `type` property is optional and can be set to `primary`, `success`, `info`, `warning`, or `danger`. If it is not set, the default type will be used. ## Return value A `Promise` that resolves to the value of the button pressed. If the `value` property of button is set it is returned, otherwise `label` property will be returned. ## Examples ```html ``` Presents a dialog to the user to authenticate with their Puter account. ## Syntax ```js puter.ui.authenticateWithPuter() ``` ## Parameters None. ## Return value A `Promise` that will resolve to `true`. If the user cancels the dialog, the promise will be rejected with an error. ## Examples ```html ``` Creates and displays a window. ## Syntax ```js puter.ui.createWindow() puter.ui.createWindow(options) ``` ## Parameters #### `options` (optional) A set of key/value pairs that configure the window. * `center` (Boolean): if set to `true`, window will be placed at the center of the screen. * `content` (String): content of the window. * `disable_parent_window` (Boolean): if set to `true`, the parent window will be blocked until current window is closed. * `has_head` (Boolean): if set to `true`, window will have a head which contains the icon and close, minimize, and maximize buttons. * `height` (Float): height of window in pixels. * `is_resizable` (Boolean): if set to `true`, user will be able to resize the window. * `show_in_taskbar` (Boolean): if set to `true`, window will be represented in the taskbar. * `title` (String): title of the window. * `width` (Float): width of window in pixels. ## Examples ```html ``` Will terminate the running application and close its window. ## Syntax ```js puter.exit() ``` ## Parameters `puter.exit()` does not accept any parameters. ## Examples ```html ``` Allows you to dynamically launch another app from within your app. ## Syntax ```js puter.ui.launchApp() puter.ui.launchApp(appName) puter.ui.launchApp(appName, args) puter.ui.launchApp(args) ``` ## Parameters #### `appName` (String) Name of the app. If not provided, a new instance of the current app will be launched. #### `args` (Object) Arguments to pass to the app. If `appName` is not provided, these arguments will be passed to the current app. ## Return value A `Promise` that will resolve to an [`AppConnection`](/Objects/AppConnection) once the app is launched. ## Examples ```html ``` Listen to broadcast events from Puter. If the broadcast was received before attaching the handler, then the handler is called immediately with the most recent value. ## Syntax ```js puter.ui.on(eventName, handler) ``` ## Parameters #### `eventName` (String) Name of the event to listen to. #### `handler` (Function) Callback function run when the broadcast event is received. ## Broadcasts Possible broadcasts are: #### `localeChanged` Sent on app startup, and whenever the user's locale on Puter is changed. The value passed to `handler` is: ```js { language, // (String) Language identifier, such as 'en' or 'pt-BR' } ``` #### `themeChanged` Sent on app startup, and whenever the user's desktop theme on Puter is changed. The value passed to `handler` is: ```js { palette: { primaryHue, // (Float) Hue of the theme color primarySaturation, // (String) Saturation of the theme color as a percentage, with % sign primaryLightness, // (String) Lightness of the theme color as a percentage, with % sign primaryAlpha, // (Float) Opacity of the theme color from 0 to 1 primaryColor, // (String) CSS color value for text } } ``` ## Examples ```html ``` Specify a function to execute when the one or more items have been opened. Items can be opened via a variety of methods such as: drag and dropping onto the app, double-clicking on an item, right-clicking on an item and choosing an app from the 'Open With...' submenu. **Note** `onItemsOpened` is not called when items are opened using `showOpenFilePicker()`. ## Syntax ```js puter.ui.onItemsOpened(handler) ``` ## Parameters #### `handler` (Function) A function to execute after items are opened by user action. ## Examples ```html ``` Specify a callback function to execute if the app is launched with items. `onLaunchedWithItems` will be called if one or more items are opened via double-clicking on items, right-clicking on items and choosing the app from the 'Open With...' submenu. ## Syntax ```js puter.ui.onLaunchedWithItems(handler) ``` ## Parameters #### `handler` (Function) A function to execute after items are opened by user action. The function will be passed an array of items. Each items is either a file or a directory. ## Examples ```html ``` Specify a function to execute when the window is about to close. For example the provided function will run right after the 'X' button of the window has been pressed. **Note** `onWindowClose` is not called when app is closed using `puter.exit()`. ## Syntax ```js puter.ui.onWindowClose(handler) ``` ## Parameters #### `handler` (Function) A function to execute when the window is going to close. ## Examples ```html ``` Obtain a connection to the app that launched this app. ## Syntax ```js puter.ui.parentApp() ``` ## Parameters `puter.ui.parentApp()` does not accept any parameters. ## Return value An [`AppConnection`](/Objects/AppConnection) to the parent, or null if there is no parent app. ## Examples ```html ``` Creates a menubar in the UI. The menubar is a horizontal bar at the top of the window that contains menus. ## Syntax ```js puter.ui.setMenubar(options) ``` ## Parameters #### `options.items` (Array) An array of menu items. Each item can be a menu or a menu item. Each menu item can have a label, an action, and a submenu. #### `options.items.label` (String) The label of the menu item. #### `options.items.action` (Function) A function to execute when the menu item is clicked. #### `options.items.items` (Array) An array of submenu items. ## Examples ```html ``` Allows the user to dynamically set the height of the window. ## Syntax ```js puter.ui.setWindowHeight(height) ``` ## Parameters #### `height` (Float) The new height for this window. Must be a positive number. Minimum height is 200px, if a value less than 200 is provided, the height will be set to 200px. ## Examples ```html ``` Allows the user to dynamically set the position of the window. ## Syntax ```js puter.ui.setWindowPosition(x, y) ``` ## Parameters #### `x` (Float) The new x position for this window. Must be a positive number. #### `y` (Float) The new y position for this window. Must be a positive number. ## Examples ```html ``` Allows the user to dynamically set the width and height of the window. ## Syntax ```js puter.ui.setWindowSize(width, height) ``` ## Parameters #### `width` (Float) The new width for this window. Must be a positive number. Minimum width is 200px, if a value less than 200 is provided, the width will be set to 200px. #### `height` (Float) The new height for this window. Must be a positive number. Minimum height is 200px, if a value less than 200 is provided, the height will be set to 200px. ## Examples ```html ``` Allows the user to dynamically set the title of the window. ## Syntax ```js puter.ui.setWindowTitle(title) ``` ## Parameters #### `title` (String) The new title for this window. ## Examples ```html ``` Allows the user to dynamically set the width of the window. ## Syntax ```js puter.ui.setWindowWidth(width) ``` ## Parameters #### `width` (Float) The new width for this window. Must be a positive number. Minimum width is 200px, if a value less than 200 is provided, the width will be set to 200px. ## Examples ```html ``` Presents the user with a color picker dialog allowing them to select a color. ## Syntax ```js puter.ui.showColorPicker() puter.ui.showColorPicker(defaultColor) puter.ui.showColorPicker(options) ``` ## Examples ```html ``` Presents the user with a directory picker dialog allowing them to pick a directory from their Puter cloud storage. ## Syntax ```js puter.ui.showDirectoryPicker() puter.ui.showDirectoryPicker(options) ``` ## Parameters #### `options` (optional) A set of key/value pairs that configure the directory picker dialog. * `multiple` (Boolean): if set to `true`, user will be able to select multiple directories. Default is `false`. ## Return value A `Promise` that resolves to either one FSItem or an array of FSItem objects, depending on how many directories were selected by the user. ## Examples ```html

``` Presents the user with a list of fonts allowing them to preview and select a font. ## Syntax ```js puter.ui.showFontPicker() puter.ui.showFontPicker(defaultFont) puter.ui.showFontPicker(options) ``` ## Parameters #### `defaultFont` (String) The default font to select when the font picker is opened. ## Examples ```html

A cool Font Picker demo!

``` Presents the user with a file picker dialog allowing them to pick a file from their Puter cloud storage. ## Syntax ```js puter.ui.showOpenFilePicker() puter.ui.showOpenFilePicker(options) ``` ## Parameters #### `options` (optional) A set of key/value pairs that configure the file picker dialog. * `multiple` (Boolean): if set to `true`, user will be able to select multiple files. Default is `false`. * `accept` (String): The list of MIME types that are accepted by the file picker. Default is `*/*`. ## Return value A `Promise` that resolves to either one FSItem or an array of FSItem objects, depending on how many files were selected by the user. ## Examples ```html

``` Presents the user with a file picker dialog allowing them to specify where and with what name to save a file. ## Syntax ```js puter.ui.showSaveFilePicker() puter.ui.showSaveFilePicker(data, defaultFileName) ``` ## Parameters #### `defaultFileName` (String) The default file name to use. ## Examples ```html

``` A property of the `puter` object that returns the appID of the current application. ## Syntax ```js puter.appID ``` ## Examples Get the ID of the current application
```html ```
Prints a string by appending it to the body of the document. This is useful for debugging and testing purposes and is not recommended for production use. ## Syntax ```js puter.print(text); ``` ## Parameters #### `text` (String) The text to print. ## Examples Print "Hello, world!"
```html ```
A function that generates a domain-safe name by combining a random adjective, a random noun, and a random number (between 0 and 9999). The result is returned as a string with components separated by hyphens by default. You can change the separator by passing a string as the first argument to the function. ## Syntax ```js puter.randName() puter.randName(separator) ``` ## Parameters #### `separator` (String) The separator to use between components. Defaults to `-`. ## Examples Generate a random name
```html ```
To Do List

A simple to do list app with cloud functionalities powered by the Puter Key-Value Store.

AI Chat

A chat app with AI using the Puter AI module. This app is powered by OpenAI GPT-3.5 Turbo.

Image Describer

Allows you take a picture and describe it using the Puter AI module. This app is powered by OpenAI GPT-4 Vision.

Text Summarizer

Uses the Puter AI module to summarize a given long text. The model used in the background is GPT-3.5 Turbo.

To begin using Puter.js, simply add it to your web application. There's no need for configuration, keys, or passwords. Just include the Puter.js script, and you're ready to start: ```html ``` ## Basic Usage Once you've added the Puter.js script to your web application, a global `puter` object will be available for you to use. This object contains all of the functionality provided by Puter.js. For example, to use GPT-3.5 Turbo, you can call the `puter.ai.chat` function: ```html ``` This is all you need to use GPT-3.5 Turbo in your app. No backend code, no configuration, and no API keys. Just include the Puter.js script, and you're ready to start. ## What is Puter.js? Build powerful web apps without writing a single line of backend code. Puter.js provides full, free access to various cloud and AI services directly from your frontend code. It brings Cloud Storage, Key-Value Store, GPT-3.5 Turbo, DALL·E, Hosting, and more to your frontend code. Puter.js works in a way that every user of your app will cover their own costs, so whether you have 1 user or 1 million users, your app won't cost you anything to run. In other words, Puter.js gives your app infinitely scalable Cloud and AI for free. Puter.js is powered by [Puter.com](https://puter.com), the scalable personal cloud platform with a heavy focus on privacy. Puter does not use tracking technologies and does not monetize or even collect personal information.

Puter.js is open-source!

Examples

Cloud Storage
Cloud Key-Value Store
AI
Hosting
#### Cloud Storage (FileSystem) ```html;intro-fs-write ```
#### Save user preference in the cloud Key-Value Store ```html;intro-kv-set ```
#### Chat with GPT-3.5 Turbo ```html;intro-chatgpt ```

GPT-4 Vision

```html;intro-gpt-vision ```
#### Publish a static website ```html;intro-hosting ```

FAQ

Do I need a Puter.com account or an API key to use Puter.js?

No, you don't need a Puter.com account, API key, or any other registration or configuration to use Puter.js. All you need is to include the Puter.js SDK in your HTML page and you can start using Puter.js right away. ```html ```

Do I need to publish my app on Puter.com to use Puter.js?

No. Puter.js works in any HTML page and you can use it in your own website whether you host it on Puter.com or anywhere else.

How can you make the cloud and AI free for developers? How do you make money?

Using Puter.js, users of your apps will pay for the cloud and AI services, so as the developer of the app your cost remains practically zero no matter how many users you have. Every user gets a free tier and if they need more resources, they will be able to pay for more resources; we plan to make money by charging a small fee on top of the cloud and AI services when users choose to pay for more resources. In this document we will cover the security model of Puter.js and how it manages apps' access to user data and cloud resources. ## Authentication If Puter.js is being used in a website, as opposed to a puter.com app, the user will have to authenticate with Puter.com first, or in other words, the user needs to give your website permission before you can use any of the cloud services on their behalf. Fortunately, Puter.js handles this automatically and the user will be prompted to sign in with their Puter.com account when your code tries to access any cloud services. If the user is already signed in, they will not be prompted to sign in again. You can build your app as if the user is already signed in, and Puter.js will handle the authentication process for you whenever it's needed.
The user will be automatically prompted to sign in with their Puter.com account when your code tries to access any cloud services or resources.
If Puter.js is being used in an app published on Puter.com, the user will be automatically signed in and your app will have full access to all cloud services. ## Default permissions Once the user has been authenticated, your app will get a few things by default: - **An app directory** in the user's cloud storage. This is where your app can freely store files and directories. The path to this directory will look like `~/AppData//`. This directory is automatically created for your app when the user has been authenticated the first time. Your app will not be able to access any files or data outside of this directory by default. - **A key-value store** in the user's space. Your app will have its own sandboxed key-value store that it can freely write to and read from. Only your app will be able to access this key-value store, and no other apps will be able to access it. Your app will not be able to access any other key-value stores by default either.
Apps are sandboxed by default! Apps are not able to access any files, directories, or data outside of their own directory and key-value store within a user's account. This is to ensure that apps can't access any data or resources that they shouldn't have access to.
Your app will also be able to use the following services by default: - **AI**: Your app will be able to use the AI services provided by Puter.com. This includes chat, txt2img, img2txt, and more. - **Hosting**: Your app will be able to use puter to create and publish websites on the user's behalf.