@authgate/browser 0.1.0 → 0.2.0

package/LICENSE

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

@@ -12,6 +12,8 @@ coupling and hidden behavior.
 
 - Read AuthGate CSRF token from cookies
 - Perform a safe logout request with CSRF protection
+- Explicit success/failure signaling
+- Optional redirect after logout
 - Zero dependencies
 - Framework-agnostic (works with React, Vue, vanilla JS, etc.)
 
@@ -37,6 +39,8 @@ const csrf = getCSRFToken();
 
 Returns the value of the `authgate_csrf` cookie, or `null` if not present.
 
+This function only **reads** the CSRF token. It does not generate or validate it.
+
 ---
 
 ### Logout
@@ -44,7 +48,7 @@ Returns the value of the `authgate_csrf` cookie, or `null` if not present.
 ```ts
 import { logout } from "@authgate/browser";
 
-await logout();
+const result = await logout();
 ```
 
 This will:
@@ -53,6 +57,17 @@ This will:
 - Attach the CSRF token via `X-CSRF-Token`
 - Include credentials (`cookies`)
 
+The function returns a result indicating whether logout succeeded:
+
+```ts
+type LogoutResult =
+  | { ok: true }
+  | { ok: false; reason: "missing_csrf" | "request_failed" | "unauthorized" };
+```
+
+Applications that do not need to react programmatically to logout may safely
+ignore the return value.
+
 ---
 
 ### Logout with redirect
@@ -61,7 +76,24 @@ This will:
 await logout({ redirectTo: "/" });
 ```
 
-After a successful logout request, the browser is redirected to the given path.
+If the logout request succeeds, the browser is redirected to the given path.
+
+Redirecting is an optional side-effect and does **not** define success.
+Applications may choose to handle navigation themselves instead.
+
+---
+
+### Example (React / SPA)
+
+```ts
+const result = await logout();
+
+if (result.ok) {
+  setUser(null);
+} else {
+  console.error("Logout failed:", result.reason);
+}
+```
 
 ---
 
@@ -80,7 +112,7 @@ No cookies are set, modified, or cleared by this library.
 - No authentication logic
 - No token refresh
 - No session management
-- No redirects except when explicitly requested
+- No implicit redirects
 - No framework-specific helpers
 
 This package exists solely to reduce boilerplate and prevent integration mistakes.
@@ -91,7 +123,6 @@ This package exists solely to reduce boilerplate and prevent integration mistake
 
 - Works with any backend protected by AuthGate
 - Compatible with SSR and SPA architectures
-- Safe to use in multi-app or monorepo setups
 
 ---
 

package/dist/index.d.ts

@@ -1,4 +1,40 @@
+/**
+ * Returns the AuthGate CSRF token from the browser cookies.
+ *
+ * The CSRF token is issued by AuthGate and stored in the `authgate_csrf`
+ * cookie. This helper does not validate the token; it only reads it.
+ *
+ * @returns The CSRF token string, or `null` if the cookie is missing.
+ */
 export declare function getCSRFToken(): string | null;
+/**
+ * The result of a logout attempt.
+ *
+ * - `{ ok: true }` indicates that logout succeeded.
+ * - `{ ok: false, reason }` indicates that logout failed for a known reason.
+ */
+type LogoutResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "missing_csrf" | "request_failed" | "unauthorized";
+};
+/**
+ * Logs the user out by calling the AuthGate logout endpoint.
+ *
+ * This function:
+ * - Reads the CSRF token from the browser cookies
+ * - Sends a POST request to `/auth/logout`
+ * - Optionally redirects the browser on success
+ *
+ * Redirecting is a side-effect and does not define success. Applications
+ * that need to react to logout programmatically (e.g. SPA state updates)
+ * should inspect the returned result instead.
+ *
+ * @param opts.redirectTo Optional URL to redirect to after successful logout.
+ * @returns A `LogoutResult` indicating whether logout succeeded or failed.
+ */
 export declare function logout(opts?: {
     redirectTo?: string;
-}): Promise<void>;
+}): Promise<LogoutResult>;
+export {};

package/dist/index.js

@@ -1,22 +1,69 @@
+/**
+ * Reads a cookie value by name from `document.cookie`.
+ *
+ * This is a small internal helper used by the AuthGate browser SDK.
+ * It returns `null` if the cookie is not present.
+ */
 function getCookie(name) {
     const match = document.cookie
         .split("; ")
         .find((c) => c.startsWith(name + "="));
     return match ? decodeURIComponent(match.split("=")[1]) : null;
 }
+/**
+ * Returns the AuthGate CSRF token from the browser cookies.
+ *
+ * The CSRF token is issued by AuthGate and stored in the `authgate_csrf`
+ * cookie. This helper does not validate the token; it only reads it.
+ *
+ * @returns The CSRF token string, or `null` if the cookie is missing.
+ */
 export function getCSRFToken() {
     return getCookie("authgate_csrf");
 }
+/**
+ * Logs the user out by calling the AuthGate logout endpoint.
+ *
+ * This function:
+ * - Reads the CSRF token from the browser cookies
+ * - Sends a POST request to `/auth/logout`
+ * - Optionally redirects the browser on success
+ *
+ * Redirecting is a side-effect and does not define success. Applications
+ * that need to react to logout programmatically (e.g. SPA state updates)
+ * should inspect the returned result instead.
+ *
+ * @param opts.redirectTo Optional URL to redirect to after successful logout.
+ * @returns A `LogoutResult` indicating whether logout succeeded or failed.
+ */
 export async function logout(opts) {
     const csrf = getCSRFToken();
-    await fetch("/auth/logout", {
-        method: "POST",
-        headers: {
-            "X-CSRF-Token": csrf ?? "",
-        },
-        credentials: "include",
-    });
-    if (opts?.redirectTo !== undefined) {
+    if (!csrf) {
+        return { ok: false, reason: "missing_csrf" };
+    }
+    let res;
+    try {
+        res = await fetch("/auth/logout", {
+            method: "POST",
+            headers: {
+                "X-CSRF-Token": csrf,
+            },
+            credentials: "include",
+        });
+    }
+    catch {
+        return { ok: false, reason: "request_failed" };
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            reason: res.status === 401 || res.status === 403
+                ? "unauthorized"
+                : "request_failed",
+        };
+    }
+    if (opts?.redirectTo) {
         window.location.href = opts.redirectTo;
     }
+    return { ok: true };
 }

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@authgate/browser",
-  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexlup06-authgate/authgate-browser.git"
+  },
+  "version": "0.2.0",
   "description": "Browser-side helpers for AuthGate (logout, CSRF forwarding)",
   "license": "MIT",
   "type": "module",