eregistrations-js/README.md

A JavaScript library that simplifies usage of eRegistrations APIs.

# eregistrations-js

A JavaScript library that simplifies usage of eRegistrations APIs.

## Installation

### From NPM Registry
```bash
# Install as dependency in your project
npm install eregistrations-js
```

### From Bitbucket Repository

#### Global Installation
```bash
# Install latest version
npm install -g https://bitbucket.org/unctad/ai-tools.git

# Install specific version/tag
npm install -g https://bitbucket.org/unctad/ai-tools.git#v2.2.0
```

#### Local Installation
```bash
# Install latest version
npm install https://bitbucket.org/unctad/ai-tools.git

# Install specific version/tag
npm install https://bitbucket.org/unctad/ai-tools.git#v2.2.0
```

#### For Development (if you have repository access)
```bash
# Using SSH (requires SSH key setup)
git clone git@bitbucket.org:unctad/ai-tools.git
cd ai-tools
npm install
```

## Configuration

### Environment Variables

Create a `.env` file in your project root with the following variables:

```
# BPA API variables
BPA_API_URL=https://bpa.your-domain.com
TOKEN=your-access-token-here
SERVICE_ID=your-service-id

# GDB API variables (if using GDB functions)
GDB_API_URL=https://gdb.your-domain.com
GDB_TOKEN=your-gdb-access-token
```

See `.env.example` for a template.

## Usage

This package uses CommonJS module system, so you can require it in your Node.js application:

### Importing the Library

#### CommonJS

```javascript
// CommonJS require - All functions
const eregistrations = require('eregistrations-js');

// Or import specific functions
const { 
  // BPA API functions
  getServiceDeterminants, 
  createDeterminant,
  addDeterminantToComponent,
  getServiceRegistrations, 
  getServiceFields, 
  getServiceNames, 
  getServiceBots, 
  getServiceRoles,
  getServiceForms,

  // GDB API functions
  createOrModifyDatabase,
  getDatabaseSchema,
  getList,

  // Types
  Config,
  GdbConfig
} = require('eregistrations-js');
```

#### TypeScript/ES Modules

```typescript
// TypeScript import - All functions
import * as eregistrations from 'eregistrations-js';

// Or import specific functions
import { 
  // BPA API functions
  getServiceDeterminants, 
  createDeterminant,
  addDeterminantToComponent,
  getServiceRegistrations, 
  getServiceFields, 
  getServiceNames, 
  getServiceBots, 
  getServiceRoles, 
  getServiceForms,

  // GDB API functions
  createOrModifyDatabase,
  getDatabaseSchema,
  getList,

  // Types
  Config,
  GdbConfig
} from 'eregistrations-js';
import { config as loadEnv } from 'dotenv';

// Load environment variables
loadEnv();
```

### Configuration

#### BPA API Configuration

```typescript
const bpaConfig: Config = {
  baseApiUrl: process.env.BPA_API_URL!,
  token: process.env.TOKEN!, // Access token is required
  serviceId: process.env.SERVICE_ID
};
```

#### GDB API Configuration

```typescript
const gdbConfig: GdbConfig = {
  baseApiUrl: process.env.GDB_API_URL!,
  token: process.env.GDB_TOKEN!, // Access token is required
  catalogName: 'MyDatabase',
  code: 'MDB',
  version: 1
  // Additional properties as needed
};
```

### Authentication

Starting from version 2.0.0, this library no longer handles authentication internally. You must provide a valid access token directly in the config object for both BPA and GDB APIs. You are responsible for obtaining and refreshing the tokens as needed from your authentication provider.

## BPA API

The Business Process Automation (BPA) API provides functionality for managing services, determinants, forms, and more.

### BPA Examples

#### Getting Service Determinants

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const determinants = await getServiceDeterminants(config);
  console.log('Service determinants:', determinants);
} catch (error) {
  console.error('Error:', error);
}
```

#### Creating a Determinant

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!,
    determinantName: "MyTextDeterminant",
    targetFormFieldKey: "someField",
    operator: "EQUALS",
    value: "someValue",
    type: "text"
  };

  const newDeterminant = await createDeterminant(config);

  console.log('Created determinant:', newDeterminant);
} catch (error) {
  console.error('Error:', error);
}
```

#### Adding a Determinant to a Component

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!,
    determinantId: "your-determinant-id",
    formId: "your-form-id",
    componentKey: "your-component-key"
  };

  const result = await addDeterminantToComponent(config);

  console.log('Determinant added to component:', result);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting Service Registrations

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const registrations = await getServiceRegistrations(config);
  console.log('Service registrations:', registrations);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting Service Fields

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const fields = await getServiceFields(config);
  console.log('Service fields:', fields);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting All Service Names

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!
  };

  const services = await getServiceNames(config);
  console.log('All services:', services);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting Service Bots

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const bots = await getServiceBots(config);
  console.log('Service bots:', bots);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting Service Roles

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const roles = await getServiceRoles(config);
  console.log('Service roles:', roles);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting Service Forms

```typescript
try {
  const config: Config = {
    baseApiUrl: process.env.BPA_API_URL!,
    token: process.env.TOKEN!,
    serviceId: process.env.SERVICE_ID!
  };

  const forms = await getServiceForms(config);
  console.log('Service forms:', forms);
} catch (error) {
  console.error('Error:', error);
}
```

## GDB API

The Generic Database (GDB) API provides functionality to interact with the Generic Database service, allowing you to create and manage databases.

### GDB Examples

#### Creating or Modifying a Database

```typescript
try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    catalogName: 'MyDatabase',
    code: 'MDB',
    version: 1,
    schema: {
      type: 'object',
      properties: {
        ID: {
          type: 'string',
          triggers: [
            {
              conditions: [
                {
                  logic: '==',
                  value: '',
                  gate: '&&'
                }
              ],
              actions: [
                {
                  type: 'set-value',
                  value: '{code}{indexNoByCode}',
                  field_id: 1
                },
                {
                  type: 'upper-case',
                  field_id: 1
                }
              ]
            }
          ],
          primaryKey: true,
          readOnly: true,
          $id: 1
        },
        Name: {
          type: 'string',
          $id: 2
        }
      },
      required: ['ID', 'Name'],
      $incrementIndex: 2
    },
    schemaTags: [
      {
        name: '',
        path: '/ID',
        is_fulltext: true
      },
      {
        name: '',
        path: '/Name',
        is_fulltext: true
      }
    ],
    schemaFlags: [
      {
        name: 'unique',
        path: '/ID'
      },
      {
        name: 'mandatory',
        path: '/ID'
      },
      {
        name: 'mandatory',
        path: '/Name'
      }
    ],
    isDraft: true
  };

  const result = await createOrModifyDatabase(config);
  console.log('Database created or modified:', result);
  console.log('Database link:', result.link);
} catch (error) {
  console.error('Error:', error);
}
```

#### Getting Database Schema

```typescript
try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    databaseId: '123' // Replace with actual database ID
  };

  const schema = await getDatabaseSchema(config);
  console.log('Database schema:', schema);
  console.log('Schema structure:', schema.schema);
} catch (error) {
  console.error('Error:', error);
}
```

#### Querying Data from a Database

```typescript
try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    code: 'MyDatabaseCode', // The database code to query
    query: 'query.Name=John' // The query parameter to filter results
  };

  const results = await getList(config);
  console.log('Query results:', results);
  
  // You can access individual records if the result is an array
  if (Array.isArray(results) && results.length > 0) {
    console.log('First record:', results[0]);
  }
} catch (error) {
  console.error('Error:', error);
}
```

#### Paginated Queries with page_size

```typescript
try {
  const config: GdbConfig = {
    baseApiUrl: process.env.GDB_API_URL!,
    token: process.env.GDB_TOKEN!,
    code: 'MyDatabaseCode',
    query: 'query.Status=Active', // Filter for active records
    page_size: 10 // Limit to 10 results per page
  };

  const results = await getList(config);
  console.log('Paginated results:', results);
  
  // The API may return results in a structured format with pagination info
  if (results.results && Array.isArray(results.results)) {
    console.log(`Showing ${results.results.length} of ${results.count} total records`);
    console.log('Current page:', results.currentPage);
    console.log('Has next page:', results.next !== null);
  }
} catch (error) {
  console.error('Error:', error);
}
```

## Requirements

- Node.js >= 20.11.19

## Development

1. Clone the repository
2. Install dependencies: `npm install`
3. Create a `.env` file with your configuration (see `.env.example`)
4. Run tests: `npm test`
5. Build: `npm run build`

## Major Changes in Version 2.0.0

- Removed internal authentication handling - you must now provide a valid token directly
- Simplified the Config interface by removing authUrl, realm, and credentials properties
- Made the token property required in the Config interface
- Fixed API endpoint URLs for various services

## Changes in Version 2.2.0

- Added new `getDatabaseSchema` function to the GDB API for retrieving database schema information
- Fixed issues with database creation and schema retrieval 
- Improved test coverage for GDB functionality

## Changes in Version 2.3.0

- Added new `getList` function to the GDB API for querying data from a database
- Enhanced GDB functionality with filtering capabilities using the query parameter

## Changes in Version 2.4.0

- Enhanced `getList` function with pagination support through the `page_size` parameter
- Improved URL construction for cleaner and more efficient API requests

## License

MIT