Facilio Connections SDK (Node.js)

ESM client for Node.js 18+ (fetch). Concepts: ../README.md. HTTP paths, JSON shapes, headers: ../docs/api-reference.md.

Installation

Package: @facilio/connections-sdk.

From this repository

npm install file:../connections-sdk/nodejs
# or: npm install file:./connections-sdk/nodejs

yarn add file:../connections-sdk/nodejs

Complete walkthrough (code)

Linear script-style example, matching the Python README flow. All calls are async (return Promises).

import { ConnectionsClient, ConnectionsClientConfig } from "@facilio/connections-sdk";

async function main() {
  // initialize connections client
  let client = new ConnectionsClient(
    process.env.CONNECTIONS_BASE_URL ?? "https://your-host",
    process.env.CONNECTIONS_SERVICE_TOKEN ?? "",
  );

  /*
  Using cookies instead of service token:

  client = new ConnectionsClient(
    new ConnectionsClientConfig({
      baseUrl: "https://connections.facilio.com",
      serviceToken: "",
      csrfToken: "",
      extraHeaders: {
        Cookie: "fc.idToken.connections=xxxxxxxx; JSESSIONID=xxxxxx",
      },
      timeoutMs: 120_000,
    }),
  );
  */

  // list connections
  console.log(await client.listConnections());

  // get connection name
  const got = await client.getConnection("servicenow-connection");
  console.log(got.connection?.display_name);

  // get actions for the connection
  console.log(await client.listActions("servicenow-connection"));

  // get action inputs for the action
  console.log(
    await client.listActionInputs(
      "servicenow-connection",
      "add-comment-in-servicenow-task",
    ),
  );

  console.log(
    await client.listActionOutputMeta(
      "servicenow-connection",
      "add-comment-in-servicenow-task",
    ),
  );

  const result = await client
    .connection("servicenow-connection")
    .actions()
    .execute("add-comment-in-servicenow-task", {
      input: {
        parentId: "1234567890",
        body: "This is a test comment",
      },
    });

  console.log(result);
  if (result?.job_id) {
    await client.getJobResult(String(result.job_id));
  }

  // Same calls via fluent: client.connection("crm-prod").actions().execute("fetch-deal", { input: { ... } });
}

main().catch(console.error);

Errors throw ConnectionsApiError (statusCode, body). JSON on the wire is snake_case.

Method reference

All instance methods that call the API are async and return Promise<object> unless noted. Errors: ConnectionsApiError (statusCode, body).

ConnectionsClientConfig

| Field | Header / effect | |-------|-----------------| | baseUrl | Origin only; client uses ${baseUrl}/api/v1. | | serviceToken | X-Service-Token (omit or "" for cookie-only). | | csrfToken | X-CSRF-Token (session-style auth alongside Cookie). | | timeoutMs | AbortSignal.timeout(timeoutMs) per request. | | extraHeaders | Merged (e.g. Cookie). |

Client construction

| Form | Purpose | |------|---------| | new ConnectionsClient(baseUrl, serviceToken?) | serviceToken defaults to "". | | new ConnectionsClient(new ConnectionsClientConfig({ … })) | Full config — see Local development. |

Fluent roots

| Fluent | HTTP | |--------|------| | jobs().result(jobId) | GET /jobs/{jobId} | | connections().list(relayId?, options?) | GET /connections — lists all connections. options.authorized is accepted for compatibility but ignored; use options.templateId to narrow by template | | actionsCatalog().list() | GET /actions (tenant-wide; not the same as connection(slug).actions()) | | connection(slug) | Object with get, authorize, unauthorize, setActive, http, file, sql, actions (all functions; call http() etc. to get verb objects) |

Jobs

| Flat | Fluent | |------|--------| | getJobResult(jobId) | jobs().result(jobId) |

Connections

| Flat | Fluent | HTTP | |------|--------|------| | listConnections(relayId?, options?) | connections().list(relayId, options) | GET /connections — lists all; options.authorized ignored. Call with no args to list everything | | getConnection(slug) | connection(slug).get() | GET /connections/{slug} | | authorizeConnection(slug) | connection(slug).authorize() | POST …/authorize {} | | unauthorizeConnection(slug) | connection(slug).unauthorize() | POST …/unauthorize {} | | toggleConnectionActive(slug, active) | connection(slug).setActive(active) | POST …/toggle-active { active } |

Actions — read

| Flat | Fluent | HTTP | |------|--------|------| | listAllActions() | actionsCatalog().list() | GET /actions | | listActions(connectionSlug) | connection(slug).actions().list() | GET /connections/{slug}/actions | | getAction(connectionSlug, actionSlug) | connection(slug).actions().get(actionSlug) | GET /connections/{slug}/actions/{actionSlug} | | listActionInputs(connectionSlug, actionSlug) | connection(slug).actions().listInputs(actionSlug) | GET /connections/{slug}/actions/{actionSlug}/inputs | | listActionOutputMeta(connectionSlug, actionSlug) | connection(slug).actions().listOutputs(actionSlug) | GET /connections/{slug}/actions/{actionSlug}/outputs |

Saved action execute

| Flat | Fluent | |------|--------| | executeAction(connectionSlug, actionSlug, body?, opts?) | connection(slug).actions().execute(actionSlug, body?, opts?) |

• opts: { async?: boolean, timeoutMs?: number } → query async=true, timeout_ms=.
• HTTP: POST /connections/{slug}/actions/{actionSlug}/execute.

Positional arguments on typed POST methods (HTTP, file, SQL)

Every executeHttp*, executeFile*, executeSql*, and the fluent http().*, file().*, sql().* methods share the same trailing shape:

(…, parameters = {}, asyncFlag = false, timeoutMs = null)

| Position / field | Meaning | |------------------|---------| | parameters | Request body for the executor (e.g. path, query, headers, body for HTTP). | | asyncFlag | When true, append async=true. | | timeoutMs | When not null, append timeout_ms=. |

All four combinations of asyncFlag / timeoutMs (absent vs set) are valid, same as the other SDKs.

Typed HTTP

| Flat | Fluent (connection(slug).http()) | Path under /api/v1/connections/{slug} | |------|-------------------------------------|---------------------------------------------| | executeHttpGet | get | POST .../http/get | | executeHttpPost | post | POST .../http/post | | executeHttpPatch | patch | POST .../http/patch | | executeHttpPut | put | POST .../http/put | | executeHttpDelete | delete | POST .../http/delete |

Filesystem

| Flat | Fluent | Path suffix | |------|--------|-------------| | executeFileReadFile | read | /file/readFile | | executeFileUploadFile | upload | /file/uploadFile | | executeFileAppendFile | append | /file/appendFile | | executeFileListFiles | listFiles | /file/listFiles | | executeFileRenameFile | rename | /file/renameFile | | executeFileMoveFile | move | /file/moveFile | | executeFileDeleteFile | delete | /file/deleteFile |

SQL

| Flat | Fluent | Path suffix | |------|--------|-------------| | executeSqlQuery | query | /sql/query | | executeSqlSelect | select | /sql/select | | executeSqlInsert | insert | /sql/insert | | executeSqlUpdate | update | /sql/update | | executeSqlDelete | delete | /sql/delete | | executeSqlExecute | execute | /sql/execute (not saved actions) |

Parameter shapes: api-reference.md.

Exported symbols

ConnectionsClient, ConnectionsClientConfig, ConnectionsApiError.

Local development without a service token (cookies + CSRF)

import { ConnectionsClient, ConnectionsClientConfig } from "@facilio/connections-sdk";

const client = new ConnectionsClient(
  new ConnectionsClientConfig({
    baseUrl: "http://localhost:8081",
    serviceToken: "",
    csrfToken: "paste-fc-csrfToken-cookie-value",
    extraHeaders: {
      Cookie: "JSESSIONID=...; fc.idToken.connections=...; fc.csrfToken=...",
    },
    timeoutMs: 120_000,
  }),
);

Tests

cd connections-sdk/nodejs
npm test

Bump version in package.json before publish.