nextjs-hasura-auth 0.1.1 → 0.1.2

package/APOLLO.md

@@ -17,13 +17,13 @@ The Apollo Client setup provides a unified interface for sending GraphQL queries
     *   **Admin Secret Fallback:** If no `token` is provided, but the `HASURA_ADMIN_SECRET` environment variable is set (or a `secret` is passed explicitly), it's sent in the `x-hasura-admin-secret` header (for both HTTP and WS).
     *   **Public Access:** If neither a token nor a secret is available, requests are sent without authentication headers.
 *   **Server-Side Rendering (SSR) / Client-Side Rendering (CSR) Compatibility:** The client can be created and used both on the server and the client.
-*   **Convenient Provider:** The `createClient` function returns an enhanced client instance that includes a `.Provider` component (`ApolloClientWithProvider`) for easily wrapping parts of your React application.
+*   **Convenient Provider:** The `createApolloClient` function returns an enhanced client instance that includes a `.Provider` component (`ApolloClientWithProvider`) for easily wrapping parts of your React application.
 *   **Helper Hook:** Provides `useCreateApolloClient` hook for easily creating memoized client instances in React components, especially useful for integrating with authentication state.
 
 <details>
 <summary>Core Exports & Options (`lib/apollo.tsx`)</summary>
 
-*   `createClient(options: ApolloOptions): ApolloClientWithProvider`: Creates a new Apollo Client instance.
+*   `createApolloClient(options: ApolloOptions): ApolloClientWithProvider`: Creates a new Apollo Client instance.
     *   `options.url`: Hasura GraphQL endpoint URL (defaults to `process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL`).
     *   `options.ws`: Boolean, enable WebSocket link for subscriptions (defaults to `false`, only works client-side).
     *   `options.token`: String, JWT token for Bearer authentication.
@@ -124,26 +124,26 @@ The Apollo Client setup provides a unified interface for sending GraphQL queries
 
 ### Server-Side (SSR/SSG/Server Components/API Routes)
 
-1.  **Create Client Instance:** Use `createClient` directly. You need to decide how to authenticate:
+1.  **Create Client Instance:** Use `createApolloClient` directly. You need to decide how to authenticate:
     *   **Admin Access:** Pass the admin secret (e.g., from environment variables) using the `secret` option if you need privileged access.
     *   **User Access:** If running in the context of a specific user request, obtain their Hasura JWT (e.g., from session data, request headers) and pass it using the `token` option.
 
     ```typescript
     // Example in an API Route or Server Component
-    import { createClient } from '@/lib/apollo'; // Adjust path
+    import { createApolloClient } from '@/lib/apollo'; // Adjust path
     import { gql } from '@apollo/client';
     // import { getToken } from "next-auth/jwt"
 
     async function getUserDataOnServer(userId: string, request?: Request) {
       // Option 1: Use Admin Secret for privileged access
-      // const client = createClient({
+      // const client = createApolloClient({
       //   secret: process.env.HASURA_ADMIN_SECRET // Ensure secret is available server-side
       // });
 
       // Option 2: Use User Token (if available from request/session)
       // Example: const sessionToken = await getToken({ req: request, secret: process.env.NEXTAUTH_SECRET });
       // const hasuraToken = sessionToken?.accessToken;
-      const client = createClient({
+      const client = createApolloClient({
         token: process.env.SOME_SERVICE_ACCOUNT_TOKEN_IF_NEEDED // Or fetch user token if applicable
         // url: process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL // URL can also be passed explicitly
       });

package/GENERATOR.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This document describes the `Generator` function located in `lib/generator.ts`. Its purpose is to dynamically generate GraphQL query strings, `DocumentNode` objects (compatible with Apollo Client), and corresponding variables based on a provided set of options and a Hasura-like schema (`schema.json`). This simplifies the process of constructing GraphQL operations (queries, mutations, subscriptions) within the application.
+This document describes the `Generator` function located in `lib/generator.ts`. Its purpose is to dynamically generate GraphQL query strings, `DocumentNode` objects (compatible with Apollo Client), and corresponding variables based on a provided set of options and a Hasura-like schema (`public/hasura-schema.json`). This simplifies the process of constructing GraphQL operations (queries, mutations, subscriptions) within the application.
 
 ## Usage
 
@@ -14,11 +14,10 @@ This document describes the `Generator` function located in `lib/generator.ts`.
 // Assuming 'nextjs-hasura-auth' is your published package name
 import { Generator, GenerateOptions, GenerateResult } from 'nextjs-hasura-auth'; 
 // Assuming schema is correctly loaded (you might need to handle schema loading differently when using the package)
-// import schema from './schema.json'; 
+import schema from './public/hasura-schema.json'; 
 
 // Initialize the generator (Schema needs to be passed)
-// const generate = Generator(schema); 
-// TODO: Document how schema should be provided when using the package
+const generate = Generator(schema); 
 
 // Define options for your query
 const options: GenerateOptions = {
@@ -77,7 +76,7 @@ The `generate` function accepts an object with the following properties:
 
 ## Examples
 
-*(Note: Variable types like `users_bool_exp`, `[users_order_by!]`, `uuid!`, `users_pk_columns_input!`, `users_set_input!`, `[users_insert_input!]!` are inferred based on schema structure and conventions. Ensure your `schema.json` reflects the actual types used by Hasura.)*
+*(Note: Variable types like `users_bool_exp`, `[users_order_by!]`, `uuid!`, `users_pk_columns_input!`, `users_set_input!`, `[users_insert_input!]!` are inferred based on schema structure and conventions. Ensure your `public/hasura-schema.json` reflects the actual types used by Hasura.)*
 
 **Navigation**
 

package/README.md

@@ -4,6 +4,7 @@ This project provides a robust starting point for building applications using Ne
 
 [![Generator Documentation](https://img.shields.io/badge/Generator%20Docs-MD-blue)](GENERATOR.md) [![Apollo Client Documentation](https://img.shields.io/badge/Apollo%20Client%20Docs-MD-orange)](APOLLO.md)
 [![Authentication Helpers Documentation](https://img.shields.io/badge/Auth%20Helpers%20Docs-MD-green)](AUTH.md) [![Hasura Admin Client Documentation](https://img.shields.io/badge/Hasura%20Client%20Docs-MD-purple)](HASURA.md)
+[![Generated Client Documentation](https://img.shields.io/badge/Generated%20Client%20Docs-MD-cyan)](CLIENT.md)
 
 See [`GENERATOR.md`](GENERATOR.md) for detailed documentation on the dynamic GraphQL query generator, which simplifies creating queries, mutations, and subscriptions based on your Hasura schema.
 
@@ -13,6 +14,8 @@ See [`AUTH.md`](AUTH.md) for documentation on WebSocket and request authenticati
 
 See [`HASURA.md`](HASURA.md) for details on the Hasura Admin API client used for migrations.
 
+See [`CLIENT.md`](CLIENT.md) for details on the `Client` class and React hooks that combine the Generator and Apollo Client for easy data operations.
+
 ## ✨ Features Checklist
 
 **Implemented:**
@@ -22,16 +25,17 @@ See [`HASURA.md`](HASURA.md) for details on the Hasura Admin API client used for
 *   [x] **Unified Apollo Client:** A configured Apollo Client instance handles both authenticated HTTP requests (via the proxy) and direct, authenticated WebSocket connections for subscriptions.
 *   [x] **Dynamic Query Generator:** A versatile query generator (`lib/generator.ts`) allows dynamic creation of GraphQL operations based on options and schema, suitable for client/server use.
 *   [x] **WebSocket Authentication:** Real-time subscriptions connect directly to Hasura via WebSockets, authenticated using the user's session JWT.
+*   [x] **Generated Client Wrapper:** A `Client` class and associated React hooks (`useQuery`, `useSubscription`) that combine the Generator and Apollo Client for simplified data fetching and mutations (`lib/client.tsx`).
 
 **Planned / Future Ideas:**
 
-*   [ ] **Convenience Hooks:** Create easy-to-use React hooks (`useQuery`, `useSubscription`, potentially a `useCRUD` hook/class) that integrate the `Generator` with Apollo Client for streamlined data fetching in components.
+*   [ ] **Advanced Convenience Hooks:** Potentially create a more advanced `useCRUD` hook/class built on top of the existing `Client` or hooks for even more streamlined common CRUD operations in components.
 *   [ ] **Multi-Platform Builds:** Native builders for Android, iOS, MacOS, Windows, Linux, Oculus (e.g., using Tauri, Capacitor, or Electron).
 *   [ ] **Unique Environment Builders:** Specific builds for Chrome Extensions, Firefox Extensions, and VSCode Extensions (including custom UI elements).
 *   [ ] Additional Authentication Providers (OAuth: Google, GitHub, etc.).
 *   [ ] Role-based access control examples.
 *   [ ] Advanced caching strategies.
-*   [ ] Comprehensive end-to-end testing setup.
+*   [ ] Comprehensive end-to-end testing setup for UI and hooks.
 
 ## 🚀 Core Concepts
 
@@ -67,7 +71,7 @@ Interaction with the Hasura GraphQL Engine is handled in two primary ways:
 
 ### 4. Dynamic Query Generation (`GENERATOR.md`)
 
-*   The core `Generator` function in `lib/generator.ts` allows you to build complex GraphQL operations dynamically based on a simple options object and your `schema.json`.
+*   The core `Generator` function in `lib/generator.ts` allows you to build complex GraphQL operations dynamically based on a simple options object and your `public/hasura-schema.json`.
 *   This avoids writing lengthy GraphQL query strings manually.
 *   See [`GENERATOR.md`](GENERATOR.md) for full usage details and examples.
 *   *Convenience hooks (like `useQuery`, `useSubscription`, `useCRUD`) are planned to further simplify using the generator within React components.*
@@ -89,10 +93,10 @@ Interaction with the Hasura GraphQL Engine is handled in two primary ways:
 │   ├── debug.ts          # Debug utility
 │   └── ...
 ├── public/               # Static assets
+│   ├── hasura-schema.json # Hasura GraphQL schema (for Generator)
 ├── styles/               # Global styles
 ├── .env                  # Environment variables (Gitignored)
 ├── GENERATOR.md          # Query Generator Documentation
-├── schema.json           # Hasura GraphQL schema (for Generator)
 ├── next.config.js        # Next.js configuration
 ├── package.json          # Project dependencies and scripts
 └── tsconfig.json         # TypeScript configuration
@@ -159,7 +163,7 @@ Interaction with the Hasura GraphQL Engine is handled in two primary ways:
     *   Ensure `NEXTAUTH_URL` points to your application's base URL.
 
 4.  **Update Hasura Schema:**
-    Make sure the `schema.json` file in the root is up-to-date with your Hasura instance's schema. You might need to fetch this from Hasura if you've made changes.
+    Make sure the `public/hasura-schema.json` file in the root is up-to-date with your Hasura instance's schema. You might need to fetch this from Hasura if you've made changes.
 
 5.  **Run the development server:**
     ```bash

package/dist/lib/apollo.d.ts

@@ -1,15 +1,15 @@
 import { ApolloClient } from '@apollo/client';
-/**
- * Get JWT secret from environment variables
- * @returns {Uint8Array} Secret key for JWT signing
- */
-export declare const getJwtSecret: () => Uint8Array;
-interface ApolloOptions {
+export interface ApolloOptions {
     url?: string;
     ws?: boolean;
     token?: string;
     secret?: string;
 }
+export interface ApolloClientWithProvider extends ApolloClient<any> {
+    Provider: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+}
 /**
  * Create Apollo Client
  *
@@ -19,7 +19,7 @@ interface ApolloOptions {
  * @param {string} options.secret - Admin secret for Hasura
  * @returns {ApolloClient} Apollo Client
  */
-export declare function createClient(options?: ApolloOptions): ApolloClient<import("@apollo/client").NormalizedCacheObject>;
+export declare function createApolloClient(options?: ApolloOptions): ApolloClientWithProvider;
 /**
  * Get or create Apollo client instance
  * @param options Client options
@@ -30,14 +30,14 @@ export declare function getClient(options?: {}): ApolloClient<any>;
  * React hook to get Apollo client instance
  * @returns Apollo client instance
  */
-export declare function useClient(options: ApolloOptions): ApolloClient<import("@apollo/client").NormalizedCacheObject>;
+export declare function useCreateApolloClient(options: ApolloOptions): ApolloClientWithProvider;
 /**
  * Check connection to Hasura GraphQL endpoint
  * @returns {Promise<boolean>} True if connection is successful
  */
 export declare function checkConnection(client?: ApolloClient<any>): Promise<boolean>;
 declare const _default: {
-    createClient: typeof createClient;
+    createApolloClient: typeof createApolloClient;
     getClient: typeof getClient;
     getJwtSecret: () => Uint8Array;
     checkConnection: typeof checkConnection;

package/dist/lib/{apollo.js → apollo.jsx}

@@ -12,10 +12,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getJwtSecret = void 0;
-exports.createClient = createClient;
+exports.createApolloClient = createApolloClient;
 exports.getClient = getClient;
-exports.useClient = useClient;
+exports.useCreateApolloClient = useCreateApolloClient;
 exports.checkConnection = checkConnection;
 const client_1 = require("@apollo/client");
 const context_1 = require("@apollo/client/link/context");
@@ -25,39 +24,11 @@ const graphql_ws_1 = require("graphql-ws");
 const cross_fetch_1 = __importDefault(require("cross-fetch"));
 const debug_1 = __importDefault(require("./debug"));
 const react_1 = require("react");
+const jwt_1 = require("./jwt");
 // Create a debug logger for this module
 const debug = (0, debug_1.default)('apollo');
 // Determine if running on client
 const isClient = typeof window !== 'undefined';
-/**
- * Get JWT secret from environment variables
- * @returns {Uint8Array} Secret key for JWT signing
- */
-const getJwtSecret = () => {
-    try {
-        const jwtSecret = process.env.HASURA_JWT_SECRET || '{"type":"HS256","key":"your-secret-key"}';
-        // Parse JWT configuration (may be in JSON format)
-        let secretKey;
-        try {
-            const jwtConfig = typeof jwtSecret === 'string' ? JSON.parse(jwtSecret) : jwtSecret;
-            secretKey = jwtConfig.key;
-            if (!secretKey) {
-                throw new Error('JWT key not found in configuration');
-            }
-        }
-        catch (e) {
-            // If failed to parse as JSON, use as string
-            secretKey = jwtSecret;
-        }
-        // Convert key to Uint8Array (required for jose)
-        return new TextEncoder().encode(secretKey);
-    }
-    catch (error) {
-        debug('apollo', '❌ Error getting JWT secret:', error);
-        throw error;
-    }
-};
-exports.getJwtSecret = getJwtSecret;
 /**
  * Create Apollo Client
  *
@@ -67,7 +38,7 @@ exports.getJwtSecret = getJwtSecret;
  * @param {string} options.secret - Admin secret for Hasura
  * @returns {ApolloClient} Apollo Client
  */
-function createClient(options = {}) {
+function createApolloClient(options = {}) {
     // Default values
     const { url = process.env.NEXT_PUBLIC_HASURA_GRAPHQL_URL, ws = false, token = undefined, secret = process.env.HASURA_ADMIN_SECRET } = options;
     if (!url) {
@@ -140,7 +111,7 @@ function createClient(options = {}) {
         }, wsLink, httpLink);
     }
     // Create Apollo Client
-    return new client_1.ApolloClient({
+    const apolloClient = new client_1.ApolloClient({
         link: splitLink,
         cache: new client_1.InMemoryCache(),
         defaultOptions: {
@@ -157,6 +128,10 @@ function createClient(options = {}) {
             },
         }
     });
+    apolloClient.Provider = function Provider({ children }) {
+        return <client_1.ApolloProvider client={apolloClient}>{children}</client_1.ApolloProvider>;
+    };
+    return apolloClient;
 }
 // Default client instance
 let clientInstance = null;
@@ -167,7 +142,7 @@ let clientInstance = null;
  */
 function getClient(options = {}) {
     if (!clientInstance) {
-        clientInstance = createClient(options);
+        clientInstance = createApolloClient(options);
     }
     return clientInstance;
 }
@@ -175,8 +150,8 @@ function getClient(options = {}) {
  * React hook to get Apollo client instance
  * @returns Apollo client instance
  */
-function useClient(options) {
-    return (0, react_1.useMemo)(() => createClient(options), [options]);
+function useCreateApolloClient(options) {
+    return (0, react_1.useMemo)(() => createApolloClient(options), [options]);
 }
 const CHECK_CONNECTION = (0, client_1.gql) `
 query CheckConnection {
@@ -199,8 +174,8 @@ function checkConnection() {
     });
 }
 exports.default = {
-    createClient,
+    createApolloClient,
     getClient,
-    getJwtSecret: exports.getJwtSecret,
+    getJwtSecret: jwt_1.getJwtSecret,
     checkConnection
 };

package/dist/lib/auth.d.ts

@@ -0,0 +1,16 @@
+import { NextRequest } from "next/server";
+import { IncomingMessage } from "http";
+import { JWT } from 'next-auth/jwt';
+import WebSocket from "ws";
+export declare function getTokenFromRequest(request: NextRequest): Promise<JWT | null>;
+export declare function WsClientsManager(route?: string): {
+    Client: (client: WebSocket) => string;
+    getToken(request: IncomingMessage, clientId: string): Promise<string | JWT | null>;
+    parseUser(request: IncomingMessage, clientId: string): Promise<any>;
+    delete(clientId: string): void;
+    getClient(clientId: string): {
+        ws: WebSocket;
+        userId?: string;
+        user?: any;
+    } | undefined;
+};

package/dist/lib/auth.jsx

@@ -0,0 +1,159 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTokenFromRequest = getTokenFromRequest;
+exports.WsClientsManager = WsClientsManager;
+const debug_1 = __importDefault(require("@/lib/debug"));
+const jwt_1 = require("next-auth/jwt");
+const uuid_1 = require("uuid");
+const debug = (0, debug_1.default)('auth');
+function getTokenFromRequest(request) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const secureCookie = request.url.startsWith('https');
+        const cookieName = secureCookie
+            ? '__Secure-next-auth.session-token'
+            : 'next-auth.session-token';
+        debug(`GET /api/auth: Using cookie name: ${cookieName}, secure: ${secureCookie}`);
+        const token = yield (0, jwt_1.getToken)({
+            req: request, // Cast to any to satisfy getToken, NextRequest works
+            secret: process.env.NEXTAUTH_SECRET,
+            cookieName: cookieName,
+        });
+        return token;
+    });
+}
+function WsClientsManager(route = '') {
+    const clientManagerId = route + (0, uuid_1.v4)();
+    debug(`(${clientManagerId}): New WebSocket clients manager established.`);
+    const clients = new Map();
+    return {
+        Client: (client) => {
+            const clientId = (0, uuid_1.v4)();
+            clients.set(clientId, { ws: client });
+            debug(`(${clientManagerId}): New client (${clientId}) connected.`);
+            return clientId;
+        },
+        getToken(request, clientId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const cookieHeader = request.headers.cookie;
+                const userAgent = request.headers['user-agent'];
+                const forwardedProto = request.headers['x-forwarded-proto'];
+                const connectionEncrypted = (_a = request.connection) === null || _a === void 0 ? void 0 : _a.encrypted;
+                debug(`${clientManagerId}: (${clientId}): Incoming request details - URL: ${request.url}, Method: ${request.method}, User-Agent: ${userAgent}`);
+                debug(`${clientManagerId}: (${clientId}): Incoming headers:`, request.headers);
+                debug(`${clientManagerId}: (${clientId}): Connection encrypted: ${connectionEncrypted}`);
+                debug(`${clientManagerId}: (${clientId}): X-Forwarded-Proto: ${forwardedProto}`);
+                debug(`${clientManagerId}: (${clientId}): Full cookie header:`, cookieHeader || 'No cookies header');
+                // Determine secure context and cookie name
+                const isSecure = forwardedProto === 'https' || connectionEncrypted;
+                const sessionCookieName = isSecure
+                    ? '__Secure-next-auth.session-token'
+                    : 'next-auth.session-token';
+                debug(`${clientManagerId}: (${clientId}): Determined secure context: ${isSecure}`);
+                debug(`${clientManagerId}: (${clientId}): Expecting session cookie name: ${sessionCookieName}`);
+                let token = null;
+                let payload = null;
+                let userId = null;
+                const rawToken = false; // Keep false
+                try {
+                    debug(`SOCKET /api/auth (${clientId}): Preparing adapted request for getToken (raw: ${rawToken})...`);
+                    const parsedCookies = request.headers.cookie ?
+                        Object.fromEntries(request.headers.cookie.split('; ').map(c => {
+                            const [key, ...val] = c.split('=');
+                            return [key, decodeURIComponent(val.join('='))];
+                        }))
+                        : {};
+                    debug(`SOCKET /api/auth (${clientId}): Parsed cookies object:`, parsedCookies);
+                    const adaptedReq = {
+                        headers: request.headers,
+                        cookies: parsedCookies,
+                        url: request.url || '',
+                        method: request.method || 'GET',
+                    };
+                    debug(`SOCKET /api/auth (${clientId}): Final adapted request object for getToken:`, adaptedReq);
+                    const getTokenParams = {
+                        req: adaptedReq,
+                        secret: process.env.NEXTAUTH_SECRET,
+                        cookieName: sessionCookieName,
+                        raw: rawToken, // Should be false now
+                    };
+                    debug(`${clientManagerId}: (${clientId}): Calling getToken with params:`, {
+                        cookieName: getTokenParams.cookieName,
+                        raw: getTokenParams.raw,
+                        secretProvided: !!getTokenParams.secret,
+                    });
+                    token = yield (0, jwt_1.getToken)(getTokenParams);
+                    debug(`${clientManagerId}: (${clientId}): getToken result received.`);
+                    debug(`${clientManagerId}: (${clientId}): Decoded token value from getToken:`, token);
+                    debug(`${clientManagerId}: (${clientId}): getToken result type: ${typeof token}, isNull: ${token === null}`);
+                    if (token && typeof token === 'object' && token.sub) {
+                        payload = token;
+                        userId = payload.sub;
+                        debug(`${clientManagerId}: (${clientId}): User ${userId} authenticated via decoded token from getToken.`);
+                    }
+                    else {
+                        debug(`${clientManagerId}: (${clientId}): No valid token found or token is not an object with sub property.`);
+                    }
+                    return token;
+                }
+                catch (error) {
+                    debug(`${clientManagerId}: (${clientId}): Error preparing adapted request for getToken:`, error);
+                    throw error;
+                }
+            });
+        },
+        parseUser(request, clientId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const token = yield this.getToken(request, clientId);
+                if (token && typeof token === 'object' && token.sub) {
+                    const _a = token, { accessToken } = _a, user = __rest(_a, ["accessToken"]);
+                    const client = clients.get(clientId);
+                    if (client) {
+                        client.userId = token.sub;
+                        client.user = user;
+                        clients.set(clientId, client);
+                        debug(`${clientManagerId}: (${clientId}): Client parsed and updated.`);
+                    }
+                    else {
+                        debug(`${clientManagerId}: (${clientId}): No client found in clients map.`);
+                    }
+                    return user;
+                }
+                else {
+                    debug(`${clientManagerId}: (${clientId}): No valid token found or token is not an object with sub property.`);
+                }
+                return null;
+            });
+        },
+        delete(clientId) {
+            clients.delete(clientId);
+            debug(`${clientManagerId}: (${clientId}): Client deleted from clients map.`);
+        },
+        getClient(clientId) {
+            return clients.get(clientId);
+        }
+    };
+}

package/dist/lib/client.d.ts

@@ -0,0 +1,82 @@
+import { ApolloClient, ApolloError, FetchResult, Observable, OperationVariables, useQuery as useApolloQuery, useSubscription as useApolloSubscription } from '@apollo/client';
+import { GenerateOptions, GenerateResult } from './generator';
+/**
+ * Represents the result structure from Apollo hooks, including potential errors.
+ */
+export interface HookResult<TData = any> {
+    loading: boolean;
+    data?: TData;
+    error?: ApolloError;
+    [key: string]: any;
+    generatedQuery?: GenerateResult['query'];
+    generatedVariables?: GenerateResult['variables'];
+}
+export declare class Client {
+    private apolloClient;
+    private generate;
+    constructor(apolloClient: ApolloClient<any>);
+    /**
+     * Executes a GraphQL query (select operation).
+     * @param options - Options for generating the query.
+     * @returns Promise resolving with the query result data.
+     * @throws ApolloError if the query fails or returns GraphQL errors.
+     */
+    select<TData = any>(options: Omit<GenerateOptions, 'operation'>): Promise<TData>;
+    /**
+     * Executes a GraphQL insert mutation.
+     * @param options - Options for generating the mutation.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    insert<TData = any>(options: Omit<GenerateOptions, 'operation'>): Promise<TData>;
+    /**
+     * Executes a GraphQL update mutation.
+     * @param options - Options for generating the mutation.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    update<TData = any>(options: Omit<GenerateOptions, 'operation'>): Promise<TData>;
+    /**
+     * Executes a GraphQL delete mutation.
+     * @param options - Options for generating the mutation.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    delete<TData = any>(options: Omit<GenerateOptions, 'operation'>): Promise<TData>;
+    /**
+     * Initiates a GraphQL subscription.
+     * @param options - Options for generating the subscription.
+     * @returns An Observable for the subscription results.
+     */
+    subscribe<TData = any, TVariables extends OperationVariables = OperationVariables>(options: Omit<GenerateOptions, 'operation'>): Observable<FetchResult<TData>>;
+}
+/**
+ * Hook to get the Apollo Client instance.
+ * Prefers the explicitly provided client, falls back to context, throws if none found.
+ * @param providedClient - An optional ApolloClient instance.
+ * @returns The ApolloClient instance.
+ * @throws Error if no client is found.
+ */
+export declare function useClient(providedClient?: ApolloClient<any> | null): ApolloClient<any>;
+/**
+ * Hook to perform a GraphQL query using the generator.
+ * @template TData - The expected data type.
+ * @param options - Options for the generator (operation is automatically set to 'query').
+ * @param providedClient - Optional ApolloClient instance to use instead of context.
+ * @param hookOptions - Optional additional options passed directly to Apollo's useQuery hook.
+ * @returns An object containing loading state, data, error, and the generated query/variables.
+ */
+export declare function useQuery<TData = any>(options: Omit<GenerateOptions, 'operation'>, providedClient?: ApolloClient<any> | null, hookOptions?: Omit<Parameters<typeof useApolloQuery>[1], 'variables' | 'client' | 'query'>): HookResult<TData>;
+/** Alias for useQuery */
+export declare const useSelect: typeof useQuery;
+/**
+ * Hook to perform a GraphQL subscription using the generator.
+ * @template TData - The expected data type.
+ * @param options - Options for the generator (operation is automatically set to 'subscription').
+ * @param providedClient - Optional ApolloClient instance to use instead of context.
+ * @param hookOptions - Optional additional options passed directly to Apollo's useSubscription hook.
+ * @returns An object containing loading state, data, error, and the generated query/variables.
+ */
+export declare function useSubscription<TData = any>(options: Omit<GenerateOptions, 'operation'>, providedClient?: ApolloClient<any> | null, hookOptions?: Omit<Parameters<typeof useApolloSubscription>[1], 'variables' | 'client' | 'query'>): HookResult<TData>;
+/** Alias for useSubscription */
+export declare const useSubscribe: typeof useSubscription;