@iglo.tech/iglo.base 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+## 1.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 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.

package/LICENSE

@@ -0,0 +1,18 @@
+The MIT License (MIT)
+Copyright (c) 2022 - present, Gani Georgiev
+Copyright (c) 2026 - present, iglo.base contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.