Skip to content

sdk-v1.0.0

Choose a tag to compare

@github-actions github-actions released this 12 Nov 17:55
73f4c2c

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 to bun test.

  • fixed: loadFromCookie crash on a null cookie value, an upstream bug

  • difference from upstream: a non-string token from a cookie (loadFromCookie) or from AsyncAuthStore's initial value becomes "" instead of preserving the non-string value.

  • difference from upstream: a non-object @jsonPayload in convertFormDataToObject is skipped instead of spreading primitive characters via Object.assign.

  • SSR server core (@iglo.tech/iglo.base/ssr): createServerClient per request, resumed from the session cookie, with requests sent cache: "no-store" at the fetch layer; createSuperuserClient with impersonate; createSessionCache({ ttl, maxEntries, clock }) (LRU, SHA-256 token keys, ttl in 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- and Secure follow the app's own request, not the backend URL); createRequestCookieAdapter for Web Request/Response handlers. The ssr entry shares the SDK's classes with @iglo.tech/iglo.base, so instanceof ClientResponseError agrees across both.

  • SSR OAuth2 and CSRF (@iglo.tech/iglo.base/ssr): pb.startOAuth2(provider, { callbackUrl, redirectTo?, collection? }) and pb.completeOAuth2(request) for the redirect flow, with a 10-minute temporary cookie bound to the state and a typed result (OAuth2Error or the server's ClientResponseError); on https only the __Host- cookie names are read, and providers that return by POST (Sign in with Apple) are refused with unsupported-provider (use the popup flow for them); redirectTo accepts same-origin paths only; handlePopupHandOff(request, options) completes a popup sign-in from a same-origin POST, checked with one auth-refresh; checkCsrf(request, { allowedOrigins? }) and checkOrigin reject cross-site state-changing requests that carry the session cookie; an invalid allowedOrigins entry 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, from impersonate), the server client's record and iglo.base's clock (serverTime) at render, or null when nobody is signed in; handleBrowserTokenRenew(request, options) is the adapter route that renews it (POST only, Origin-checked, session checked with iglo.base, no-cache headers); createServerClient({ readableCookie: true }) is the fallback without superuser credentials, which writes the session cookie without HttpOnly. createBrowserClient({ url, token?, record?, serverTime?, renewUrl?, handOffUrl?, ... }) returns a Client that 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 call onDisconnect). Timers are capped below setTimeout'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 with csrf: false), answer the renew, popup and OAuth2 routes at configurable paths, and expose the page's server client and mintBrowserToken. 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's session(request) returns a headers() function to call when the route builds its response. The Next.js adapter runs on the Node.js runtime only (proxy.ts on Next.js 16). The adapters take the session cache and superuser client from the app, and fail at creation without either superuser credentials or readableCookie. Example apps in examples/nextjs and examples/sveltekit run end to end (bun run test:examples), including the OAuth2 sign-in from their login pages.