Repository navigation
sdk-v1.0.0
First release, published as @iglo.tech/iglo.base (npm organization iglo.tech, public access). Every import path keeps its subpath under this name, for example @iglo.tech/iglo.base/ssr/browser.
-
Forked from the PocketBase JavaScript SDK v0.28.1 (
ff30f71041aeb8107001bb1ac82ad56a4fbeb93c). ESM-only package (import PocketBase from "@iglo.tech/iglo.base"). -
Strict TypeScript sources without
any(except deliberately loose public shapes), type tests, tests ported tobun test. -
fixed: loadFromCookie crash on a null cookie value, an upstream bug
-
difference from upstream: a non-string token from a cookie (
loadFromCookie) or fromAsyncAuthStore's initial value becomes""instead of preserving the non-string value. -
difference from upstream: a non-object
@jsonPayloadinconvertFormDataToObjectis skipped instead of spreading primitive characters viaObject.assign. -
SSR server core (
@iglo.tech/iglo.base/ssr):createServerClientper request, resumed from the session cookie, with requests sentcache: "no-store"at the fetch layer;createSuperuserClientwithimpersonate;createSessionCache({ ttl, maxEntries, clock })(LRU, SHA-256 token keys,ttlin milliseconds); token lifetimes learned from auth responses, sliding refresh at half the lifetime; single-flight refresh that applies each outcome per request;pb.auth.verify(); server sign-in and sign-out write the session cookie; app-origin cookie security (__Host-andSecurefollow the app's own request, not the backend URL);createRequestCookieAdapterfor WebRequest/Responsehandlers. Thessrentry shares the SDK's classes with@iglo.tech/iglo.base, soinstanceof ClientResponseErroragrees across both. -
SSR OAuth2 and CSRF (
@iglo.tech/iglo.base/ssr):pb.startOAuth2(provider, { callbackUrl, redirectTo?, collection? })andpb.completeOAuth2(request)for the redirect flow, with a 10-minute temporary cookie bound to the state and a typed result (OAuth2Erroror the server'sClientResponseError); on https only the__Host-cookie names are read, and providers that return by POST (Sign in with Apple) are refused withunsupported-provider(use the popup flow for them);redirectToaccepts same-origin paths only;handlePopupHandOff(request, options)completes a popup sign-in from a same-origin POST, checked with oneauth-refresh;checkCsrf(request, { allowedOrigins? })andcheckOriginreject cross-site state-changing requests that carry the session cookie; an invalidallowedOriginsentry throws on every call. -
SSR browser client and realtime (
@iglo.tech/iglo.base/ssr,@iglo.tech/iglo.base/ssr/browser):mintBrowserToken(serverClient, superuser?, { duration? })mints the page's short token (15 minutes by default, fromimpersonate), the server client's record and iglo.base's clock (serverTime) at render, ornullwhen nobody is signed in;handleBrowserTokenRenew(request, options)is the adapter route that renews it (POSTonly, Origin-checked, session checked with iglo.base, no-cache headers);createServerClient({ readableCookie: true })is the fallback without superuser credentials, which writes the session cookie withoutHttpOnly.createBrowserClient({ url, token?, record?, serverTime?, renewUrl?, handOffUrl?, ... })returns aClientthat renews its token before it expires, measured on the server's clock, shares one renewal between parallel callers, signs out on a 401, keeps the token and retries (at most ten times in a row) on a network error or 5xx, and keeps realtime subscriptions authorized: a renewal for the same user resubmits them (RealtimeService.resubmit()), a sign-out or a change of user opens a new connection for them (RealtimeService.reconnect(), which upstream requires for any change other than the same record; it retries like a dropped connection and does not callonDisconnect). Timers are capped belowsetTimeout's maximum, and successful renewals are at least 30 seconds apart.handOff()clears the popup token on any failure.pb.dispose()stops its timers. The browser entry is browser-safe and shares the SDK's classes with the main entry. -
difference from upstream (realtime): when a connection is closed or replaced while its first subscription request is in flight, the continuation of the old connection no longer resolves the pending connects or cancels the next reconnect. Upstream's SDK, when a connection drops during that request, cancels its own retry and stops reconnecting until the app subscribes again; the SDK keeps retrying with the usual backoff.
-
SSR framework adapters (
@iglo.tech/iglo.base/ssr/next,@iglo.tech/iglo.base/ssr/sveltekit,@iglo.tech/iglo.base/ssr/nuxt,@iglo.tech/iglo.base/ssr/astro,@iglo.tech/iglo.base/ssr/react-router): zero-dependency, server-only subpaths that resume the session per request, write cookies back, run the CSRF check (opt out withcsrf: false), answer the renew, popup and OAuth2 routes at configurable paths, and expose the page's server client andmintBrowserToken. Every response of a request that carries user data (a session cookie, a cookie write, a minted browser token) gets the no-cache headers, including a cookie the handler writes after the adapter's check. The React Router adapter'ssession(request)returns aheaders()function to call when the route builds its response. The Next.js adapter runs on the Node.js runtime only (proxy.tson Next.js 16). The adapters take the session cache and superuser client from the app, and fail at creation without either superuser credentials orreadableCookie. Example apps inexamples/nextjsandexamples/sveltekitrun end to end (bun run test:examples), including the OAuth2 sign-in from their login pages.