@lalternative/auth 0.4.0 → 0.4.2

package/README.md

@@ -3,7 +3,8 @@
 Shared [Better Auth](https://better-auth.com) wrapper for L'Alternative apps.
 
 Provides platform auth defaults (email-OTP + admin plugins), a React client,
-and the auth UI forms (verify-email, forgot/reset password, auth layout).
+and the auth UI forms (login, register, verify-email, forgot/reset password,
+auth layout).
 
 ## Install
 
@@ -32,7 +33,7 @@ export const authClient = createPlatformAuthClient({ baseURL })
 
 ```tsx
 // UI + hooks
-import { VerifyEmailForm, ForgotPasswordForm, ResetPasswordForm, AuthLayout, useSession, useLogout } from "@lalternative/auth"
+import { LoginForm, RegisterForm, SocialButtons, VerifyEmailForm, ForgotPasswordForm, ResetPasswordForm, AuthLayout, useSession, useLogout } from "@lalternative/auth"
 ```
 
 ### Invitations

package/dist/chunk-73BHM4PZ.js

@@ -0,0 +1,72 @@
+// src/invitation.ts
+var OUTCOME_BY_STATUS = {
+  404: "unknown",
+  409: "claimed",
+  410: "expired"
+};
+async function claimInvitation({
+  endpoint,
+  token,
+  externalUserId,
+  apiKey,
+  extra,
+  headers,
+  timeoutMs = 5e3
+}) {
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+        ...headers
+      },
+      body: JSON.stringify({
+        token,
+        external_user_id: externalUserId,
+        ...extra
+      }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (res.ok) return "granted";
+    return OUTCOME_BY_STATUS[res.status] ?? "failed";
+  } catch {
+    return "failed";
+  }
+}
+function inviteTokenFrom(request, param = "invite") {
+  const direct = new URL(request.url).searchParams.get(param);
+  if (direct && direct.trim() !== "") return direct;
+  const referer = request.headers.get("referer");
+  if (!referer) return null;
+  try {
+    const token = new URL(referer).searchParams.get(param);
+    return token && token.trim() !== "" ? token : null;
+  } catch {
+    return null;
+  }
+}
+var SIGNUP_COMPLETING = [
+  "/sign-up/email",
+  "/sign-in/email-otp",
+  "/email-otp/verify-email",
+  "/callback/"
+];
+function completesSignup(pathname) {
+  return SIGNUP_COMPLETING.some((p) => pathname.includes(p));
+}
+function invitationOutcomeCookie(outcome, name = "invite_claim") {
+  return `${name}=${outcome}; Path=/; Max-Age=120; SameSite=Lax`;
+}
+function isInvitationFailure(outcome) {
+  return outcome === "expired" || outcome === "claimed" || outcome === "unknown";
+}
+
+export {
+  claimInvitation,
+  inviteTokenFrom,
+  completesSignup,
+  invitationOutcomeCookie,
+  isInvitationFailure
+};
+//# sourceMappingURL=chunk-73BHM4PZ.js.map

package/dist/chunk-73BHM4PZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/invitation.ts"],"sourcesContent":["import type { InvitationFailure } from \"./types\"\n\n/**\n * What became of a claim, in terms the invitee can be told.\n *\n * 'expired' and 'claimed' are kept apart from 'unknown' because only they say\n * the offer was real, which is what tells someone that asking for a new link is\n * worth it rather than doubting the address they were invited at. The three\n * failures match InvitationFailure, so an outcome feeds InvitationNotice\n * directly.\n */\nexport type ClaimOutcome = \"granted\" | InvitationFailure | \"failed\"\n\nconst OUTCOME_BY_STATUS: Record<number, ClaimOutcome> = {\n  404: \"unknown\",\n  409: \"claimed\",\n  410: \"expired\",\n}\n\nexport interface ClaimInvitationOptions {\n  /** Absolute URL of the endpoint that redeems a token. */\n  endpoint: string\n  token: string\n  /** The account the app just created, which the grant is attached to. */\n  externalUserId: string\n  /** Sent as the Authorization bearer — typically the app's API key. */\n  apiKey?: string\n  /** Merged into the request body, for backends wanting more than the token. */\n  extra?: Record<string, unknown>\n  /** Headers merged last, so a caller can pass a cookie-based credential. */\n  headers?: Record<string, string>\n  /** Bounds the call so a slow API never stalls the sign-in response. */\n  timeoutMs?: number\n}\n\n/**\n * Redeems an invitation token for a user who has just signed in, turning the\n * offer into a grant on their account.\n *\n * Why this belongs on the SERVER, on the auth callback rather than in the page:\n * the invitation link lands on /register?invite=<token>, but the sign-up that\n * follows can complete through any of three flows (password + OTP, OAuth\n * redirect, email verification), and only two of them return to the page that\n * held the token. Claiming where the session is established covers every flow\n * with one code path.\n *\n * Best-effort by design: a sign-in must never fail because an invitation could\n * not be redeemed. A failed claim leaves the invitation unclaimed and the user\n * on their default tier — recoverable by following the link again, since a\n * refused claim consumes nothing.\n */\nexport async function claimInvitation({\n  endpoint,\n  token,\n  externalUserId,\n  apiKey,\n  extra,\n  headers,\n  timeoutMs = 5000,\n}: ClaimInvitationOptions): Promise<ClaimOutcome> {\n  try {\n    const res = await fetch(endpoint, {\n      method: \"POST\",\n      headers: {\n        \"content-type\": \"application/json\",\n        ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),\n        ...headers,\n      },\n      body: JSON.stringify({\n        token,\n        external_user_id: externalUserId,\n        ...extra,\n      }),\n      signal: AbortSignal.timeout(timeoutMs),\n    })\n\n    if (res.ok) return \"granted\"\n    return OUTCOME_BY_STATUS[res.status] ?? \"failed\"\n  } catch {\n    return \"failed\"\n  }\n}\n\n/**\n * Extracts the invitation token from an auth request.\n *\n * The token lives on the page the invitee landed on (/register?invite=…), never\n * on the auth endpoints themselves, so it has to be recovered from the request\n * that completes the sign-up. Two sources, because no single one covers every\n * flow: the URL, for the OAuth callback reached through a redirect whose query\n * string the app controls; and the Referer, for the password and OTP flows,\n * which are XHR calls issued BY that page and therefore carry it.\n *\n * Reading it per-request keeps the claim stateless: nothing associates a\n * browser with a pending invitation, and a request with no token claims\n * nothing. A malformed Referer is ignored rather than thrown on — it is\n * attacker-controlled input on a best-effort path.\n */\nexport function inviteTokenFrom(\n  request: Request,\n  param = \"invite\",\n): string | null {\n  const direct = new URL(request.url).searchParams.get(param)\n  if (direct && direct.trim() !== \"\") return direct\n\n  const referer = request.headers.get(\"referer\")\n  if (!referer) return null\n  try {\n    const token = new URL(referer).searchParams.get(param)\n    return token && token.trim() !== \"\" ? token : null\n  } catch {\n    return null\n  }\n}\n\n/**\n * BetterAuth paths that complete a sign-up. Email/password returns the user\n * straight from sign-up/email; the OTP and OAuth flows only produce a usable\n * account once the verification/callback succeeds, so those are the moments\n * worth reacting to.\n */\nconst SIGNUP_COMPLETING = [\n  \"/sign-up/email\",\n  \"/sign-in/email-otp\",\n  \"/email-otp/verify-email\",\n  \"/callback/\",\n]\n\n/**\n * Whether this request is the one that just created a usable account — the\n * moment to provision, claim an invitation, or greet someone. Matching on the\n * path rather than on a response body keeps it flow-agnostic: the three\n * sign-up flows return three different shapes.\n */\nexport function completesSignup(pathname: string): boolean {\n  return SIGNUP_COMPLETING.some((p) => pathname.includes(p))\n}\n\n/**\n * Carries a failed claim to the next page. The claim happens inside an auth\n * response nobody renders, so its result would otherwise reach only the server\n * log — leaving an invitee on the default tier with no idea their link had\n * lapsed. Short-lived and readable by the page, which reports it and clears it.\n */\nexport function invitationOutcomeCookie(\n  outcome: ClaimOutcome,\n  name = \"invite_claim\",\n): string {\n  return `${name}=${outcome}; Path=/; Max-Age=120; SameSite=Lax`\n}\n\n/**\n * Whether an outcome is one the invitee should be shown a reason for.\n * 'failed' is excluded: it means the call did not complete, so the offer may\n * still be good and telling someone their invitation is invalid would be wrong.\n */\nexport function isInvitationFailure(\n  outcome: ClaimOutcome,\n): outcome is InvitationFailure {\n  return outcome === \"expired\" || outcome === \"claimed\" || outcome === \"unknown\"\n}\n"],"mappings":";AAaA,IAAM,oBAAkD;AAAA,EACtD,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AACP;AAkCA,eAAsB,gBAAgB;AAAA,EACpC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AACd,GAAkD;AAChD,MAAI;AACF,UAAM,MAAM,MAAM,MAAM,UAAU;AAAA,MAChC,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,QAChB,GAAI,SAAS,EAAE,eAAe,UAAU,MAAM,GAAG,IAAI,CAAC;AAAA,QACtD,GAAG;AAAA,MACL;AAAA,MACA,MAAM,KAAK,UAAU;AAAA,QACnB;AAAA,QACA,kBAAkB;AAAA,QAClB,GAAG;AAAA,MACL,CAAC;AAAA,MACD,QAAQ,YAAY,QAAQ,SAAS;AAAA,IACvC,CAAC;AAED,QAAI,IAAI,GAAI,QAAO;AACnB,WAAO,kBAAkB,IAAI,MAAM,KAAK;AAAA,EAC1C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAiBO,SAAS,gBACd,SACA,QAAQ,UACO;AACf,QAAM,SAAS,IAAI,IAAI,QAAQ,GAAG,EAAE,aAAa,IAAI,KAAK;AAC1D,MAAI,UAAU,OAAO,KAAK,MAAM,GAAI,QAAO;AAE3C,QAAM,UAAU,QAAQ,QAAQ,IAAI,SAAS;AAC7C,MAAI,CAAC,QAAS,QAAO;AACrB,MAAI;AACF,UAAM,QAAQ,IAAI,IAAI,OAAO,EAAE,aAAa,IAAI,KAAK;AACrD,WAAO,SAAS,MAAM,KAAK,MAAM,KAAK,QAAQ;AAAA,EAChD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQA,IAAM,oBAAoB;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAQO,SAAS,gBAAgB,UAA2B;AACzD,SAAO,kBAAkB,KAAK,CAAC,MAAM,SAAS,SAAS,CAAC,CAAC;AAC3D;AAQO,SAAS,wBACd,SACA,OAAO,gBACC;AACR,SAAO,GAAG,IAAI,IAAI,OAAO;AAC3B;AAOO,SAAS,oBACd,SAC8B;AAC9B,SAAO,YAAY,aAAa,YAAY,aAAa,YAAY;AACvE;","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import * as better_auth_react from 'better-auth/react';
+import { P as PlatformAuthClientConfig } from './types-DxllDyOa.js';
+import 'better-auth';
+
+/**
+ * Creates a Better Auth client for React usage.
+ * Provides useSession() hook and other React-integrated methods.
+ */
+declare function createPlatformAuthClient(config?: PlatformAuthClientConfig): better_auth_react.ReactAuthClient<{
+    baseURL: string;
+    plugins: any[];
+}>;
+type PlatformAuthClient = ReturnType<typeof createPlatformAuthClient>;
+
+export { type PlatformAuthClient, createPlatformAuthClient };

package/dist/client.js

@@ -0,0 +1,13 @@
+// src/client.ts
+import { createAuthClient } from "better-auth/react";
+import { emailOTPClient, adminClient } from "better-auth/client/plugins";
+function createPlatformAuthClient(config) {
+  return createAuthClient({
+    baseURL: config?.baseURL ?? (typeof window !== "undefined" ? window.location.origin : "http://localhost:3000"),
+    plugins: [emailOTPClient(), adminClient(), ...config?.plugins ?? []]
+  });
+}
+export {
+  createPlatformAuthClient
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import { createAuthClient } from \"better-auth/react\"\nimport { emailOTPClient, adminClient } from \"better-auth/client/plugins\"\nimport type { PlatformAuthClientConfig } from \"./types\"\n\n/**\n * Creates a Better Auth client for React usage.\n * Provides useSession() hook and other React-integrated methods.\n */\nexport function createPlatformAuthClient(config?: PlatformAuthClientConfig) {\n  return createAuthClient({\n    baseURL:\n      config?.baseURL ??\n      (typeof window !== \"undefined\"\n        ? window.location.origin\n        : \"http://localhost:3000\"),\n    plugins: [emailOTPClient(), adminClient(), ...(config?.plugins ?? [])],\n  })\n}\n\nexport type PlatformAuthClient = ReturnType<typeof createPlatformAuthClient>\n"],"mappings":";AAAA,SAAS,wBAAwB;AACjC,SAAS,gBAAgB,mBAAmB;AAOrC,SAAS,yBAAyB,QAAmC;AAC1E,SAAO,iBAAiB;AAAA,IACtB,SACE,QAAQ,YACP,OAAO,WAAW,cACf,OAAO,SAAS,SAChB;AAAA,IACN,SAAS,CAAC,eAAe,GAAG,YAAY,GAAG,GAAI,QAAQ,WAAW,CAAC,CAAE;AAAA,EACvE,CAAC;AACH;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { L as LoginFormProps, R as RegisterFormProps, V as VerifyEmailFormProps, F as ForgotPasswordFormProps, a as ResetPasswordFormProps, A as AuthLayoutProps, I as InvitationNoticeProps } from './types-DxllDyOa.js';
+export { b as InvitationFailure, P as PlatformAuthClientConfig, c as PlatformAuthConfig, d as PlatformAuthMailer, e as PlatformAuthMailerArgs, f as PlatformAuthMailerType, g as PlatformSession, h as PlatformSessionData, i as PlatformUser } from './types-DxllDyOa.js';
+import * as better_auth_react from 'better-auth/react';
+import * as better_auth from 'better-auth';
+import { PlatformAuthClient } from './client.js';
+import * as react from 'react';
+export { C as ClaimOutcome, i as isInvitationFailure } from './invitation-CzfLna7q.js';
+
+/**
+ * Returns a useSession hook bound to the given auth client.
+ * Usage: const { data: session, isPending } = useSession(authClient)
+ */
+declare function useSession(authClient: PlatformAuthClient): {
+    data: {
+        user: better_auth.StripEmptyObjects<{
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            email: string;
+            emailVerified: boolean;
+            name: string;
+            image?: string | null | undefined;
+        }>;
+        session: better_auth.StripEmptyObjects<{
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            userId: string;
+            expiresAt: Date;
+            token: string;
+            ipAddress?: string | null | undefined;
+            userAgent?: string | null | undefined;
+        }>;
+    } | null;
+    isPending: boolean;
+    isRefetching: boolean;
+    error: better_auth_react.BetterFetchError | null;
+    refetch: (queryParams?: {
+        query?: better_auth.SessionQueryParams;
+    } | undefined) => Promise<void>;
+};
+/**
+ * Returns a logout function bound to the given auth client.
+ * Usage: const logout = useLogout(authClient)
+ */
+declare function useLogout(authClient: PlatformAuthClient): () => Promise<void>;
+
+declare function LoginForm({ onSuccess, registerUrl, forgotPasswordUrl, socialCallbackUrl, socialProviders, coreTokenUrl, authClient, }: LoginFormProps): react.JSX.Element;
+
+declare function RegisterForm({ onSuccess, loginUrl, legal, socialCallbackUrl, socialProviders, authClient, }: RegisterFormProps): react.JSX.Element;
+
+interface SocialButtonsProps {
+    providers: Array<"google" | "github">;
+    onSelect: (provider: "google" | "github") => void | Promise<void>;
+    disabled?: boolean;
+}
+declare function SocialButtons({ providers, onSelect, disabled, }: SocialButtonsProps): react.JSX.Element | null;
+
+declare function VerifyEmailForm({ email, onSuccess, authClient, }: VerifyEmailFormProps): react.JSX.Element;
+
+declare function ForgotPasswordForm({ onSuccess, loginUrl, authClient, }: ForgotPasswordFormProps): react.JSX.Element;
+
+declare function ResetPasswordForm({ email, onSuccess, loginUrl, authClient, }: ResetPasswordFormProps): react.JSX.Element;
+
+declare function AuthLayout({ logo, title, subtitle, children, footer, }: AuthLayoutProps): react.JSX.Element;
+
+/**
+ * What an invitee sees when their link does not work.
+ *
+ * It names the reason instead of merging the cases into one message: "expired"
+ * tells someone their link was real and that asking for another one is worth
+ * it, which "invalid" does not. Short TTLs make that distinction routine.
+ *
+ * The only way forward offered is a mailto, deliberately. A self-service
+ * "request a new invitation" form would mean a public endpoint accepting dead
+ * tokens, a queue to moderate, and a way to probe which tokens once existed —
+ * for a flow where the operator already knows the person by name.
+ */
+declare function InvitationNotice({ reason, supportEmail, title, action, }: InvitationNoticeProps): react.JSX.Element;
+
+export { AuthLayout, AuthLayoutProps, ForgotPasswordForm, ForgotPasswordFormProps, InvitationNotice, InvitationNoticeProps, LoginForm, LoginFormProps, RegisterForm, RegisterFormProps, ResetPasswordForm, ResetPasswordFormProps, SocialButtons, VerifyEmailForm, VerifyEmailFormProps, useLogout, useSession };