{"id":13406502,"url":"https://github.com/churchtools/churchtools-js-client","last_synced_at":"2025-03-14T11:30:28.708Z","repository":{"id":37099726,"uuid":"297949673","full_name":"churchtools/churchtools-js-client","owner":"churchtools","description":"JavaScript client to easily access the ChurchTools REST-API","archived":false,"fork":false,"pushed_at":"2024-05-14T11:59:40.000Z","size":6933,"stargazers_count":18,"open_issues_count":2,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-18T12:20:22.247Z","etag":null,"topics":["api","api-client","churchtools","javascript","js"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/churchtools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-23T11:36:25.000Z","updated_at":"2024-07-23T08:47:38.325Z","dependencies_parsed_at":"2024-01-18T23:05:27.466Z","dependency_job_id":"29fa43c6-7a27-40bc-a203-9db654b64d3c","html_url":"https://github.com/churchtools/churchtools-js-client","commit_stats":{"total_commits":292,"total_committers":10,"mean_commits":29.2,"dds":0.4691780821917808,"last_synced_commit":"4d425a7f4f17c47adc0d80d2a96c78359b718f97"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/churchtools%2Fchurchtools-js-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/churchtools%2Fchurchtools-js-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/churchtools%2Fchurchtools-js-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/churchtools%2Fchurchtools-js-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/churchtools","download_url":"https://codeload.github.com/churchtools/churchtools-js-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243569007,"owners_count":20312345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","churchtools","javascript","js"],"created_at":"2024-07-30T19:02:32.025Z","updated_at":"2025-03-14T11:30:28.696Z","avatar_url":"https://github.com/churchtools.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# churchtools-js-client\n\nchurchtools-js-client is a client written in JavaScript to easily access the\n[ChurchTools REST API](https://demo.church.tools/api). Its main benefits include:\n\n- Easy to use abstraction of the login process which handles session cookies and automatically performs a re-login if\n  the session expired (using the login token provided).\n- Supports both, the old and the new version of the ChurchTools API.\n- Automatically requests and handles the submission of CSRF tokens for the old API.\n- Can be used in a web application running in a browser or on server-side in a Node.js application.\n\n## Installation\n\nPlease use `npm` to install this package in your application:\n\n```npm install @churchtools/churchtools-client```\n\nIf your target application is a Node.js application, you will also need to install the packages\n`axios-cookiejar-support` and `tough-cookie`. They are not required when targeting a web browser.\n\n### CORS Header Configuration\n\nIf you intend to connect to a ChurchTools instance from an application running in a web browser,\nany request to the ChurchTools instance is effectively a cross origin request. As a security concept the browser will\nblock these requests by default.\n\nHowever, the [CORS mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) can be used to allow the\nrespective requests. This requires setting CORS headers on the server side.\n\nIf you host your ChurchTools instance on your own server, you need to enable CORS headers in your\n`churchtools.config`:\n\n```\naccess_control_allow_origin=https://your-website-where-you-use-churchtools-js-client.com\naccess_control_allow_credentials=true\n```\n\nPlease refer [to the ChurchTools documentation](https://intern.church.tools/?q=churchwiki#WikiView/filterWikicategory_id:0/doc:CORS/follow_redirect:true/)\nfor more information.\n\nIf you use the ChurchTools hosting service, please\n[contact the ChurchTools support](https://www.church.tools/de/contact) to set CORS headers.\n\n## Usage Example\n\nThe import of the package slightly differs in a web application from a Node.js application:\n\n### Web Application\n\n```html\n\u003cscript src=\"node_modules/@churchtools/churchtools-client/dist/churchtools-client.bundled.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n    const { churchtoolsClient, activateLogging } = window.churchtoolsClient;\n\n    activateLogging();\n    churchtoolsClient.setBaseUrl('https://demo.church.tools');\n\n    churchtoolsClient.get('/whoami').then(whoAmI =\u003e {\n        console.log(whoAmI);\n    }).catch(error =\u003e {\n        console.error(error);\n    });\n\u003c/script\u003e\n```\n\nFor a more sophisticated example (including login functionality), please check the examples/Browser/ directory in this\nrepository. Run `npm install` followed by `npm start` to launch a demo web server which serves a simple test application\nrunning in your browser.\n\n### Node.js Application\n\n```js\nconst { churchtoolsClient, activateLogging } = require('@churchtools/churchtools-client');\nconst axiosCookieJarSupport = require('axios-cookiejar-support');\nconst tough = require('tough-cookie');\n\nchurchtoolsClient.setCookieJar(axiosCookieJarSupport.wrapper, new tough.CookieJar());\nchurchtoolsClient.setBaseUrl('https://demo.church.tools');\n\nactivateLogging();\nchurchtoolsClient.get('/whoami').then(whoAmI =\u003e {\n    console.dir(whoAmI);\n    console.log(`Hello ${whoAmI.firstName}!`);\n});\n```\n\nFor a more sophisticated example (including login functionality), please check the examples/Node.js/ directory in this\nrepository. Run `npm install` followed by `npm start` to launch the test application.\n\n## General Usage\n\n`churchtoolsClient` when imported as described in the examples above, exposes a range of utility functions to use the\nChurchTools API. In particular, the following functions can be used:\n\n- `setBaseUrl(baseUrl: string)`\\\n  Set the URL of the ChurchTools instance you want to connect to. Please see below if you want to connect to multiple\n  instances.\n- `validChurchToolsUrl(baseUrl: string)`\\\n  Check if the URL points to an actual ChurchTools instance.\n- `setCookieJar(axiosCookieJarSupport, jar)`\\\n  Enable cookie support and automatic session handling. See the example above how to use it.\n  This is only required for a Node.js application, not when running in a browser.\n- `get(uri: string, params: object)`\\\n  `post(uri: string, data: object)`\\\n  `put(uri: string, data: object)`\\\n  `patch(uri: string, data: object)`\\\n  `deleteApi(uri: string, data: object)`\\\n  Send API requests. Please [check the documentation](https://demo.church.tools/api) to see what's available.\n- `oldApi(module: string, func: string, params: object)`\\\n  Send request to ChurchTools' legacy API.\n  Please [check the documentation](https://api.church.tools/) to see what's available.\n\n## Connect to multiple ChurchTools instances simultaneously\n\nIf your application needs to access multiple ChurchTools instances simultaneously, you will find that\n`setBaseUrl` only allows to set a single URL for all following calls.\n\nInstead, an object-wrapped approach can be used to manage and call multiple instances. This is an example for a Node.js\napplication:\n\n```js\nconst { ChurchtoolsClient, activateLogging } = require('@churchtools/churchtools-client');\n\nconst clientA = new ChurchToolsClient();\nclientA.setBaseUrl('https://foobar.church.tools');\nclientA.post('/login', {\n    username: usernameA,\n    password: passwordA\n}).then(result =\u003e {\n    if (result.status === 'success') {\n        console.log('Login successful!');\n        return clientA.get('/whoami');\n    }\n}).then(result =\u003e {\n    console.log('User A: ', result.data);\n});\n\nconst clientB = new ChurchToolsClient();\nclientB.setBaseUrl('https://baz.church.tools');\nclientB.post('/login', {\n    username: usernameB,\n    password: passwordB\n}).then(result =\u003e {\n    if (result.status === 'success') {\n        console.log('Login successful!');\n        return clientB.get('/whoami');\n    }\n}).then(result =\u003e {\n    console.log('User B: ', result.data);\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchurchtools%2Fchurchtools-js-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchurchtools%2Fchurchtools-js-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchurchtools%2Fchurchtools-js-client/lists"}