@interfy/client

TypeScript client for the Interfy API. Covers BPM, ECM, Custom Tables, Users, Organizational Units, and Form Files.

Installation

npm install @interfy/client

Quick Start

import { Client, AuthenticationType } from '@interfy/client'

const client = new Client('my-workspace', {
  type: AuthenticationType.OAuthClient,
  client_credentials: {
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    scope: 'your-scope',
  },
})

// List users
const users = await client.users.list()

// Start a BPM case
const newCase = await client.bpm.startCase({
  starting_stage: 42,
  context: { priority: 'high' },
})

// Upload a file to an ECM document
const file = await client.ecm.files.upload(documentId, buffer, 'report.pdf')

Authentication

OAuth2 Client Credentials

const client = new Client('workspace', {
  type: AuthenticationType.OAuthClient,
  client_credentials: {
    client_id: 'id',
    client_secret: 'secret',
    scope: 'scope',
  },
})

Basic Auth

const client = new Client('workspace', {
  type: AuthenticationType.Basic,
  basic_credentials: {
    username: 'user',
    password: 'pass',
  },
})

Environment Variables (ScriptTasks)

When running inside interfy-functions ScriptTasks, environment variables are auto-injected. No constructor arguments needed:

const client = new Client()

| Variable | Description | |----------|-------------| | INTERFY_WORKSPACE | Workspace (tenant) identifier | | INTERFY_AUTHENTICATION_TYPE | 0 = Basic, 1 = OAuth Client | | INTERFY_CLIENT_AUTH_CLIENT_ID | OAuth client ID | | INTERFY_CLIENT_AUTH_CLIENT_SECRET | OAuth client secret | | INTERFY_CLIENT_AUTH_SCOPE | OAuth scope | | INTERFY_BASIC_AUTH_USERNAME | Basic auth username | | INTERFY_BASIC_AUTH_PASSWORD | Basic auth password | | INTERFY_API_URL | API base URL (default: http://api.interfy.io/api/v2) | | INTERFY_OAUTH_URL | OAuth URL (default: http://api.interfy.io/oauth) |

Services

Users

client.users.list()
client.users.get(userId)
client.users.create({ username, email, name, surname })
client.users.update(userId, { name: 'Updated' })
client.users.activate(userId)
client.users.deactivate(userId)
client.users.restore(userId)
client.users.delete(userId)
client.users.getActiveCount()

BPM

client.bpm.listProcesses()
client.bpm.getProcess(processId)
client.bpm.getProcessVariables(processId)
client.bpm.listVariables()
client.bpm.getStage(stageId)
client.bpm.listCases()
client.bpm.startCase({ starting_stage, context?, data?, active? })
client.bpm.getCase(caseId)

ECM Documents

client.ecm.documents.get(documentId)
client.ecm.documents.create({ folder_id, title?, template_id?, fields? })
client.ecm.documents.update(documentId, data)
client.ecm.documents.importBatch({ documents: [{ folder_id, title, ... }] })

ECM Files

// Upload a file (multipart/form-data)
client.ecm.files.upload(documentId, bufferOrStream, 'filename.pdf')

// Reference an existing S3 file
client.ecm.files.uploadRemote(documentId, {
  remote_path: 's3://bucket/path',
  name: 'file.pdf',
  file_type: 'application/pdf',
  file_size: 1024,
})

client.ecm.files.update(documentId, fileId, data)

Custom Tables

client.customTables.list()
client.customTables.get(tableName)
client.customTables.getColumns(tableName)
client.customTables.listRows(tableName)
client.customTables.filterRows(tableName, { column: 'value' })
client.customTables.addRow(tableName, { column: 'value' })
client.customTables.getRow(tableName, rowId)
client.customTables.updateRow(tableName, rowId, data)
client.customTables.deleteRow(tableName, rowId)
client.customTables.truncate(tableName)

Organizational Units

client.organizationalUnits.list()
client.organizationalUnits.get(unitId)

Form Files

client.formFiles.appendFormFileToECMDocument(formFileId, ecmDocumentId)

Error Handling

All API errors are wrapped in InterfyApiError:

import { InterfyApiError } from '@interfy/client'

try {
  await client.users.get(999)
} catch (error) {
  if (error instanceof InterfyApiError) {
    console.log(error.status)    // 404
    console.log(error.endpoint)  // "client/users/999"
    console.log(error.response)  // API response body
  }
}

OAuth tokens are automatically refreshed on 401 responses.

Development

npm install
npm run build   # Compile TypeScript
npm test        # Run tests (Jest)