@palbase/web 1.0.0

package/dist/next/index.d.cts

@@ -0,0 +1,238 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { P as PB } from '../pb-Cudze7Kb.cjs';
+import '../analytics-facade-t6UrFdn7.cjs';
+import '@palbase/core';
+import '@palbase/auth';
+import '../storage-BPaeSG8K.cjs';
+import '@palbase/flags';
+
+/**
+ * handleAuthCallback — the OAuth completion route handler factory.
+ *
+ * The app's redirect_uri (registered when calling signInWithOAuth with
+ * `redirectTo: '<app>/auth/callback?provider=google&next=/dash'`) lands
+ * here with `?code&state` from the provider. The handler exchanges them
+ * SERVER-SIDE against palauth (PKCE verifier + state live server-side; the
+ * browser never holds them), writes the session cookies onto a redirect
+ * response, and sends the user on.
+ *
+ * ```ts
+ * // app/auth/callback/route.ts
+ * import { handleAuthCallback } from '@palbase/web/next';
+ * export const GET = handleAuthCallback({ defaultNext: '/' });
+ * ```
+ *
+ * MODULE-GRAPH RULE (same as ./index.ts): 'next/server' only lazily; the
+ * type-only NextRequest import erases at build time.
+ */
+
+interface HandleAuthCallbackOptions {
+    /** Where to land when the callback carries no (valid) `next` param — and on every error/MFA redirect. Default '/'. */
+    defaultNext?: string;
+}
+/**
+ * Build the callback route handler. Outcomes (all 307 redirects, all with
+ * `Cache-Control: private, no-store` — auth outcomes must never cache):
+ * - provider `error` param → `?auth_error=<error>` (+ `auth_error_description`)
+ * - missing code/state/provider → `?auth_error=invalid_callback`
+ * - exchanged AuthResult → session cookies on the redirect to `next ?? defaultNext ?? '/'`
+ * - MFA union → `?mfa_token=…&mfa_factors=a,b` on defaultNext, NO cookies
+ * - exchange failure → `?auth_error=<wire code | oauth_exchange_failed>`
+ */
+declare function handleAuthCallback(opts?: HandleAuthCallbackOptions): (request: NextRequest) => Promise<Response>;
+
+/**
+ * `pb_<endpointRef>_<scope><random>` → endpointRef ('' if malformed).
+ * Single source of truth — used by runtime storage scoping AND the
+ * palbe/next cookie naming; the two MUST agree or browser and server
+ * would read different cookies.
+ */
+declare function endpointRefFromApiKey(apiKey: string): string;
+
+/**
+ * Session-cookie codec shared by EVERY palbe/next surface (browser storage
+ * adapter, pbServer cookie adapter, middleware, auth callback). Pure
+ * functions — no 'next' imports, no palbe runtime imports — so both sides
+ * provably read and write the SAME bytes.
+ *
+ * Format (P3 design contract):
+ * - name: `palbe-session-<endpointRef>`; overflow chunk names append `.0`,
+ *   `.1`, … (cookie names otherwise avoid dots — tooling friendliness).
+ * - value: `encodeURIComponent(JSON.stringify({ a, r, e }))` with a=access
+ *   token, r=refresh token, e=expiry (ms epoch).
+ * - one cookie when the encoded value fits MAX_COOKIE_VALUE chars, else
+ *   chunks ONLY (the base name must not coexist with chunks — callers clear
+ *   stale names via clearedSessionCookieNames before writing, then honor the
+ *   encode result's `clear` overflow guard after writing).
+ */
+
+interface StoredSession {
+    accessToken: string;
+    refreshToken: string;
+    /** ms epoch */
+    expiresAt: number;
+}
+/**
+ * The P3 cookie contract attributes, shared by every server-side writer
+ * (pbServer adapter, middleware, callback); the browser writer mirrors them
+ * in document.cookie string form (next/client.ts). NOT HttpOnly by design —
+ * the browser SDK must read/write the session (Supabase-paradigm tradeoff);
+ * Max-Age = 30d = the refresh-token TTL.
+ */
+declare const SESSION_COOKIE_ATTRS: {
+    readonly path: "/";
+    readonly sameSite: "lax";
+    readonly secure: true;
+    readonly maxAge: 2592000;
+};
+declare function sessionCookieName(endpointRef: string): string;
+interface SessionCookieWrite {
+    /** Cookies to SET, in order. */
+    set: Array<{
+        name: string;
+        value: string;
+    }>;
+    /**
+     * Names to DELETE alongside the set: the one-past-the-end OVERFLOW GUARD
+     * (base write → `.0`; chunks `.0..n` → `.(n+1)`). Decode stops at the
+     * first missing chunk, so deleting exactly one-past-the-end guarantees a
+     * stale orphan chunk (left behind a gap, where presence-probing cleanup
+     * cannot see it) can never concatenate into the freshly written run.
+     * Writers MUST honor both lists.
+     */
+    clear: string[];
+}
+declare function encodeSessionCookies(endpointRef: string, session: StoredSession): SessionCookieWrite;
+/**
+ * encodeSessionCookies for percent-ENCODING cookie stores. Next's request
+ * and response cookie APIs apply encodeURIComponent to values when
+ * serializing (and decodeURIComponent on read) — handing them the codec's
+ * already-encoded values would DOUBLE-encode the wire bytes and break the
+ * browser-side reader. This variant returns the same cookie run with
+ * DECODED values: `encodeURIComponent(value)` reproduces the
+ * encodeSessionCookies bytes exactly (chunk boundaries never split an
+ * escape), so an encoding store writes byte-identical cookies to a raw
+ * writer like document.cookie.
+ */
+declare function encodeSessionCookiesDecoded(endpointRef: string, session: StoredSession): SessionCookieWrite;
+/**
+ * Read the session back from a cookie getter: the base name wins; otherwise
+ * `.0`, `.1`, … are concatenated until the first missing chunk. Tolerant:
+ * malformed URI escapes / JSON / shape → null (treated as "no session").
+ *
+ * Accepts BOTH value forms. Next's cookie stores percent-DECODE values once
+ * on read, so server-side callers (pbServer adapter, middleware) hand us the
+ * already-decoded JSON; raw readers (document.cookie) hand us the encoded
+ * form. The raw (already-decoded) parse runs FIRST because it is
+ * unambiguous — an encoded value can never raw-parse as JSON
+ * (encodeURIComponent escapes `{` itself, so it starts with `%7B`) — whereas
+ * decode-first would silently corrupt a literal `%XX` run inside a token
+ * (decodeURIComponent('%41') → 'A', no throw) or throw on an invalid escape.
+ */
+declare function decodeSessionCookies(get: (name: string) => string | undefined, endpointRef: string): StoredSession | null;
+/**
+ * Names a writer must delete before/while writing: the base name (when
+ * present) plus every existing `.N` chunk, probed in order until the first
+ * missing one (writes are always a contiguous `.0..n` run, so a gap means
+ * the end of palbe-owned chunks).
+ */
+declare function clearedSessionCookieNames(endpointRef: string, present: (name: string) => boolean): string[];
+
+/**
+ * palbeMiddleware — proactive cookie-session refresh in Next.js middleware.
+ *
+ * REQUIRED — not optional — for session-bearing RSC apps. Server Components
+ * cannot write cookies, so pbServer's reactive refresh cannot PERSIST a
+ * rotated session there: every RSC render would re-refresh from the SAME
+ * cookie refresh token, and once two of those land more than 30s apart
+ * (outside palauth's rotation grace) the reuse detector REVOKES THE WHOLE
+ * TOKEN FAMILY — the user is force-logged-out everywhere. This middleware
+ * refreshes the cookie BEFORE the RSC tree renders, so pbServer hydrates a
+ * still-valid session and never burns the token itself.
+ *
+ * MODULE-GRAPH RULES (same as ./index.ts): 'next/server' is imported only
+ * lazily (the type-only NextRequest/NextResponse imports erase at build
+ * time), and middleware.ts must import the generated palbe.gen.ts itself —
+ * Next bundles middleware as its OWN module graph; the layout.tsx import
+ * does not reach it.
+ *
+ * ```ts
+ * // middleware.ts
+ * import './palbe.gen';
+ * import { palbeMiddleware } from '@palbase/web/next';
+ * import type { NextRequest } from 'next/server';
+ *
+ * export function middleware(request: NextRequest) {
+ *   return palbeMiddleware(request);
+ * }
+ * export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+ * ```
+ */
+
+interface PalbeMiddlewareOptions {
+    /** Refresh when the access token expires within this window. Default 60s. */
+    refreshMarginMs?: number;
+    /**
+     * Pre-built response to decorate (e.g. from chained middleware) instead of
+     * building `NextResponse.next({ request })`. Pass-through cases return it
+     * UNMODIFIED. Caveat: a pre-built response snapshotted the request headers
+     * at ITS creation, so a rotated cookie reaches the browser (Set-Cookie)
+     * but not the downstream RSC render of THIS request — prefer omitting this
+     * and building your response after palbeMiddleware when possible.
+     */
+    response?: NextResponse;
+}
+/**
+ * Keep the session cookie fresh for the request. No session / still-fresh
+ * session → untouched pass-through (no cache-control changes). Stale or
+ * expired → single-flight refresh, then the rotated (or cleared, on a dead
+ * token) cookies are written onto BOTH the request (for the downstream RSC
+ * render via `NextResponse.next({ request })`) and the response (for the
+ * browser), with `Cache-Control: private, no-store` on touched responses.
+ *
+ * Cookie writes go through Next's cookie APIs with the DECODED codec values:
+ * Next percent-encodes on serialization, so the wire bytes come out exactly
+ * as the shared codec's (see encodeSessionCookiesDecoded). NextRequest's
+ * cookie store is NOT a CookieStoreLike (its set is the 2-arg/RequestCookie
+ * form), hence the direct codec calls here instead of the pbServer adapter.
+ */
+declare function palbeMiddleware(request: NextRequest, opts?: PalbeMiddlewareOptions): Promise<NextResponse>;
+
+/**
+ * Structural slice of Next's request cookie store (`await cookies()`); any
+ * object honoring it works — the seam for tests and non-Next servers.
+ * `set`/`delete` are optional because RSC-scope stores are read-only.
+ */
+interface CookieStoreLike {
+    get(name: string): {
+        name: string;
+        value: string;
+    } | undefined;
+    getAll?(): Array<{
+        name: string;
+        value: string;
+    }>;
+    set?(name: string, value: string, options?: Record<string, unknown>): void;
+    delete?(name: string): void;
+}
+/**
+ * Build a per-request `PB` client over the request's cookies. Reads the
+ * session the browser SDK wrote (shared cookie codec), refreshes pre-flight
+ * when expired, and — where the store is writable (Server Actions, Route
+ * Handlers) — persists the rotated session back.
+ *
+ * Each call builds a fresh runtime (a handful of small objects, no I/O) —
+ * cheap enough to call per data access; code paths invoking it many times
+ * within one request MAY memoize per-request (e.g. React's `cache()`), but
+ * don't have to.
+ *
+ * ```ts
+ * const pb = await pbServer();
+ * const todos = await pb.todos.list();
+ * ```
+ */
+declare function pbServer(opts?: {
+    cookies?: CookieStoreLike;
+}): Promise<PB>;
+
+export { type CookieStoreLike, type HandleAuthCallbackOptions, type PalbeMiddlewareOptions, SESSION_COOKIE_ATTRS, type SessionCookieWrite, type StoredSession, clearedSessionCookieNames, decodeSessionCookies, encodeSessionCookies, encodeSessionCookiesDecoded, endpointRefFromApiKey, handleAuthCallback, palbeMiddleware, pbServer, sessionCookieName };

package/dist/next/index.d.ts

@@ -0,0 +1,238 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { P as PB } from '../pb-BmgkAe97.js';
+import '../analytics-facade-DkOwkEpi.js';
+import '@palbase/core';
+import '@palbase/auth';
+import '../storage-BPaeSG8K.js';
+import '@palbase/flags';
+
+/**
+ * handleAuthCallback — the OAuth completion route handler factory.
+ *
+ * The app's redirect_uri (registered when calling signInWithOAuth with
+ * `redirectTo: '<app>/auth/callback?provider=google&next=/dash'`) lands
+ * here with `?code&state` from the provider. The handler exchanges them
+ * SERVER-SIDE against palauth (PKCE verifier + state live server-side; the
+ * browser never holds them), writes the session cookies onto a redirect
+ * response, and sends the user on.
+ *
+ * ```ts
+ * // app/auth/callback/route.ts
+ * import { handleAuthCallback } from '@palbase/web/next';
+ * export const GET = handleAuthCallback({ defaultNext: '/' });
+ * ```
+ *
+ * MODULE-GRAPH RULE (same as ./index.ts): 'next/server' only lazily; the
+ * type-only NextRequest import erases at build time.
+ */
+
+interface HandleAuthCallbackOptions {
+    /** Where to land when the callback carries no (valid) `next` param — and on every error/MFA redirect. Default '/'. */
+    defaultNext?: string;
+}
+/**
+ * Build the callback route handler. Outcomes (all 307 redirects, all with
+ * `Cache-Control: private, no-store` — auth outcomes must never cache):
+ * - provider `error` param → `?auth_error=<error>` (+ `auth_error_description`)
+ * - missing code/state/provider → `?auth_error=invalid_callback`
+ * - exchanged AuthResult → session cookies on the redirect to `next ?? defaultNext ?? '/'`
+ * - MFA union → `?mfa_token=…&mfa_factors=a,b` on defaultNext, NO cookies
+ * - exchange failure → `?auth_error=<wire code | oauth_exchange_failed>`
+ */
+declare function handleAuthCallback(opts?: HandleAuthCallbackOptions): (request: NextRequest) => Promise<Response>;
+
+/**
+ * `pb_<endpointRef>_<scope><random>` → endpointRef ('' if malformed).
+ * Single source of truth — used by runtime storage scoping AND the
+ * palbe/next cookie naming; the two MUST agree or browser and server
+ * would read different cookies.
+ */
+declare function endpointRefFromApiKey(apiKey: string): string;
+
+/**
+ * Session-cookie codec shared by EVERY palbe/next surface (browser storage
+ * adapter, pbServer cookie adapter, middleware, auth callback). Pure
+ * functions — no 'next' imports, no palbe runtime imports — so both sides
+ * provably read and write the SAME bytes.
+ *
+ * Format (P3 design contract):
+ * - name: `palbe-session-<endpointRef>`; overflow chunk names append `.0`,
+ *   `.1`, … (cookie names otherwise avoid dots — tooling friendliness).
+ * - value: `encodeURIComponent(JSON.stringify({ a, r, e }))` with a=access
+ *   token, r=refresh token, e=expiry (ms epoch).
+ * - one cookie when the encoded value fits MAX_COOKIE_VALUE chars, else
+ *   chunks ONLY (the base name must not coexist with chunks — callers clear
+ *   stale names via clearedSessionCookieNames before writing, then honor the
+ *   encode result's `clear` overflow guard after writing).
+ */
+
+interface StoredSession {
+    accessToken: string;
+    refreshToken: string;
+    /** ms epoch */
+    expiresAt: number;
+}
+/**
+ * The P3 cookie contract attributes, shared by every server-side writer
+ * (pbServer adapter, middleware, callback); the browser writer mirrors them
+ * in document.cookie string form (next/client.ts). NOT HttpOnly by design —
+ * the browser SDK must read/write the session (Supabase-paradigm tradeoff);
+ * Max-Age = 30d = the refresh-token TTL.
+ */
+declare const SESSION_COOKIE_ATTRS: {
+    readonly path: "/";
+    readonly sameSite: "lax";
+    readonly secure: true;
+    readonly maxAge: 2592000;
+};
+declare function sessionCookieName(endpointRef: string): string;
+interface SessionCookieWrite {
+    /** Cookies to SET, in order. */
+    set: Array<{
+        name: string;
+        value: string;
+    }>;
+    /**
+     * Names to DELETE alongside the set: the one-past-the-end OVERFLOW GUARD
+     * (base write → `.0`; chunks `.0..n` → `.(n+1)`). Decode stops at the
+     * first missing chunk, so deleting exactly one-past-the-end guarantees a
+     * stale orphan chunk (left behind a gap, where presence-probing cleanup
+     * cannot see it) can never concatenate into the freshly written run.
+     * Writers MUST honor both lists.
+     */
+    clear: string[];
+}
+declare function encodeSessionCookies(endpointRef: string, session: StoredSession): SessionCookieWrite;
+/**
+ * encodeSessionCookies for percent-ENCODING cookie stores. Next's request
+ * and response cookie APIs apply encodeURIComponent to values when
+ * serializing (and decodeURIComponent on read) — handing them the codec's
+ * already-encoded values would DOUBLE-encode the wire bytes and break the
+ * browser-side reader. This variant returns the same cookie run with
+ * DECODED values: `encodeURIComponent(value)` reproduces the
+ * encodeSessionCookies bytes exactly (chunk boundaries never split an
+ * escape), so an encoding store writes byte-identical cookies to a raw
+ * writer like document.cookie.
+ */
+declare function encodeSessionCookiesDecoded(endpointRef: string, session: StoredSession): SessionCookieWrite;
+/**
+ * Read the session back from a cookie getter: the base name wins; otherwise
+ * `.0`, `.1`, … are concatenated until the first missing chunk. Tolerant:
+ * malformed URI escapes / JSON / shape → null (treated as "no session").
+ *
+ * Accepts BOTH value forms. Next's cookie stores percent-DECODE values once
+ * on read, so server-side callers (pbServer adapter, middleware) hand us the
+ * already-decoded JSON; raw readers (document.cookie) hand us the encoded
+ * form. The raw (already-decoded) parse runs FIRST because it is
+ * unambiguous — an encoded value can never raw-parse as JSON
+ * (encodeURIComponent escapes `{` itself, so it starts with `%7B`) — whereas
+ * decode-first would silently corrupt a literal `%XX` run inside a token
+ * (decodeURIComponent('%41') → 'A', no throw) or throw on an invalid escape.
+ */
+declare function decodeSessionCookies(get: (name: string) => string | undefined, endpointRef: string): StoredSession | null;
+/**
+ * Names a writer must delete before/while writing: the base name (when
+ * present) plus every existing `.N` chunk, probed in order until the first
+ * missing one (writes are always a contiguous `.0..n` run, so a gap means
+ * the end of palbe-owned chunks).
+ */
+declare function clearedSessionCookieNames(endpointRef: string, present: (name: string) => boolean): string[];
+
+/**
+ * palbeMiddleware — proactive cookie-session refresh in Next.js middleware.
+ *
+ * REQUIRED — not optional — for session-bearing RSC apps. Server Components
+ * cannot write cookies, so pbServer's reactive refresh cannot PERSIST a
+ * rotated session there: every RSC render would re-refresh from the SAME
+ * cookie refresh token, and once two of those land more than 30s apart
+ * (outside palauth's rotation grace) the reuse detector REVOKES THE WHOLE
+ * TOKEN FAMILY — the user is force-logged-out everywhere. This middleware
+ * refreshes the cookie BEFORE the RSC tree renders, so pbServer hydrates a
+ * still-valid session and never burns the token itself.
+ *
+ * MODULE-GRAPH RULES (same as ./index.ts): 'next/server' is imported only
+ * lazily (the type-only NextRequest/NextResponse imports erase at build
+ * time), and middleware.ts must import the generated palbe.gen.ts itself —
+ * Next bundles middleware as its OWN module graph; the layout.tsx import
+ * does not reach it.
+ *
+ * ```ts
+ * // middleware.ts
+ * import './palbe.gen';
+ * import { palbeMiddleware } from '@palbase/web/next';
+ * import type { NextRequest } from 'next/server';
+ *
+ * export function middleware(request: NextRequest) {
+ *   return palbeMiddleware(request);
+ * }
+ * export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] };
+ * ```
+ */
+
+interface PalbeMiddlewareOptions {
+    /** Refresh when the access token expires within this window. Default 60s. */
+    refreshMarginMs?: number;
+    /**
+     * Pre-built response to decorate (e.g. from chained middleware) instead of
+     * building `NextResponse.next({ request })`. Pass-through cases return it
+     * UNMODIFIED. Caveat: a pre-built response snapshotted the request headers
+     * at ITS creation, so a rotated cookie reaches the browser (Set-Cookie)
+     * but not the downstream RSC render of THIS request — prefer omitting this
+     * and building your response after palbeMiddleware when possible.
+     */
+    response?: NextResponse;
+}
+/**
+ * Keep the session cookie fresh for the request. No session / still-fresh
+ * session → untouched pass-through (no cache-control changes). Stale or
+ * expired → single-flight refresh, then the rotated (or cleared, on a dead
+ * token) cookies are written onto BOTH the request (for the downstream RSC
+ * render via `NextResponse.next({ request })`) and the response (for the
+ * browser), with `Cache-Control: private, no-store` on touched responses.
+ *
+ * Cookie writes go through Next's cookie APIs with the DECODED codec values:
+ * Next percent-encodes on serialization, so the wire bytes come out exactly
+ * as the shared codec's (see encodeSessionCookiesDecoded). NextRequest's
+ * cookie store is NOT a CookieStoreLike (its set is the 2-arg/RequestCookie
+ * form), hence the direct codec calls here instead of the pbServer adapter.
+ */
+declare function palbeMiddleware(request: NextRequest, opts?: PalbeMiddlewareOptions): Promise<NextResponse>;
+
+/**
+ * Structural slice of Next's request cookie store (`await cookies()`); any
+ * object honoring it works — the seam for tests and non-Next servers.
+ * `set`/`delete` are optional because RSC-scope stores are read-only.
+ */
+interface CookieStoreLike {
+    get(name: string): {
+        name: string;
+        value: string;
+    } | undefined;
+    getAll?(): Array<{
+        name: string;
+        value: string;
+    }>;
+    set?(name: string, value: string, options?: Record<string, unknown>): void;
+    delete?(name: string): void;
+}
+/**
+ * Build a per-request `PB` client over the request's cookies. Reads the
+ * session the browser SDK wrote (shared cookie codec), refreshes pre-flight
+ * when expired, and — where the store is writable (Server Actions, Route
+ * Handlers) — persists the rotated session back.
+ *
+ * Each call builds a fresh runtime (a handful of small objects, no I/O) —
+ * cheap enough to call per data access; code paths invoking it many times
+ * within one request MAY memoize per-request (e.g. React's `cache()`), but
+ * don't have to.
+ *
+ * ```ts
+ * const pb = await pbServer();
+ * const todos = await pb.todos.list();
+ * ```
+ */
+declare function pbServer(opts?: {
+    cookies?: CookieStoreLike;
+}): Promise<PB>;
+
+export { type CookieStoreLike, type HandleAuthCallbackOptions, type PalbeMiddlewareOptions, SESSION_COOKIE_ATTRS, type SessionCookieWrite, type StoredSession, clearedSessionCookieNames, decodeSessionCookies, encodeSessionCookies, encodeSessionCookiesDecoded, endpointRefFromApiKey, handleAuthCallback, palbeMiddleware, pbServer, sessionCookieName };