churchtools-js-client

KO | EN

gitlite — search

#python #react #ai #golang #rust #deep-learning #java #windows #cli #awesome-list #pytorch #security #mcp #open-source

churchtools-js-client

(★ 27)

JavaScript client to easily access the ChurchTools REST-API

churchtools-js-client Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# churchtools-js-client

churchtools-js-client is a client written in JavaScript to easily access the
[ChurchTools REST API](https://demo.church.tools/api). Its main benefits include:

- Easy to use abstraction of the login process which handles session cookies and automatically performs a re-login if
  the session expired (using the login token provided).
- Supports both, the old and the new version of the ChurchTools API.
- Automatically requests and handles the submission of CSRF tokens for the old API.
- Can be used in a web application running in a browser or on server-side in a Node.js application.

## Installation

Please use `npm` to install this package in your application:

```npm install @churchtools/churchtools-client```

If your target application is a Node.js application, you will also need to install the packages
`axios-cookiejar-support` and `tough-cookie`. They are not required when targeting a web browser.

### CORS Header Configuration

If you intend to connect to a ChurchTools system from an application running in a web browser,
any request to the ChurchTools system is effectively a cross origin request. As a security concept the browser will
block these requests by default.

However, the [CORS mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) can be used to allow the
respective requests. This requires setting CORS headers on the server side: In your ChurchTools system go to the system
settings > Integrations > Cross-Origin Resource Sharing and add a new entry to the Access Control Allow Origin list.

For development that will be something like `http:/localhost:5173`. If your app is running on another web server, use
its url like `https://your-website-where-you-use-churchtools-js-client.com`.

Please refer [to the ChurchTools Academy](https://churchtools.academy/help/system-einstellungen/api/0-cors/)
for more information.

## Usage Example

The import of the package slightly differs in a web application from a Node.js application:

### Web Application

```html
<script src="node_modules/@churchtools/churchtools-client/dist/churchtools-client.bundled.js"></script>
<script>
    const { churchtoolsClient, activateLogging } = window.churchtoolsClient;

activateLogging();
    churchtoolsClient.setBaseUrl('https://demo.church.tools');

churchtoolsClient.get('/whoami').then(whoAmI => {
        console.log(whoAmI);
    }).catch(error => {
        console.error(error);
    });
</script>
```

For a more sophisticated example (including login functionality), please check the examples/Browser/ directory in this
repository. Run `npm install` followed by `npm start` to launch a demo web server which serves a simple test application
running in your browser.

### Node.js Application

```js
const { churchtoolsClient, activateLogging } = require('@churchtools/churchtools-client');
const axiosCookieJarSupport = require('axios-cookiejar-support');
const tough = require('tough-cookie');

churchtoolsClient.setCookieJar(axiosCookieJarSupport.wrapper, new tough.CookieJar());
churchtoolsClient.setBaseUrl('https://demo.church.tools');

activateLogging();
churchtoolsClient.get('/whoami').then(whoAmI => {
    console.dir(whoAmI);
    console.log(`Hello ${whoAmI.firstName}!`);
});
```

For a more sophisticated example (including login functionality), please check the examples/Node.js/ directory in this
repository. Run `npm install` followed by `npm start` to launch the test application.

## General Usage

`churchtoolsClient` when imported as described in the examples above, exposes a range of utility functions to use the
ChurchTools API. In particular, the following functions can be used:

- `setBaseUrl(baseUrl: string)`\
  Set the URL of the ChurchTools system you want to connect to. Please see below if you want to connect to multiple systems.
- `validChurchToolsUrl(baseUrl: string)`\
  Check if the URL points to an actual ChurchTools system.
- `setCookieJar(axiosCookieJarSupport, jar)`\
  Enable cookie support and automatic session handling. See the example above how to use it.
  This is only required for a Node.js application, not when running in a browser.
- `get(uri: string, params: object)`\
  `post(uri: string, data: object)`\
  `put(uri: string, data: object)`\
  `patch(uri: string, data: object)`\
  `deleteApi(uri: string, data: object)`\
  Send API requests. Please [check the documentation](https://demo.church.tools/api) to see what's available.
- `oldApi(module: string, func: string, params: object)`\
  Send request to ChurchTools' legacy API.
  Please [check the documentation](https://api.church.tools/) to see what's available.

## Connect to multiple ChurchTools systems simultaneously

If your application needs to access multiple ChurchTools systems simultaneously, you will find that
`setBaseUrl` only allows to set a single URL for all following calls.

Instead, an object-wrapped approach can be used to manage and call multiple systems. This is an example for a Node.js
application:

```js
const { ChurchtoolsClient, activateLogging } = require('@churchtools/churchtools-client');

churchtools-js-client

churchtools-js-client Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

churchtools-js-client

churchtools-js-client Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README