Fix puter.js docs and types drift 10 aug

[reynaldichernando]

closes #3485

summary:

AI

• chat
  • ChatMessage.images types should not be forced
  • chat chunk image missing in types and obj docs
  • chat.md error chunk missing in types and obj docs
• listModelProviders
  • Add to AI.md (similar to other functions)
• txt2img
  • missing replicate provider options types (need to check replicate actual docs for types)
  • input_image_mime_type missing in docs (need to figure out which provider uses this)

Apps

• create
  • title docs should not be required
  • indexurl if not present should say throw an error

Auth

• signIn
  • request_auth missing from types and docs (although idk what this is for)
• getMonthlyUsage
  • add to Auth.md (similar to other functions)
• getDetailedAppUsage
  • add to Auth.md (similar to other functions)

Cloud Storage

• write
  • data shouldn’t be required, it just writes empty file (update docs and types)
• readdir
  • recursive missing from types and docs
  • depth missing from types and docs
• move
  • newName missing from docs
• stat
  • returnWorkers missing from types and docs
• getReadURL
  • add to FS.md (similar to other functions)
• upload
  • missing callbacks from docs

Key-Value Store

• decr
  • 64 bit limit missing from docs (same with incr)
• list
  • fix type string[] when any option is set, to KVListPage

Peer

• serve
  • PuterPeerServer needs its own object page and should be linked instead of inline in serve.md
• connect
  • PuterPeerConnection needs its own object page and should be linked instead of inline in connect.md

UI

• contextMenu
  • missing theme option in docs
  • missing x option in docs
  • missing y option in docs
  • add to UI.md (similar to other functions)
• exit
  • UI.md should say puter.exit
• setMenubar
  • missing theme option in docs
• hideWindow
  • add to UI.md (similar to other functions)
• showWindow
  • add to UI.md (similar to other functions)

Perms

• Perms.md
  • add websites in platform

Utilities

• env
  • missing nodejs, web-worker, service-worker
• print
  • missing options syntax in docs
  • missing escapeHTML option

Objects

• App
  • App.users need optional user_email

[reynaldichernando]

some stuff are intentionally left as is because it will just confuse devs + our checker incorrectly tagged something

and some other stuff will need to be in its own PR/issue (new features)

[Copilot]

Pull request overview

This PR reduces drift between the puter.js SDK runtime, its TypeScript declarations, and the public documentation by updating types and docs across several API families (AI, FS, KV, UI, Auth, Peer, Utils, Objects).

Changes:

• Updates puter.js TypeScript module declarations to match current runtime behavior (UI, KV pagination, FS options, Auth, AI).
• Refreshes and expands documentation pages for multiple APIs (UI, FS, Auth, AI, Utils, KV) to reflect supported options/behaviors.
• Adds dedicated Object docs for Peer connection/server types and wires them into the docs sidebar and Objects index.

Reviewed changes

Copilot reviewed 26 out of 31 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/puter-js/types/modules/ui.d.ts	Adds x/y positioning options to ContextMenuOptions.
src/puter-js/types/modules/kv.d.ts	Adjusts typing for the paginated kv.list() return mode switch.
src/puter-js/types/modules/filesystem.d.ts	Adds readdir recursion/depth options; documents stat.returnWorkers; makes write data optional.
src/puter-js/types/modules/auth.d.ts	Adds request_auth option to auth.signIn().
src/puter-js/types/modules/ai.d.ts	Makes ChatMessage.images optional; adds streamed chunk image/error fields; adds Replicate txt2img option types.
src/docs/src/Utils/print.md	Documents puter.print(text, options) and escapeHTML.
src/docs/src/Utils/env.md	Documents additional puter.env values (nodejs, web-worker, service-worker).
src/docs/src/UI/setMenubar.md	Documents the theme option for setMenubar.
src/docs/src/UI/contextMenu.md	Documents theme, x, y (standalone-only behavior explained).
src/docs/src/UI.md	Updates UI index links (adds showWindow/hideWindow, fixes puter.exit() link, adds contextMenu).
src/docs/src/sidebar.js	Adds sidebar entries for PuterPeerConnection and PuterPeerServer objects.
src/docs/src/Perms.md	Expands platforms to include websites.
src/docs/src/Peer/serve.md	Links return type to the new PuterPeerServer object doc and shortens inline description.
src/docs/src/Peer/connect.md	Links return type to the new PuterPeerConnection object doc and shortens inline description.
src/docs/src/Objects/puterpeerserver.md	New object documentation page for PuterPeerServer.
src/docs/src/Objects/puterpeerconnection.md	New object documentation page for PuterPeerConnection.
src/docs/src/Objects/chatresponsechunk.md	Documents image and error streaming chunk shapes.
src/docs/src/Objects/app.md	Notes optional user_email in App.users results and when it appears.
src/docs/src/Objects.md	Adds peer object links to the Objects index.
src/docs/src/KV/decr.md	Adds the 64-bit integer limit note to decr() docs.
src/docs/src/FS/write.md	Documents data as optional and expands supported data types.
src/docs/src/FS/upload.md	Documents upload progress callbacks with an example.
src/docs/src/FS/stat.md	Documents returnWorkers option.
src/docs/src/FS/readdir.md	Documents recursive and depth options.
src/docs/src/FS/move.md	Documents newName option.
src/docs/src/FS.md	Adds getReadURL() to the FS API index.
src/docs/src/Auth/signIn.md	Documents request_auth option.
src/docs/src/Auth.md	Adds getMonthlyUsage() and getDetailedAppUsage() to the Auth index.
src/docs/src/Apps/create.md	Clarifies indexURL failure behavior and makes title optional in docs.
src/docs/src/AI/txt2img.md	Documents input_image_mime_type and clarifies raw-base64 behavior.
src/docs/src/AI.md	Adds listModelProviders() to the AI index.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.