Blade Authentication Utilities

Common errors

• Error: Invalid trigger syntax provided.

  cause Attempting to use pre-3.29.0 trigger syntax after upgrading to version 3.29.0 or later.
  fix Update your trigger definitions to comply with the simplified trigger syntax introduced in `blade-auth` v3.29.0. Consult the latest Blade documentation for examples.

• TypeError: Cannot read properties of undefined (reading 'isAuthenticated')

  cause The `getAuthSession()` function returned `null` or `undefined` because the user is not logged in or the authentication service is not initialized correctly.
  fix Always check if the session object returned by `getAuthSession()` is defined and its properties (like `isAuthenticated`) exist before accessing them. Ensure `initAuth` is called before any other auth operations.

• AuthError: Invalid credentials.

  cause The username or password provided to `signIn` or `signUp` did not match records on the authentication server.
  fix Double-check the provided credentials. If this error persists, investigate the server-side authentication logs or ensure the `apiBaseUrl` provided to `initAuth` points to the correct authentication endpoint.

Warnings

• breaking Version 3.29.0 introduced a 'simplified trigger syntax' which updated auth logic and likely renders previous trigger configurations incompatible. Applications upgrading from earlier 3.x versions will need to adapt their trigger definitions.
  Fix: Review the official Blade documentation for the updated trigger syntax introduced in 3.29.0 and refactor existing trigger configurations accordingly. Pay close attention to how triggers are declared and loaded.
• gotcha When defining or referencing triggers, ensure they are consistently kebab-cased. Version 3.29.8 explicitly documented this convention, suggesting it's important for correct functionality.
  Fix: Standardize all trigger names and references to use kebab-case (e.g., `my-auth-trigger` instead of `myAuthTrigger`).
• gotcha This library is primarily built for the Blade ecosystem. Attempting to use `blade-auth` outside of a properly configured Blade application context might lead to unexpected behavior or require significant manual setup not covered by its utilities.
  Fix: Ensure your project is a Blade application and `blade-auth` is integrated as intended by the framework's documentation. Avoid standalone usage without understanding its dependencies on the Blade runtime.

Install

• npm install blade-auth npm
• yarn add blade-auth yarn
• pnpm add blade-auth pnpm

Imports

• initAuth
  wrong:

  const initAuth = require('blade-auth').initAuth;

  correct:

  import { initAuth } from 'blade-auth';

  Most Blade packages are ESM-first. Use named imports for core utilities.
• signIn
  wrong:

  import signIn from 'blade-auth/signIn';

  correct:

  import { signIn } from 'blade-auth';

  Authentication actions like `signIn` are typically named exports from the main package entry point.
• getAuthSession
  wrong:

  const { getAuthSession } = require('blade-auth');

  correct:

  import { getAuthSession } from 'blade-auth';

  For retrieving the current authentication state or session, `getAuthSession` is a common named export.

Quickstart

This quickstart demonstrates the initialization of `blade-auth`, a user signup and sign-in flow, retrieving the current session, and finally signing out.

import { initAuth, signIn, signUp, signOut, getAuthSession } from 'blade-auth';

interface AuthConfig {
  apiBaseUrl: string;
  jwtSecret: string;
}

interface UserCredentials {
  email: string;
  password: string;
}

async function runAuthFlow() {
  // Initialize auth with configuration
  const config: AuthConfig = {
    apiBaseUrl: process.env.BLADE_API_URL ?? 'https://api.example.com/v1',
    jwtSecret: process.env.BLADE_JWT_SECRET ?? 'super-secret-key-please-change'
  };
  
  // In a real app, this would be configured once, likely on app start
  initAuth(config);

  const user: UserCredentials = {
    email: 'test@example.com',
    password: 'password123'
  };

  try {
    console.log('Attempting to sign up...');
    const signUpResult = await signUp(user.email, user.password);
    console.log('Sign up successful:', signUpResult);

    console.log('Attempting to sign in...');
    const signInResult = await signIn(user.email, user.password);
    console.log('Sign in successful:', signInResult);

    console.log('Getting current auth session...');
    const session = await getAuthSession();
    console.log('Current session:', session);

    if (session?.isAuthenticated) {
      console.log('User is authenticated. Token:', session.token);
    }

    console.log('Attempting to sign out...');
    await signOut();
    console.log('Sign out successful.');

    const postSignOutSession = await getAuthSession();
    console.log('Session after sign out:', postSignOutSession);

  } catch (error) {
    console.error('Authentication error:', error);
  }
}

runAuthFlow();