nextjs-hasura-auth 0.1.1 → 0.1.3

package/APOLLO.md

@@ -1,174 +1,101 @@
-# Apollo Client Setup (`APOLLO.md`)
-
-This document describes the configured Apollo Client instance provided by this package (`lib/apollo.tsx` or similar) for interacting with your Hasura GraphQL API.
-
-## Purpose
-
-The Apollo Client setup provides a unified interface for sending GraphQL queries, mutations, and subscriptions to Hasura, automatically handling authentication based on the provided JWT token or Hasura Admin Secret.
-
-## Key Features
-
-*   **Direct Connection:** Connects directly to your Hasura GraphQL endpoint (`NEXT_PUBLIC_HASURA_GRAPHQL_URL`) for HTTP requests and WebSocket endpoint (`NEXT_PUBLIC_HASURA_WS_ENDPOINT` derived from the HTTP URL) for subscriptions.
-*   **Split Link:** Intelligently routes GraphQL operations:
-    *   **HTTP Requests (Queries/Mutations):** Sent via standard HTTP.
-    *   **WebSocket Connections (Subscriptions):** Uses a WebSocket connection (`graphql-ws`). This requires `ws: true` during client creation and only works client-side.
-*   **Flexible Authentication:**
-    *   **JWT Token Priority:** If a `token` is provided during client creation, it's sent as a `Bearer` token in the `Authorization` header (for both HTTP and WS).
-    *   **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.
-*   **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.
-    *   `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.
-    *   `options.secret`: String, Hasura Admin Secret (defaults to `process.env.HASURA_ADMIN_SECRET`).
-*   `useCreateApolloClient(options: ApolloOptions): ApolloClientWithProvider`: React hook to create a memoized Apollo Client instance. Recreates the client if `options` change.
-*   `getClient(options?: ApolloOptions): ApolloClient<any>`: Gets or creates a singleton Apollo Client instance. *Note: Using the singleton pattern might be tricky if the authentication token needs to change dynamically. `useCreateApolloClient` is often preferred in React components.*
-*   `checkConnection(client?): Promise<boolean>`: Sends a simple introspection query to check connectivity to the Hasura endpoint.
-*   `getJwtSecret(): Uint8Array`: Utility to get the Hasura JWT secret key from `process.env.HASURA_JWT_SECRET` (used internally by other parts of the auth system, not typically needed directly for Apollo client setup).
-
-</details>
-
-## Usage
-
-### Client-Side (React Components - Recommended)
-
-1.  **Ensure `SessionProvider` is set up:** The Apollo client often relies on session data (like a JWT) for authentication. Make sure `next-auth/react`'s `SessionProvider` wraps your application, usually in the root layout.
-2.  **Wrap your application/layout with the client's Provider:** Use the `useCreateApolloClient` hook to create a client instance based on the session state and wrap your components using `client.Provider`.
-
-    ```typescript
-    // Example in app/layout.tsx
-    'use client'; // Layout needs to be client-side for providers and hooks
-
-    import { SessionProvider, useSession } from "next-auth/react";
-    import { useCreateApolloClient } from '@/lib/apollo'; // Adjust path
-    import { useMemo } from "react";
-    // Other imports (ThemeProvider, etc.)
-
-    // Wrapper component to manage Apollo client based on session
-    function ApolloWrapper({ children }: { children: React.ReactNode }) {
-      const { data: session } = useSession(); // Get session from next-auth
-
-      // Create Apollo Client, passing the Hasura JWT from the session
-      // The client will be recreated if the session changes
-      const client = useCreateApolloClient(useMemo(() => ({
-        // Make sure your next-auth session callback adds the correct
-        // Hasura-compatible JWT to the session object (e.g., session.accessToken)
-        token: session?.accessToken, // Pass the Hasura JWT
-        ws: true // Enable WebSocket support for subscriptions
-      }), [session]));
-
-      // Use the convenient Provider attached to the client instance
-      return (
-        <client.Provider>
-          {children}
-        </client.Provider>
-      );
-    }
-
-    export default function RootLayout({ children }: { children: React.ReactNode }) {
-      return (
-        <html lang="en" suppressHydrationWarning>
-          <head />
-          <body>
-            {/* SessionProvider is required for useSession hook */}
-            <SessionProvider>
-              {/* ApolloWrapper provides the Apollo client based on session */}
-              <ApolloWrapper>
-                {/* Other providers like ThemeProvider */}
-                {/* <ThemeProvider ...> */}
-                  {children}
-                {/* </ThemeProvider> */}
-              </ApolloWrapper>
-            </SessionProvider>
-          </body>
-        </html>
-      );
-    }
-    ```
-
-3.  **Use Apollo Hooks in Components:** Import and use hooks like `useQuery`, `useMutation`, or `useSubscription` directly. The client provided by the context will handle authentication automatically based on the token passed during its creation.
-
-    ```typescript
-    import { useQuery, gql } from '@apollo/client';
-    // import { Generator } from 'nextjs-hasura-auth'; // Optional: Use with Generator
-
-    function UserProfile() {
-      // Assume user ID is available, e.g., from session or props
-      const userId = '...';
-
-      const GET_USER = gql`
-        query GetUser($userId: uuid!) {
-          users_by_pk(id: $userId) {
-            id
-            name
-            email
-          }
-        }
-      `;
-
-      // The client from ApolloWrapper's context is used automatically
-      const { loading, error, data } = useQuery(GET_USER, {
-         variables: { userId }
-      });
-
-      // ... render logic ...
-    }
-    ```
-
-### Server-Side (SSR/SSG/Server Components/API Routes)
-
-1.  **Create Client Instance:** Use `createClient` 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 { 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({
-      //   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({
-        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
-      });
-
-      const GET_USER = gql`...`; // Your query
-
-      try {
-        const { data } = await client.query({
-          query: GET_USER,
-          variables: { userId },
-          // Important for server-side: Avoid using client-side cache
-          fetchPolicy: 'network-only',
-        });
-        return data.users_by_pk;
-      } catch (error) {
-        console.error('Error fetching user data:', error);
-        return null;
-      }
-    }
-    ```
-
-2.  **Fetch Data:** Use `client.query(...)` or `client.mutate(...)`.
-
-## Important Considerations
-
-*   **JWT Token:** Ensure your authentication system (like `next-auth`) generates a Hasura-compatible JWT containing the necessary `https://hasura.io/jwt/claims` and includes it in the session data (e.g., as `session.accessToken`) for the client-side integration to work.
-*   **Environment Variables:** Securely manage `HASURA_ADMIN_SECRET`, `NEXTAUTH_SECRET`, and potentially `HASURA_JWT_SECRET` using environment variable configuration in your hosting provider (e.g., Vercel). `NEXT_PUBLIC_HASURA_GRAPHQL_URL` needs to be accessible client-side.
-*   **WebSocket Security:** WebSocket connections initiated from the client include the token/secret directly in the `connectionParams`. Ensure your Hasura endpoint is properly secured (e.g., using HTTPS/WSS). 
+# Apollo Client Setup (`lib/apollo.tsx`)
+
+This file provides the `useCreateApolloClient` hook, a crucial part of the library for interacting with your Hasura GraphQL backend.
+
+## `useCreateApolloClient` Hook
+
+A React hook to create and memoize an Apollo Client instance configured for the Hasura backend.
+
+```tsx
+import { useCreateApolloClient } from 'nextjs-hasura-auth';
+
+function MyComponent() {
+  // Create client for HTTP only
+  const apolloClientHttp = useCreateApolloClient({ token: 'your-auth-token' });
+
+  // Create client for HTTP and WebSocket (subscriptions)
+  const apolloClientWs = useCreateApolloClient({ token: 'your-auth-token', ws: true });
+
+  // ... use apolloClient
+}
+```
+
+### Purpose
+
+This hook simplifies the setup of an Apollo Client tailored for Hasura environments, handling both HTTP and WebSocket connections, authentication headers, and role management.
+
+### Arguments
+
+-   `options` (object):
+    -   `token` (string | undefined): Optional authentication token (JWT) to be included in headers.
+    -   `ws` (boolean): Optional flag (default: `false`) to enable WebSocket connection for subscriptions.
+
+### Return Value
+
+-   `ApolloClient<NormalizedCacheObject>`: An initialized and memoized Apollo Client instance.
+
+### Key Features
+
+1.  **HTTP Link (`httpLink`)**: Configured for standard GraphQL operations (queries, mutations) using `createHttpLink`.
+2.  **WebSocket Link (`wsLink`)**: Configured for GraphQL subscriptions using `graphql-ws`. Enabled only if `ws: true` is passed in the options. It uses `createClient` from `graphql-ws`.
+3.  **Role Link (`roleLink`)**: **New!** This is an `ApolloLink` middleware using `setContext` that intercepts outgoing **HTTP requests**. It checks the `context` object passed to the Apollo operation (e.g., in `useQuery`, `useMutation`). If a `role` property is found in the operation's context, it adds the `X-Hasura-Role` header to the HTTP request with the specified role.
+    *   **Important Note:** This dynamic role setting via context currently **only works for HTTP requests** (queries and mutations). It **does not** dynamically set the role for WebSocket connections (subscriptions). For subscriptions, the role is determined by the `connectionParams` when the WebSocket connection is established, which typically uses the `token` provided to `useCreateApolloClient` to infer the role on the backend.
+4.  **Authentication Headers**:
+    *   For HTTP requests, it automatically includes `Authorization: Bearer <token>` (if provided) and `X-Hasura-Admin-Secret` (if `process.env.HASURA_ADMIN_SECRET` is set). The `roleLink` adds the `X-Hasura-Role` header if a `role` is provided in the operation's context.
+    *   For WebSocket connections, `connectionParams` are set with `headers` containing `Authorization` and `X-Hasura-Admin-Secret`.
+5.  **Request Splitting**: Uses `split` to direct operations to `httpLink` (via `roleLink` and `authLink`) or `wsLink` based on the operation type. Subscriptions go to `wsLink` (if `ws: true`), others go to `httpLink`.
+6.  **Error Handling (`errorLink`)**: Includes basic error logging for GraphQL and network errors using `onError`.
+7.  **Caching**: Uses `InMemoryCache` for client-side caching.
+8.  **Memoization**: The `useMemo` hook ensures the client instance is created only once per component lifecycle or when the `token` or `ws` options change, preventing unnecessary client recreations.
+
+### How `roleLink` Works
+
+The `roleLink` leverages Apollo Link's `setContext` middleware.
+
+```typescript
+// Simplified logic within useCreateApolloClient
+import { setContext } from '@apollo/client/link/context';
+
+const roleLink = setContext((_operation, context) => {
+  // context here is the *link* context, which includes headers etc.
+  // and importantly, the context passed from the hook/operation call.
+  const operationContext = context?.graphqlContext || {}; // Access context passed from useQuery/useMutation etc.
+  const role = operationContext.role; // Get the role from the operation's context
+
+  // If a role is provided in the operation's context, add it to the headers
+  if (role) {
+    return {
+      headers: {
+        ...context.headers, // Preserve existing headers (like Authorization)
+        'X-Hasura-Role': role,
+      },
+    };
+  }
+
+  // Otherwise, return the existing headers unchanged
+  return {
+    headers: context.headers,
+  };
+});
+
+// This roleLink is then chained before the httpLink:
+// link: from([errorLink, roleLink, authLink, httpLink]) // for HTTP
+```
+
+When you use the data fetching hooks from `lib/client.tsx` (like `useQuery`, `useMutation`) and pass a `role` in the `hookOptions`, that `role` becomes part of the operation's context (`graphqlContext`), which `roleLink` then reads to set the appropriate `X-Hasura-Role` header for that specific HTTP request.
+
+```tsx
+// Example using useQuery with a role
+const { data } = useQuery(GET_POSTS, {
+  hookOptions: {
+    // These options are passed to Apollo's useQuery
+    variables: { limit: 10 },
+    // This context object is passed along the link chain
+    context: {
+      role: 'editor', // roleLink will pick this up
+    },
+  },
+});
+```
+
+This allows for fine-grained role control on a per-operation basis for queries and mutations. Remember, WebSocket subscriptions rely on the role established during the initial connection based on the token.

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,16 @@ 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;
+export declare const CHECK_CONNECTION_SUBSCRIPTION: import("@apollo/client").DocumentNode;
+export declare const CHECK_CONNECTION_QUERY: import("@apollo/client").DocumentNode;
 /**
  * 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;