Fix puter.js docs and types drift 10 aug

src/docs/src/AI.md

@@ -193,6 +193,7 @@ These AI features are supported out of the box when using Puter.js:
 
 - **[`puter.ai.chat()`](/AI/chat/)** - Chat with AI models like Claude, GPT, and others
 - **[`puter.ai.listModels()`](/AI/listModels/)** - List available AI chat models (and providers) that Puter currently exposes.
+- **[`puter.ai.listModelProviders()`](/AI/listModelProviders/)** - List the AI providers that Puter currently exposes.
 - **[`puter.ai.txt2img()`](/AI/txt2img/)** - Generate images from text descriptions
 - **[`puter.ai.img2txt()`](/AI/img2txt/)** - Extract text from images (OCR)
 - **[`puter.ai.txt2speech()`](/AI/txt2speech/)** - Convert text to speech

src/docs/src/AI/txt2img.md

@@ -37,11 +37,14 @@ Additional settings for the generation request. Available options depend on the
 | `puter_output_path` | `String` | When set, the generated image is automatically saved to this path on the Puter filesystem. Relative paths are resolved against the app's data directory (or `~/` outside an app). The caller must have write permission to the destination |
 | `input_images` | `Array<String>` | Input image(s) for image-to-image — the canonical, cross-provider field (see below). |
 | `input_image` | `String` | Single-image shorthand for `input_images`. |
+| `input_image_mime_type` | `String` | MIME type of the input image(s), e.g. `'image/png'`. Used as a fallback when the type cannot be detected from the input — pass it when supplying raw base64 without a data-URI prefix. |
 
 #### Input images (image-to-image)
 
 `input_images` is the universal way to pass image-to-image inputs across providers; `input_image` is the single-image shorthand. Each entry may be a **public URL**, a **data-URI**, or **raw base64** — providers that need base64 fetch URLs server-side (SSRF-guarded), so a URL works everywhere.
 
+Raw base64 carries no MIME type of its own. When it cannot be detected from the bytes, set `input_image_mime_type` (e.g. `'image/png'`) — Gemini rejects the request otherwise, and OpenAI, xAI, and Replicate use it to label the upload.
+
 | Provider | Multiple images? | Accepted input forms |
 |----------|------------------|----------------------|
 | OpenAI `gpt-image-*` | Yes | URL, base64 / data-URI |

src/docs/src/Apps/create.md

@@ -22,7 +22,7 @@ The name of the app to create. This name must be unique to the user's apps. If a
 
 #### `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. The index page is the page that will be displayed when the app is started.
+The URL of the app's index page. This URL must be accessible to the user. The index page is the page that will be displayed when the app is started. If this parameter is not provided, the promise will be rejected.
 
 **IMPORTANT**: The URL _must_ start with either `http://` or `https://`. Any other protocols (including `file://`, `ftp://`, etc.) are not allowed and will result in an error. For example:
 
@@ -31,7 +31,7 @@ The URL of the app's index page. This URL must be accessible to the user. If thi
 ❌ `file:///path/to/index.html` <br>
 ❌ `ftp://example.com/index.html` <br>
 
-#### `title` (required)
+#### `title` (Optional)
 
 The title of the app. If this parameter is not provided, the app will be created with `name` as its title.
 
@@ -40,7 +40,7 @@ The title of the app. If this parameter is not provided, the app will be created
 An object containing the options for the app to create. The object can contain the following properties:
 
 - `name` (String) (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` (String) (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.
+- `indexURL` (String) (required): The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the promise will be rejected.
 - `title` (String) (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` (String) (optional): The description of the app aimed at the end user.
 - `icon` (String) (optional): The new icon of the app.

src/docs/src/Auth.md

@@ -101,6 +101,8 @@ These authentication features are supported out of the box when using Puter.js:
 - **[`puter.auth.signOut()`](/Auth/signOut/)** - Sign out the current user
 - **[`puter.auth.isSignedIn()`](/Auth/isSignedIn/)** - Check if a user is signed in
 - **[`puter.auth.getUser()`](/Auth/getUser/)** - Get information about the current user
+- **[`puter.auth.getMonthlyUsage()`](/Auth/getMonthlyUsage/)** - Get the user's current monthly resource usage
+- **[`puter.auth.getDetailedAppUsage()`](/Auth/getDetailedAppUsage/)** - Get detailed usage statistics for an application
 
 ## Examples
 

src/docs/src/Auth/signIn.md

@@ -29,6 +29,8 @@ puter.auth.signIn(options)
 
 - `attempt_temp_user_creation`: A boolean value that indicates whether to Puter should automatically create a temporary user. This is useful if you want to quickly onboard a user without requiring them to sign up. They can always sign up later if they want to.
 
+- `request_auth`: A boolean value that asks the popup to let the user re-pick their account, even when your site already holds a token for them. Puter otherwise skips that prompt for a site it has seen before. Useful for an explicit "switch account" button.
+
 ## Return value
 
 A `Promise` that will resolve to a [`SignInResult`](/Objects/signinresult/) object when the user has signed in.

src/docs/src/FS.md

@@ -306,6 +306,7 @@ These cloud storage features are supported out of the box when using Puter.js:
 - **[`puter.fs.stat()`](/FS/stat/)** - Get information about a file or directory
 - **[`puter.fs.delete()`](/FS/delete/)** - Delete a file or directory
 - **[`puter.fs.upload()`](/FS/upload/)** - Upload a file from the local system
+- **[`puter.fs.getReadURL()`](/FS/getReadURL/)** - Generate a URL that can be used to read a file
 
 ## Examples
 

src/docs/src/FS/move.md

@@ -32,6 +32,7 @@ The options for the `move` operation. The following options are supported:
 - `destination` (String) - Path to the destination. Required when passing options as the only argument.
 - `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 name to give the moved file or directory. When set, `destination` is always treated as the directory to move into. Defaults to the source's own name.
 - `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.
 
 ## Return value

src/docs/src/FS/readdir.md

@@ -31,6 +31,8 @@ An object with the following properties:
 - `offset` (Number) (optional) - Skips the given number of entries. Prefer `cursor` for paging through large directories.
 - `sortBy` (String) (optional) - Sort field: `name`, `modified`, `type`, or `size`. Default is `name`.
 - `sortOrder` (String) (optional) - `asc` or `desc`. Default is `asc`.
+- `recursive` (Boolean) (optional) - If `true`, the contents of subdirectories are listed too. Defaults to `false`.
+- `depth` (Number) (optional) - How many levels to descend when `recursive` is `true`. Defaults to unlimited.
 - `cursor` (String | null) (optional) - Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one. The cursor pins the sort, so later pages must not request a different `sortBy`/`sortOrder`.
 - `includeTotal` (Boolean) (optional) - If `true`, the paginated result includes a `total` count of all entries in the directory.
 - `stream` (Boolean) (optional) - If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`.

src/docs/src/FS/stat.md

@@ -27,6 +27,7 @@ An object with the following properties:
 - `path` (String) - Path to the file or directory. Required when passing options as the only argument.
 - `uid` (String) - The UID of the file or directory. Can be used instead of `path`.
 - `returnSubdomains` (Boolean) - Whether to return subdomain information. Defaults to `false`.
+- `returnWorkers` (Boolean) - Whether to return the workers attached to the item. Workers are served alongside subdomains, so this is an alias of `returnSubdomains` — setting either one returns both. Defaults to `false`.
 - `returnPermissions` (Boolean) - Whether to return permission information. Defaults to `false`.
 - `returnVersions` (Boolean) - Whether to return version information. Defaults to `false`.
 - `returnSize` (Boolean) - Whether to return size information. Defaults to `false`.

src/docs/src/FS/upload.md

@@ -32,6 +32,21 @@ A set of key/value pairs that configure the upload process. The following option
 - `dedupeName` (Boolean) - Whether to deduplicate the file name if it already exists. Defaults to `true`. Ignored when `overwrite` is `true`.
 - `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.
 
+The following callbacks report on the upload as it runs. `operationId` identifies the upload, so a page running several uploads at once can tell them apart:
+
+- `init` (Function) - Called with `(operationId, xhr)` once the request has been created, before it is sent. The `XMLHttpRequest` is passed so you can abort the upload yourself.
+- `start` (Function) - Called with no arguments when the upload starts sending.
+- `progress` (Function) - Called with `(operationId, progress)` as bytes are sent, where `progress` is a percentage between `0` and `100`.
+- `abort` (Function) - Called with `(operationId)` if the upload is aborted.
+
+```js
+puter.fs.upload(items, './uploads', {
+    progress: (operationId, progress) => {
+        console.log(`${Math.round(progress)}%`);
+    },
+});
+```
+
 ## Return value
 
 Returns a `Promise` that resolves to:

src/docs/src/FS/write.md

@@ -22,9 +22,9 @@ puter.fs.write(file)
 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) (required)
+#### `data` (String|File|Blob|ArrayBuffer|TypedArray) (optional)
 
-The data to write to the file.
+The data to write to the file. If omitted, an empty file is created.
 
 #### `options` (Object)
 

src/docs/src/KV/decr.md

@@ -4,7 +4,7 @@ description: Decrement numeric values in key-value store by a specified amount.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-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.
+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. This operation is limited to 64 bit signed integers.
 
 ## Syntax
 

src/docs/src/Objects.md

@@ -15,6 +15,8 @@ Various object types and classes that represent different entities in the Puter
 - **[FSItem](/Objects/fsitem/)** - Represents a file or directory
 - **[KVPair](/Objects/kvpair/)** - Represents a key-value pair
 - **[MonthlyUsage](/Objects/monthlyusage/)** - Represents user's monthly resource usage information
+- **[PuterPeerConnection](/Objects/puterpeerconnection/)** - Represents a data-channel connection to a peer
+- **[PuterPeerServer](/Objects/puterpeerserver/)** - Represents a peer server and its connected clients
 - **[Speech2TxtResult](/Objects/speech2txtresult/)** - Represents speech-to-text transcription results
 - **[Subdomain](/Objects/subdomain/)** - Represents a subdomain
 - **[TTSEngine](/Objects/ttsengine/)** - Represents an available text-to-speech engine/model

src/docs/src/Objects/app.md

@@ -78,7 +78,9 @@ __Parameters__
 
 __Return value__
 
-Iterable objects each containing `{username, user_uuid}`.
+Iterable objects each containing `{username, user_uuid}`, plus an optional `user_email`.
+
+`user_email` is only present when the user granted this app the `user:<uuid>:email:read` permission (for example via [`puter.perms.requestEmail()`](/Perms/requestEmail/)); it is omitted otherwise, and may be `null` if the user granted access but has no email on file.
 
 __Example__
 

src/docs/src/Objects/chatresponsechunk.md

@@ -15,10 +15,12 @@ The kind of chunk. One of:
 
 - `"text"` - A portion of the response text.
 - `"reasoning"` - A portion of the model's reasoning/thinking output.
+- `"image"` - An image generated by an image-capable model.
 - `"tool_use"` - A tool/function the model wants to call.
 - `"compaction"` - An inline-compaction summary of earlier context (when `compaction` is enabled).
 - `"extra_content"` - Provider-specific metadata.
 - `"usage"` - Token usage totals, emitted as the final chunk.
+- `"error"` - An error raised while the response was streaming. Ends the stream.
 
 #### `text` (String)
 
@@ -28,6 +30,10 @@ A portion of the chat response text. Present on `text` chunks.
 
 A portion of the model's reasoning output. Present on `reasoning` chunks.
 
+#### `image` (Object)
+
+A generated image, in the form `{ type: "image_url", image_url: { url } }` where `url` is a data URI. Present on `image` chunks.
+
 #### `id` (String)
 
 The unique identifier for the tool call (`tool_use` chunks) or the compaction item (`compaction` chunks).
@@ -51,3 +57,7 @@ Provider-specific metadata attached to the stream.
 #### `usage` (Object)
 
 An object containing token usage totals. Present on the final `usage` chunk.
+
+#### `message` (String)
+
+A description of the error that interrupted the response. Present on `error` chunks.

src/docs/src/Objects/puterpeerconnection.md

@@ -0,0 +1,70 @@
+---
+title: PuterPeerConnection
+description: The PuterPeerConnection object representing a WebRTC data-channel connection to a peer.
+---
+
+The `PuterPeerConnection` object representing a WebRTC data-channel connection to a peer. [`puter.peer.connect()`](/Peer/connect/) resolves to one, and a [`PuterPeerServer`](/Objects/puterpeerserver/) hands one to its `connection` event for every client that joins.
+
+`PuterPeerConnection` extends [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), so events are subscribed to with `addEventListener()`.
+
+## Attributes
+
+#### `owner` (Object)
+
+Information about the user who created the server, with `username` and `uuid`.
+
+#### `connected` (Boolean)
+
+Whether the data channel is currently open.
+
+#### `closed` (Boolean)
+
+Whether the connection has been closed.
+
+#### `peerconnection` (RTCPeerConnection)
+
+The raw underlying [`RTCPeerConnection`](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection) handle, for cases the Puter API does not cover.
+
+## Methods
+
+#### `send(data)`
+
+Sends a message to the peer. `data` may be a `String`, `Blob`, `ArrayBuffer`, or `ArrayBufferView`.
+
+#### `close(reason)`
+
+Closes the connection. The optional `reason` string is delivered to the peer on its `close` event.
+
+## Events
+
+#### `open`
+
+Fired when the data channel is ready. Wait for this before calling `send()`.
+
+#### `message`
+
+Fired when a message is received. `event.data` holds the payload.
+
+#### `close`
+
+Fired when the connection closes. `event.reason` holds the reason, if one was given.
+
+#### `error`
+
+Fired when a connection error occurs. `event.error` holds the error.
+
+## Example
+
+```js
+const conn = await puter.peer.connect(inviteCode);
+
+conn.addEventListener('open', () => {
+    conn.send('Hello from the client!');
+});
+conn.addEventListener('message', (msg) => {
+    puter.print('Server says:', msg.data);
+});
+conn.addEventListener('close', (event) => {
+    puter.print('Connection closed:', event.reason);
+});
+```

src/docs/src/Objects/puterpeerserver.md

@@ -0,0 +1,50 @@
+---
+title: PuterPeerServer
+description: The PuterPeerServer object returned by puter.peer.serve(), representing a peer server and its connected clients.
+---
+
+The `PuterPeerServer` object returned by [`puter.peer.serve()`](/Peer/serve/). It holds the invite code other clients use to reach you, and tracks every client that connects.
+
+`PuterPeerServer` extends [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), so events are subscribed to with `addEventListener()`.
+
+## Attributes
+
+#### `inviteCode` (String)
+
+The code to share with other clients so they can connect with [`puter.peer.connect()`](/Peer/connect/).
+
+#### `connections` (Map)
+
+A `Map` of every connected client, keyed by connection id. The values are [`PuterPeerConnection`](/Objects/puterpeerconnection/) objects.
+
+## Methods
+
+#### `close()`
+
+Closes every client connection and the signalling connection. The invite code stops working.
+
+## Events
+
+#### `connection`
+
+Fired when a client connects. The event has the following attributes:
+
+- `conn` ([`PuterPeerConnection`](/Objects/puterpeerconnection/)) - The connection to the client.
+- `user` (Object) - Metadata about the connecting user, with `username` and `uuid` (if available).
+
+## Example
+
+```js
+const server = await puter.peer.serve();
+puter.print(`Invite code: ${server.inviteCode}`);
+
+server.addEventListener('connection', (event) => {
+    const conn = event.conn;
+    conn.addEventListener('open', () => {
+        conn.send('Hello from the server!');
+    });
+    conn.addEventListener('message', (msg) => {
+        puter.print('Client says:', msg.data);
+    });
+});
+```

src/docs/src/Peer/connect.md

@@ -5,7 +5,7 @@ platforms: [websites, apps]
 ---
 
 
-Connects to a peer server and returns a `PuterPeerConnection` instance.
+Connects to a peer server and returns a [`PuterPeerConnection`](/Objects/puterpeerconnection/) instance.
 
 <div class="info">
 
@@ -35,18 +35,7 @@ A string invite code created by `puter.peer.serve()`.
 
 ## Return value
 
-A `Promise` that resolves to a `PuterPeerConnection` instance.
-
-### `PuterPeerConnection` methods and events
-
-- `send(data)` - Send a message to the peer. Supports strings, `Blob`, `ArrayBuffer`, or `ArrayBufferView`.
-- `close(reason)` - Close the connection.
-- `owner` (`object`) - Information about the user who created the server.
-- `peerconnection` (`RTCPeerConnection`) - the raw underlying RTC handle for this connection.
-- `open` event: Fired when the data channel is ready.
-- `message` event: Fired when a message is received (`event.data`).
-- `close` event: Fired when the connection closes (`event.reason`).
-- `error` event: Fired when a connection error occurs (`event.error`).
+A `Promise` that resolves to a [`PuterPeerConnection`](/Objects/puterpeerconnection/) instance, which carries `send()` and `close()` methods and the `open`, `message`, `close`, and `error` events.
 
 ## Example
 

src/docs/src/Peer/serve.md

@@ -5,7 +5,7 @@ platforms: [websites, apps]
 ---
 
 
-Creates a peer server and returns a `PuterPeerServer` instance. The server will generate an invite code that other clients can use to connect.
+Creates a peer server and returns a [`PuterPeerServer`](/Objects/puterpeerserver/) instance. The server will generate an invite code that other clients can use to connect.
 
 <div class="info">
 
@@ -31,15 +31,7 @@ const server = await puter.peer.serve(options);
 
 ## Return value
 
-A `Promise` that resolves to a `PuterPeerServer` instance.
-
-### `PuterPeerServer` properties and events
-
-- `inviteCode` (`string`) The code you share with other clients.
-- `connections` (`Map<string, PuterPeerConnection>`) map of all connected clients
-- `connection` event: Fired when a client connects.
-  - `event.conn` (`PuterPeerConnection`) The connection to the client.
-  - `event.user` (`object`) Metadata about the connecting user (if available).
+A `Promise` that resolves to a [`PuterPeerServer`](/Objects/puterpeerserver/) instance, which carries the `inviteCode` to share, the `connections` map of connected clients, and a `connection` event fired as each client joins.
 
 ## Example