A TypeScript package for interacting with the JumpCloud API, providing user and group management capabilities.
npm install @clearfeed-ai/quix-jumpcloud-agentA TypeScript package for interacting with the JumpCloud API, providing user and group management capabilities.
- User Management: Create, read, update, delete, and list users
- Group Management: Create, delete, and list groups
- Group Membership: Assign and unassign users to/from groups
- Device Management: List devices assigned to users and all devices in the organization
- Error Handling: Comprehensive error handling with detailed error messages
- Type Safety: Full TypeScript support with proper type definitions
- Tool Integration: LangChain-compatible tools for AI agents
``bash`
yarn add @clearfeed-ai/quix-jumpcloud-agent
`typescript
import { JumpCloudService } from '@clearfeed-ai/quix-jumpcloud-agent';
const service = new JumpCloudService({
apiKey: 'your-jumpcloud-api-key',
baseUrl: 'https://console.jumpcloud.com/api' | 'https://console.eu.jumpcloud.com/api' // mandatory - depending on your base region
});
`
`typescript
// List users
const users = await service.listUsers({ limit: 10, query: 'admin' });
// Create a user
const newUser = await service.createUser({
username: 'john.doe',
email: 'john.doe@example.com',
firstname: 'John',
lastname: 'Doe'
});
// Get a specific user
const user = await service.getUser({ userId: 'user-id' });
// Update a user
const updatedUser = await service.updateUser({
userId: 'user-id',
payload: { firstname: 'Jane' }
});
// Delete a user
const deleteResult = await service.deleteUser({ userId: 'user-id' });
`
`typescript
// List groups
const groups = await service.listGroups({ limit: 10 });
// Create a group
const newGroup = await service.createGroup({
name: 'Developers',
description: 'Development team group'
});
// Assign user to group
const assignResult = await service.assignUserToGroup({
userId: 'user-id',
groupId: 'group-id'
});
// List users in a group
const groupUsers = await service.listGroupUsers({ groupId: 'group-id' });
// Remove user from group
const unassignResult = await service.unassignUserFromGroup({
userId: 'user-id',
groupId: 'group-id'
});
// Delete a group
const deleteGroupResult = await service.deleteGroup({ groupId: 'group-id' });
`
`typescript
// List devices for a specific user
const userDevices = await service.listUserDevices({ userId: 'user-id' });
// List all devices in the organization
const allDevices = await service.listDevices({ limit: 50 });
// Search for devices
const searchResults = await service.listDevices({
limit: 20,
query: 'MacBook'
});
`
`typescript
import { createJumpCloudToolsExport } from '@clearfeed-ai/quix-jumpcloud-agent';
const toolConfig = createJumpCloudToolsExport({
apiKey: 'your-jumpcloud-api-key'
});
// Use with LangChain agents
const tools = toolConfig.tools;
const prompts = toolConfig.prompts;
`
This package includes comprehensive tests that can run against a real JumpCloud API or as unit tests.
1. JumpCloud API Key: You need a valid JumpCloud API key to run integration tests
2. Node.js: Version 18 or higher
3. Yarn: Package manager
1. Install dependencies:
`bash`
cd agent-packages/packages/jumpcloud
yarn install
2. Create environment file:
Create a .env file in the jumpcloud package root:
`bash
# JumpCloud API Configuration
JUMPCLOUD_API_KEY=your_jumpcloud_api_key_here
# OR https://console.eu.jumpcloud.com/api depending on your region
JUMPCLOUD_BASE_URL=https://console.jumpcloud.com/api
# Test Configuration (optional)
TEST_USER_PREFIX=test-user-
TEST_GROUP_PREFIX=test-group-
`
3. Get your JumpCloud API Key:
- Log into your JumpCloud Admin Console
- Go to Settings → API Keys
- Create a new API key with appropriate permissions
- Copy the API key to your .env file
#### All Tests
`bash`
yarn test
#### Unit Tests Only
`bash`
yarn test utils.spec.ts
#### Integration Tests Only
`bash`
yarn test:integration
#### Specific Test Files
`bashTest the main service
yarn test integration.spec.ts
#### With Coverage
`bash
yarn test --coverage
`$3
The test suite includes:
1. Unit Tests (
utils.spec.ts): - Tests utility functions without API calls
- Fast execution, no external dependencies
2. Integration Tests (
integration.spec.ts): - Tests all service methods with real API calls
- Creates and cleans up test resources
- Comprehensive error handling tests
3. Tool Tests (
tools.spec.ts):
- Tests LangChain tool integration
- Schema validation tests
- Tool execution with real API calls$3
The integration tests are designed to be safe:
- Unique Naming: Test resources use timestamps to avoid conflicts
- Automatic Cleanup: Tests clean up created resources automatically
- Error Handling: Graceful handling of API errors and failures
- Prefixed Resources: Test users and groups are prefixed for easy identification
$3
Tests provide detailed console output showing:
- API call results
- Created resource IDs
- Cleanup operations
- Error messages for expected failures
$3
| Variable | Description | Default | Required |
| -------------------- | ---------------------- | ----------------------------------- | --------------------------- |
|
JUMPCLOUD_API_KEY | Your JumpCloud API key | - | Yes (for integration tests) |
| JUMPCLOUD_BASE_URL | JumpCloud API base URL | - | Yes |
| TEST_USER_PREFIX | Prefix for test users | test-user- | No |
| TEST_GROUP_PREFIX | Prefix for test groups | test-group- | No |API Reference
$3
The main service class that provides methods for interacting with JumpCloud.
#### Constructor
`typescript
new JumpCloudService(config: JumpCloudConfig)
`#### Methods
-
listUsers(params): List users with optional filtering
- createUser(args): Create a new user
- getUser(args): Get a specific user by ID
- updateUser(args): Update user properties
- deleteUser(args): Delete a user
- listGroups(params): List groups with optional filtering
- createGroup(args): Create a new group
- assignUserToGroup(args): Add user to group
- unassignUserFromGroup(args): Remove user from group
- listGroupUsers(args): List users in a group
- deleteGroup(args): Delete a group
- listUserDevices(args): List devices assigned to a specific user
- listDevices(params): List all devices with optional filteringAll methods return a promise that resolves to a response object with:
-
success: Boolean indicating if the operation was successful
- data: The response data (if successful)
- error: Error message (if unsuccessful)Development
$3
`bash
yarn build
`$3
`bash
yarn clean
``1. Follow the existing code style
2. Add tests for new functionality
3. Ensure all tests pass
4. Update documentation as needed
Apache-2.0