@loomup/astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loomup 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.

package/README.md

@@ -0,0 +1,60 @@
+# @loomup/astro
+
+Astro integration and SSR helpers for [Loomup](https://tryloomup.com), built on
+`@loomup/client`.
+
+## Install
+
+```bash
+npm install @loomup/astro @loomup/client
+```
+
+Astro 4 or newer is supported.
+
+## Integration
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import loomup from "@loomup/astro";
+
+export default defineConfig({
+  integrations: [
+    loomup({
+      url: process.env.LOOMUP_URL ?? "http://127.0.0.1:3000",
+    }),
+  ],
+});
+```
+
+## Server-side client
+
+```astro
+---
+import { createServerClient } from "@loomup/astro/server";
+
+const loomup = createServerClient(Astro.cookies, {
+  url: import.meta.env.LOOMUP_URL,
+});
+const { data: todos } = await loomup.from("todos").select({ limit: 20 });
+---
+
+<ul>
+  {todos.map((todo) => <li>{todo.title}</li>)}
+</ul>
+```
+
+Package exports:
+
+- `@loomup/astro` — Astro integration.
+- `@loomup/astro/server` — cookie-backed server client and storage helpers.
+- `@loomup/astro/client` — browser client for Astro islands.
+- `@loomup/astro/middleware` — authentication middleware.
+- `@loomup/astro/auth` — lower-level cookie authentication helpers.
+
+See the [Astro SDK guide](https://tryloomup.com/docs) for middleware,
+authenticated islands, object storage, and deployment guidance.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,24 @@
+/** Same-origin Astro auth endpoint for Loomup-backed applications. */
+import { type CookieStore, type CreateServerClientOptions } from "./server.js";
+export type LoomupAuthEndpointContext = {
+    request: Request;
+    cookies: CookieStore;
+    params?: Record<string, string | undefined>;
+};
+export type LoomupAuthHandlerOptions = CreateServerClientOptions & {
+    /** Catch-all Astro parameter name. Default: `loomup`. */
+    param?: string;
+};
+/**
+ * Create one Astro catch-all endpoint for login, logout, session hydration,
+ * refresh, registration, and password reset.
+ *
+ * @example
+ * ```ts
+ * // src/pages/api/loomup/[...loomup].ts
+ * import { createLoomupAuthHandler } from "@loomup/astro/auth";
+ * export const prerender = false;
+ * export const ALL = createLoomupAuthHandler({ url: import.meta.env.LOOMUP_URL });
+ * ```
+ */
+export declare function createLoomupAuthHandler(options?: LoomupAuthHandlerOptions): (context: LoomupAuthEndpointContext) => Promise<Response>;

package/dist/auth.js

@@ -0,0 +1,134 @@
+/** Same-origin Astro auth endpoint for Loomup-backed applications. */
+import { LoomupError } from "@loomup/client";
+import { createServerClient, } from "./server.js";
+function response(data, status = 200) {
+    return Response.json(data, {
+        status,
+        headers: { "Cache-Control": "private, no-store" },
+    });
+}
+async function jsonBody(request) {
+    try {
+        const value = await request.json();
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new LoomupError("request body must be a JSON object", "invalid_input", 400);
+    }
+}
+function assertSameOrigin(request) {
+    const origin = request.headers.get("Origin");
+    if (origin && origin !== new URL(request.url).origin) {
+        throw new LoomupError("cross-origin auth mutation rejected", "forbidden", 403);
+    }
+}
+function publicSession(user, accessToken) {
+    return { data: { user, access_token: accessToken } };
+}
+/**
+ * Create one Astro catch-all endpoint for login, logout, session hydration,
+ * refresh, registration, and password reset.
+ *
+ * @example
+ * ```ts
+ * // src/pages/api/loomup/[...loomup].ts
+ * import { createLoomupAuthHandler } from "@loomup/astro/auth";
+ * export const prerender = false;
+ * export const ALL = createLoomupAuthHandler({ url: import.meta.env.LOOMUP_URL });
+ * ```
+ */
+export function createLoomupAuthHandler(options = {}) {
+    const param = options.param ?? "loomup";
+    return async (context) => {
+        const action = context.params?.[param]?.replace(/^\/+|\/+$/g, "") ?? "";
+        const client = createServerClient(context.cookies, options);
+        try {
+            switch (action) {
+                case "session": {
+                    if (context.request.method !== "GET") {
+                        return response({ error: { code: "method_not_allowed" } }, 405);
+                    }
+                    const user = await client.auth.me();
+                    return response(publicSession(user, client.accessToken));
+                }
+                case "refresh": {
+                    assertSameOrigin(context.request);
+                    const tokens = await client.auth.refresh();
+                    const user = tokens.user ?? (await client.auth.me());
+                    return response(publicSession(user, tokens.access_token));
+                }
+                case "login": {
+                    assertSameOrigin(context.request);
+                    const body = await jsonBody(context.request);
+                    const tokens = await client.auth.signIn({
+                        email: String(body.email ?? ""),
+                        password: String(body.password ?? ""),
+                    });
+                    const user = tokens.user ?? (await client.auth.me());
+                    return response(publicSession(user, tokens.access_token));
+                }
+                case "register": {
+                    assertSameOrigin(context.request);
+                    const body = await jsonBody(context.request);
+                    const tokens = await client.auth.signUp({
+                        email: String(body.email ?? ""),
+                        password: String(body.password ?? ""),
+                    });
+                    const user = tokens.user ?? (await client.auth.me());
+                    return response(publicSession(user, tokens.access_token), 201);
+                }
+                case "logout": {
+                    assertSameOrigin(context.request);
+                    await client.auth.signOut();
+                    return response({ data: { ok: true } });
+                }
+                case "change-password": {
+                    assertSameOrigin(context.request);
+                    const body = await jsonBody(context.request);
+                    const currentPassword = String(body.currentPassword ?? "");
+                    const newPassword = String(body.newPassword ?? "");
+                    const user = await client.auth.me();
+                    await client.request("POST", "/account/api/change-password", {
+                        current_password: currentPassword,
+                        new_password: newPassword,
+                    });
+                    // The core revokes every refresh session on password change. Issue a
+                    // fresh current session so the browser does not fail on its next 401.
+                    const tokens = await client.auth.signIn({ email: user.email, password: newPassword });
+                    return response(publicSession(tokens.user ?? user, tokens.access_token));
+                }
+                case "password-reset/request": {
+                    assertSameOrigin(context.request);
+                    const body = await jsonBody(context.request);
+                    await client.request("POST", "/auth/password-reset/request", {
+                        email: String(body.email ?? ""),
+                    });
+                    // Never forward a self-hosted reset token to the browser. Hosted
+                    // Loomup delivers it out of band.
+                    return response({
+                        data: { ok: true, message: "if the account exists, a reset email was sent" },
+                    });
+                }
+                case "password-reset/confirm": {
+                    assertSameOrigin(context.request);
+                    const body = await jsonBody(context.request);
+                    await client.request("POST", "/auth/password-reset/confirm", {
+                        token: String(body.token ?? ""),
+                        password: String(body.password ?? ""),
+                    });
+                    return response({ data: { ok: true } });
+                }
+                default:
+                    return response({ error: { code: "not_found", message: "unknown auth action" } }, 404);
+            }
+        }
+        catch (error) {
+            if (error instanceof LoomupError) {
+                return response({ error: { code: error.code ?? "auth_error", message: error.message } }, error.status ?? 400);
+            }
+            return response({ error: { code: "internal", message: error instanceof Error ? error.message : String(error) } }, 500);
+        }
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Browser Loomup client for Astro client islands (`client:load`, etc.).
+ */
+import { type CreateClientOptions, type DefaultInsertMap, type DefaultTableMap, type DefaultUpdateMap, type LoomupClient, type LoomupProject, type User } from "@loomup/client";
+export type { AuthTokens, ChangeEvent, ControlEvent, CreateClientOptions, ListMeta, User, } from "@loomup/client";
+export { LoomupError, createClient, makeSubKey, parseSubKey, } from "@loomup/client";
+export type CreateBrowserClientOptions = {
+    /**
+     * Loomup base URL. Defaults to `import.meta.env.PUBLIC_LOOMUP_URL`
+     * (injected by the Astro integration) or `PUBLIC_LOOMUP_URL` process env.
+     */
+    url?: string;
+    token?: string;
+    refreshToken?: string;
+    WebSocketImpl?: CreateClientOptions["WebSocketImpl"];
+};
+/**
+ * Create a browser Loomup client for islands.
+ *
+ * Realtime (`subscribe` / `subscribeReady`) is supported in the browser.
+ * Prefer `createServerClient` for SSR data loads; do not open WebSockets
+ * during the server render of a request.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserClient } from "@loomup/astro/client";
+ * const lb = createBrowserClient();
+ * lb.from("todos").subscribe((ev) => console.log(ev));
+ * ```
+ */
+export declare function createBrowserClient<TMap extends DefaultTableMap = DefaultTableMap, TInsertMap extends DefaultInsertMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}, TUpdateMap extends DefaultUpdateMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}>(options?: CreateBrowserClientOptions): LoomupClient<TMap, TInsertMap, TUpdateMap>;
+export type CreateAuthenticatedProjectOptions = CreateBrowserClientOptions & {
+    /** Same-origin catch-all endpoint. Default: `/api/loomup`. */
+    authEndpoint?: string;
+    fetch?: typeof fetch;
+};
+export type AuthenticatedProject<TMap, TInsertMap, TUpdateMap> = {
+    db: LoomupProject<TMap, TInsertMap, TUpdateMap>;
+    user: User;
+    signOut(): Promise<void>;
+};
+/**
+ * Hydrate the typed `db.issues` project client without exposing the refresh
+ * token to JavaScript. Access-token renewal goes through the Astro endpoint.
+ */
+export declare function createAuthenticatedProject<TMap = DefaultTableMap, TInsertMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}, TUpdateMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}>(options?: CreateAuthenticatedProjectOptions): Promise<AuthenticatedProject<TMap, TInsertMap, TUpdateMap>>;

package/dist/client.js

@@ -0,0 +1,95 @@
+/**
+ * Browser Loomup client for Astro client islands (`client:load`, etc.).
+ */
+import { createClient, createProject, LoomupError, } from "@loomup/client";
+export { LoomupError, createClient, makeSubKey, parseSubKey, } from "@loomup/client";
+function envPublicUrl() {
+    try {
+        // Astro / Vite client and server modules.
+        const meta = import.meta;
+        if (meta.env?.PUBLIC_LOOMUP_URL)
+            return meta.env.PUBLIC_LOOMUP_URL;
+    }
+    catch {
+        /* ignore */
+    }
+    if (typeof process !== "undefined" && process.env?.PUBLIC_LOOMUP_URL) {
+        return process.env.PUBLIC_LOOMUP_URL;
+    }
+    return undefined;
+}
+function resolveBrowserUrl(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = envPublicUrl();
+    if (fromEnv)
+        return fromEnv;
+    throw new Error("@loomup/astro: createBrowserClient requires `url` or PUBLIC_LOOMUP_URL (set via the loomup() integration)");
+}
+/**
+ * Create a browser Loomup client for islands.
+ *
+ * Realtime (`subscribe` / `subscribeReady`) is supported in the browser.
+ * Prefer `createServerClient` for SSR data loads; do not open WebSockets
+ * during the server render of a request.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserClient } from "@loomup/astro/client";
+ * const lb = createBrowserClient();
+ * lb.from("todos").subscribe((ev) => console.log(ev));
+ * ```
+ */
+export function createBrowserClient(options = {}) {
+    return createClient({
+        url: resolveBrowserUrl(options.url),
+        token: options.token,
+        refreshToken: options.refreshToken,
+        WebSocketImpl: options.WebSocketImpl,
+    });
+}
+async function authRequest(fetchImpl, endpoint, action, init) {
+    const response = await fetchImpl(`${endpoint.replace(/\/$/, "")}/${action}`, {
+        credentials: "same-origin",
+        ...init,
+        headers: {
+            Accept: "application/json",
+            ...(init?.body ? { "Content-Type": "application/json" } : {}),
+            ...(init?.headers ?? {}),
+        },
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        throw new LoomupError(payload.error?.message ?? response.statusText, payload.error?.code, response.status);
+    }
+    return payload.data ?? {};
+}
+/**
+ * Hydrate the typed `db.issues` project client without exposing the refresh
+ * token to JavaScript. Access-token renewal goes through the Astro endpoint.
+ */
+export async function createAuthenticatedProject(options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const endpoint = options.authEndpoint ?? "/api/loomup";
+    const session = await authRequest(fetchImpl, endpoint, "session", { method: "GET" });
+    if (!session.user || !session.access_token) {
+        throw new LoomupError("authenticated session required", "unauthorized", 401);
+    }
+    const db = createProject({
+        url: resolveBrowserUrl(options.url),
+        token: session.access_token,
+        WebSocketImpl: options.WebSocketImpl,
+        accessTokenProvider: async () => {
+            const refreshed = await authRequest(fetchImpl, endpoint, "refresh", { method: "POST" });
+            return refreshed.access_token;
+        },
+    });
+    return {
+        db,
+        user: session.user,
+        async signOut() {
+            await authRequest(fetchImpl, endpoint, "logout", { method: "POST" });
+            db.setToken(undefined);
+        },
+    };
+}

package/dist/cookies.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cookie helpers for Loomup auth tokens in Astro SSR.
+ */
+export declare const DEFAULT_ACCESS_COOKIE = "loomup-access";
+export declare const DEFAULT_REFRESH_COOKIE = "loomup-refresh";
+/** Minimal cookie API compatible with AstroCookies (and easy to mock in tests). */
+export type CookieStore = {
+    get(name: string): {
+        value: string;
+    } | undefined;
+    set(name: string, value: string, options?: CookieWriteOptions): void;
+    delete(name: string, options?: {
+        path?: string;
+    }): void;
+};
+export type CookieWriteOptions = {
+    path?: string;
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none" | boolean;
+    expires?: Date;
+};
+export type CookieNames = {
+    access: string;
+    refresh: string;
+};
+export type CookieOptions = {
+    /** Cookie name overrides. */
+    names?: Partial<CookieNames>;
+    /**
+     * Force Secure flag. Default: true when NODE_ENV === "production",
+     * or when `secure: true` is passed.
+     */
+    secure?: boolean;
+    /** Cookie path (default "/"). */
+    path?: string;
+    /**
+     * Max-Age for the access token cookie when expires_in is missing.
+     * Default 3600 seconds.
+     */
+    accessMaxAge?: number;
+    /**
+     * Max-Age for the refresh token cookie.
+     * Default 60 * 60 * 24 * 30 (30 days).
+     */
+    refreshMaxAge?: number;
+};
+export declare function resolveCookieNames(names?: Partial<CookieNames>): CookieNames;
+export declare function isSecureDefault(explicit?: boolean): boolean;
+export declare function readTokens(cookies: CookieStore, names?: Partial<CookieNames>): {
+    access?: string;
+    refresh?: string;
+};
+export declare function writeTokens(cookies: CookieStore, tokens: {
+    access_token: string;
+    refresh_token: string;
+    expires_in?: number;
+}, options?: CookieOptions): void;
+export declare function clearTokens(cookies: CookieStore, options?: CookieOptions): void;
+/**
+ * Adapt AstroCookies (or any compatible object) to CookieStore.
+ * Accepts a structural type so tests and non-Astro callers work.
+ */
+export declare function asCookieStore(cookies: CookieStore): CookieStore;

package/dist/cookies.js

@@ -0,0 +1,58 @@
+/**
+ * Cookie helpers for Loomup auth tokens in Astro SSR.
+ */
+export const DEFAULT_ACCESS_COOKIE = "loomup-access";
+export const DEFAULT_REFRESH_COOKIE = "loomup-refresh";
+export function resolveCookieNames(names) {
+    return {
+        access: names?.access ?? DEFAULT_ACCESS_COOKIE,
+        refresh: names?.refresh ?? DEFAULT_REFRESH_COOKIE,
+    };
+}
+export function isSecureDefault(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    return (typeof process !== "undefined" &&
+        process.env?.NODE_ENV === "production");
+}
+export function readTokens(cookies, names) {
+    const n = resolveCookieNames(names);
+    return {
+        access: cookies.get(n.access)?.value,
+        refresh: cookies.get(n.refresh)?.value,
+    };
+}
+export function writeTokens(cookies, tokens, options) {
+    const n = resolveCookieNames(options?.names);
+    const path = options?.path ?? "/";
+    const secure = isSecureDefault(options?.secure);
+    const accessMaxAge = tokens.expires_in ?? options?.accessMaxAge ?? 3600;
+    const refreshMaxAge = options?.refreshMaxAge ?? 60 * 60 * 24 * 30;
+    const base = {
+        path,
+        httpOnly: true,
+        secure,
+        sameSite: "lax",
+    };
+    cookies.set(n.access, tokens.access_token, {
+        ...base,
+        maxAge: accessMaxAge,
+    });
+    cookies.set(n.refresh, tokens.refresh_token, {
+        ...base,
+        maxAge: refreshMaxAge,
+    });
+}
+export function clearTokens(cookies, options) {
+    const n = resolveCookieNames(options?.names);
+    const path = options?.path ?? "/";
+    cookies.delete(n.access, { path });
+    cookies.delete(n.refresh, { path });
+}
+/**
+ * Adapt AstroCookies (or any compatible object) to CookieStore.
+ * Accepts a structural type so tests and non-Astro callers work.
+ */
+export function asCookieStore(cookies) {
+    return cookies;
+}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @loomup/astro — Astro integration for Loomup Realtime.
+ *
+ * Server helpers: `@loomup/astro/server`
+ * Browser helpers: `@loomup/astro/client`
+ * Middleware: `@loomup/astro/middleware`
+ */
+export type LoomupIntegrationOptions = {
+    /**
+     * Loomup server URL (e.g. http://127.0.0.1:3000).
+     * Falls back to process.env.LOOMUP_URL or PUBLIC_LOOMUP_URL.
+     */
+    url?: string;
+    /**
+     * When true (default), inject PUBLIC_LOOMUP_URL for browser islands
+     * via Vite env.
+     */
+    injectPublicEnv?: boolean;
+};
+/** Structural Astro integration type (avoids hard dep on astro types at build). */
+export type AstroIntegrationLike = {
+    name: string;
+    hooks: {
+        "astro:config:setup"?: (params: {
+            updateConfig: (config: {
+                vite?: {
+                    define?: Record<string, string>;
+                    envPrefix?: string | string[];
+                };
+            }) => void;
+            logger?: {
+                info: (msg: string) => void;
+                warn: (msg: string) => void;
+            };
+        }) => void | Promise<void>;
+    };
+};
+/**
+ * Astro integration: wires PUBLIC_LOOMUP_URL for `createBrowserClient()`.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { defineConfig } from "astro/config";
+ * import loomup from "@loomup/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [loomup({ url: process.env.LOOMUP_URL })],
+ * });
+ * ```
+ */
+export default function loomup(options?: LoomupIntegrationOptions): AstroIntegrationLike;
+export type { LoomupIntegrationOptions as LoomupOptions };

package/dist/index.js

@@ -0,0 +1,57 @@
+/**
+ * @loomup/astro — Astro integration for Loomup Realtime.
+ *
+ * Server helpers: `@loomup/astro/server`
+ * Browser helpers: `@loomup/astro/client`
+ * Middleware: `@loomup/astro/middleware`
+ */
+function resolveUrl(options) {
+    if (options?.url)
+        return options.url.replace(/\/$/, "");
+    if (typeof process !== "undefined") {
+        const v = process.env?.LOOMUP_URL || process.env?.PUBLIC_LOOMUP_URL;
+        if (v)
+            return v.replace(/\/$/, "");
+    }
+    return undefined;
+}
+/**
+ * Astro integration: wires PUBLIC_LOOMUP_URL for `createBrowserClient()`.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { defineConfig } from "astro/config";
+ * import loomup from "@loomup/astro";
+ *
+ * export default defineConfig({
+ *   integrations: [loomup({ url: process.env.LOOMUP_URL })],
+ * });
+ * ```
+ */
+export default function loomup(options = {}) {
+    const inject = options.injectPublicEnv !== false;
+    return {
+        name: "@loomup/astro",
+        hooks: {
+            "astro:config:setup"({ updateConfig, logger }) {
+                const url = resolveUrl(options);
+                if (!url) {
+                    logger?.warn("@loomup/astro: no url configured (pass loomup({ url }) or set LOOMUP_URL). Browser client will need an explicit url.");
+                    return;
+                }
+                if (!inject)
+                    return;
+                // Vite define values must be JSON-serialized so they become string literals.
+                updateConfig({
+                    vite: {
+                        define: {
+                            "import.meta.env.PUBLIC_LOOMUP_URL": JSON.stringify(url),
+                        },
+                    },
+                });
+                logger?.info(`@loomup/astro: PUBLIC_LOOMUP_URL → ${url}`);
+            },
+        },
+    };
+}

package/dist/middleware.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Optional Astro middleware helper: refresh session cookies and attach user.
+ */
+import { type CreateServerClientOptions, type CookieStore } from "./server.js";
+/** Minimal middleware context (Astro APIMiddlewareContext subset). */
+export type LoomupMiddlewareContext = {
+    cookies: CookieStore;
+    locals: Record<string, unknown>;
+};
+export type LoomupMiddlewareOptions = CreateServerClientOptions & {
+    /**
+     * When true (default), call `auth.me()` after a successful token setup and
+     * set `locals.user` / `locals.loomup`. Failures clear cookies.
+     */
+    loadUser?: boolean;
+    /** Locals key for the user object (default "user"). */
+    userKey?: string;
+    /** Locals key for the Loomup client (default "loomup"). */
+    clientKey?: string;
+};
+export type MiddlewareNext = () => Promise<Response>;
+/**
+ * Returns an Astro-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * // src/middleware.ts
+ * import { defineMiddleware } from "astro:middleware";
+ * import { createLoomupMiddleware } from "@loomup/astro/middleware";
+ *
+ * const loomupMw = createLoomupMiddleware({
+ *   url: import.meta.env.LOOMUP_URL,
+ * });
+ *
+ * export const onRequest = defineMiddleware((context, next) =>
+ *   loomupMw(context, next),
+ * );
+ * ```
+ */
+export declare function createLoomupMiddleware(options?: LoomupMiddlewareOptions): (context: LoomupMiddlewareContext, next: MiddlewareNext) => Promise<Response>;

package/dist/middleware.js

@@ -0,0 +1,71 @@
+/**
+ * Optional Astro middleware helper: refresh session cookies and attach user.
+ */
+import { createServerClient, } from "./server.js";
+/**
+ * Returns an Astro-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * // src/middleware.ts
+ * import { defineMiddleware } from "astro:middleware";
+ * import { createLoomupMiddleware } from "@loomup/astro/middleware";
+ *
+ * const loomupMw = createLoomupMiddleware({
+ *   url: import.meta.env.LOOMUP_URL,
+ * });
+ *
+ * export const onRequest = defineMiddleware((context, next) =>
+ *   loomupMw(context, next),
+ * );
+ * ```
+ */
+export function createLoomupMiddleware(options = {}) {
+    const loadUser = options.loadUser !== false;
+    const userKey = options.userKey ?? "user";
+    const clientKey = options.clientKey ?? "loomup";
+    return async (context, next) => {
+        const client = createServerClient(context.cookies, options);
+        context.locals[clientKey] = client;
+        const hasAccess = Boolean(client.accessToken);
+        const hasRefresh = Boolean(
+        // refresh is private; re-read from cookies via a no-op path:
+        // createServerClient already loaded tokens — try refresh if no access.
+        options.refreshToken ||
+            context.cookies.get(options.cookies?.names?.refresh ?? "loomup-refresh")?.value);
+        if (!hasAccess && hasRefresh) {
+            try {
+                await client.auth.refresh();
+            }
+            catch {
+                await client.auth.signOut().catch(() => { });
+                context.locals[userKey] = undefined;
+                return next();
+            }
+        }
+        if (loadUser && client.accessToken) {
+            try {
+                const user = await client.auth.me();
+                context.locals[userKey] = user;
+            }
+            catch {
+                // Stale access token — try refresh once, then clear.
+                try {
+                    if (hasRefresh) {
+                        await client.auth.refresh();
+                        context.locals[userKey] = await client.auth.me();
+                    }
+                    else {
+                        await client.auth.signOut().catch(() => { });
+                        context.locals[userKey] = undefined;
+                    }
+                }
+                catch {
+                    await client.auth.signOut().catch(() => { });
+                    context.locals[userKey] = undefined;
+                }
+            }
+        }
+        return next();
+    };
+}

package/dist/objectStorage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Server-side object storage helpers for Astro endpoints / SSR.
+ * ServerLoomupClient extends LoomupClient and already has `.storage`.
+ */
+import type { LoomupClient, StorageObject, StorageUploadOptions } from "@loomup/client";
+export type UploadFormDataOptions = StorageUploadOptions & {
+    fileField?: string;
+    path?: string;
+    pathField?: string;
+    pathPrefix?: string;
+};
+export declare function fileAndPathFromFormData(form: FormData, options?: UploadFormDataOptions): {
+    path: string;
+    file: Blob;
+    contentType?: string;
+};
+export declare function uploadFromFormData(client: LoomupClient, bucket: string, form: FormData, options?: UploadFormDataOptions): Promise<StorageObject>;
+export declare function storageDownloadResponse(client: LoomupClient, bucket: string, path: string, init?: ResponseInit): Promise<Response>;

package/dist/objectStorage.js

@@ -0,0 +1,62 @@
+/**
+ * Server-side object storage helpers for Astro endpoints / SSR.
+ * ServerLoomupClient extends LoomupClient and already has `.storage`.
+ */
+function isFileLike(v) {
+    return (typeof Blob !== "undefined" &&
+        v instanceof Blob &&
+        typeof v.arrayBuffer === "function");
+}
+export function fileAndPathFromFormData(form, options) {
+    const fileField = options?.fileField ?? "file";
+    const pathField = options?.pathField ?? "path";
+    const raw = form.get(fileField);
+    if (!isFileLike(raw)) {
+        throw new Error(`@loomup/astro: FormData field "${fileField}" must be a File/Blob`);
+    }
+    let path = options?.path ??
+        (typeof form.get(pathField) === "string"
+            ? String(form.get(pathField))
+            : undefined) ??
+        (typeof raw.name === "string" && raw.name ? raw.name : undefined);
+    if (!path || !path.trim()) {
+        throw new Error(`@loomup/astro: object path required (pass options.path, form field "${pathField}", or a named File)`);
+    }
+    path = path.replace(/^\/+/, "");
+    if (options?.pathPrefix) {
+        const prefix = options.pathPrefix.endsWith("/")
+            ? options.pathPrefix
+            : `${options.pathPrefix}/`;
+        path = `${prefix}${path}`;
+    }
+    const contentType = options?.contentType ??
+        (raw.type && raw.type.length > 0 ? raw.type : undefined);
+    return { path, file: raw, contentType };
+}
+export async function uploadFromFormData(client, bucket, form, options) {
+    const { path, file, contentType } = fileAndPathFromFormData(form, options);
+    return client.storage.from(bucket).upload(path, file, {
+        contentType,
+        upsert: options?.upsert,
+    });
+}
+export async function storageDownloadResponse(client, bucket, path, init) {
+    const upstream = await client.storage.from(bucket).downloadResponse(path);
+    const headers = new Headers(init?.headers);
+    for (const name of [
+        "content-type",
+        "content-length",
+        "etag",
+        "cache-control",
+        "content-disposition",
+    ]) {
+        const v = upstream.headers.get(name);
+        if (v && !headers.has(name))
+            headers.set(name, v);
+    }
+    return new Response(upstream.body, {
+        status: init?.status ?? upstream.status,
+        statusText: init?.statusText ?? upstream.statusText,
+        headers,
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Server-side Loomup client for Astro (SSR frontmatter, endpoints, middleware).
+ * Persists access/refresh tokens in httpOnly cookies.
+ */
+import { LoomupClient, type AuthTokens, type CreateClientOptions, type DefaultTableMap, type LoomupProject } from "@loomup/client";
+import { type CookieOptions, type CookieStore } from "./cookies.js";
+export type { CookieNames, CookieOptions, CookieStore, CookieWriteOptions, } from "./cookies.js";
+export { DEFAULT_ACCESS_COOKIE, DEFAULT_REFRESH_COOKIE, clearTokens, readTokens, resolveCookieNames, writeTokens, } from "./cookies.js";
+export type { AuthTokens, ChangeEvent, ControlEvent, CreateClientOptions, ListMeta, User, StorageObject, StorageBucketInfo, StorageUploadOptions, StorageListOptions, StorageListResult, StorageUploadBody, } from "@loomup/client";
+export { LoomupError, createClient, StorageBucket, encodeObjectPath, normalizeStorageUpload, } from "@loomup/client";
+export { fileAndPathFromFormData, uploadFromFormData, storageDownloadResponse, type UploadFormDataOptions, } from "./objectStorage.js";
+export type CreateServerClientOptions = {
+    /**
+     * Loomup base URL. Defaults to LOOMUP_URL or PUBLIC_LOOMUP_URL env.
+     */
+    url?: string;
+    /** Override initial tokens (otherwise read from cookies). */
+    token?: string;
+    refreshToken?: string;
+    /** Cookie naming and security options. */
+    cookies?: CookieOptions;
+    /**
+     * Extra createClient options (e.g. WebSocketImpl if you ever use
+     * realtime on the server — not recommended for request-scoped SSR).
+     */
+    client?: Omit<CreateClientOptions, "url" | "token" | "refreshToken">;
+};
+/**
+ * Cookie-backed Loomup client for Astro SSR.
+ * Extends the core client so `.from()`, `.request()`, etc. stay identical.
+ * Auth methods and automatic refresh write tokens back to cookies.
+ */
+export declare class ServerLoomupClient<TMap = DefaultTableMap, TInsertMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}, TUpdateMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}> extends LoomupClient<TMap, TInsertMap, TUpdateMap> {
+    private readonly cookieStore;
+    private readonly cookieOptions?;
+    /** Last known refresh token (core field is private; we mirror for cookie writes). */
+    private mirroredRefresh?;
+    constructor(cookieStore: CookieStore, options: CreateClientOptions & {
+        cookieOptions?: CookieOptions;
+    });
+    private persistFromTokens;
+    private clearCookieTokens;
+    signUp(creds: {
+        email: string;
+        password: string;
+    }): Promise<AuthTokens>;
+    signIn(creds: {
+        email: string;
+        password: string;
+    }): Promise<AuthTokens>;
+    refresh(): Promise<AuthTokens>;
+    signOut(): Promise<void>;
+    setToken(token: string | undefined): void;
+    setRefreshToken(token: string | undefined): void;
+    /**
+     * Same surface as LoomupClient.auth, but methods go through overrides
+     * so cookies stay in sync.
+     */
+    get auth(): {
+        signUp: (creds: {
+            email: string;
+            password: string;
+        }) => Promise<AuthTokens>;
+        register: (creds: {
+            email: string;
+            password: string;
+        }) => Promise<AuthTokens>;
+        signIn: (creds: {
+            email: string;
+            password: string;
+        }) => Promise<AuthTokens>;
+        login: (creds: {
+            email: string;
+            password: string;
+        }) => Promise<AuthTokens>;
+        signOut: () => Promise<void>;
+        logout: () => Promise<void>;
+        me: () => Promise<import("@loomup/client").User>;
+        refresh: () => Promise<AuthTokens>;
+    };
+}
+/**
+ * Create a server Loomup client bound to Astro cookies.
+ *
+ * @example
+ * ```ts
+ * ---
+ * import { createServerClient, uploadFromFormData } from "@loomup/astro/server";
+ * const lb = createServerClient(Astro.cookies, { url: import.meta.env.LOOMUP_URL });
+ * const { data } = await lb.from("todos").select({ limit: 20 });
+ * // Object storage: await lb.storage.from("avatars").upload(...)
+ * // or: await uploadFromFormData(lb, "avatars", await Astro.request.formData())
+ * ---
+ * ```
+ */
+export declare function createServerClient<TMap = DefaultTableMap, TInsertMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}, TUpdateMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}>(cookies: CookieStore, options?: CreateServerClientOptions): ServerLoomupClient<TMap, TInsertMap, TUpdateMap>;
+/**
+ * Cookie-backed SSR client with generated property access (`db.issues`).
+ * This is the server-side counterpart to `createAuthenticatedProject`.
+ */
+export declare function createServerProject<TMap = DefaultTableMap, TInsertMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}, TUpdateMap = {
+    [K in keyof TMap]: Partial<TMap[K]> & Record<string, unknown>;
+}>(cookies: CookieStore, options?: CreateServerClientOptions): LoomupProject<TMap, TInsertMap, TUpdateMap>;

package/dist/server.js

@@ -0,0 +1,131 @@
+/**
+ * Server-side Loomup client for Astro (SSR frontmatter, endpoints, middleware).
+ * Persists access/refresh tokens in httpOnly cookies.
+ */
+import { LoomupClient, projectFromClient, } from "@loomup/client";
+import { asCookieStore, clearTokens, readTokens, writeTokens, } from "./cookies.js";
+export { DEFAULT_ACCESS_COOKIE, DEFAULT_REFRESH_COOKIE, clearTokens, readTokens, resolveCookieNames, writeTokens, } from "./cookies.js";
+export { LoomupError, createClient, StorageBucket, encodeObjectPath, normalizeStorageUpload, } from "@loomup/client";
+export { fileAndPathFromFormData, uploadFromFormData, storageDownloadResponse, } from "./objectStorage.js";
+function resolveServerUrl(explicit) {
+    if (explicit)
+        return explicit;
+    if (typeof process !== "undefined") {
+        const fromEnv = process.env?.LOOMUP_URL || process.env?.PUBLIC_LOOMUP_URL;
+        if (fromEnv)
+            return fromEnv;
+    }
+    throw new Error("@loomup/astro: createServerClient requires `url` or LOOMUP_URL / PUBLIC_LOOMUP_URL");
+}
+/**
+ * Cookie-backed Loomup client for Astro SSR.
+ * Extends the core client so `.from()`, `.request()`, etc. stay identical.
+ * Auth methods and automatic refresh write tokens back to cookies.
+ */
+export class ServerLoomupClient extends LoomupClient {
+    cookieStore;
+    cookieOptions;
+    /** Last known refresh token (core field is private; we mirror for cookie writes). */
+    mirroredRefresh;
+    constructor(cookieStore, options) {
+        super(options);
+        this.cookieStore = cookieStore;
+        this.cookieOptions = options.cookieOptions;
+        this.mirroredRefresh = options.refreshToken;
+    }
+    persistFromTokens(data) {
+        this.mirroredRefresh = data.refresh_token;
+        writeTokens(this.cookieStore, data, this.cookieOptions);
+    }
+    clearCookieTokens() {
+        this.mirroredRefresh = undefined;
+        clearTokens(this.cookieStore, this.cookieOptions);
+    }
+    async signUp(creds) {
+        const data = await super.signUp(creds);
+        this.persistFromTokens(data);
+        return data;
+    }
+    async signIn(creds) {
+        const data = await super.signIn(creds);
+        this.persistFromTokens(data);
+        return data;
+    }
+    async refresh() {
+        const data = await super.refresh();
+        this.persistFromTokens(data);
+        return data;
+    }
+    async signOut() {
+        await super.signOut();
+        this.clearCookieTokens();
+    }
+    setToken(token) {
+        super.setToken(token);
+        if (token && this.mirroredRefresh) {
+            writeTokens(this.cookieStore, {
+                access_token: token,
+                refresh_token: this.mirroredRefresh,
+            }, this.cookieOptions);
+        }
+        else if (!token) {
+            // Clearing access only — still clear both for safety on full logout paths.
+            clearTokens(this.cookieStore, this.cookieOptions);
+        }
+    }
+    setRefreshToken(token) {
+        super.setRefreshToken(token);
+        this.mirroredRefresh = token;
+    }
+    /**
+     * Same surface as LoomupClient.auth, but methods go through overrides
+     * so cookies stay in sync.
+     */
+    get auth() {
+        return {
+            signUp: (creds) => this.signUp(creds),
+            register: (creds) => this.signUp(creds),
+            signIn: (creds) => this.signIn(creds),
+            login: (creds) => this.signIn(creds),
+            signOut: () => this.signOut(),
+            logout: () => this.signOut(),
+            me: () => this.me(),
+            refresh: () => this.refresh(),
+        };
+    }
+}
+/**
+ * Create a server Loomup client bound to Astro cookies.
+ *
+ * @example
+ * ```ts
+ * ---
+ * import { createServerClient, uploadFromFormData } from "@loomup/astro/server";
+ * const lb = createServerClient(Astro.cookies, { url: import.meta.env.LOOMUP_URL });
+ * const { data } = await lb.from("todos").select({ limit: 20 });
+ * // Object storage: await lb.storage.from("avatars").upload(...)
+ * // or: await uploadFromFormData(lb, "avatars", await Astro.request.formData())
+ * ---
+ * ```
+ */
+export function createServerClient(cookies, options = {}) {
+    const store = asCookieStore(cookies);
+    const fromCookies = readTokens(store, options.cookies?.names);
+    const url = resolveServerUrl(options.url);
+    const token = options.token ?? fromCookies.access;
+    const refreshToken = options.refreshToken ?? fromCookies.refresh;
+    return new ServerLoomupClient(store, {
+        url,
+        token,
+        refreshToken,
+        cookieOptions: options.cookies,
+        ...options.client,
+    });
+}
+/**
+ * Cookie-backed SSR client with generated property access (`db.issues`).
+ * This is the server-side counterpart to `createAuthenticatedProject`.
+ */
+export function createServerProject(cookies, options = {}) {
+    return projectFromClient(createServerClient(cookies, options));
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@loomup/astro",
+  "version": "0.1.0",
+  "description": "Astro integration and SSR helpers for Loomup Realtime",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./middleware": {
+      "import": "./dist/middleware.js",
+      "types": "./dist/middleware.d.ts"
+    },
+    "./auth": {
+      "import": "./dist/auth.js",
+      "types": "./dist/auth.d.ts"
+    }
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test dist/test/*.test.js",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@loomup/client": "^0.1.0",
+    "astro": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://tryloomup.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bluppco/loomup-js.git",
+    "directory": "packages/astro"
+  },
+  "bugs": {
+    "url": "https://github.com/bluppco/loomup-js/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}