@nhost/nhost-js 3.3.0 → 4.0.0

package/dist/src/nhost.js

@@ -0,0 +1,323 @@
+import { generateServiceUrl } from "./";
+import { createAPIClient as createAuthClient, } from "./auth";
+import { attachAccessTokenMiddleware, sessionRefreshMiddleware, updateSessionFromResponseMiddleware, } from "./fetch";
+import { createAPIClient as createFunctionsClient, } from "./functions";
+import { createAPIClient as createGraphQLClient, } from "./graphql";
+import { detectStorage, refreshSession, SessionStorage, } from "./session/";
+import { createAPIClient as createStorageClient, } from "./storage";
+/**
+ * Main client class that provides unified access to all Nhost services.
+ * This class serves as the central interface for interacting with Nhost's
+ * authentication, storage, GraphQL, and serverless functions capabilities.
+ */
+export class NhostClient {
+    /**
+     * Authentication client providing methods for user sign-in, sign-up, and session management.
+     * Use this client to handle all authentication-related operations.
+     */
+    auth;
+    /**
+     * Storage client providing methods for file operations (upload, download, delete).
+     * Use this client to manage files in your Nhost storage.
+     */
+    storage;
+    /**
+     * GraphQL client providing methods for executing GraphQL operations against your Hasura backend.
+     * Use this client to query and mutate data in your database through GraphQL.
+     */
+    graphql;
+    /**
+     * Functions client providing methods for invoking serverless functions.
+     * Use this client to call your custom serverless functions deployed to Nhost.
+     */
+    functions;
+    /**
+     * Storage implementation used for persisting session information.
+     * This handles saving, retrieving, and managing authentication sessions across requests.
+     */
+    sessionStorage;
+    /**
+     * Create a new Nhost client. This constructor is reserved for advanced use cases.
+     * For typical usage, use [createClient](#createclient) or [createServerClient](#createserverclient) instead.
+     *
+     * @param auth - Authentication client instance
+     * @param storage - Storage client instance
+     * @param graphql - GraphQL client instance
+     * @param functions - Functions client instance
+     * @param sessionStorage - Storage implementation for session persistence
+     */
+    constructor(auth, storage, graphql, functions, sessionStorage) {
+        this.auth = auth;
+        this.storage = storage;
+        this.graphql = graphql;
+        this.functions = functions;
+        this.sessionStorage = sessionStorage;
+    }
+    /**
+     * Get the current session from storage.
+     * This method retrieves the authenticated user's session information if one exists.
+     *
+     * @returns The current session or null if no session exists
+     *
+     * @example
+     * ```ts
+     * const session = nhost.getUserSession();
+     * if (session) {
+     *   console.log('User is authenticated:', session.user.id);
+     * } else {
+     *   console.log('No active session');
+     * }
+     * ```
+     */
+    getUserSession() {
+        return this.sessionStorage.get();
+    }
+    /**
+     * Refresh the session using the current refresh token
+     * in the storage and update the storage with the new session.
+     *
+     * This method can be used to proactively refresh tokens before they expire
+     * or to force a refresh when needed.
+     *
+     * @param marginSeconds - The number of seconds before the token expiration to refresh the session. If the token is still valid for this duration, it will not be refreshed. Set to 0 to force the refresh.
+     *
+     * @returns The new session or null if there is currently no session or if refresh fails
+     *
+     * @example
+     * ```ts
+     * // Refresh token if it's about to expire in the next 5 minutes
+     * const refreshedSession = await nhost.refreshSession(300);
+     *
+     * // Force refresh regardless of current token expiration
+     * const forcedRefresh = await nhost.refreshSession(0);
+     * ```
+     */
+    async refreshSession(marginSeconds = 60) {
+        return refreshSession(this.auth, this.sessionStorage, marginSeconds);
+    }
+    /**
+     * Clear the session from storage.
+     *
+     * This method removes the current authentication session, effectively logging out the user.
+     * Note that this is a client-side operation and doesn't invalidate the refresh token on
+     * the server, which can be done with `nhost.auth.signOut({refreshToken: session.refreshTokenId})`.
+     * If the middle `updateSessionFromResponseMiddleware` is used, the session will be removed
+     * from the storage automatically and calling this method is not necessary.
+     *
+     * @example
+     * ```ts
+     * // Log out the user
+     * nhost.clearSession();
+     * ```
+     */
+    clearSession() {
+        this.sessionStorage.remove();
+    }
+}
+/**
+ * Creates and configures a new Nhost client instance optimized for client-side usage.
+ *
+ * This helper method instantiates a fully configured Nhost client by:
+ * - Instantiating the various service clients (auth, storage, functions and graphql)
+ * - Auto-detecting and configuring an appropriate session storage (localStorage in browsers, memory otherwise)
+ * - Setting up a sophisticated middleware chain for seamless authentication management:
+ *   - Automatically refreshing tokens before they expire
+ *   - Attaching authorization tokens to all service requests
+ *   - Updating the session storage when new tokens are received
+ *
+ * This method includes automatic session refresh middleware, making it ideal for
+ * client-side applications where long-lived sessions are expected.
+ *
+ * @param options - Configuration options for the client
+ * @returns A configured Nhost client
+ *
+ * @example
+ * ```ts
+ * // Create client using Nhost cloud default URLs
+ * const nhost = createClient({
+ *   subdomain: 'abcdefgh',
+ *   region: 'eu-central-1'
+ * });
+ *
+ * // Create client with custom service URLs
+ * const customNhost = createClient({
+ *   authUrl: 'https://auth.example.com',
+ *   storageUrl: 'https://storage.example.com',
+ *   graphqlUrl: 'https://graphql.example.com',
+ *   functionsUrl: 'https://functions.example.com'
+ * });
+ *
+ * // Create client using cookies for storing the session
+ * import { CookieStorage } from "@nhost/nhost-js/session";
+ *
+ * const nhost = createClient({
+ *   subdomain: 'abcdefgh',
+ *   region: 'eu-central-1',
+ *   storage: new CookieStorage({
+ *      secure: import.meta.env.ENVIRONMENT === 'production',
+ *   })
+ * });
+ * ```
+ */
+export function createClient(options = {}) {
+    const { subdomain, region, authUrl, storageUrl, graphqlUrl, functionsUrl, storage = detectStorage(), } = options;
+    const sessionStorage = new SessionStorage(storage);
+    // Determine base URLs for each service
+    const authBaseUrl = generateServiceUrl("auth", subdomain, region, authUrl);
+    const storageBaseUrl = generateServiceUrl("storage", subdomain, region, storageUrl);
+    const graphqlBaseUrl = generateServiceUrl("graphql", subdomain, region, graphqlUrl);
+    const functionsBaseUrl = generateServiceUrl("functions", subdomain, region, functionsUrl);
+    // Create auth client
+    const auth = createAuthClient(authBaseUrl);
+    const mwChain = getMiddlewareChain(auth, sessionStorage, true);
+    for (const mw of mwChain) {
+        auth.pushChainFunction(mw);
+    }
+    // Create storage and graphql clients with the refresh and attach token middlewares
+    const storageClient = createStorageClient(storageBaseUrl, mwChain);
+    const graphqlClient = createGraphQLClient(graphqlBaseUrl, mwChain);
+    const functionsClient = createFunctionsClient(functionsBaseUrl, mwChain);
+    // Return an initialized NhostClient
+    return new NhostClient(auth, storageClient, graphqlClient, functionsClient, sessionStorage);
+}
+/**
+ * Creates and configures a new Nhost client instance optimized for server-side usage.
+ *
+ * This helper method instantiates a fully configured Nhost client specifically designed for:
+ * - Server components (in frameworks like Next.js or Remix)
+ * - API routes and middleware
+ * - Backend services and server-side rendering contexts
+ *
+ * Key differences from the standard client:
+ * - Requires explicit storage implementation (must be provided)
+ * - Disables automatic session refresh middleware (to prevent race conditions in server contexts)
+ * - Still attaches authorization tokens and updates session storage from responses
+ *
+ * The server client is ideal for short-lived request contexts where session tokens
+ * are passed in (like cookie-based authentication flows) and automatic refresh
+ * mechanisms could cause issues with concurrent requests.
+ *
+ * @param options - Configuration options for the server client (requires storage implementation)
+ * @returns A configured Nhost client optimized for server-side usage
+ *
+ * @example
+ * ```ts
+ * // Example with cookie storage for Next.js API route or server component
+ * import { cookies } from 'next/headers';
+ *
+ * const nhost = createServerClient({
+ *   region: process.env["NHOST_REGION"] || "local",
+ *   subdomain: process.env["NHOST_SUBDOMAIN"] || "local",
+ *   storage: {
+ *     // storage compatible with Next.js server components
+ *     get: (): Session | null => {
+ *       const s = cookieStore.get(key)?.value || null;
+ *       if (!s) {
+ *         return null;
+ *       }
+ *       const session = JSON.parse(s) as Session;
+ *       return session;
+ *     },
+ *     set: (value: Session) => {
+ *       cookieStore.set(key, JSON.stringify(value));
+ *     },
+ *     remove: () => {
+ *       cookieStore.delete(key);
+ *     },
+ *   },
+ * });
+ *
+ * // Example with cookie storage for Next.js middleware
+ * const nhost = createServerClient({
+ *   region: process.env["NHOST_REGION"] || "local",
+ *   subdomain: process.env["NHOST_SUBDOMAIN"] || "local",
+ *   storage: {
+ *     // storage compatible with Next.js middleware
+ *     get: (): Session | null => {
+ *       const raw = request.cookies.get(key)?.value || null;
+ *       if (!raw) {
+ *         return null;
+ *       }
+ *       const session = JSON.parse(raw) as Session;
+ *       return session;
+ *     },
+ *     set: (value: Session) => {
+ *       response.cookies.set({
+ *         name: key,
+ *         value: JSON.stringify(value),
+ *         path: "/",
+ *         httpOnly: false, //if set to true we can't access it in the client
+ *         secure: process.env.NODE_ENV === "production",
+ *         sameSite: "lax",
+ *         maxAge: 60 * 60 * 24 * 30, // 30 days in seconds
+ *       });
+ *     },
+ *     remove: () => {
+ *       response.cookies.delete(key);
+ *     },
+ *   },
+ * });
+ *
+ * // Example for express reading session from a cookie
+ *
+ * import express, { Request, Response } from "express";
+ * import cookieParser from "cookie-parser";
+ *
+ * app.use(cookieParser());
+ *
+ * const nhostClientFromCookies = (req: Request) => {
+ *   return createServerClient({
+ *     subdomain: "local",
+ *     region: "local",
+ *     storage: {
+ *       get: (): Session | null => {
+ *         const s = req.cookies.nhostSession || null;
+ *         if (!s) {
+ *           return null;
+ *         }
+ *         const session = JSON.parse(s) as Session;
+ *         return session;
+ *       },
+ *       set: (_value: Session) => {
+ *         throw new Error("It is easier to handle the session in the client");
+ *       },
+ *       remove: () => {
+ *         throw new Error("It is easier to handle the session in the client");
+ *       },
+ *     },
+ *   });
+ * };
+ * ```
+ */
+export function createServerClient(options) {
+    const { subdomain, region, authUrl, storageUrl, graphqlUrl, functionsUrl, storage, } = options;
+    const sessionStorage = new SessionStorage(storage);
+    // Determine base URLs for each service
+    const authBaseUrl = generateServiceUrl("auth", subdomain, region, authUrl);
+    const storageBaseUrl = generateServiceUrl("storage", subdomain, region, storageUrl);
+    const graphqlBaseUrl = generateServiceUrl("graphql", subdomain, region, graphqlUrl);
+    const functionsBaseUrl = generateServiceUrl("functions", subdomain, region, functionsUrl);
+    // Create auth client
+    const auth = createAuthClient(authBaseUrl);
+    const mwChain = getMiddlewareChain(auth, sessionStorage, false);
+    for (const mw of mwChain) {
+        auth.pushChainFunction(mw);
+    }
+    // Create storage and graphql clients with the refresh and attach token middlewares
+    const storageClient = createStorageClient(storageBaseUrl, mwChain);
+    const graphqlClient = createGraphQLClient(graphqlBaseUrl, mwChain);
+    const functionsClient = createFunctionsClient(functionsBaseUrl, mwChain);
+    // Return an initialized NhostClient
+    return new NhostClient(auth, storageClient, graphqlClient, functionsClient, sessionStorage);
+}
+function getMiddlewareChain(auth, storage, autoRefresh) {
+    const mwChain = [
+        updateSessionFromResponseMiddleware(storage),
+        attachAccessTokenMiddleware(storage),
+    ];
+    if (autoRefresh) {
+        mwChain.unshift(sessionRefreshMiddleware(auth, storage));
+    }
+    return mwChain;
+}
+//# sourceMappingURL=nhost.js.map

package/dist/src/nhost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nhost.js","sourceRoot":"","sources":["../../src/nhost.ts"],"names":[],"mappings":"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"}

package/dist/src/session/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Session management module for Nhost authentication
+ *
+ * This module exports utilities for managing authentication sessions across
+ * different environments and storage backends. It provides:
+ *
+ * - Session storage abstractions for different environments
+ * - Session persistence and synchronization
+ * - Automatic token refresh mechanisms
+ *
+ * This is an advanced submodule of the Nhost SDK, primarily used internally but it is exposed
+ * for advanced use cases.
+ *
+ * @packageDocumentation
+ */
+export { refreshSession } from "./refreshSession";
+export type { DecodedToken, Session } from "./session";
+export { detectStorage, type SessionChangeCallback, SessionStorage, } from "./storage";
+export { CookieStorage, DEFAULT_SESSION_KEY, LocalStorage, MemoryStorage, type SessionStorageBackend, } from "./storageBackend";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EACL,aAAa,EACb,KAAK,qBAAqB,EAC1B,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC"}

package/dist/src/session/index.js

@@ -0,0 +1,19 @@
+/**
+ * Session management module for Nhost authentication
+ *
+ * This module exports utilities for managing authentication sessions across
+ * different environments and storage backends. It provides:
+ *
+ * - Session storage abstractions for different environments
+ * - Session persistence and synchronization
+ * - Automatic token refresh mechanisms
+ *
+ * This is an advanced submodule of the Nhost SDK, primarily used internally but it is exposed
+ * for advanced use cases.
+ *
+ * @packageDocumentation
+ */
+export { refreshSession } from "./refreshSession";
+export { detectStorage, SessionStorage, } from "./storage";
+export { CookieStorage, DEFAULT_SESSION_KEY, LocalStorage, MemoryStorage, } from "./storageBackend";
+//# sourceMappingURL=index.js.map

package/dist/src/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EACL,aAAa,EAEb,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,aAAa,GAEd,MAAM,kBAAkB,CAAC"}

package/dist/src/session/refreshSession.d.ts

@@ -0,0 +1,17 @@
+import type { Client as AuthClient } from "../auth";
+import type { Session } from "./session";
+import type { SessionStorage } from "./storage";
+/**
+ * Refreshes the authentication session if needed
+ *
+ * This function checks if the current session needs to be refreshed based on
+ * the access token expiration time. If a refresh is needed, it will attempt to
+ * refresh the token using the provided auth client.
+ *
+ * @param auth - The authentication client to use for token refresh
+ * @param storage - The session storage implementation
+ * @param marginSeconds - The number of seconds before the token expiration to refresh the session. If the token is still valid for this duration, it will not be refreshed. Set to 0 to force the refresh.
+ * @returns A promise that resolves to the current session (refreshed if needed) or null if no session exists
+ */
+export declare const refreshSession: (auth: AuthClient, storage: SessionStorage, marginSeconds?: number) => Promise<Session | null>;
+//# sourceMappingURL=refreshSession.d.ts.map

package/dist/src/session/refreshSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshSession.d.ts","sourceRoot":"","sources":["../../../src/session/refreshSession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAiB,MAAM,SAAS,CAAC;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AA4BhD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,UAAU,EAChB,SAAS,cAAc,EACvB,sBAAkB,KACjB,OAAO,CAAC,OAAO,GAAG,IAAI,CAmBxB,CAAC"}

package/dist/src/session/refreshSession.js

@@ -0,0 +1,120 @@
+class DummyLock {
+    async request(_name, _options, 
+    // biome-ignore lint/suspicious/noExplicitAny: any
+    callback) {
+        return callback();
+    }
+}
+const lock = typeof navigator !== "undefined" && navigator.locks
+    ? navigator.locks
+    : new DummyLock();
+/**
+ * Refreshes the authentication session if needed
+ *
+ * This function checks if the current session needs to be refreshed based on
+ * the access token expiration time. If a refresh is needed, it will attempt to
+ * refresh the token using the provided auth client.
+ *
+ * @param auth - The authentication client to use for token refresh
+ * @param storage - The session storage implementation
+ * @param marginSeconds - The number of seconds before the token expiration to refresh the session. If the token is still valid for this duration, it will not be refreshed. Set to 0 to force the refresh.
+ * @returns A promise that resolves to the current session (refreshed if needed) or null if no session exists
+ */
+export const refreshSession = async (auth, storage, marginSeconds = 60) => {
+    try {
+        return await _refreshSession(auth, storage, marginSeconds);
+    }
+    catch (error) {
+        try {
+            // we retry the refresh token in case of transient error
+            // or race conditions
+            console.warn("error refreshing session, retrying:", error);
+            return await _refreshSession(auth, storage, marginSeconds);
+        }
+        catch (error) {
+            const errResponse = error;
+            if (errResponse?.status === 401) {
+                // this probably means the refresh token is invalid
+                console.error("session probably expired");
+                storage.remove();
+            }
+            return null;
+        }
+    }
+};
+/**
+ * Internal implementation of the refresh session logic
+ *
+ * @param auth - The authentication client to use for token refresh
+ * @param storage - The session storage implementation
+ * @param marginSeconds - How many seconds before expiration to trigger a refresh
+ * @returns A promise that resolves to the current session (refreshed if needed) or null if no session exists
+ * @private
+ */
+const _refreshSession = async (auth, storage, marginSeconds = 60) => {
+    const { session, needsRefresh, } = await lock.request("nhostSessionLock", { mode: "shared" }, async () => {
+        return _needsRefresh(storage, marginSeconds);
+    });
+    if (!session) {
+        return null; // No session found
+    }
+    if (!needsRefresh) {
+        return session; // No need to refresh
+    }
+    const refreshedSession = await lock.request("nhostSessionLock", { mode: "exclusive" }, async () => {
+        const { session, needsRefresh, sessionExpired } = _needsRefresh(storage, marginSeconds);
+        if (!session) {
+            return null; // No session found
+        }
+        if (!needsRefresh) {
+            return session; // No need to refresh
+        }
+        try {
+            const response = await auth.refreshToken({
+                refreshToken: session.refreshToken,
+            });
+            storage.set(response.body);
+            return response.body;
+        }
+        catch (error) {
+            if (!sessionExpired) {
+                return session;
+            }
+            throw error;
+        }
+    });
+    return refreshedSession;
+};
+/**
+ * Checks if the current session needs to be refreshed based on token expiration
+ *
+ * @param storage - The session storage implementation
+ * @param marginSeconds - How many seconds before expiration to trigger a refresh
+ * @returns An object containing the session, whether it needs refreshing, and whether it has expired
+ * @private
+ */
+const _needsRefresh = (storage, marginSeconds = 60) => {
+    const session = storage.get();
+    if (!session) {
+        return { session: null, needsRefresh: false, sessionExpired: false };
+    }
+    if (!session.decodedToken || !session.decodedToken.exp) {
+        // if the session does not have a valid decoded token, treat it as expired
+        // as we can't determine its validity
+        return { session, needsRefresh: true, sessionExpired: true };
+    }
+    // Force refresh if marginSeconds is 0
+    if (marginSeconds === 0) {
+        return { session, needsRefresh: true, sessionExpired: false };
+    }
+    const currentTime = Date.now();
+    if (session.decodedToken.exp - currentTime > marginSeconds * 1000) {
+        return { session, needsRefresh: false, sessionExpired: false };
+    }
+    return {
+        session,
+        needsRefresh: true,
+        sessionExpired: session.decodedToken.exp < currentTime,
+    };
+};
+//# sourceMappingURL=refreshSession.js.map

package/dist/src/session/refreshSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshSession.js","sourceRoot":"","sources":["../../../src/session/refreshSession.ts"],"names":[],"mappings":"AAKA,MAAM,SAAS;IACb,KAAK,CAAC,OAAO,CACX,KAAa,EACb,QAA0C;IAC1C,kDAAkD;IAClD,QAA4B;QAE5B,OAAO,QAAQ,EAAE,CAAC;IACpB,CAAC;CACF;AAYD,MAAM,IAAI,GACR,OAAO,SAAS,KAAK,WAAW,IAAI,SAAS,CAAC,KAAK;IACjD,CAAC,CAAC,SAAS,CAAC,KAAK;IACjB,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EACjC,IAAgB,EAChB,OAAuB,EACvB,aAAa,GAAG,EAAE,EACO,EAAE;IAC3B,IAAI,CAAC;QACH,OAAO,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YACH,wDAAwD;YACxD,qBAAqB;YACrB,OAAO,CAAC,IAAI,CAAC,qCAAqC,EAAE,KAAK,CAAC,CAAC;YAC3D,OAAO,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,WAAW,GAAG,KAAqC,CAAC;YAC1D,IAAI,WAAW,EAAE,MAAM,KAAK,GAAG,EAAE,CAAC;gBAChC,mDAAmD;gBACnD,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;gBAC1C,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,KAAK,EAC3B,IAAgB,EAChB,OAAuB,EACvB,aAAa,GAAG,EAAE,EACO,EAAE;IAC3B,MAAM,EACJ,OAAO,EACP,YAAY,GACb,GAAuD,MAAM,IAAI,CAAC,OAAO,CACxE,kBAAkB,EAClB,EAAE,IAAI,EAAE,QAAQ,EAAE,EAClB,KAAK,IAAI,EAAE;QACT,OAAO,aAAa,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAC/C,CAAC,CACF,CAAC;IAEF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,CAAC,mBAAmB;IAClC,CAAC;IAED,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC,CAAC,qBAAqB;IACvC,CAAC;IAED,MAAM,gBAAgB,GAAmB,MAAM,IAAI,CAAC,OAAO,CACzD,kBAAkB,EAClB,EAAE,IAAI,EAAE,WAAW,EAAE,EACrB,KAAK,IAAI,EAAE;QACT,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,GAAG,aAAa,CAC7D,OAAO,EACP,aAAa,CACd,CAAC;QAEF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,CAAC,mBAAmB;QAClC,CAAC;QAED,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,OAAO,CAAC,CAAC,qBAAqB;QACvC,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC;gBACvC,YAAY,EAAE,OAAO,CAAC,YAAY;aACnC,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAE3B,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpB,OAAO,OAAO,CAAC;YACjB,CAAC;YAED,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,gBAAgB,CAAC;AAC1B,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,CAAC,OAAuB,EAAE,aAAa,GAAG,EAAE,EAAE,EAAE;IACpE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACvE,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC;QACvD,0EAA0E;QAC1E,qCAAqC;QACrC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAC/D,CAAC;IAED,sCAAsC;IACtC,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,IAAI,OAAO,CAAC,YAAY,CAAC,GAAG,GAAG,WAAW,GAAG,aAAa,GAAG,IAAI,EAAE,CAAC;QAClE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,OAAO;QACL,OAAO;QACP,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,GAAG,WAAW;KACvD,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/session/session.d.ts

@@ -0,0 +1,24 @@
+import type { Session as AuthSession } from "../auth";
+/**
+ * Decoded JWT token payload with processed timestamps and Hasura claims
+ */
+export interface DecodedToken {
+    /** Token expiration time as Date object */
+    exp?: number;
+    /** Token issued at time as Date object */
+    iat?: number;
+    /** Token issuer */
+    iss?: string;
+    /** Token subject (user ID) */
+    sub?: string;
+    /** Hasura JWT claims with PostgreSQL arrays converted to JavaScript arrays */
+    "https://hasura.io/jwt/claims"?: Record<string, unknown>;
+    /** Any other JWT claims */
+    [key: string]: unknown;
+}
+export interface Session extends AuthSession {
+    /** Decoded JWT token payload with processed timestamps and Hasura claims */
+    decodedToken: DecodedToken;
+}
+export declare const decodeUserSession: (accessToken: string) => DecodedToken;
+//# sourceMappingURL=session.d.ts.map

package/dist/src/session/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/session/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,8BAA8B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD,2BAA2B;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,OAAQ,SAAQ,WAAW;IAC1C,4EAA4E;IAC5E,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,eAAO,MAAM,iBAAiB,GAAI,aAAa,MAAM,KAAG,YA8CvD,CAAC"}

package/dist/src/session/session.js

@@ -0,0 +1,48 @@
+export const decodeUserSession = (accessToken) => {
+    const s = accessToken.split(".");
+    if (s.length !== 3 || !s[1]) {
+        throw new Error("Invalid access token format");
+    }
+    const decodedToken = JSON.parse(typeof atob !== "undefined"
+        ? atob(s[1])
+        : Buffer.from(s[1], "base64").toString("utf-8"));
+    // Convert iat and exp to Date objects
+    const iat = typeof decodedToken["iat"] === "number"
+        ? decodedToken["iat"] * 1000 // Convert seconds to milliseconds
+        : undefined;
+    const exp = typeof decodedToken["exp"] === "number"
+        ? decodedToken["exp"] * 1000 // Convert seconds to milliseconds
+        : undefined;
+    // Process Hasura claims - dynamically convert PostgreSQL array notation to arrays
+    const hasuraClaims = decodedToken["https://hasura.io/jwt/claims"];
+    const processedClaims = hasuraClaims
+        ? Object.entries(hasuraClaims).reduce((acc, [key, value]) => {
+            if (typeof value === "string" && isPostgresArray(value)) {
+                acc[key] = parsePostgresArray(value);
+            }
+            else {
+                acc[key] = value;
+            }
+            return acc;
+        }, {})
+        : undefined;
+    return {
+        ...decodedToken,
+        iat,
+        exp,
+        "https://hasura.io/jwt/claims": processedClaims,
+    };
+};
+const isPostgresArray = (value) => {
+    return value.startsWith("{") && value.endsWith("}");
+};
+const parsePostgresArray = (value) => {
+    if (!value || value === "{}")
+        return [];
+    // Remove curly braces and split by comma, handling quoted values
+    return value
+        .slice(1, -1)
+        .split(",")
+        .map((item) => item.trim().replace(/^"(.*)"$/, "$1"));
+};
+//# sourceMappingURL=session.js.map

package/dist/src/session/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/session/session.ts"],"names":[],"mappings":"AAyBA,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,WAAmB,EAAgB,EAAE;IACrE,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAC7B,OAAO,IAAI,KAAK,WAAW;QACzB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACZ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CACvB,CAAC;IAE7B,sCAAsC;IACtC,MAAM,GAAG,GACP,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,QAAQ;QACrC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,kCAAkC;QAC/D,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,GAAG,GACP,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,QAAQ;QACrC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,kCAAkC;QAC/D,CAAC,CAAC,SAAS,CAAC;IAEhB,kFAAkF;IAClF,MAAM,YAAY,GAAG,YAAY,CAAC,8BAA8B,CAEnD,CAAC;IACd,MAAM,eAAe,GAAG,YAAY;QAClC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,CACjC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YACpB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxD,GAAG,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACnB,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC,EACD,EAA6B,CAC9B;QACH,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO;QACL,GAAG,YAAY;QACf,GAAG;QACH,GAAG;QACH,8BAA8B,EAAE,eAAe;KAChD,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,KAAa,EAAW,EAAE;IACjD,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,KAAa,EAAY,EAAE;IACrD,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACxC,iEAAiE;IACjE,OAAO,KAAK;SACT,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;SACZ,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC,CAAC"}