@lunora/client 0.0.0 → 1.0.0-alpha.10

package/dist/ssr/index.d.mts

@@ -0,0 +1,115 @@
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-B5vWSgvD.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-B5vWSgvD.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-3XJD-2hM.mjs";
+import '@lunora/runtime';
+/**
+* Structural shape of a better-auth `getSession` call's resolved value.
+*
+* better-auth's `auth.api.getSession({ headers })` returns `{ user, session }`
+* when a valid session cookie is present, or `null` otherwise. We keep `user`
+* and `session` as open records so `@lunora/client/ssr` carries no hard dependency on
+* better-auth's concrete `User`/`Session` types — the adapter passing the real
+* `auth` instance keeps full inference, while this package stays decoupled.
+*/
+interface ServerSession<User extends Record<string, unknown> = Record<string, unknown>, Session extends Record<string, unknown> = Record<string, unknown>> {
+  readonly session: Session;
+  readonly user: User;
+}
+/**
+* Structural subset of a better-auth instance: just the one endpoint
+* `getServerSession` needs. Typing it this way (rather than importing
+* `@lunora/auth`'s `LunoraAuth`) means `@lunora/client/ssr` does not depend on
+* better-auth internals — any object exposing `api.getSession` works, including
+* a test stub. The concrete return type is inferred from the passed instance.
+*/
+interface AuthLike<Result = ServerSession | null> {
+  readonly api: {
+    getSession: (input: {
+      headers: Headers;
+    }) => Promise<Result> | Result;
+  };
+}
+/**
+* Anything `getServerSession` can read request headers from: a `Request`, a
+* `Headers` object, or a plain object exposing `headers`. SSR loaders across
+* meta-frameworks hand back slightly different request objects, so accept the
+* common shapes rather than forcing the caller to unwrap.
+*/
+type HeadersSource = Headers | Request | {
+  readonly headers: Headers;
+};
+/**
+* Resolve the signed-in session from a request inside an SSR loader.
+*
+* Wraps `auth.api.getSession({ headers })` — the helper every meta-framework
+* app otherwise hand-rolls — so a loader can read identity off the inbound
+* cookies in one call. Returns `{ user, session }` when a valid session cookie
+* is present, or `null` for anonymous requests.
+*
+* The `auth` parameter is structurally typed ({@link AuthLike}), so this
+* package does not depend on better-auth internals; pass a real
+* `@lunora/auth` instance to keep full type inference on `user`/`session`.
+* Forward the resolved session's token to `createServerClient` to run the
+* server-side load (and the later WS subscription) as the same identity.
+*/
+declare const getServerSession: <Result>(request: HeadersSource, auth: AuthLike<Result>) => Promise<NonNullable<Result> | null>;
+/**
+* Serialize a {@link Preloaded} token to a JSON string for embedding in the
+* rendered HTML (e.g. a `&lt;script>` payload the client
+* reads on hydration). Every field of `Preloaded` is JSON-serializable by
+* construction — `preloadQuery` only captures the query args, function path,
+* optional shard key, and the resolved value — so this is a thin, explicit
+* `JSON.stringify` that documents the dehydration seam and keeps callers from
+* accidentally stringifying a non-serializable wrapper.
+*
+* The `&lt;` is escaped to `&lt;` so the payload is safe to inline inside a
+* `&lt;script>` tag without a stray `&lt;/script>` (or `&lt;!--`) prematurely closing
+* it — the standard XSS-safe script-embedding precaution. This escaping is NOT
+* sufficient for an HTML *attribute* sink (which also needs the quote and `&amp;`
+* characters escaped); embed the output in a raw-text script element, not a
+* data attribute.
+*/
+declare const serializePreloaded: <T>(preloaded: Preloaded<T>) => string;
+/**
+* Inverse of {@link serializePreloaded}: parse a serialized token back into a
+* {@link Preloaded} value on the client. The `&lt;` escape from serialization
+* is transparent to `JSON.parse`, so no un-escaping step is needed.
+*/
+declare const deserializePreloaded: <T = unknown>(serialized: string) => Preloaded<T>;
+/** Options accepted by {@link createServerClient}. */
+interface ServerClientOptions {
+  /**
+  * `fetch` implementation used for HTTP RPC. Defaults to the ambient global
+  * `fetch` (present in Node 18+, Workers, and meta-framework SSR runtimes).
+  * Pass one explicitly to forward cookies/headers or to use an instrumented
+  * fetch.
+  */
+  fetch?: typeof fetch;
+  /**
+  * Bearer token sent as `Authorization: Bearer &lt;token>` on every RPC. In an
+  * SSR loader you typically read this from the request (e.g. the session
+  * resolved by `getServerSession`) and pass it here so the server-side
+  * load runs as the signed-in user — and so the client subscription that
+  * resumes after hydration carries the same identity.
+  */
+  token?: string;
+  /** Base URL of the deployed Lunora worker, e.g. `https://app.example.workers.dev`. */
+  url: string;
+}
+/**
+* Build a request-scoped {@link LunoraClient} for use inside an SSR loader. SSR
+* data loading only ever calls `.query()` (HTTP RPC over `fetch`); a
+* `LunoraClient` opens a socket lazily on `.subscribe()`/`.stream()` and those
+* are never called server-side, so no live connection is established even if the
+* server runtime happens to expose a global `WebSocket`.
+*
+* Create one per request rather than sharing a module-level instance: the bearer
+* token (and any forwarded cookies in `fetch`) are per-user, and a shared client
+* would leak one request's identity into another.
+*
+* This is the framework-neutral home of the helper that previously lived only in
+* `@lunora/react/server`; the React server module re-exports the same surface so
+* existing imports keep working.
+*/
+declare const createServerClient: (options: ServerClientOptions) => LunoraClient;
+export { type AuthLike, type HeadersSource, type Preloaded, type ServerClientOptions, type ServerSession, createServerClient, deserializePreloaded, getServerSession, serializePreloaded };

package/dist/ssr/index.d.ts

@@ -0,0 +1,115 @@
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-B5vWSgvD.js";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-B5vWSgvD.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-CKZR675M.js";
+import '@lunora/runtime';
+/**
+* Structural shape of a better-auth `getSession` call's resolved value.
+*
+* better-auth's `auth.api.getSession({ headers })` returns `{ user, session }`
+* when a valid session cookie is present, or `null` otherwise. We keep `user`
+* and `session` as open records so `@lunora/client/ssr` carries no hard dependency on
+* better-auth's concrete `User`/`Session` types — the adapter passing the real
+* `auth` instance keeps full inference, while this package stays decoupled.
+*/
+interface ServerSession<User extends Record<string, unknown> = Record<string, unknown>, Session extends Record<string, unknown> = Record<string, unknown>> {
+  readonly session: Session;
+  readonly user: User;
+}
+/**
+* Structural subset of a better-auth instance: just the one endpoint
+* `getServerSession` needs. Typing it this way (rather than importing
+* `@lunora/auth`'s `LunoraAuth`) means `@lunora/client/ssr` does not depend on
+* better-auth internals — any object exposing `api.getSession` works, including
+* a test stub. The concrete return type is inferred from the passed instance.
+*/
+interface AuthLike<Result = ServerSession | null> {
+  readonly api: {
+    getSession: (input: {
+      headers: Headers;
+    }) => Promise<Result> | Result;
+  };
+}
+/**
+* Anything `getServerSession` can read request headers from: a `Request`, a
+* `Headers` object, or a plain object exposing `headers`. SSR loaders across
+* meta-frameworks hand back slightly different request objects, so accept the
+* common shapes rather than forcing the caller to unwrap.
+*/
+type HeadersSource = Headers | Request | {
+  readonly headers: Headers;
+};
+/**
+* Resolve the signed-in session from a request inside an SSR loader.
+*
+* Wraps `auth.api.getSession({ headers })` — the helper every meta-framework
+* app otherwise hand-rolls — so a loader can read identity off the inbound
+* cookies in one call. Returns `{ user, session }` when a valid session cookie
+* is present, or `null` for anonymous requests.
+*
+* The `auth` parameter is structurally typed ({@link AuthLike}), so this
+* package does not depend on better-auth internals; pass a real
+* `@lunora/auth` instance to keep full type inference on `user`/`session`.
+* Forward the resolved session's token to `createServerClient` to run the
+* server-side load (and the later WS subscription) as the same identity.
+*/
+declare const getServerSession: <Result>(request: HeadersSource, auth: AuthLike<Result>) => Promise<NonNullable<Result> | null>;
+/**
+* Serialize a {@link Preloaded} token to a JSON string for embedding in the
+* rendered HTML (e.g. a `&lt;script>` payload the client
+* reads on hydration). Every field of `Preloaded` is JSON-serializable by
+* construction — `preloadQuery` only captures the query args, function path,
+* optional shard key, and the resolved value — so this is a thin, explicit
+* `JSON.stringify` that documents the dehydration seam and keeps callers from
+* accidentally stringifying a non-serializable wrapper.
+*
+* The `&lt;` is escaped to `&lt;` so the payload is safe to inline inside a
+* `&lt;script>` tag without a stray `&lt;/script>` (or `&lt;!--`) prematurely closing
+* it — the standard XSS-safe script-embedding precaution. This escaping is NOT
+* sufficient for an HTML *attribute* sink (which also needs the quote and `&amp;`
+* characters escaped); embed the output in a raw-text script element, not a
+* data attribute.
+*/
+declare const serializePreloaded: <T>(preloaded: Preloaded<T>) => string;
+/**
+* Inverse of {@link serializePreloaded}: parse a serialized token back into a
+* {@link Preloaded} value on the client. The `&lt;` escape from serialization
+* is transparent to `JSON.parse`, so no un-escaping step is needed.
+*/
+declare const deserializePreloaded: <T = unknown>(serialized: string) => Preloaded<T>;
+/** Options accepted by {@link createServerClient}. */
+interface ServerClientOptions {
+  /**
+  * `fetch` implementation used for HTTP RPC. Defaults to the ambient global
+  * `fetch` (present in Node 18+, Workers, and meta-framework SSR runtimes).
+  * Pass one explicitly to forward cookies/headers or to use an instrumented
+  * fetch.
+  */
+  fetch?: typeof fetch;
+  /**
+  * Bearer token sent as `Authorization: Bearer &lt;token>` on every RPC. In an
+  * SSR loader you typically read this from the request (e.g. the session
+  * resolved by `getServerSession`) and pass it here so the server-side
+  * load runs as the signed-in user — and so the client subscription that
+  * resumes after hydration carries the same identity.
+  */
+  token?: string;
+  /** Base URL of the deployed Lunora worker, e.g. `https://app.example.workers.dev`. */
+  url: string;
+}
+/**
+* Build a request-scoped {@link LunoraClient} for use inside an SSR loader. SSR
+* data loading only ever calls `.query()` (HTTP RPC over `fetch`); a
+* `LunoraClient` opens a socket lazily on `.subscribe()`/`.stream()` and those
+* are never called server-side, so no live connection is established even if the
+* server runtime happens to expose a global `WebSocket`.
+*
+* Create one per request rather than sharing a module-level instance: the bearer
+* token (and any forwarded cookies in `fetch`) are per-user, and a shared client
+* would leak one request's identity into another.
+*
+* This is the framework-neutral home of the helper that previously lived only in
+* `@lunora/react/server`; the React server module re-exports the same surface so
+* existing imports keep working.
+*/
+declare const createServerClient: (options: ServerClientOptions) => LunoraClient;
+export { type AuthLike, type HeadersSource, type Preloaded, type ServerClientOptions, type ServerSession, createServerClient, deserializePreloaded, getServerSession, serializePreloaded };

package/dist/ssr/index.mjs

@@ -0,0 +1,4 @@
+export { getServerSession } from '../packem_shared/getServerSession-8jXewqxd.mjs';
+export { deserializePreloaded, serializePreloaded } from '../packem_shared/deserializePreloaded-C0eJTY_W.mjs';
+export { createServerClient } from '../packem_shared/createServerClient-BxkNcRlR.mjs';
+export { preloadQuery, preloadedQueryResult } from '../packem_shared/preloadQuery-lobFkD2Z.mjs';

package/package.json

@@ -1,31 +1,67 @@
 {
   "name": "@lunora/client",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.10",
   "description": "Lunora browser SDK: WebSocket transport, optimistic updates, and an offline mutation queue",
-  "license": "FSL-1.1-Apache-2.0",
+  "keywords": [
+    "cloudflare",
+    "durable-objects",
+    "lunora",
+    "offline-queue",
+    "optimistic-updates",
+    "realtime",
+    "websocket",
+    "workers"
+  ],
   "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/anolilab/lunora.git",
     "directory": "packages/client"
   },
-  "bugs": {
-    "url": "https://github.com/anolilab/lunora/issues"
-  },
-  "keywords": [
-    "lunora",
-    "cloudflare",
-    "workers",
-    "durable-objects",
-    "websocket",
-    "optimistic-updates",
-    "offline-queue",
-    "realtime"
+  "files": [
+    "./dist",
+    "README.md",
+    "LICENSE.md",
+    "__assets__"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./query": {
+      "types": "./dist/query/index.d.ts",
+      "import": "./dist/query/index.mjs"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.mjs"
+    },
+    "./pagination": {
+      "types": "./dist/pagination/index.d.ts",
+      "import": "./dist/pagination/index.mjs"
+    },
+    "./ssr": {
+      "types": "./dist/ssr/index.d.ts",
+      "import": "./dist/ssr/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
 }