nextjs-hasura-auth 0.1.1 → 0.1.3

package/dist/lib/authDbUtils.js

@@ -0,0 +1,183 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashPassword = hashPassword;
+exports.comparePassword = comparePassword;
+exports.getOrCreateUserAndAccount = getOrCreateUserAndAccount;
+const bcrypt_1 = __importDefault(require("bcrypt"));
+const client_1 = require("@apollo/client"); // Import ApolloError
+const debug_1 = __importDefault(require("./debug"));
+const debug = (0, debug_1.default)('auth:db-utils');
+const SALT_ROUNDS = 10;
+/**
+ * Hashes a password using bcrypt.
+ * @param password The plain text password.
+ * @returns The hashed password.
+ */
+function hashPassword(password) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const hashedPassword = yield bcrypt_1.default.hash(password, SALT_ROUNDS);
+        debug('Password hashed successfully.');
+        return hashedPassword;
+    });
+}
+/**
+ * Compares a plain text password with a hash.
+ * @param password The plain text password.
+ * @param hash The hash to compare against.
+ * @returns True if the password matches the hash, false otherwise.
+ */
+function comparePassword(password, hash) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const isMatch = yield bcrypt_1.default.compare(password, hash);
+        debug(`Password comparison result: ${isMatch}`);
+        return isMatch;
+    });
+}
+/**
+ * Finds or creates a user and their associated account based on provider information.
+ * This function handles the core logic of linking OAuth/Credentials logins to Hasura users.
+ *
+ * @param client The initialized NHA Client instance.
+ * @param provider The OAuth provider name (e.g., 'google', 'credentials').
+ * @param providerAccountId The user's unique ID from the provider.
+ * @param profile Optional profile information from the provider (name, email, image).
+ * @returns The Hasura user object associated with the account.
+ * @throws Error if user/account processing fails.
+ */
+function getOrCreateUserAndAccount(client, provider, providerAccountId, profile) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        debug(`getOrCreateUserAndAccount called for provider: ${provider}, providerAccountId: ${providerAccountId}`);
+        // --- 1. Try to find the account --- 
+        let existingUser = null;
+        try {
+            const accountResult = yield client.select({
+                table: 'accounts',
+                where: {
+                    provider: { _eq: provider },
+                    provider_account_id: { _eq: providerAccountId },
+                },
+                returning: [
+                    { user: ['id', 'name', 'email', 'email_verified', 'image', 'password', 'created_at', 'updated_at', 'is_admin', 'hasura_role'] } // Removed extra backslashes
+                ],
+                limit: 1, // Optimization: we only need one
+            });
+            if (((_a = accountResult === null || accountResult === void 0 ? void 0 : accountResult.accounts) === null || _a === void 0 ? void 0 : _a.length) > 0 && accountResult.accounts[0].user) {
+                existingUser = accountResult.accounts[0].user;
+                debug(`Found existing account for ${provider}:${providerAccountId}. User ID: ${existingUser.id}`);
+                // Optionally update user profile info (name, image) from provider here if desired
+                // await client.update({ table: 'users', pk_columns: { id: existingUser.id }, _set: { name: profile.name, image: profile.image } });
+                return existingUser;
+            }
+        }
+        catch (error) {
+            debug(`Error searching for account ${provider}:${providerAccountId}:`, error);
+            throw new Error(`Failed to search for existing account: ${error.message}`);
+        }
+        debug(`No existing account found for ${provider}:${providerAccountId}. Proceeding to find/create user.`);
+        // --- 2. Try to find the user by email (if provided) ---
+        // Important: Only link if email is provided and preferably verified by the OAuth provider.
+        // For credentials, we find the user first in the `authorize` function.
+        if ((profile === null || profile === void 0 ? void 0 : profile.email) && provider !== 'credentials') { // Avoid linking for credentials here
+            try {
+                const userByEmailResult = yield client.select({
+                    table: 'users',
+                    where: { email: { _eq: profile.email } },
+                    returning: ['id', 'name', 'email', 'email_verified', 'image', 'password', 'created_at', 'updated_at', 'is_admin', 'hasura_role'], // Removed extra backslashes
+                    limit: 1,
+                });
+                if (((_b = userByEmailResult === null || userByEmailResult === void 0 ? void 0 : userByEmailResult.users) === null || _b === void 0 ? void 0 : _b.length) > 0) {
+                    existingUser = userByEmailResult.users[0];
+                    debug(`Found existing user by email ${profile.email}. User ID: ${existingUser.id}. Linking account.`);
+                    // Link account to this existing user
+                    yield client.insert({
+                        table: 'accounts',
+                        object: {
+                            user_id: existingUser.id,
+                            provider: provider,
+                            provider_account_id: providerAccountId,
+                            type: provider === 'credentials' ? 'credentials' : 'oauth', // Set type based on provider
+                        },
+                        returning: ['id'], // Removed extra backslashes
+                    });
+                    debug(`Account ${provider}:${providerAccountId} linked to user ${existingUser.id}.`);
+                    return existingUser;
+                }
+            }
+            catch (error) {
+                // Handle potential duplicate account insertion error gracefully if needed
+                if (error instanceof client_1.ApolloError && error.message.includes('Uniqueness violation')) {
+                    debug(`Account ${provider}:${providerAccountId} likely already linked during concurrent request. Attempting to refetch.`);
+                    // Retry finding the account, as it might have been created concurrently
+                    return getOrCreateUserAndAccount(client, provider, providerAccountId, profile);
+                }
+                else {
+                    debug(`Error searching for user by email ${profile.email} or linking account:`, error);
+                    throw new Error(`Failed to process user by email or link account: ${error.message}`);
+                }
+            }
+        }
+        // --- 3. Create new user and account --- 
+        debug(`No existing user found by email or account link. Creating new user and account for ${provider}:${providerAccountId}.`);
+        try {
+            // We need to insert the user first, then the account linking to it.
+            // Hasura doesn't directly support nested inserts with linking back in the same mutation easily via the generator.
+            const newUserInput = {
+                name: profile === null || profile === void 0 ? void 0 : profile.name,
+                email: profile === null || profile === void 0 ? void 0 : profile.email, // Will be null for credentials initially, set later?
+                image: profile === null || profile === void 0 ? void 0 : profile.image,
+                hasura_role: 'user', // Default role
+                // email_verified: profile?.email_verified ? new Date().toISOString() : null, // Need verification logic for OAuth
+            };
+            // For credentials, the user is created *after* email verification, but we handle it here for OAuth
+            const newUserResult = yield client.insert({
+                table: 'users',
+                object: newUserInput,
+                // Return all fields needed for the session/JWT
+                returning: ['id', 'name', 'email', 'email_verified', 'image', 'password', 'created_at', 'updated_at', 'is_admin', 'hasura_role'], // Removed extra backslashes
+            });
+            if (!((_c = newUserResult === null || newUserResult === void 0 ? void 0 : newUserResult.insert_users_one) === null || _c === void 0 ? void 0 : _c.id)) {
+                throw new Error('Failed to create new user or retrieve its ID.');
+            }
+            const newUser = newUserResult.insert_users_one;
+            debug(`New user created with ID: ${newUser.id}`);
+            // Now create the account linked to the new user
+            yield client.insert({
+                table: 'accounts',
+                object: {
+                    user_id: newUser.id,
+                    provider: provider,
+                    provider_account_id: providerAccountId,
+                    type: provider === 'credentials' ? 'credentials' : 'oauth', // Set type based on provider
+                },
+                returning: ['id'], // Removed extra backslashes
+            });
+            debug(`Account ${provider}:${providerAccountId} created and linked to new user ${newUser.id}.`);
+            return newUser;
+        }
+        catch (error) {
+            debug('Error creating new user or account:', error);
+            // Handle potential duplicate user email error more gracefully if necessary
+            if (error instanceof client_1.ApolloError && error.message.includes('Uniqueness violation') && error.message.includes('users_email_key')) {
+                debug(`User with email ${profile === null || profile === void 0 ? void 0 : profile.email} likely already exists. Attempting to find and link.`);
+                // If user creation failed due to duplicate email, retry finding by email and linking account
+                if ((profile === null || profile === void 0 ? void 0 : profile.email) && provider !== 'credentials') {
+                    return getOrCreateUserAndAccount(client, provider, providerAccountId, profile);
+                }
+            }
+            throw new Error(`Failed to create new user/account: ${error.message}`);
+        }
+    });
+}

package/dist/lib/client.d.ts

@@ -0,0 +1,81 @@
+import { QueryHookOptions as ApolloQueryHookOptions, SubscriptionHookOptions as ApolloSubscriptionHookOptions, MutationHookOptions as ApolloMutationHookOptions, MutationTuple, QueryResult, SubscriptionResult, OperationVariables, ApolloClient, NormalizedCacheObject, FetchResult, Observable } from '@apollo/client';
+import { GenerateOptions } from './generator';
+interface ClientMethodOptions extends Omit<GenerateOptions, 'operation'> {
+    role?: string;
+}
+export declare class Client {
+    private apolloClient;
+    private generate;
+    constructor(apolloClient: ApolloClient<NormalizedCacheObject>);
+    /**
+     * Executes a GraphQL query (select operation).
+     * @param options - Options for generating the query, including an optional `role`.
+     * @returns Promise resolving with the query result data.
+     * @throws ApolloError if the query fails or returns GraphQL errors.
+     */
+    select<TData = any>(options: ClientMethodOptions): Promise<TData>;
+    /**
+     * Executes a GraphQL insert mutation.
+     * @param options - Options for generating the mutation, including an optional `role`.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    insert<TData = any>(options: ClientMethodOptions): Promise<TData>;
+    /**
+     * Executes a GraphQL update mutation.
+     * @param options - Options for generating the mutation, including an optional `role`.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    update<TData = any>(options: ClientMethodOptions): Promise<TData>;
+    /**
+     * Executes a GraphQL delete mutation.
+     * @param options - Options for generating the mutation, including an optional `role`.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    delete<TData = any>(options: ClientMethodOptions): Promise<TData>;
+    /**
+     * Initiates a GraphQL subscription.
+     * Note: Role support via context might not work for WebSockets depending on Apollo Link setup.
+     * Role is typically set during WebSocket connection establishment.
+     * @param options - Options for generating the subscription, including an optional `role`.
+     * @returns An Observable for the subscription results.
+     */
+    subscribe<TData = any, TVariables extends OperationVariables = OperationVariables>(options: ClientMethodOptions): Observable<FetchResult<TData>>;
+    useSubscription<TData = any, TVariables extends OperationVariables = OperationVariables>(generateOptions: ClientGeneratorOptions, hookOptions?: SubscriptionHookOptions<TData, TVariables> & {
+        variables?: TVariables;
+    }): SubscriptionResult<TData, TVariables>;
+    useQuery<TData = any, TVariables extends OperationVariables = OperationVariables>(generateOptions: ClientGeneratorOptions, hookOptions?: QueryHookOptions<TData, TVariables> & {
+        variables?: TVariables;
+    }): QueryResult<TData, TVariables>;
+}
+/**
+ * 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): Client;
+type BaseHookOptions = {
+    role?: string;
+};
+type QueryHookOptions<TData, TVariables extends OperationVariables> = BaseHookOptions & Omit<ApolloQueryHookOptions<TData, TVariables>, 'query' | 'variables' | 'context'>;
+type SubscriptionHookOptions<TData, TVariables extends OperationVariables> = BaseHookOptions & Omit<ApolloSubscriptionHookOptions<TData, TVariables>, 'query' | 'variables' | 'context'>;
+type MutationHookOptions<TData, TVariables extends OperationVariables> = BaseHookOptions & Omit<ApolloMutationHookOptions<TData, TVariables>, 'mutation' | 'variables' | 'context'>;
+type ClientGeneratorOptions = Omit<GenerateOptions, 'operation'>;
+export declare function useQuery<TData = any, TVariables extends OperationVariables = OperationVariables>(generateOptions: ClientGeneratorOptions, hookOptions?: QueryHookOptions<TData, TVariables> & {
+    variables?: TVariables;
+}): QueryResult<TData, TVariables>;
+export declare function useSubscription<TData = any, TVariables extends OperationVariables = OperationVariables>(generateOptions: ClientGeneratorOptions, hookOptions?: SubscriptionHookOptions<TData, TVariables> & {
+    variables?: TVariables;
+}): SubscriptionResult<TData, TVariables>;
+export declare function useMutation<TData = any, TVariables extends OperationVariables = OperationVariables>(generateOptions: GenerateOptions, // Use full GenerateOptions for mutations
+hookOptions?: MutationHookOptions<TData, TVariables>): MutationTuple<TData, TVariables>;
+export declare const useSelect: typeof useQuery;
+export declare const useInsert: (genOpts: Omit<GenerateOptions, "operation">, hookOpts?: MutationHookOptions<any, any>) => MutationTuple<any, any>;
+export declare const useUpdate: (genOpts: Omit<GenerateOptions, "operation">, hookOpts?: MutationHookOptions<any, any>) => MutationTuple<any, any>;
+export declare const useDelete: (genOpts: Omit<GenerateOptions, "operation">, hookOpts?: MutationHookOptions<any, any>) => MutationTuple<any, any>;
+export declare const useSubscribe: typeof useSubscription;
+export {};

package/dist/lib/client.js

@@ -0,0 +1,353 @@
+"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.useSubscribe = exports.useDelete = exports.useUpdate = exports.useInsert = exports.useSelect = exports.Client = void 0;
+exports.useClient = useClient;
+exports.useQuery = useQuery;
+exports.useSubscription = useSubscription;
+exports.useMutation = useMutation;
+const client_1 = require("@apollo/client");
+const react_1 = require("react");
+const client_2 = require("@apollo/client");
+const debug_1 = __importDefault(require("./debug"));
+const generator_1 = __importDefault(require("./generator"));
+const debug = (0, debug_1.default)('nha:client');
+class Client {
+    constructor(apolloClient) {
+        if (!apolloClient) {
+            throw new Error('❌ ApolloClient instance must be provided to the Client constructor.');
+        }
+        this.apolloClient = apolloClient;
+        this.generate = generator_1.default; // Use the imported generator function
+        debug('Client class initialized with ApolloClient instance.');
+    }
+    /**
+     * Executes a GraphQL query (select operation).
+     * @param options - Options for generating the query, including an optional `role`.
+     * @returns Promise resolving with the query result data.
+     * @throws ApolloError if the query fails or returns GraphQL errors.
+     */
+    select(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { role } = options, genOptions = __rest(options, ["role"]); // Extract role
+            debug('Executing select with options:', genOptions, 'Role:', role);
+            const generated = this.generate(Object.assign(Object.assign({}, genOptions), { operation: 'query' }));
+            try {
+                const result = yield this.apolloClient.query({
+                    query: generated.query,
+                    variables: generated.variables,
+                    fetchPolicy: 'network-only', // Ensure fresh data for direct calls
+                    context: role ? { role } : undefined, // Pass role in context
+                });
+                if (result.errors) {
+                    debug('GraphQL errors during select:', result.errors);
+                    throw new client_1.ApolloError({ graphQLErrors: result.errors });
+                }
+                debug('Select successful, returning data.');
+                return result.data;
+            }
+            catch (error) {
+                debug('Error during select:', error);
+                throw error; // Re-throw original error (could be ApolloError or network error)
+            }
+        });
+    }
+    /**
+     * Executes a GraphQL insert mutation.
+     * @param options - Options for generating the mutation, including an optional `role`.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    insert(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { role } = options, genOptions = __rest(options, ["role"]); // Extract role
+            debug('Executing insert with options:', genOptions, 'Role:', role);
+            const generated = this.generate(Object.assign(Object.assign({}, genOptions), { operation: 'insert' }));
+            try {
+                const result = yield this.apolloClient.mutate({
+                    mutation: generated.query,
+                    variables: generated.variables,
+                    context: role ? { role } : undefined, // Pass role in context
+                });
+                if (result.errors) {
+                    debug('GraphQL errors during insert:', result.errors);
+                    throw new client_1.ApolloError({ graphQLErrors: result.errors });
+                }
+                // Check if data exists, otherwise return an empty object or handle as needed
+                const returnData = (_a = result.data) !== null && _a !== void 0 ? _a : {};
+                debug('Insert successful, returning data.');
+                return returnData;
+            }
+            catch (error) {
+                debug('Error during insert:', error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Executes a GraphQL update mutation.
+     * @param options - Options for generating the mutation, including an optional `role`.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    update(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { role } = options, genOptions = __rest(options, ["role"]); // Extract role
+            debug('Executing update with options:', genOptions, 'Role:', role);
+            const generated = this.generate(Object.assign(Object.assign({}, genOptions), { operation: 'update' }));
+            try {
+                const result = yield this.apolloClient.mutate({
+                    mutation: generated.query,
+                    variables: generated.variables,
+                    context: role ? { role } : undefined, // Pass role in context
+                });
+                if (result.errors) {
+                    debug('GraphQL errors during update:', result.errors);
+                    throw new client_1.ApolloError({ graphQLErrors: result.errors });
+                }
+                const returnData = (_a = result.data) !== null && _a !== void 0 ? _a : {};
+                debug('Update successful, returning data.');
+                return returnData;
+            }
+            catch (error) {
+                debug('Error during update:', error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Executes a GraphQL delete mutation.
+     * @param options - Options for generating the mutation, including an optional `role`.
+     * @returns Promise resolving with the mutation result data.
+     * @throws ApolloError if the mutation fails or returns GraphQL errors.
+     */
+    delete(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { role } = options, genOptions = __rest(options, ["role"]); // Extract role
+            debug('Executing delete with options:', genOptions, 'Role:', role);
+            const generated = this.generate(Object.assign(Object.assign({}, genOptions), { operation: 'delete' }));
+            try {
+                const result = yield this.apolloClient.mutate({
+                    mutation: generated.query,
+                    variables: generated.variables,
+                    context: role ? { role } : undefined, // Pass role in context
+                });
+                if (result.errors) {
+                    debug('GraphQL errors during delete:', result.errors);
+                    throw new client_1.ApolloError({ graphQLErrors: result.errors });
+                }
+                const returnData = (_a = result.data) !== null && _a !== void 0 ? _a : {};
+                debug('Delete successful, returning data.');
+                return returnData;
+            }
+            catch (error) {
+                debug('Error during delete:', error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Initiates a GraphQL subscription.
+     * Note: Role support via context might not work for WebSockets depending on Apollo Link setup.
+     * Role is typically set during WebSocket connection establishment.
+     * @param options - Options for generating the subscription, including an optional `role`.
+     * @returns An Observable for the subscription results.
+     */
+    subscribe(options) {
+        const { role } = options, genOptions = __rest(options, ["role"]); // Extract role
+        debug('Initiating subscribe with options:', genOptions, 'Role:', role);
+        const generated = this.generate(Object.assign(Object.assign({}, genOptions), { operation: 'subscription' }));
+        return this.apolloClient.subscribe({
+            query: generated.query,
+            variables: generated.variables,
+            context: role ? { role } : undefined, // Pass role, effectiveness depends on link chain
+        });
+    }
+    useSubscription(
+    // First arg: Generator options (table, returning, where, etc.)
+    generateOptions, 
+    // Second arg: Hook options (Apollo options + role)
+    hookOptions // Allow variables here for subscription
+    ) {
+        return useSubscription(generateOptions, (0, react_1.useMemo)(() => (Object.assign(Object.assign({}, hookOptions), { client: this.apolloClient })), [hookOptions]));
+    }
+    ;
+    useQuery(
+    // First arg: Generator options (table, returning, where, etc.)
+    generateOptions, 
+    // Second arg: Hook options (Apollo options + role)
+    hookOptions // Allow variables here for query
+    ) {
+        return useQuery(generateOptions, (0, react_1.useMemo)(() => (Object.assign(Object.assign({}, hookOptions), { client: this.apolloClient })), [hookOptions]));
+    }
+}
+exports.Client = Client;
+// --- React Hooks ---
+/**
+ * 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.
+ */
+function useClient(providedClient) {
+    const ApolloContext = (0, client_1.getApolloContext)();
+    const contextValue = (0, react_1.useContext)(ApolloContext);
+    const contextClient = contextValue === null || contextValue === void 0 ? void 0 : contextValue.client;
+    const client = providedClient !== null && providedClient !== void 0 ? providedClient : contextClient;
+    if (!client) {
+        throw new Error('❌ useClient: No ApolloClient instance found. Provide one directly or ensure the component is wrapped in an ApolloProvider.');
+    }
+    return (0, react_1.useMemo)(() => new Client(client), [client]);
+}
+// Helper to extract Apollo options and context for HOOKS
+// Adjusted to not expect variables in mutation options directly
+function prepareHookArgs(options, isMutation = false) {
+    const _a = options || {}, { role } = _a, apolloOptions = __rest(_a, ["role"]);
+    const context = role ? { role } : undefined;
+    // Extract variables only if not a mutation (variables are passed to mutate fn)
+    // And if options actually contain variables (e.g., for query/sub)
+    const variables = !isMutation && options && 'variables' in options ? options.variables : undefined;
+    debug('Preparing hook args', { role, context, variables: isMutation ? '(mutation - in mutate fn)' : variables, apolloOptions });
+    return { context, variables, apolloOptions };
+}
+// Standalone Hooks
+function useQuery(
+// First arg: Generator options (table, returning, where, etc.)
+generateOptions, 
+// Second arg: Hook options (Apollo options + role)
+hookOptions // Allow variables here for query
+) {
+    var _a, _b;
+    const client = (0, client_2.useApolloClient)(); // Use client from context
+    // Generate query using the imported 'generate' function
+    const { query: queryString, variables: generatedVariables, varCounter } = (0, react_1.useMemo)(() => (0, generator_1.default)(Object.assign({ operation: 'query' }, generateOptions)), [generateOptions]);
+    // Ensure gql receives a string
+    const query = (0, react_1.useMemo)(() => (0, client_1.gql) `${queryString}`, [queryString]);
+    // Combine variables from generator and hook options (hook options override)
+    // Cast the combined object to TVariables
+    const combinedVariables = Object.assign(Object.assign({}, generatedVariables), hookOptions === null || hookOptions === void 0 ? void 0 : hookOptions.variables);
+    // Prepare arguments for the actual Apollo hook
+    const { context, apolloOptions } = prepareHookArgs(hookOptions, false);
+    const operationName = ((_a = query.definitions[0]) === null || _a === void 0 ? void 0 : _a.kind) === 'OperationDefinition' ? ((_b = query.definitions[0].name) === null || _b === void 0 ? void 0 : _b.value) || 'UnnamedQuery' : 'UnnamedQuery';
+    debug(`Executing query ${operationName}`, { query: queryString, variables: combinedVariables, context, options: apolloOptions });
+    const result = (0, client_2.useQuery)(query, Object.assign({ client, variables: combinedVariables, context }, apolloOptions));
+    debug(`Query ${operationName} result`, { loading: result.loading, error: result.error, data: !!result.data });
+    return result;
+}
+function useSubscription(
+// First arg: Generator options (table, returning, where, etc.)
+generateOptions, 
+// Second arg: Hook options (Apollo options + role)
+hookOptions // Allow variables here for subscription
+) {
+    var _a, _b, _c;
+    const apolloClient = (0, client_2.useApolloClient)(); // Use client from context
+    const client = (_a = hookOptions === null || hookOptions === void 0 ? void 0 : hookOptions.client) !== null && _a !== void 0 ? _a : apolloClient;
+    // Generate subscription using the imported 'generate' function
+    const { query: subscriptionString, variables: generatedVariables, varCounter } = (0, react_1.useMemo)(() => (0, generator_1.default)(Object.assign({ operation: 'subscription' }, generateOptions)), [generateOptions]);
+    // Ensure gql receives a string
+    const subscription = (0, react_1.useMemo)(() => (0, client_1.gql) `${subscriptionString}`, [subscriptionString]);
+    // Combine variables from generator and hook options (hook options override)
+    // Cast the combined object to TVariables
+    const combinedVariables = Object.assign(Object.assign({}, generatedVariables), hookOptions === null || hookOptions === void 0 ? void 0 : hookOptions.variables);
+    // Prepare arguments for the actual Apollo hook
+    const { context, apolloOptions } = prepareHookArgs(hookOptions, false);
+    const operationName = ((_b = subscription.definitions[0]) === null || _b === void 0 ? void 0 : _b.kind) === 'OperationDefinition' ? ((_c = subscription.definitions[0].name) === null || _c === void 0 ? void 0 : _c.value) || 'UnnamedSub' : 'UnnamedSub';
+    // Note: WebSocketLink in apollo.tsx might not support dynamic context/role per subscription easily.
+    // The role set via context here primarily affects the initial HTTP request if applicable,
+    // or needs custom WebSocket handling if role must change mid-subscription.
+    debug(`Executing subscription ${operationName}`, { query: subscriptionString, variables: combinedVariables, context, options: apolloOptions });
+    // Explicitly cast apolloOptions to the correct type expected by useApolloSubscription
+    const typedApolloOptions = apolloOptions;
+    const result = (0, client_2.useSubscription)(subscription, Object.assign({ client, variables: combinedVariables, context }, (typedApolloOptions)));
+    debug(`Subscription ${operationName} result`, { loading: result.loading, error: result.error, data: !!result.data });
+    return result;
+}
+function useMutation(
+// First arg: Generator options (MUST include operation: 'insert' | 'update' | 'delete')
+generateOptions, // Use full GenerateOptions for mutations
+// Second arg: Hook options (Apollo options + role)
+hookOptions) {
+    var _a, _b, _c;
+    const apolloClient = (0, client_2.useApolloClient)(); // Use client from context
+    const client = (_a = hookOptions === null || hookOptions === void 0 ? void 0 : hookOptions.client) !== null && _a !== void 0 ? _a : apolloClient;
+    // Validate that operation is insert/update/delete
+    if (!['insert', 'update', 'delete'].includes(generateOptions.operation)) {
+        throw new Error(`useMutation hook requires operation to be 'insert', 'update', or 'delete' in generateOptions.`);
+    }
+    // Generate mutation using the imported 'generate' function
+    // Variables from generateOptions are the *base* for the mutation
+    const { query: mutationString, variables: baseVariables, varCounter } = (0, react_1.useMemo)(() => (0, generator_1.default)(generateOptions), [generateOptions]);
+    // Ensure gql receives a string
+    const mutation = (0, react_1.useMemo)(() => (0, client_1.gql) `${mutationString}`, [mutationString]);
+    // Prepare arguments for the actual Apollo hook (context, apolloOptions)
+    // Variables are NOT prepared here, they are passed to the mutate function
+    const { context, apolloOptions } = prepareHookArgs(hookOptions, true); // Pass true for isMutation
+    const operationName = ((_b = mutation.definitions[0]) === null || _b === void 0 ? void 0 : _b.kind) === 'OperationDefinition' ? ((_c = mutation.definitions[0].name) === null || _c === void 0 ? void 0 : _c.value) || 'UnnamedMutation' : 'UnnamedMutation';
+    debug(`Preparing mutation ${operationName}`, { query: mutationString, context, options: apolloOptions, baseVariables });
+    // Explicitly cast apolloOptions to the correct type expected by useApolloMutation
+    const typedApolloOptions = apolloOptions;
+    // Variables are passed to the mutate function, not the hook itself usually
+    const [mutate, result] = (0, client_2.useMutation)(mutation, Object.assign({ client, // Pass the client explicitly if needed
+        context }, (typedApolloOptions)));
+    // Wrap the mutate function to potentially add logging or other logic
+    const wrappedMutate = (0, react_1.useCallback)((mutateOptions) => __awaiter(this, void 0, void 0, function* () {
+        // Combine base variables from generator with variables passed to this specific mutate call
+        // Cast the combined object to TVariables
+        const finalVariables = Object.assign(Object.assign({}, baseVariables), mutateOptions === null || mutateOptions === void 0 ? void 0 : mutateOptions.variables);
+        debug(`Executing mutation ${operationName}`, {
+            variables: finalVariables,
+            context: (mutateOptions === null || mutateOptions === void 0 ? void 0 : mutateOptions.context) || context, // Use context from mutate call or default
+            optimisticResponse: mutateOptions === null || mutateOptions === void 0 ? void 0 : mutateOptions.optimisticResponse,
+            update: !!(mutateOptions === null || mutateOptions === void 0 ? void 0 : mutateOptions.update),
+        });
+        try {
+            // Pass final combined variables to the actual mutate function
+            const mutationResult = yield mutate(Object.assign(Object.assign({}, mutateOptions), { variables: finalVariables }));
+            debug(`Mutation ${operationName} success`, { data: mutationResult.data });
+            return mutationResult;
+        }
+        catch (error) {
+            debug(`Mutation ${operationName} error`, { error });
+            // Let the error propagate to be handled by Apollo Client / component
+            throw error;
+        }
+    }), [mutate, operationName, context, baseVariables]); // Include baseVariables in dependency array
+    debug(`Mutation ${operationName} hook state`, { loading: result.loading, error: result.error, data: result.data });
+    return [wrappedMutate, result];
+}
+// Aliases for convenience (Hooks)
+exports.useSelect = useQuery;
+const useInsert = (genOpts, hookOpts) => useMutation(Object.assign({ operation: 'insert' }, genOpts), hookOpts);
+exports.useInsert = useInsert;
+const useUpdate = (genOpts, hookOpts) => useMutation(Object.assign({ operation: 'update' }, genOpts), hookOpts);
+exports.useUpdate = useUpdate;
+const useDelete = (genOpts, hookOpts) => useMutation(Object.assign({ operation: 'delete' }, genOpts), hookOpts);
+exports.useDelete = useDelete;
+exports.useSubscribe = useSubscription;

package/dist/lib/email.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sends the verification email to a newly registered user.
+ * @param email - The recipient's email address.
+ * @param token - The verification token.
+ * @returns Promise<boolean> - True if email was sent successfully.
+ */
+export declare function sendVerificationEmail(email: string, token: string): Promise<boolean>;