@haruhimemoe/next-kit 0.1.0

package/dist/auth/osu-id.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file src/auth/osu-id.ts
+ * @desc The osu! provider id on its own, so browser code (osuSignIn) can use it without loading
+ *       the profile mapping.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** better-auth genericOAuth provider id; also the last segment of the callback path. */
+export declare const OSU_PROVIDER_ID = "osu";

package/dist/auth/osu-id.js

@@ -0,0 +1,10 @@
+/**
+ * @file src/auth/osu-id.ts
+ * @desc The osu! provider id on its own, so browser code (osuSignIn) can use it without loading
+ *       the profile mapping.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** better-auth genericOAuth provider id; also the last segment of the callback path. */
+export const OSU_PROVIDER_ID = "osu";

package/dist/auth/osu.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file src/auth/osu.ts
+ * @desc The osu! pieces of better-auth: the provider id, the extra user fields, the profile
+ *       mapping (through @haruhimemoe/osu's toOsuUser, with a synthetic email since osu! gives
+ *       none), the genericOAuth provider config (identify + public, PKCE, profile refreshed on
+ *       every sign-in), and dropping OAuth tokens from account writes. Moved from packs and
+ *       pools (src/lib/auth.ts, src/constants/auth.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { OSU_PROVIDER_ID } from "./osu-id.js";
+export { OSU_PROVIDER_ID };
+/** The fields osu! fills in on every user row. */
+export declare const OSU_USER_FIELDS: {
+    readonly osuId: {
+        readonly type: "number";
+        readonly required: true;
+    };
+    readonly username: {
+        readonly type: "string";
+        readonly required: true;
+    };
+    readonly avatarUrl: {
+        readonly type: "string";
+        readonly required: false;
+    };
+    readonly countryCode: {
+        readonly type: "string";
+        readonly required: false;
+    };
+};
+/**
+ * @function osuProfileToUser
+ * @param raw {unknown} the /api/v2/me profile better-auth fetched
+ * @returns the better-auth user fields. osu! OAuth returns no email, so each osu! id gets a stable
+ *          synthetic one (the adapter requires an email). better-auth wants image left out, not
+ *          null, when there is no avatar.
+ * @throws {z.ZodError} when the profile has no id or username (never guess an identity)
+ */
+export declare const osuProfileToUser: (raw: unknown) => {
+    osuId: number;
+    username: string;
+    avatarUrl: string | null;
+    countryCode: string | null;
+    email: string;
+    emailVerified: false;
+    name: string;
+    image?: string;
+};
+/**
+ * @function withoutTokens
+ * @param account {T} an account write
+ * @returns {T} the same fields with accessToken, refreshToken and idToken null: neither app calls
+ *          osu! as the user, so none keeps osu! tokens
+ */
+export declare const withoutTokens: <T extends Record<string, unknown>>(account: T) => T;
+/** osuProvider's input: the osu! OAuth app's credentials. */
+export type OsuProviderOptions = {
+    clientId: string;
+    clientSecret: string;
+};
+/**
+ * @function osuProvider
+ * @param options {OsuProviderOptions} the osu! app's client id and secret
+ * @returns the genericOAuth config entry for osu!: identify + public scopes, PKCE, the profile
+ *          mapped with osuProfileToUser and refreshed on every sign-in
+ */
+export declare const osuProvider: ({ clientId, clientSecret }: OsuProviderOptions) => {
+    authorizationUrl: "https://osu.ppy.sh/oauth/authorize";
+    tokenUrl: "https://osu.ppy.sh/oauth/token";
+    userInfoUrl: "https://osu.ppy.sh/api/v2/me";
+    providerId: string;
+    clientId: string;
+    clientSecret: string;
+    scopes: ("identify" | "public")[];
+    pkce: boolean;
+    overrideUserInfo: boolean;
+    mapProfileToUser: typeof osuProfileToUser;
+};

package/dist/auth/osu.js

@@ -0,0 +1,67 @@
+/**
+ * @file src/auth/osu.ts
+ * @desc The osu! pieces of better-auth: the provider id, the extra user fields, the profile
+ *       mapping (through @haruhimemoe/osu's toOsuUser, with a synthetic email since osu! gives
+ *       none), the genericOAuth provider config (identify + public, PKCE, profile refreshed on
+ *       every sign-in), and dropping OAuth tokens from account writes. Moved from packs and
+ *       pools (src/lib/auth.ts, src/constants/auth.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { OSU_OAUTH, OSU_SIGN_IN_SCOPES, toOsuUser } from "@haruhimemoe/osu/shapes";
+import { OSU_PROVIDER_ID } from "./osu-id.js";
+export { OSU_PROVIDER_ID };
+/** The fields osu! fills in on every user row. */
+export const OSU_USER_FIELDS = {
+    osuId: { type: "number", required: true },
+    username: { type: "string", required: true },
+    avatarUrl: { type: "string", required: false },
+    countryCode: { type: "string", required: false },
+};
+/**
+ * @function osuProfileToUser
+ * @param raw {unknown} the /api/v2/me profile better-auth fetched
+ * @returns the better-auth user fields. osu! OAuth returns no email, so each osu! id gets a stable
+ *          synthetic one (the adapter requires an email). better-auth wants image left out, not
+ *          null, when there is no avatar.
+ * @throws {z.ZodError} when the profile has no id or username (never guess an identity)
+ */
+export const osuProfileToUser = (raw) => {
+    const user = toOsuUser(raw);
+    return {
+        email: `${user.osuId}@osu.local`,
+        emailVerified: false,
+        name: user.username,
+        ...user,
+        ...(user.avatarUrl ? { image: user.avatarUrl } : {}),
+    };
+};
+/**
+ * @function withoutTokens
+ * @param account {T} an account write
+ * @returns {T} the same fields with accessToken, refreshToken and idToken null: neither app calls
+ *          osu! as the user, so none keeps osu! tokens
+ */
+export const withoutTokens = (account) => ({
+    ...account,
+    accessToken: null,
+    refreshToken: null,
+    idToken: null,
+});
+/**
+ * @function osuProvider
+ * @param options {OsuProviderOptions} the osu! app's client id and secret
+ * @returns the genericOAuth config entry for osu!: identify + public scopes, PKCE, the profile
+ *          mapped with osuProfileToUser and refreshed on every sign-in
+ */
+export const osuProvider = ({ clientId, clientSecret }) => ({
+    providerId: OSU_PROVIDER_ID,
+    clientId,
+    clientSecret,
+    ...OSU_OAUTH,
+    scopes: [...OSU_SIGN_IN_SCOPES],
+    pkce: true,
+    overrideUserInfo: true,
+    mapProfileToUser: osuProfileToUser,
+});

package/dist/auth/session.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file src/auth/session.ts
+ * @desc Reading the caller from a request's session cookie. Route handlers pass
+ *       request.headers; server pages pass await headers(). Apps add their own rules on top
+ *       (an admin list, refusing system accounts). Moved from packs and pools
+ *       (getUserFromHeaders in src/lib/auth.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The signed-in osu! user, as both apps pass it around. */
+export type OsuSessionUser = {
+    id: string;
+    osuId: number;
+    username: string;
+    avatarUrl: string | null;
+};
+/** A session as better-auth returns it with the osu! user fields. */
+export type OsuSession = {
+    user: {
+        id: string;
+        osuId: number;
+        username: string;
+        avatarUrl?: string | null | undefined;
+    };
+};
+/** What getOsuUser needs from a better-auth instance. */
+export type SessionReader = {
+    api: {
+        getSession: (input: {
+            headers: Headers;
+        }) => Promise<OsuSession | null>;
+    };
+};
+/**
+ * @function toSessionUser
+ * @param session {OsuSession} a session better-auth returned
+ * @returns {OsuSessionUser} id, osu! id, username and avatar (null when there is none)
+ */
+export declare const toSessionUser: ({ user }: OsuSession) => OsuSessionUser;
+/**
+ * @function getOsuUser
+ * @param auth {SessionReader} the better-auth instance (createOsuAuth's)
+ * @param headers {Headers} request headers (the session cookie)
+ * @returns {Promise<OsuSessionUser | null>} the signed-in user, or null (no, forged or expired
+ *          session)
+ */
+export declare const getOsuUser: (auth: SessionReader, headers: Headers) => Promise<OsuSessionUser | null>;

package/dist/auth/session.js

@@ -0,0 +1,32 @@
+/**
+ * @file src/auth/session.ts
+ * @desc Reading the caller from a request's session cookie. Route handlers pass
+ *       request.headers; server pages pass await headers(). Apps add their own rules on top
+ *       (an admin list, refusing system accounts). Moved from packs and pools
+ *       (getUserFromHeaders in src/lib/auth.ts).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/**
+ * @function toSessionUser
+ * @param session {OsuSession} a session better-auth returned
+ * @returns {OsuSessionUser} id, osu! id, username and avatar (null when there is none)
+ */
+export const toSessionUser = ({ user }) => ({
+    id: user.id,
+    osuId: user.osuId,
+    username: user.username,
+    avatarUrl: user.avatarUrl ?? null,
+});
+/**
+ * @function getOsuUser
+ * @param auth {SessionReader} the better-auth instance (createOsuAuth's)
+ * @param headers {Headers} request headers (the session cookie)
+ * @returns {Promise<OsuSessionUser | null>} the signed-in user, or null (no, forged or expired
+ *          session)
+ */
+export const getOsuUser = async (auth, headers) => {
+    const session = await auth.api.getSession({ headers });
+    return session ? toSessionUser(session) : null;
+};

package/dist/auth-react/RestoreSignedIn.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file src/auth-react/RestoreSignedIn.tsx
+ * @desc For pages that know on the server that the visitor is signed in (the sign-in page with a
+ *       session, an account page): if this browser has no signed-in marker (a session from before
+ *       the marker existed, or a cleared cookie), ask for the session once, which sets the marker
+ *       and fixes the header. With `next`, the sign-in page then continues there. Moved from packs
+ *       and pools (src/components/auth/RestoreSignedIn.tsx, body-identical).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type ReactNode } from "react";
+/** RestoreSignedIn's props. */
+export type RestoreSignedInProps = {
+    /** The page-wide account store (createAccount's `store`). */
+    store: {
+        recheck: () => Promise<void>;
+    };
+    /** The app's marker check (createSignedInMarker's `has`). */
+    hasMarker: (cookieHeader: string) => boolean;
+    /** Where to go once the session is restored (the sign-in page's `next`). */
+    next?: string;
+    /** Shown while it goes on to `next`. */
+    pending?: ReactNode;
+    /** Test seam (default: document.cookie). */
+    readCookie?: () => string;
+};
+/**
+ * @function RestoreSignedIn
+ * @param props {RestoreSignedInProps} the store, the marker check, `next` and what to show
+ * @returns {ReactNode} nothing without `next`; `pending` while it goes on to `next`
+ */
+export declare function RestoreSignedIn({ store, hasMarker, next, pending, readCookie, }: RestoreSignedInProps): ReactNode;

package/dist/auth-react/RestoreSignedIn.js

@@ -0,0 +1,38 @@
+/**
+ * @file src/auth-react/RestoreSignedIn.tsx
+ * @desc For pages that know on the server that the visitor is signed in (the sign-in page with a
+ *       session, an account page): if this browser has no signed-in marker (a session from before
+ *       the marker existed, or a cleared cookie), ask for the session once, which sets the marker
+ *       and fixes the header. With `next`, the sign-in page then continues there. Moved from packs
+ *       and pools (src/components/auth/RestoreSignedIn.tsx, body-identical).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRouter } from "next/navigation.js";
+import { useEffect } from "react";
+const readDocumentCookie = () => document.cookie;
+const SIGNING_IN = _jsx("p", { className: "text-c3 text-sm", children: "Signing you in\u2026" });
+/**
+ * @function RestoreSignedIn
+ * @param props {RestoreSignedInProps} the store, the marker check, `next` and what to show
+ * @returns {ReactNode} nothing without `next`; `pending` while it goes on to `next`
+ */
+export function RestoreSignedIn({ store, hasMarker, next, pending = SIGNING_IN, readCookie = readDocumentCookie, }) {
+    const router = useRouter();
+    useEffect(() => {
+        if (next === undefined && hasMarker(readCookie()))
+            return;
+        let live = true;
+        store.recheck().then(() => {
+            if (live && next !== undefined)
+                router.replace(next);
+        });
+        return () => {
+            live = false;
+        };
+    }, [next, store, hasMarker, readCookie, router]);
+    return next === undefined ? null : pending;
+}

package/dist/auth-react/account-store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file src/auth-react/account-store.ts
+ * @desc Who is signed in, for a header's account menu. The store asks the server only when the
+ *       readable signed-in marker is present, once per page load, so anonymous visitors cost no
+ *       request; another tab signing in or out is caught up when this one is shown again, at a
+ *       request only when the marker changed. markSignedOut() updates every subscriber at once.
+ *       Moved from packs and pools (src/hooks/useAccount.ts, body-identical).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The account as the page sees it. */
+export type Account = {
+    status: "loading";
+} | {
+    status: "signed-out";
+} | {
+    status: "signed-in";
+    user: {
+        id: string;
+        username: string;
+        avatarUrl: string | null;
+    };
+};
+/** The part of a better-auth session the store reads. */
+export type SessionData = {
+    user: {
+        id: string;
+        username: string;
+        avatarUrl?: string | null;
+    };
+};
+/** What the store needs: a session fetch, a cookie read and a marker clear (tests pass fakes). */
+export type AccountDeps = {
+    getSession: () => Promise<SessionData | null>;
+    readCookie: () => string;
+    hasMarker: (cookieHeader: string) => boolean;
+    clearMarker: () => void;
+};
+/** A useSyncExternalStore store of the account. */
+export type AccountStore = {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => Account;
+    markSignedOut: () => void;
+    /** Ask the server even without the marker (pages that know the user is signed in). */
+    recheck: () => Promise<void>;
+};
+/** Before the first answer, and during server render. */
+export declare const LOADING: Account;
+/**
+ * @function createAccountStore
+ * @param deps {AccountDeps} session fetch, cookie read, marker check and clear
+ * @returns {AccountStore} starts on the first subscription
+ */
+export declare const createAccountStore: ({ getSession, readCookie, hasMarker, clearMarker, }: AccountDeps) => AccountStore;

package/dist/auth-react/account-store.js

@@ -0,0 +1,78 @@
+/**
+ * @file src/auth-react/account-store.ts
+ * @desc Who is signed in, for a header's account menu. The store asks the server only when the
+ *       readable signed-in marker is present, once per page load, so anonymous visitors cost no
+ *       request; another tab signing in or out is caught up when this one is shown again, at a
+ *       request only when the marker changed. markSignedOut() updates every subscriber at once.
+ *       Moved from packs and pools (src/hooks/useAccount.ts, body-identical).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** Before the first answer, and during server render. */
+export const LOADING = Object.freeze({ status: "loading" });
+const SIGNED_OUT = Object.freeze({ status: "signed-out" });
+/**
+ * @function createAccountStore
+ * @param deps {AccountDeps} session fetch, cookie read, marker check and clear
+ * @returns {AccountStore} starts on the first subscription
+ */
+export const createAccountStore = ({ getSession, readCookie, hasMarker, clearMarker, }) => {
+    let state = LOADING;
+    let started = false;
+    const listeners = new Set();
+    const set = (next) => {
+        state = next;
+        for (const listener of listeners)
+            listener();
+    };
+    // Asks the server; a session there also (re)sets the marker cookie.
+    const load = () => getSession().then((data) => {
+        if (!data) {
+            clearMarker();
+            set(SIGNED_OUT);
+            return;
+        }
+        const { id, username, avatarUrl } = data.user;
+        set({ status: "signed-in", user: { id, username, avatarUrl: avatarUrl ?? null } });
+    }, () => set(SIGNED_OUT));
+    const sync = () => {
+        if (document.visibilityState === "hidden")
+            return;
+        const marked = hasMarker(readCookie());
+        if (!marked && state.status === "signed-in")
+            set(SIGNED_OUT);
+        else if (marked && state.status === "signed-out")
+            void load();
+    };
+    const start = () => {
+        if (started)
+            return;
+        started = true;
+        if (typeof document !== "undefined")
+            document.addEventListener("visibilitychange", sync);
+        if (!hasMarker(readCookie())) {
+            set(SIGNED_OUT);
+            return;
+        }
+        void load();
+    };
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            start();
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot: () => state,
+        markSignedOut: () => {
+            clearMarker();
+            set(SIGNED_OUT);
+        },
+        recheck: () => {
+            started = true;
+            return load();
+        },
+    };
+};

package/dist/auth-react/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file src/auth-react/index.ts
+ * @desc @haruhimemoe/next-kit/auth-react: the browser side of osu! sign-in. The signed-in marker
+ *       cookie, the account store and useAccount, RestoreSignedIn, what the sign-in button
+ *       sends, and where to go after sign-in. No "use client" here: the hook and component
+ *       files carry it, so a server page can still call safeNextPath from this entry point.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { OSU_PROVIDER_ID } from "../auth/osu-id.js";
+export { DEFAULT_SIGN_IN_PATH, type SafeNextOptions, safeNextPath, signInHref, } from "../server/safe-next.js";
+export { type Account, type AccountDeps, type AccountStore, createAccountStore, LOADING, type SessionData, } from "./account-store.js";
+export { createSignedInMarker, markerMaxAge, type SignedInMarker } from "./marker.js";
+export { RestoreSignedIn, type RestoreSignedInProps } from "./RestoreSignedIn.js";
+export { type OsuSignIn, osuSignIn } from "./sign-in.js";
+export { type AccountKit, type BoundRestoreProps, createAccount, type SessionClient, sessionFetcher, useAccount, } from "./use-account.js";

package/dist/auth-react/index.js

@@ -0,0 +1,17 @@
+/**
+ * @file src/auth-react/index.ts
+ * @desc @haruhimemoe/next-kit/auth-react: the browser side of osu! sign-in. The signed-in marker
+ *       cookie, the account store and useAccount, RestoreSignedIn, what the sign-in button
+ *       sends, and where to go after sign-in. No "use client" here: the hook and component
+ *       files carry it, so a server page can still call safeNextPath from this entry point.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { OSU_PROVIDER_ID } from "../auth/osu-id.js";
+export { DEFAULT_SIGN_IN_PATH, safeNextPath, signInHref, } from "../server/safe-next.js";
+export { createAccountStore, LOADING, } from "./account-store.js";
+export { createSignedInMarker, markerMaxAge } from "./marker.js";
+export { RestoreSignedIn } from "./RestoreSignedIn.js";
+export { osuSignIn } from "./sign-in.js";
+export { createAccount, sessionFetcher, useAccount, } from "./use-account.js";

package/dist/auth-react/marker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file src/auth-react/marker.ts
+ * @desc A readable "this browser may be signed in" cookie. It holds no secret; it only tells the
+ *       page whether asking the server for the session is worth a request, so visitors who never
+ *       sign in cost none. The server sets it with the session and clears it on sign-out or a
+ *       missing session (createOsuAuth in @haruhimemoe/next-kit/auth). Browser-safe. Moved from
+ *       packs and pools (src/lib/signed-in-marker.ts), which differed only in the cookie name.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The marker for one cookie name. */
+export type SignedInMarker = {
+    /** The cookie's name, like "pools-signed-in". */
+    name: string;
+    /** True when a Cookie header (or document.cookie) has the marker set. */
+    has: (cookieHeader: string) => boolean;
+    /** Expires the marker on a document (tests pass a stand-in). */
+    clear: (target?: {
+        cookie: string;
+    }) => void;
+};
+/**
+ * @function markerMaxAge
+ * @param expiresAt {Date | string} when the session expires
+ * @param now {number} current time in ms (tests)
+ * @returns {number} whole seconds until then, at least 0
+ */
+export declare const markerMaxAge: (expiresAt: Date | string, now?: number) => number;
+/**
+ * @function createSignedInMarker
+ * @param name {string} the cookie's name, one per app
+ * @returns {SignedInMarker} has and clear for that cookie
+ */
+export declare const createSignedInMarker: (name: string) => SignedInMarker;

package/dist/auth-react/marker.js

@@ -0,0 +1,30 @@
+/**
+ * @file src/auth-react/marker.ts
+ * @desc A readable "this browser may be signed in" cookie. It holds no secret; it only tells the
+ *       page whether asking the server for the session is worth a request, so visitors who never
+ *       sign in cost none. The server sets it with the session and clears it on sign-out or a
+ *       missing session (createOsuAuth in @haruhimemoe/next-kit/auth). Browser-safe. Moved from
+ *       packs and pools (src/lib/signed-in-marker.ts), which differed only in the cookie name.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/**
+ * @function markerMaxAge
+ * @param expiresAt {Date | string} when the session expires
+ * @param now {number} current time in ms (tests)
+ * @returns {number} whole seconds until then, at least 0
+ */
+export const markerMaxAge = (expiresAt, now = Date.now()) => Math.max(0, Math.floor((new Date(expiresAt).getTime() - now) / 1000));
+/**
+ * @function createSignedInMarker
+ * @param name {string} the cookie's name, one per app
+ * @returns {SignedInMarker} has and clear for that cookie
+ */
+export const createSignedInMarker = (name) => ({
+    name,
+    has: (cookieHeader) => cookieHeader.split(/;\s*/).includes(`${name}=1`),
+    clear: (target = document) => {
+        target.cookie = `${name}=; Path=/; Max-Age=0; SameSite=Lax`;
+    },
+});

package/dist/auth-react/sign-in.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file src/auth-react/sign-in.ts
+ * @desc What a "Sign in with osu!" button sends better-auth: the provider, where to land, and an
+ *       error page that keeps `next`, so a failed sign-in explains itself and can still go on
+ *       (better-auth adds &error=<code>). pools did this; packs sent /signin?error=oauth and
+ *       lost `next`.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The body of authClient.signIn.social for osu!. */
+export type OsuSignIn = {
+    provider: string;
+    callbackURL: string;
+    errorCallbackURL: string;
+};
+/**
+ * @function osuSignIn
+ * @param next {string} where to land after signing in (already checked with safeNextPath)
+ * @param signInPath {string} the sign-in page (default /signin)
+ * @returns {OsuSignIn} { provider: "osu", callbackURL: next, errorCallbackURL:
+ *          "/signin?next=<next>" }
+ */
+export declare const osuSignIn: (next: string, signInPath?: string) => OsuSignIn;

package/dist/auth-react/sign-in.js

@@ -0,0 +1,24 @@
+/**
+ * @file src/auth-react/sign-in.ts
+ * @desc What a "Sign in with osu!" button sends better-auth: the provider, where to land, and an
+ *       error page that keeps `next`, so a failed sign-in explains itself and can still go on
+ *       (better-auth adds &error=<code>). pools did this; packs sent /signin?error=oauth and
+ *       lost `next`.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { OSU_PROVIDER_ID } from "../auth/osu-id.js";
+import { DEFAULT_SIGN_IN_PATH, signInHref } from "../server/safe-next.js";
+/**
+ * @function osuSignIn
+ * @param next {string} where to land after signing in (already checked with safeNextPath)
+ * @param signInPath {string} the sign-in page (default /signin)
+ * @returns {OsuSignIn} { provider: "osu", callbackURL: next, errorCallbackURL:
+ *          "/signin?next=<next>" }
+ */
+export const osuSignIn = (next, signInPath = DEFAULT_SIGN_IN_PATH) => ({
+    provider: OSU_PROVIDER_ID,
+    callbackURL: next,
+    errorCallbackURL: signInHref(next, signInPath),
+});

package/dist/auth-react/use-account.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file src/auth-react/use-account.ts
+ * @desc The React side of the account store: useAccount (loading during server render), and
+ *       createAccount, which wires a store to a better-auth client and the app's marker cookie
+ *       the way packs and pools each did at the bottom of src/hooks/useAccount.ts.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type ReactNode } from "react";
+import { type Account, type AccountStore, type SessionData } from "./account-store.js";
+import type { SignedInMarker } from "./marker.js";
+/** The part of a better-auth client the store calls. */
+export type SessionClient = {
+    getSession: () => Promise<{
+        data?: unknown;
+        error?: unknown;
+    }>;
+};
+/**
+ * @function sessionFetcher
+ * @param client {SessionClient} the app's better-auth client
+ * @returns {() => Promise<SessionData | null>} a getSession that throws better-auth's error
+ */
+export declare const sessionFetcher: (client: SessionClient) => () => Promise<SessionData | null>;
+/**
+ * @function useAccount
+ * @param store {AccountStore} the page-wide store
+ * @returns {Account} current account state ("loading" during server render)
+ */
+export declare const useAccount: (store: AccountStore) => Account;
+/** RestoreSignedIn with the store and marker already bound: what a server page can render. */
+export type BoundRestoreProps = {
+    next?: string;
+    pending?: ReactNode;
+};
+/** What createAccount returns: the store, and the hook, sign-out and component bound to it. */
+export type AccountKit = {
+    store: AccountStore;
+    useAccount: () => Account;
+    markSignedOut: () => void;
+    RestoreSignedIn: (props: BoundRestoreProps) => ReactNode;
+};
+/**
+ * @function createAccount
+ * @param client {SessionClient} the app's better-auth client
+ * @param marker {SignedInMarker} the app's signed-in marker
+ * @returns {AccountKit} a page-wide store reading document.cookie, with its hook, sign-out and
+ *          RestoreSignedIn (export them from the app's own "use client" module, so server pages
+ *          render <RestoreSignedIn next={next} /> with only serializable props)
+ */
+export declare const createAccount: (client: SessionClient, marker: SignedInMarker) => AccountKit;