tessl/npm-keycloak--keycloak-admin-client

A comprehensive TypeScript client library for interacting with Keycloak's Administration API.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Utility Functions

Name: tessl/npm-keycloak--keycloak-admin-client
Author: tessl

Error handling, network utilities, authentication helpers, and common constants for robust client operations.

Capabilities

Network Error Handling

Custom error class providing detailed information about HTTP failures and response data.

/**
 * Enhanced error class for network-related failures
 * Provides access to HTTP response and parsed response data
 */
class NetworkError extends Error {
  /** The HTTP Response object that caused the error */
  response: Response;
  /** Parsed response data (JSON, text, etc.) */
  responseData: unknown;
  
  /**
   * Create a new NetworkError instance
   * @param message - Error message describing the failure
   * @param options - Error options with response details
   */
  constructor(message: string, options: NetworkErrorOptions);
}

/**
 * Options for NetworkError construction
 */
interface NetworkErrorOptions {
  /** HTTP Response object */
  response: Response;
  /** Parsed response data */
  responseData: unknown;
}

Usage Examples:

import { NetworkError } from "@keycloak/keycloak-admin-client";

try {
  await kcAdminClient.users.findOne({ id: "non-existent-user-id" });
} catch (error) {
  if (error instanceof NetworkError) {
    console.log("HTTP Status:", error.response.status); // 404
    console.log("Status Text:", error.response.statusText); // "Not Found"
    console.log("Response Data:", error.responseData); // Error details from server
    console.log("Error Message:", error.message); // "Request failed with status 404"
    
    // Handle specific error cases
    switch (error.response.status) {
      case 401:
        console.log("Authentication required");
        break;
      case 403:
        console.log("Insufficient permissions");
        break;
      case 404:
        console.log("Resource not found");
        break;
      case 409:
        console.log("Resource conflict (duplicate)");
        break;
    }
  }
}

Enhanced Fetch Function

HTTP utility function with automatic error handling and response parsing.

/**
 * Enhanced fetch function with automatic error handling
 * Throws NetworkError for non-2xx responses
 * @param input - Request URL, Request object, or URL object
 * @param init - Optional RequestInit configuration
 * @returns Promise resolving to Response object
 * @throws NetworkError for HTTP errors
 */
function fetchWithError(
  input: Request | string | URL,
  init?: RequestInit,
): Promise<Response>;

/**
 * Parse response body automatically based on Content-Type
 * @param response - HTTP Response object
 * @returns Parsed response data (JSON object, text, etc.)
 */
function parseResponse(response: Response): Promise<any>;

Usage Examples:

import { fetchWithError, parseResponse } from "@keycloak/keycloak-admin-client";

// Basic usage with automatic error handling
try {
  const response = await fetchWithError("https://api.example.com/data", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${token}`,
    },
    body: JSON.stringify({ data: "example" }),
  });
  
  const data = await parseResponse(response);
  console.log("Success:", data);
} catch (error) {
  if (error instanceof NetworkError) {
    console.log("Request failed:", error.message);
  }
}

Query Parameter Utilities

Utility functions for converting objects to URL query parameters.

/**
 * Convert object to URL search parameters string
 * Handles nested objects, arrays, and undefined values
 * @param params - Object with query parameters
 * @returns URL-encoded query string (without leading '?')
 */
function stringifyQueryParams(params: Record<string, unknown>): string;

Usage Examples:

import { stringifyQueryParams } from "@keycloak/keycloak-admin-client";

// Simple parameters
const queryString = stringifyQueryParams({
  max: 10,
  first: 0,
  search: "john",
  enabled: true,
});
// Result: "max=10&first=0&search=john&enabled=true"

// Complex parameters with arrays and nested objects
const complexQuery = stringifyQueryParams({
  max: 50,
  attributes: ["email", "firstName", "lastName"],
  filter: {
    enabled: true,
    emailVerified: false,
  },
  sort: "username:asc",
});
// Properly encoded query string for complex data structures

Required Action Constants

Predefined constants for Keycloak required actions.

/**
 * Standard Keycloak required action aliases
 * Used for user required actions and email actions
 */
enum RequiredActionAlias {
  /** Email verification required action */
  VERIFY_EMAIL = "VERIFY_EMAIL",
  /** Profile update required action */
  UPDATE_PROFILE = "UPDATE_PROFILE",
  /** TOTP configuration required action */
  CONFIGURE_TOTP = "CONFIGURE_TOTP",
  /** Password update required action */
  UPDATE_PASSWORD = "UPDATE_PASSWORD",
  /** Terms and conditions acceptance required action */
  TERMS_AND_CONDITIONS = "TERMS_AND_CONDITIONS",
}

/**
 * Exported required action constant for convenience
 * Alias for RequiredActionAlias enum
 */
const requiredAction: typeof RequiredActionAlias;

Usage Examples:

import { requiredAction } from "@keycloak/keycloak-admin-client";

// Send email with required actions
await kcAdminClient.users.executeActionsEmail({
  id: userId,
  actions: [
    requiredAction.VERIFY_EMAIL,
    requiredAction.UPDATE_PROFILE,
    requiredAction.CONFIGURE_TOTP,
  ],
  clientId: "my-client",
  redirectUri: "https://myapp.com/welcome",
  lifespan: 3600, // 1 hour
});

// Check all available required actions
const allActions = Object.values(requiredAction);
console.log("Available required actions:", allActions);
// ["VERIFY_EMAIL", "UPDATE_PROFILE", "CONFIGURE_TOTP", "UPDATE_PASSWORD", "TERMS_AND_CONDITIONS"]

Configuration Constants

Default configuration values used throughout the client.

/**
 * Default Keycloak server base URL
 * Used when no baseUrl is provided in ConnectionConfig
 */
const defaultBaseUrl = "http://127.0.0.1:8180";

/**
 * Default realm name for authentication and operations
 * Used when no realmName is provided in ConnectionConfig
 */
const defaultRealm = "master";

Usage Examples:

import { defaultBaseUrl, defaultRealm } from "@keycloak/keycloak-admin-client";

// Use defaults explicitly
const kcAdminClient = new KeycloakAdminClient({
  baseUrl: defaultBaseUrl, // "http://127.0.0.1:8180"
  realmName: defaultRealm, // "master"
});

// Check if using defaults
console.log("Using default URL:", kcAdminClient.baseUrl === defaultBaseUrl);
console.log("Using default realm:", kcAdminClient.realmName === defaultRealm);

Authentication Utilities

Low-level authentication functions for custom token management.

/**
 * Settings for token acquisition
 */
interface Settings {
  /** Realm name for authentication */
  realmName?: string;
  /** Keycloak base URL */
  baseUrl?: string;
  /** OAuth2 scope parameter */
  scope?: string;
  /** Authentication credentials */
  credentials: Credentials;
  /** Additional request options */
  requestOptions?: RequestInit;
}

/**
 * Acquire access and refresh tokens using specified settings
 * Low-level function used internally by auth() method
 * @param settings - Authentication settings and credentials
 * @returns Promise resolving to token response
 * @throws NetworkError for authentication failures
 */
function getToken(settings: Settings): Promise<TokenResponse>;

Usage Examples:

import { getToken } from "@keycloak/keycloak-admin-client";

// Direct token acquisition (advanced usage)
try {
  const tokenResponse = await getToken({
    baseUrl: "https://keycloak.example.com",
    realmName: "my-realm",
    credentials: {
      grantType: "client_credentials",
      clientId: "service-account",
      clientSecret: "secret-key",
    },
    requestOptions: {
      timeout: 10000,
    },
  });
  
  console.log("Access Token:", tokenResponse.accessToken);
  console.log("Expires In:", tokenResponse.expiresIn);
  console.log("Token Type:", tokenResponse.tokenType);
} catch (error) {
  if (error instanceof NetworkError) {
    console.log("Token acquisition failed:", error.responseData);
  }
}

Error Handling Patterns

Common patterns for handling different types of errors in Keycloak operations.

// Pattern 1: Resource not found handling
try {
  const user = await kcAdminClient.users.findOne({ id: userId });
  console.log("User found:", user);
} catch (error) {
  if (error instanceof NetworkError && error.response.status === 404) {
    console.log("User does not exist");
    return null;
  }
  throw error; // Re-throw other errors
}

// Pattern 2: Using catchNotFound option
const user = await kcAdminClient.users.findOne(
  { id: userId },
  { catchNotFound: true }
);
if (!user) {
  console.log("User does not exist");
}

// Pattern 3: Batch operations error handling
const results = [];
const errors = [];

for (const userData of usersToCreate) {
  try {
    const result = await kcAdminClient.users.create(userData);
    results.push(result);
  } catch (error) {
    if (error instanceof NetworkError) {
      errors.push({
        userData,
        status: error.response.status,
        error: error.responseData,
      });
    } else {
      errors.push({ userData, error: error.message });
    }
  }
}

console.log(`Created ${results.length} users, ${errors.length} errors`);

tessl/npm-keycloak--keycloak-admin-client