mirror of
https://github.com/HeyPuter/puter.git
synced 2026-11-06 14:07:51 +00:00
Juan Fernando Castro
93798cba93
* fix(puter-js): background push syncs never prompt for sign-in The load-time sync and the resync after the browser replaces a subscription ask for the key and announce the subscription without opening Puter's sign-in; only enable() may. The confirmation and the removal never open it, and looking up the user for the opt-in uses a non-interactive /whoami. A rejected token during a background sync is not reported as a sync failure. * fix(puter-js): turning push off in one tab stops other tabs' syncs Tabs of a site take a shared Web Lock to subscribe and announce, and again to confirm, without holding it while the confirmation push is on its way. A load sync re-reads the opt-in inside the lock and stops when it is gone. disable() tells the other tabs first, so their syncs and any enable() in flight stop, then forgets the opt-ins and removes the subscription inside the same lock. Without Web Locks the re-reads and the message still apply. * fix(puter-js): wait for a push confirmation only once the lock is held A sync queued behind another tab's lock started its 30 second confirmation timer and listener before it got the lock, so a long wait failed the sync or left the timeout unhandled. The listener now starts inside the locked step, right before the subscription is announced. * test(puter-js): reach the push sync in the boot sign-in e2e The push page now has the user's opt-in and cached user from an earlier load, starts its sync before boot's own requests come back, and gets a rejected token from the push routes, so the spec covers the key request that must not open a sign-in. * fix(puter-js): sign-out and disable() remove only Puter's push subscription Removal now looks at the subscription's application server key and ends it only when it is Puter's: the key stored at the last subscribe, or the server's key when none is stored. Any other subscription on the site is left as it is and the server is not told about it. Without a named worker, as at sign-out or disable() without serviceWorker, every registration on the origin is checked, so a subscription under a folder worker is the one removed. * fix(puter-js): sign-out and a user change end this browser's pushes Sign-out stops this tab's syncs, tells the site's other tabs, and inside the push lock forgets every opt-in and tap, ends Puter's subscription in the browser, then sends the removal with the leaving user's token as a keepalive request so it is still sent if the page reloads. puter.auth.signOut() returns a promise that resolves once that is done; the token is still discarded at once. A different user signing in over a session, or after the token was dropped, gets the same cleanup with the token of the user signed in before. A new token for the same user, or a dropped token, keeps everything. A page load finding a Puter subscription with no opt-in for the signed-in user, or with nobody signed in, ends it in the browser. Opt-in records that can't be read leave it as it is. * fix(puter-js): record a push opt-in before other tabs can check it enable() now writes the user's opt-in inside the push lock, right after the server has the subscription and before the lock is released. A tab loading at the same time waits for the lock, reads the opt-in, and keeps the new subscription. A failed announce, or push turned off while it ran, records nothing. * fix(puter-js): push cleanup runs without the lock where Web Locks refuse In a frame where navigator.locks.request rejects, such as a sandboxed frame, sign-out, disable(), the load-time check and syncs now run their step without the lock instead of rejecting, so signOut() still resolves and the subscription is still ended. * fix(puter-js): send the sign-out removal again when keepalive is refused A keepalive request that needs a CORS preflight is refused by some browsers. The removal at sign-out is then sent once more as a normal request with the same token and without a sign-in prompt, after the browser has already ended the subscription. * test(puter-js): run the push boot test on full Chromium and skip it without push support The headless shell keeps Notification.permission at 'denied' after the permission is granted, so onPush() never synced there and the test saw no key request. The test now launches full Chromium itself, since a channel can't be set per test, and is skipped on WebKit and wherever the page has no PushManager or notification permission. * fix(puter-js): a user change finishes its push cleanup before enable() enable() waits for the cleanup a user change started. When the token was dropped and a different user signs in from enable(), the pushes of the user signed in before end first, and the new user keeps their new opt-in and subscription. A token that sign-out already cleaned up is not cleaned up again when the next user signs in. * fix(puter-js): a tap without a URL opens the site the push came from A page that calls onPush() or enable() saves where taps resolve for its worker: the worker's folder when the page is inside it, else the site's root. push-sw.js and the notifications a page shows itself read relative URLs from it, and fall back to the worker's scope when nothing is saved. * fix(puter-js): push taps go to top-level windows only push-sw.js routes taps, and holds back a page's notification for a focused window, among top-level windows only, as the GUI's worker does. Challenges and subscription changes still reach every window of the origin. * fix(puter-js): deliver a push tap to the page once push-sw.js keeps a tap before posting it to an open page. The page runs its click handler only after taking that copy out of IndexedDB in one readwrite transaction, and acknowledges only then. When no acknowledgement comes in time, the worker takes the copy itself and opens the tap's URL only if the page hadn't. The wait starts at the post and ends at most 800 ms after the click, so openWindow still runs in time. Pages and workers without this keep today's behaviour. * fix(puter-js): clear stored push taps that nobody reads push-sw.js removes taps kept over five minutes on every push and tap, and a page sweeps them once when onPush() syncs. A page opened for a tap ignores a kept tap older than that, and removes it when no click handler is added within 10 seconds of loading. * fix(puter-js): a late page already at the tap's URL still gets the tap When no acknowledgement comes in time and the window is already at the tap's URL, push-sw.js leaves the copy it kept for that page instead of taking it back, so the page's click handler still runs when it answers late. A copy nobody takes is removed with the other old taps. * fix(puter-js): a push tap runs at most once when IndexedDB fails A page that can't take a kept tap out of IndexedDB leaves it to the worker instead of running it, and a worker whose claim fails leaves it to the page instead of opening the tap's URL. * fix(puter-js): take a tap back and keep it for the next page in one step When no acknowledgement comes in time, push-sw.js takes its copy back and keeps it, without the id, for the page it opens in one readwrite transaction, leaving more of Firefox's window-opening allowance for openWindow. * test(puter-js): shorten the fake IndexedDB comment * test(puter-js): keep the push boot test comment to one line * fix(puter-js): a user signing back in with the same token gets the user-change cleanup again The token that sign-out already cleaned up is skipped only for the next user change. Once the same token is set again, a later sign-in by a different user ends its pushes as usual. * fix(static): push-sw.js refreshes at the CDN within five minutes * feat(puter-js): the push worker can skip saved handlers * fix(puter-js): off() keeps a saved push handler another tab still uses * docs(notifications): self-hosting the push worker * docs(notifications): name the pinned push worker version as a placeholder * fix(puter-js): pages with push handlers can enter the back/forward cache * test(puter-js): a restored page saves its push handler again * docs(notifications): pin the push worker only with a pinned puter.js
Puter.js
Learn More · Docs · Tutorials · Examples · X
Puter.js gives you auth, cloud storage, database, AI, and more through a single JavaScript library. It is the go-to backend for AI-generated apps.
There is nothing to configure, no API keys, no infrastructure to set up, whether you write the code yourself or have your AI tool do it. Tools like Claude Code, Codex, OpenCode, Lovable, and Replit can generate complete, production-ready apps in a single shot with fewer AI tokens.
Installation
NPM:
npm install @heyputer/puter.js
CDN:
Include Puter.js directly in your HTML via CDN in the <head> section:
<script src="https://js.puter.com/v2/"></script>
Usage
Browser
ES Modules
import {puter} from '@heyputer/puter.js';
// or
import puter from '@heyputer/puter.js';
// or
import '@heyputer/puter.js'; // puter will be available globally
CommonJS
const {puter} = require('@heyputer/puter.js');
// or
const puter = require('@heyputer/puter.js');
// or
require('@heyputer/puter.js'); // puter will be available globally
Node.js (with Auth Token)
const {init} = require("@heyputer/puter.js/src/init.cjs"); // NODE JS ONLY
// or
import {init} from "@heyputer/puter.js/src/init.cjs";
const puter = init(process.env.puterAuthToken); // uses your auth token
const puter2 = init(process.env.puterAuthToken2); // use some other auth token
Node.js (with Auth Token + Web Login)
const {init, getAuthToken} = require("@heyputer/puter.js/src/init.cjs");
// or
import {init, getAuthToken} from "@heyputer/puter.js/src/init.cjs";
const authToken = await getAuthToken(); // performs browser based auth and retrieves token (requires browser)
const puter = init(authToken); // uses your auth token
Usage Example
After importing, you can use the global puter object:
// Print a message
puter.print('Hello from Puter.js!');
// Chat with GPT-5 nano
puter.ai.chat('What color was Napoleon\'s white horse?').then(response => {
puter.print(response);
});
Starter Templates
You can also use one of the following templates:
- Client-side projects: Angular, React, Next.js, Vue.js, Vanilla.js
- Node.js + Express: Node.js + Express template
Setting Custom Origins
By default puter.js uses the official Puter API and GUI origins. You can customize these origins by setting global variables before importing the SDK like so:
// For API origin
globalThis.PUTER_API_ORIGIN = 'https://custom-api.puter.com';
// For GUI origin
globalThis.PUTER_ORIGIN = 'https://custom-gui.puter.com';
import {puter} from '@heyputer/puter.js'; // or however you import it for your env
Documentation & Community
License
Apache-2.0