@clearblade/ia-env/README.md

Toolkit for interacting with Intelligent Assets (IA) APIs and utils within a ClearBlade environment

# @clearblade/ia-env

A ClearBlade platform-exclusive package for managing Intelligent Asset (IA) entities and their configurations. This package is specifically designed to run only within the ClearBlade platform environment and will not function in other JavaScript environments (Node.js, browsers, Bun, etc.). It provides a comprehensive set of tools for managing assets, rules, groups, events, and user permissions within an IA system. It is designed to be used by IA components or custom code deployed inside an IA system, offering both modern (V8) and ES5 compatible interfaces for different runtime environments.

## Installation

```bash
npm install @clearblade/ia-env
```

## Usage

The package provides two different entry points depending on your runtime environment:

```typescript
// For V8 services (modern JavaScript runtime)
import { createRule } from '@clearblade/ia-env/modern';

// For duktape services (ES5 compatible runtime)
import { createRule } from '@clearblade/ia-env/es5';
```

## API Reference

### Core Functions

#### Rule Management

- `createRule`: Create a new rule in the IA environment
- `deleteRule`: Delete an existing rule
- `createRuleType`: Create a new rule type
- `deleteRuleType`: Delete an existing rule type

#### Asset Management

- `createAsset`: Create a new asset
- `createAssetLock`: Create a lock for asset operations
- `updateAsset`: Update an existing asset
- `updateAssetType`: Update an asset type definition

#### Group Management

- `createGroup`: Create a new group
- `createGroupLock`: Create a lock for group operations
- `updateGroupChildren`: Update the children of a group

#### Event Management

- `createEventType`: Create a new event type
- `deleteEventType`: Delete an existing event type

#### User Management

- `updateUserRoles`: Update roles for a user
- `resetPassword`: Reset a user's password

### Types and Interfaces

The package exports several important types and interfaces:

- `Asset`: Asset type definition
- `Group`: Group type definition
- `User`: User type definition
- `AttrSchema`: Attribute schema definition
- `PermissionDefinition`: Permission definition interface
- `PermissionDefinitionList`: List of permission definitions

### Error Types

The package includes several error classes for error handling:

- `AlreadyExistsError`
- `ForbiddenError`
- `IAError`
- `InternalServerError`
- `InvalidArgumentError`
- `NotFoundError`
- `RouteRemovedError`

## Constants

- `IA_PERMISSION_CATEGORIES`: Available permission categories
- `USER_INVITE_STATUS`: User invitation status constants
- `ATTR_DATA_TYPE`: Attribute data type constants
- `CollectionName`: Collection name constants

## Utilities

- `Router`: Router utility for handling routes
- `Route`: Route type definition
- `RouteHandlerCreator`: Route handler creator type
- `GetParams`: Parameter type for GET requests
- `createRoutes`: Function to create routes
- `withMigration`: Migration utility
- `AssetTypeCache`: Cache for asset types
- `UserRoles`: User roles utility
- `UserRoleIdsCache`: Cache for user role IDs

## Note on Current Scope

This package currently provides support for a subset of IA entities and their operations. Additional IA entities and their corresponding operations will be added in future releases. The current implementation focuses on core functionality for assets, rules, groups, events, and user management. Please check the package version and documentation for the most up-to-date list of supported entities and operations.