Client Management

/**
 * Client query interface for filtering and pagination
 */
interface ClientQuery extends PaginatedQuery {
  /** Filter by client ID */
  clientId?: string;
  /** Only return viewable clients */
  viewableOnly?: boolean;
  /** Enable search mode */
  search?: boolean;
  /** Query string for search */
  q?: string;
}

interface PaginatedQuery {
  /** Starting index for pagination (0-based) */
  first?: number;
  /** Maximum number of results to return */
  max?: number;
}

/**
 * Find clients with optional filtering and pagination
 * @param query - Optional query parameters for filtering clients
 * @returns Array of client representations
 */
find(query?: ClientQuery): Promise<ClientRepresentation[]>;

/**
 * Create a new client
 * @param client - Client representation with client details
 * @returns Object containing the ID of the created client
 */
create(client: ClientRepresentation): Promise<{ id: string }>;

/**
 * Get a single client by ID
 * @param params - Parameters including client ID
 * @returns Client representation or undefined if not found
 */
findOne(params: { id: string }): Promise<ClientRepresentation | undefined>;

/**
 * Update an existing client
 * @param query - Query containing client ID
 * @param client - Updated client representation
 */
update(query: { id: string }, client: ClientRepresentation): Promise<void>;

/**
 * Delete a client
 * @param params - Parameters containing client ID
 */
del(params: { id: string }): Promise<void>;

// Find all clients
const clients = await kcAdminClient.clients.find();

// Search for specific client
const myClients = await kcAdminClient.clients.find({
  clientId: "my-app",
});

// Create OAuth2 confidential client
const { id } = await kcAdminClient.clients.create({
  clientId: "my-oauth-client",
  name: "My OAuth2 Application",
  enabled: true,
  publicClient: false,
  standardFlowEnabled: true,
  directAccessGrantsEnabled: true,
  serviceAccountsEnabled: true,
  redirectUris: ["https://myapp.com/callback"],
  webOrigins: ["https://myapp.com"],
  protocol: "openid-connect",
});

// Update client configuration
await kcAdminClient.clients.update({ id }, {
  description: "Updated OAuth2 client",
  baseUrl: "https://myapp.com",
  adminUrl: "https://myapp.com/admin",
});

// Get client details
const client = await kcAdminClient.clients.findOne({ id });

/**
 * Complete client representation with all OAuth2/OIDC configuration options
 */
interface ClientRepresentation {
  /** Access control permissions */
  access?: Record<string, boolean>;
  /** Admin URL for client callbacks */
  adminUrl?: string;
  /** Custom client attributes */
  attributes?: Record<string, any>;
  /** Authentication flow binding overrides */
  authenticationFlowBindingOverrides?: Record<string, any>;
  /** Enable authorization services (UMA) */
  authorizationServicesEnabled?: boolean;
  /** Authorization server settings */
  authorizationSettings?: ResourceServerRepresentation;
  /** Base URL for client */
  baseUrl?: string;
  /** Bearer-only client (no login redirect) */
  bearerOnly?: boolean;
  /** Client authenticator type */
  clientAuthenticatorType?: string;
  /** Unique client identifier */
  clientId?: string;
  /** Require user consent */
  consentRequired?: boolean;
  /** Default client scopes */
  defaultClientScopes?: string[];
  /** Default roles for new users */
  defaultRoles?: string[];
  /** Client description */
  description?: string;
  /** Enable direct access grants (Resource Owner Password Credentials) */
  directAccessGrantsEnabled?: boolean;
  /** Whether client is enabled */
  enabled?: boolean;
  /** Always display in admin console */
  alwaysDisplayInConsole?: boolean;
  /** Enable frontchannel logout */
  frontchannelLogout?: boolean;
  /** Allow full scope mappings */
  fullScopeAllowed?: boolean;
  /** Unique client UUID */
  id?: string;
  /** Enable implicit flow */
  implicitFlowEnabled?: boolean;
  /** Client display name */
  name?: string;
  /** Node re-registration timeout */
  nodeReRegistrationTimeout?: number;
  /** Not-before policy timestamp */
  notBefore?: number;
  /** Optional client scopes */
  optionalClientScopes?: string[];
  /** Origin information */
  origin?: string;
  /** Protocol type (openid-connect, saml) */
  protocol?: string;
  /** Protocol mappers configuration */
  protocolMappers?: ProtocolMapperRepresentation[];
  /** Public client (no client secret) */
  publicClient?: boolean;
  /** Valid redirect URIs */
  redirectUris?: string[];
  /** Registered cluster nodes */
  registeredNodes?: Record<string, any>;
  /** Registration access token */
  registrationAccessToken?: string;
  /** Root URL for relative URIs */
  rootUrl?: string;
  /** Client secret (for confidential clients) */
  secret?: string;
  /** Enable service accounts */
  serviceAccountsEnabled?: boolean;
  /** Enable standard flow (Authorization Code) */
  standardFlowEnabled?: boolean;
  /** Surrogate auth required */
  surrogateAuthRequired?: boolean;
  /** Valid web origins for CORS */
  webOrigins?: string[];
}

// Public SPA client
await kcAdminClient.clients.create({
  clientId: "spa-app",
  name: "Single Page Application",
  enabled: true,
  publicClient: true,
  standardFlowEnabled: true,
  implicitFlowEnabled: false,
  directAccessGrantsEnabled: false,
  redirectUris: ["https://spa.example.com/*"],
  webOrigins: ["https://spa.example.com"],
  protocol: "openid-connect",
});

// Confidential server-side client
await kcAdminClient.clients.create({
  clientId: "backend-service",
  name: "Backend Service",
  enabled: true,
  publicClient: false,
  standardFlowEnabled: true,
  directAccessGrantsEnabled: true,
  serviceAccountsEnabled: true,
  redirectUris: ["https://backend.example.com/callback"],
  webOrigins: ["https://backend.example.com"],
  protocol: "openid-connect",
});

// Machine-to-machine client (service account only)
await kcAdminClient.clients.create({
  clientId: "m2m-service",
  name: "Machine to Machine Service",
  enabled: true,
  publicClient: false,
  serviceAccountsEnabled: true,
  standardFlowEnabled: false,
  implicitFlowEnabled: false,
  directAccessGrantsEnabled: false,
  protocol: "openid-connect",
});

// Bearer-only resource server
await kcAdminClient.clients.create({
  clientId: "api-server",
  name: "API Resource Server",
  enabled: true,
  bearerOnly: true,
  protocol: "openid-connect",
});

/**
 * Create a new role for the client
 * @param params - Client ID and role representation
 * @returns Object containing the role name
 */
createRole(params: { id: string; role: RoleRepresentation }): Promise<{ roleName: string }>;

/**
 * List all roles for a client
 * @param params - Parameters containing client ID
 * @returns Array of client role representations
 */
listRoles(params: { id: string }): Promise<RoleRepresentation[]>;

/**
 * Find a specific client role by name
 * @param params - Client ID and role name
 * @returns Role representation or null if not found
 */
findRole(params: { id: string; roleName: string }): Promise<RoleRepresentation | null>;

/**
 * Update an existing client role
 * @param query - Client ID and role name
 * @param role - Updated role representation
 */
updateRole(query: { id: string; roleName: string }, role: RoleRepresentation): Promise<void>;

/**
 * Delete a client role
 * @param params - Client ID and role name
 */
delRole(params: { id: string; roleName: string }): Promise<void>;

/**
 * Find users with specific client role
 * @param params - Client ID, role name, and pagination options
 * @returns Array of users with the specified role
 */
findUsersWithRole(params: {
  id: string;
  roleName: string;
  briefRepresentation?: boolean;
  first?: number;
  max?: number;
}): Promise<UserRepresentation[]>;

// Create client roles
await kcAdminClient.clients.createRole({
  id: clientId,
  role: {
    name: "admin",
    description: "Administrator role for the client",
    composite: false,
  },
});

await kcAdminClient.clients.createRole({
  id: clientId,
  role: {
    name: "user",
    description: "Standard user role",
    composite: false,
  },
});

// List all client roles
const clientRoles = await kcAdminClient.clients.listRoles({ id: clientId });

// Find specific role
const adminRole = await kcAdminClient.clients.findRole({
  id: clientId,
  roleName: "admin",
});

// Find users with client role
const admins = await kcAdminClient.clients.findUsersWithRole({
  id: clientId,
  roleName: "admin",
  briefRepresentation: true,
});

/**
 * Get the service account user for a client
 * @param params - Parameters containing client ID
 * @returns User representation of the service account
 */
getServiceAccountUser(params: { id: string }): Promise<UserRepresentation>;

// Get service account user
const serviceAccount = await kcAdminClient.clients.getServiceAccountUser({
  id: clientId,
});

// Use the service account user ID for role mappings
await kcAdminClient.users.addRealmRoleMappings({
  id: serviceAccount.id!,
  roles: [{ id: "realm-role-id", name: "service-role" }],
});

/**
 * Generate a new client secret
 * @param params - Parameters containing client ID
 * @returns New credential representation with secret
 */
generateNewClientSecret(params: { id: string }): Promise<CredentialRepresentation>;

/**
 * Get current client secret
 * @param params - Parameters containing client ID
 * @returns Current credential representation
 */
getClientSecret(params: { id: string }): Promise<CredentialRepresentation>;

// Generate new client secret
const newSecret = await kcAdminClient.clients.generateNewClientSecret({
  id: clientId,
});
console.log("New secret:", newSecret.value);

// Get current secret
const currentSecret = await kcAdminClient.clients.getClientSecret({
  id: clientId,
});

/**
 * Get default client scopes for a client
 * @param params - Parameters containing client ID
 * @returns Array of default client scopes
 */
listDefaultClientScopes(params: { id: string }): Promise<ClientScopeRepresentation[]>;

/**
 * Add default client scope to client
 * @param params - Client ID and client scope ID
 */
addDefaultClientScope(params: { id: string; clientScopeId: string }): Promise<void>;

/**
 * Remove default client scope from client
 * @param params - Client ID and client scope ID
 */
delDefaultClientScope(params: { id: string; clientScopeId: string }): Promise<void>;

/**
 * Get optional client scopes for a client
 * @param params - Parameters containing client ID
 * @returns Array of optional client scopes
 */
listOptionalClientScopes(params: { id: string }): Promise<ClientScopeRepresentation[]>;

/**
 * Add optional client scope to client
 * @param params - Client ID and client scope ID
 */
addOptionalClientScope(params: { id: string; clientScopeId: string }): Promise<void>;

/**
 * Remove optional client scope from client
 * @param params - Client ID and client scope ID
 */
delOptionalClientScope(params: { id: string; clientScopeId: string }): Promise<void>;

/**
 * Create protocol mapper for client
 * @param params - Client ID and protocol mapper configuration
 * @returns Created protocol mapper ID
 */
addProtocolMapper(params: { id: string; mapper: ProtocolMapperRepresentation }): Promise<{ id: string }>;

/**
 * List protocol mappers for client
 * @param params - Parameters containing client ID
 * @returns Array of protocol mapper representations
 */
listProtocolMappers(params: { id: string }): Promise<ProtocolMapperRepresentation[]>;

/**
 * Find protocol mapper by ID
 * @param params - Client ID and mapper ID
 * @returns Protocol mapper representation or undefined
 */
findProtocolMapperById(params: { id: string; mapperId: string }): Promise<ProtocolMapperRepresentation | undefined>;

/**
 * Update protocol mapper
 * @param query - Client ID and mapper ID
 * @param mapper - Updated protocol mapper representation
 */
updateProtocolMapper(query: { id: string; mapperId: string }, mapper: ProtocolMapperRepresentation): Promise<void>;

/**
 * Delete protocol mapper
 * @param params - Client ID and mapper ID
 */
delProtocolMapper(params: { id: string; mapperId: string }): Promise<void>;

// Add audience mapper for JWT tokens
await kcAdminClient.clients.addProtocolMapper({
  id: clientId,
  mapper: {
    name: "audience-mapper",
    protocol: "openid-connect",
    protocolMapper: "oidc-audience-mapper",
    config: {
      "included.client.audience": "my-api",
      "access.token.claim": "true",
    },
  },
});

// Add custom claim mapper
await kcAdminClient.clients.addProtocolMapper({
  id: clientId,
  mapper: {
    name: "department-mapper",
    protocol: "openid-connect",
    protocolMapper: "oidc-usermodel-attribute-mapper",
    config: {
      "user.attribute": "department",
      "claim.name": "department",
      "access.token.claim": "true",
      "id.token.claim": "true",
      "userinfo.token.claim": "true",
    },
  },
});

/**
 * Get installation/configuration for client adapter
 * @param params - Client ID and provider ID
 * @returns Installation configuration string
 */
getInstallationProvider(params: { 
  id: string; 
  providerId: string; 
}): Promise<string>;

// Get keycloak.json for JavaScript adapter
const keycloakJson = await kcAdminClient.clients.getInstallationProvider({
  id: clientId,
  providerId: "keycloak-oidc-keycloak-json",
});

// Get configuration for Spring Boot adapter
const springConfig = await kcAdminClient.clients.getInstallationProvider({
  id: clientId,
  providerId: "keycloak-oidc-jboss-subsystem",
});

/**
 * List user sessions for client
 * @param params - Client ID with optional pagination
 * @returns Array of user sessions for the client
 */
listSessions(params: { id: string; first?: number; max?: number }): Promise<UserSessionRepresentation[]>;

/**
 * Get offline sessions count for client
 * @param params - Parameters containing client ID
 * @returns Object containing the count of offline sessions
 */
getOfflineSessionCount(params: { id: string }): Promise<{ count: number }>;

/**
 * List offline sessions for client
 * @param params - Client ID with optional pagination
 * @returns Array of offline sessions
 */
listOfflineSessions(params: { id: string; first?: number; max?: number }): Promise<UserSessionRepresentation[]>;

/**
 * Register cluster node for client
 * @param params - Client ID and node information
 */
registerClusterNode(params: { id: string; node: Record<string, any> }): Promise<void>;

/**
 * Unregister cluster node for client
 * @param params - Parameters containing client ID
 */
unregisterClusterNode(params: { id: string }): Promise<void>;