palbase 0.5.2 → 0.6.2

package/types/web/src/ssr.d.ts

@@ -0,0 +1,86 @@
+import type { User } from './auth.js';
+import { type ClientOptions, type PalbaseClient } from './client.js';
+import type { SessionStore } from './session.js';
+/** A cookie's attributes, as Next.js's cookies().set and the cookie package name them. */
+export interface CookieOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    expires?: Date;
+    sameSite?: 'lax' | 'strict' | 'none';
+    secure?: boolean;
+    httpOnly?: boolean;
+}
+/**
+ * The request's cookies, and — where the server can write the response's — a
+ * way to write them. An answer that writes a session's cookies is one user's:
+ * setAll is given the headers that keep any cache between the server and the
+ * browser from keeping it and handing it to someone else — set them on the
+ * response with the cookies.
+ */
+export interface CookieMethods {
+    getAll(): {
+        name: string;
+        value: string;
+    }[] | Promise<{
+        name: string;
+        value: string;
+    }[]>;
+    setAll?(cookies: {
+        name: string;
+        value: string;
+        options: CookieOptions;
+    }[], headers: Record<string, string>): void | Promise<void>;
+}
+/** What an answer that writes a session's cookies is sent with: kept by no cache. */
+export declare const NO_STORE_HEADERS: Readonly<Record<string, string>>;
+/**
+ * What the session's cookies are written with unless the app says: the whole
+ * site; sent when a link from elsewhere opens it (a sign-in link); over https
+ * alone (a page served on http — a developer's computer — says secure: false,
+ * and the browser's client says it of a page on http itself); kept as long as
+ * a browser keeps a cookie (400 days — the session itself ends when its
+ * refresh token does); readable by the page, as the browser client reads it.
+ */
+export declare const SESSION_COOKIE_OPTIONS: CookieOptions;
+/** The session's cookie for the project the publishable key is of: pb-<ref>-session (with .0, .1, … when it is long). */
+export declare function sessionCookieName(publishableKey: string): string;
+/**
+ * The session in cookies named `name` (one, or numbered parts): read from
+ * getAll on every load, written with setAll — or not at all where there is
+ * none to write with.
+ */
+export declare function cookieSessionStore(name: string, cookies: CookieMethods, options?: CookieOptions, shared?: boolean): SessionStore;
+type SsrOptions = Omit<ClientOptions, 'storage'> & {
+    cookieOptions?: CookieOptions;
+};
+/**
+ * A server's client for one request, its session in the request's cookies:
+ * it renews the session before a call that finds it about to lapse when it
+ * can write the response's cookies (setAll), and never when it cannot.
+ */
+export declare function createServerClient(opts: SsrOptions & {
+    cookies: CookieMethods;
+}): PalbaseClient;
+/** The page's cookies (document.cookie). */
+export declare function documentCookies(): CookieMethods;
+/**
+ * The browser's client, its session in the page's cookies — where the
+ * server's pages read it. Renewed behind the call, as any browser client's,
+ * one tab at a time.
+ */
+export declare function createBrowserClient(opts: SsrOptions): PalbaseClient;
+/**
+ * Who is signed in, as auth says — a server's middleware calls it on the way
+ * in, with a client that writes the response's cookies: the session is
+ * renewed first when it has little left (a renewal that could not be made
+ * keeps it while its token works), then auth is asked whose its token is.
+ * Null when no one is signed in, the session is over, or auth does not take
+ * the token: a cookie the browser could have written is never taken at its
+ * word. Asking writes nothing back: only a renewal writes the session, so an
+ * answer never puts back the session its request carried over one the
+ * browser renewed meanwhile (whose old refresh token, used again later, would
+ * end the session).
+ */
+export declare function keepSession(pb: PalbaseClient): Promise<User | null>;
+export {};