From 2a49689fad1fe6a1bd020403e622f2b8a3501a8d Mon Sep 17 00:00:00 2001
From: Reynaldi Chernando <12949382+reynaldichernando@users.noreply.github.com>
Date: Tue, 20 Oct 2026 18:39:49 +0700
Subject: [PATCH] fix contradicting jsdocs and docs (#4282)

---
 src/docs/src/Apps/checkName.md                 |  2 +-
 src/docs/src/Apps/create.md                    |  4 ++--
 src/docs/src/Apps/update.md                    |  2 +-
 src/docs/src/Events/onPersistent.md            |  3 ++-
 src/docs/src/Objects/app.md                    |  4 ++--
 src/docs/src/rate-limits-and-quotas.md         |  2 +-
 src/puter-js/src/index.js                      |  2 +-
 src/puter-js/src/modules/FileSystem/types.js   |  2 +-
 src/puter-js/src/modules/apps/checkName.js     |  2 +-
 src/puter-js/src/modules/apps/create.js        |  4 ++--
 src/puter-js/src/modules/apps/types.js         | 10 +++++-----
 src/puter-js/src/modules/events/types.js       |  5 +++--
 src/puter-js/src/modules/hosting/create.js     |  8 +++++---
 src/puter-js/src/modules/networking/PSocket.js |  1 -
 src/puter-js/src/modules/networking/types.js   |  5 ++---
 15 files changed, 29 insertions(+), 27 deletions(-)

diff --git a/src/docs/src/Apps/checkName.md b/src/docs/src/Apps/checkName.md
index ebd72037a..6dabd7f0f 100644
--- a/src/docs/src/Apps/checkName.md
+++ b/src/docs/src/Apps/checkName.md
@@ -4,7 +4,7 @@ description: Check whether an app name is still available.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-Checks whether an app name is available to you, without creating anything. Useful before calling [`puter.apps.create()`](/Apps/create/), which rejects when the name is already taken.
+Checks whether an app name is free, without creating anything. App names are unique across all Puter accounts, so a name is free only when no app on any account uses it. Useful before calling [`puter.apps.create()`](/Apps/create/), which rejects when the name is already taken.
 
 ## Syntax
 
diff --git a/src/docs/src/Apps/create.md b/src/docs/src/Apps/create.md
index a5c9310b8..a083a350d 100755
--- a/src/docs/src/Apps/create.md
+++ b/src/docs/src/Apps/create.md
@@ -18,7 +18,7 @@ puter.apps.create(options)
 
 #### `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.
+The name of the app to create. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected.
 
 #### `indexURL` (required)
 
@@ -39,7 +39,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.
+- `name` (String) (required): The name of the app to create. App names are unique across all Puter accounts. If any app already has this name, 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 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.
diff --git a/src/docs/src/Apps/update.md b/src/docs/src/Apps/update.md
index eb49a46fd..9c574c47a 100755
--- a/src/docs/src/Apps/update.md
+++ b/src/docs/src/Apps/update.md
@@ -17,7 +17,7 @@ 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.
+- `name` (optional): The new name of the app. App names are unique across all Puter accounts. If any app already has this name, 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.
diff --git a/src/docs/src/Events/onPersistent.md b/src/docs/src/Events/onPersistent.md
index 61bffaa95..843f9200f 100644
--- a/src/docs/src/Events/onPersistent.md
+++ b/src/docs/src/Events/onPersistent.md
@@ -158,7 +158,8 @@ The promise rejects with `{ message, code }`:
 | `events_background_consent_required` | The subscription targets `worker` and the user hasn't granted `events:background`. |
 | `events_context_too_large` | The serialized `context` is over 4 KB. |
 | `events_context_invalid` | `context` is not JSON-serializable. |
-| `invalid_targets` | An unknown target, `push` with `single`, or `worker` with no app. |
+| `invalid_targets` | `targets` is empty or not an array, it has an unknown target, it has `push` with `single`, an app's `single` subscription leaves out `worker`, or it has `worker` with no app. |
+| `bad_request` | `delivery` isn't `'broadcast'` or `'single'`, or `handlerName` isn't a string or is over 128 characters. |
 | `invalid_expires_at` | `expiresAt` is not a future time. |
 | `invalid_include_value` | `includeValue` isn't a boolean, or the subject isn't `kv:`. |
 | `subject_does_not_exist` | The subject doesn't exist, or this account can't read it. |
diff --git a/src/docs/src/Objects/app.md b/src/docs/src/Objects/app.md
index d3bfe2cf7..aed409c06 100755
--- a/src/docs/src/Objects/app.md
+++ b/src/docs/src/Objects/app.md
@@ -78,7 +78,7 @@ __Parameters__
 
 __Return value__
 
-Iterable objects each containing `{username, user_uuid}`, plus an optional `user_email`.
+Iterable objects each containing `{user, 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.request('email')`](/Perms/request/)); it is omitted otherwise, and may be `null` if the user granted access but has no email on file.
 
@@ -117,7 +117,7 @@ __Parameters__
 
 __Return value__
 
-An array of objects each containing `{username, user_uuid}`.
+An array of objects each containing `{user, user_uuid}`.
 
 __Example__
 
diff --git a/src/docs/src/rate-limits-and-quotas.md b/src/docs/src/rate-limits-and-quotas.md
index 681b38b64..e2ff3c275 100644
--- a/src/docs/src/rate-limits-and-quotas.md
+++ b/src/docs/src/rate-limits-and-quotas.md
@@ -541,7 +541,7 @@ When the holder's balance runs out, deliveries stop and persistent subscriptions
 
 ### Networking
 
-[`puter.net`](/Networking/) sockets connect through a relay that takes a single-use token. A page fetches one token when it opens its first socket and reuses the connection for later sockets; `puter.net.generateWispV1URL()` fetches a new one on every call.
+[`puter.net`](/Networking/) sockets connect through a relay that takes a token. Each token is valid for 24 hours, or until the session that created it ends. A page fetches one token when it opens its first socket and reuses the connection for later sockets; `puter.net.generateWispV1URL()` fetches a new one on every call.
 
 | Limit                     | Paid | Free | Anonymous |
 | ------------------------- | ---- | ---- | --------- |
diff --git a/src/puter-js/src/index.js b/src/puter-js/src/index.js
index 5804f6fa6..cb32cb42b 100644
--- a/src/puter-js/src/index.js
+++ b/src/puter-js/src/index.js
@@ -801,7 +801,7 @@ export class Puter {
         /** @type {import('./modules/networking/types.js').Networking} */
         this.net = {
             /**
-             * Mints a relay URL (server + single-use token) for speaking
+             * Mints a relay URL (server + 24-hour token) for speaking
              * the Wisp v1 protocol directly, which is what the sockets
              * below do for you.
              *
diff --git a/src/puter-js/src/modules/FileSystem/types.js b/src/puter-js/src/modules/FileSystem/types.js
index fc025fe19..ca95f292f 100644
--- a/src/puter-js/src/modules/FileSystem/types.js
+++ b/src/puter-js/src/modules/FileSystem/types.js
@@ -126,7 +126,7 @@
  * @property {boolean} [recursive] Whether to also list the contents of subdirectories. Defaults to
  * `false`.
  * @property {number} [depth] How many levels to descend when `recursive` is `true`. Defaults to
- * unlimited.
+ * `10`, which is also the maximum; larger values are clamped to `10`.
  */
 
 /**
diff --git a/src/puter-js/src/modules/apps/checkName.js b/src/puter-js/src/modules/apps/checkName.js
index 753002e5e..ea2ba4f5a 100644
--- a/src/puter-js/src/modules/apps/checkName.js
+++ b/src/puter-js/src/modules/apps/checkName.js
@@ -4,7 +4,7 @@ import { invalidRequest } from './lib/validate.js';
 /** @typedef {import('./types.js').CheckAppNameResult} CheckAppNameResult */
 
 /**
- * Checks whether an app name is available to the user.
+ * Checks whether an app name is free, meaning no app on any account uses it.
  *
  * @this {import('./index.js').AppsModule}
  * @param {string} name
diff --git a/src/puter-js/src/modules/apps/create.js b/src/puter-js/src/modules/apps/create.js
index 301c58dbe..66b9f00da 100644
--- a/src/puter-js/src/modules/apps/create.js
+++ b/src/puter-js/src/modules/apps/create.js
@@ -19,8 +19,8 @@ import { invalidRequest } from './lib/validate.js';
  * @returns {Promise<CreateAppResult>}
  */
 /**
- * Creates a Puter app. The name must be unique to the user's apps (rejects
- * otherwise) and `indexURL` must start with `http://` or `https://`. Accepts
+ * Creates a Puter app. The name must not be used by any app on any account
+ * (rejects otherwise) and `indexURL` must start with `http://` or `https://`. Accepts
  * either positional `create(name, indexURL, title?)` or an options object.
  *
  * @this {import('./index.js').AppsModule}
diff --git a/src/puter-js/src/modules/apps/types.js b/src/puter-js/src/modules/apps/types.js
index 143f4c66d..a1fb66265 100644
--- a/src/puter-js/src/modules/apps/types.js
+++ b/src/puter-js/src/modules/apps/types.js
@@ -4,7 +4,7 @@
  * A user of an app, as returned by `App.users()` and `App.getUsers()`.
  *
  * @typedef {Object} AppUser
- * @property {string} username The user's username.
+ * @property {string} user The user's username.
  * @property {string} user_uuid The user's unique identifier.
  * @property {string | null} [user_email] The user's email address. Only present when the user granted
  * this app the `user:<uuid>:email:read` permission (e.g. via `puter.perms.requestEmail()`); omitted
@@ -78,8 +78,8 @@
  * Options for creating an app with `Apps.create()`.
  *
  * @typedef {Object} CreateAppOptions
- * @property {string} name The name of the app to create. Must be unique to the user's apps; if an app
- * with this name already exists the promise is rejected.
+ * @property {string} name The name of the app to create. App names are unique across all accounts; if
+ * any app already has this name the promise is rejected.
  * @property {string} indexURL The URL of the app's index page, displayed when the app is started. Must
  * start with `http://` or `https://`; other protocols are not allowed.
  * @property {string} [title] The human-readable title of the app. Defaults to `name` if not provided.
@@ -101,8 +101,8 @@
  * Attributes to update with `Apps.update()`.
  *
  * @typedef {Object} UpdateAppAttributes
- * @property {string} [name] The new name of the app. Must be unique to the user's apps; if an app with
- * this name already exists the promise is rejected.
+ * @property {string} [name] The new name of the app. App names are unique across all accounts; if any
+ * app already has this name the promise is rejected.
  * @property {string} [indexURL] The new URL of the app's index page. Must be accessible to the user.
  * @property {string} [title] The new title of the app.
  * @property {string} [description] The new description of the app aimed at the end user.
diff --git a/src/puter-js/src/modules/events/types.js b/src/puter-js/src/modules/events/types.js
index 50cc71db2..55692d985 100644
--- a/src/puter-js/src/modules/events/types.js
+++ b/src/puter-js/src/modules/events/types.js
@@ -195,8 +195,9 @@
  *   delivers to everything listening; `single` delivers to exactly one
  *   consumer, which must acknowledge, and requires a `handlerName`.
  * @property {Array<'socket' | 'worker' | 'push'>} [targets] Transports the
- *   deliveries may take. Defaults to `['socket', 'worker']`. A `single`
- *   subscription may not target `push`.
+ *   deliveries may take. Defaults to `['socket', 'worker']` when an app
+ *   subscribes and `['socket']` when an account session with no app does. A
+ *   `single` subscription may not target `push`.
  * @property {string} [handlerName] The published handler this subscription
  *   binds to. Required for `single`.
  * @property {Function | string | { file: string }} [handler] The handler
diff --git a/src/puter-js/src/modules/hosting/create.js b/src/puter-js/src/modules/hosting/create.js
index 126ae965a..830ffb718 100644
--- a/src/puter-js/src/modules/hosting/create.js
+++ b/src/puter-js/src/modules/hosting/create.js
@@ -19,9 +19,11 @@ import { normalizeSubdomain } from './lib/args.js';
  * Creates a new subdomain served from the given directory. Rejects if a
  * subdomain with that name already exists or the path does not exist.
  *
- * Accepts `create(subdomain)`, `create(subdomain, dirPath)`, or the object
- * form `create({ subdomain, root_dir })`. A full host (`sub.puter.site`) is
- * accepted in place of a bare subdomain and stripped to its label.
+ * Accepts `create(subdomain, dirPath)` or the object form
+ * `create({ subdomain, root_dir })`; both need the directory. A full
+ * `sub.puter.site` or `sub.puter.com` host is accepted in place of a bare
+ * subdomain and stripped to its label, when the label is only lowercase
+ * letters and digits.
  *
  * @this {import('./index.js').HostingModule}
  * @param {string | { subdomain: string, root_dir?: string }} subdomainOrObject
diff --git a/src/puter-js/src/modules/networking/PSocket.js b/src/puter-js/src/modules/networking/PSocket.js
index d33eb8d6b..68e3c067e 100644
--- a/src/puter-js/src/modules/networking/PSocket.js
+++ b/src/puter-js/src/modules/networking/PSocket.js
@@ -21,7 +21,6 @@ export let wispInfo = {
  * @property {Error} error Fires when the socket hits an error; a `close` follows shortly after. The
  * human-readable reason is on `error.message`.
  * @property {boolean} close Fires when the socket is closed. `true` if it closed due to an error.
- * @property {void} drain Fires when the write buffer has been flushed.
  * @property {Uint8Array} tlsdata The `PTLSSocket` spelling of `data`.
  * @property {void} tlsopen The `PTLSSocket` spelling of `open`.
  * @property {boolean} tlsclose The `PTLSSocket` spelling of `close`.
diff --git a/src/puter-js/src/modules/networking/types.js b/src/puter-js/src/modules/networking/types.js
index 34a6a67c0..d2568bec4 100644
--- a/src/puter-js/src/modules/networking/types.js
+++ b/src/puter-js/src/modules/networking/types.js
@@ -9,7 +9,6 @@
  *     | 'data'
  *     | 'error'
  *     | 'close'
- *     | 'drain'
  *     | 'tlsdata'
  *     | 'tlsopen'
  *     | 'tlsclose'} SocketEvent
@@ -21,8 +20,8 @@
  * restrictions.
  *
  * @typedef {Object} Networking
- * @property {() => Promise<string>} generateWispV1URL Mints a relay URL (server plus single-use
- * token) for speaking the Wisp v1 protocol directly.
+ * @property {() => Promise<string>} generateWispV1URL Mints a relay URL (server plus a token valid
+ * for 24 hours) for speaking the Wisp v1 protocol directly.
  * @property {typeof import('./PSocket.js').PSocket} Socket Constructor for a raw TCP `Socket`.
  * @property {{ TLSSocket: typeof import('./PTLS.js').PTLSSocket }} tls Constructor for a
  * TLS-protected `TLSSocket`.