{"id":21241049,"url":"https://github.com/acaengine/ts-client","last_synced_at":"2025-07-04T11:34:06.517Z","repository":{"id":56241627,"uuid":"181256218","full_name":"acaengine/ts-client","owner":"acaengine","description":"Client library for interacting with ACAEngine from Typescript. ","archived":false,"fork":false,"pushed_at":"2020-11-18T22:05:23.000Z","size":1247,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-03T17:35:00.671Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acaengine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-14T03:34:34.000Z","updated_at":"2020-05-27T01:53:46.000Z","dependencies_parsed_at":"2022-08-15T15:20:21.069Z","dependency_job_id":null,"html_url":"https://github.com/acaengine/ts-client","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaengine%2Fts-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaengine%2Fts-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaengine%2Fts-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaengine%2Fts-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acaengine","download_url":"https://codeload.github.com/acaengine/ts-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acaengine%2Fts-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258533618,"owners_count":22716280,"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":[],"created_at":"2024-11-21T00:54:21.210Z","updated_at":"2025-06-12T18:08:18.189Z","avatar_url":"https://github.com/acaengine.png","language":"TypeScript","readme":"# TypeScript ACAEngine Library\n\nThis library is a Typescript interface to ACAEngine\n\n## Compilation\n\nYou can build the library from source after installing the dependencies with the command\n\n`npm run build`\n\n## Usage\n\nAPI docs can be found [here](https://acaengine.github.io/ts-client)\n\nYou can install the ACAEngine Typescript client with the npm command\n\n`npm install --save-dev @acaengine/ts-client`\n\nAfter the package is installed you can import `ACAEngine` into your application\n\n```typescript\nimport { ACAEngine } from '@acaengine/ts-client'\n```\n\nBefore using ACAEngine it will need to be intialised.\n\n```typescript\nACAEngine.init(config);\n```\n\nThe init method takes a `config` object with the following properties\n\n|Property|Description|Optional|Type|Example|\n|--------|-----------|--------|----|-------|\n|`host`|Host name and port of the ACAEngine server|Yes|`string`|`\"dev.acaengine.com:8080\"`|\n|`mock`|Whether to initialise ACAEngine with mock services|Yes|`boolean`|`true`|\n|`auth_uri`|URI for authorising users session|No|`string`|`\"/auth/oauth/authorize\"`|\n|`token_uri`|URI for generating new auth tokens|No|`string`|`\"/auth/token\"`|\n|`redirect_uri`|URI to redirect user to after authorising session|No|`string`|`\"/oauth-resp.html\"`|\n|`scope`|Scope of the user permissions needed by the application|No|`string`|`\"admin\"`|\n|`storage`|Browser storage to use for storing user credentials|Yes|`\"local\" \\| \"session\"`| |\n|`handle_login`|Whether ACAEngine should handle user login|Yes|`boolean`|`true`|\n\nOnce initialised the `ACAEngine` object will expose interfaces to ACAEngine's websocket and http APIs\n\n### Websocket API\n\n`ACAEngine` exposes a websocket API through the `bindings` service.\n\nThe `bindings` service is used to provide real-time interaction with modules running on ACAEngine. It provides an interface to build efficient, responsive user interfaces, monitoring systems and other extensions which require live, two-way or asynchronous interaction.\n\nOnce ACAEngine has initialised you can listen to values on modules\n\n```typescript\nconst my_mod = ACAEngine.bindings.module('sys-death-star', 'TestModule', 3);\nconst my_variable = my_mod.binding('power');\nconst unbind = my_variable.bind();\nconst sub = my_variable.listen((value) =\u003e doSomething(value));\n```\n\nThis binds to the `power` status variable on the 3rd `TestModule` in the system `sys-death-star`.\nAny changes to the value of `power` on ACAEngine will then be emitted to the function passed to `listen`.\n\nOther than listening to changes of values you can also remotely execute methods on modules.\n\n```typescript\nconst my_mod = ACAEngine.bindings.module('sys-death-star', 'DemoModule', 2);\nmy_mod.exec('power_off').then(\n    (resp) =\u003e handleSuccess(resp)\n    (err) =\u003e handleError(err)\n);\n```\n\nThis will execute the method `power_off` on the 2nd `DemoModule` in the system `sys-death-star`.\nIf the method doesn't exist or the system is turned off it will return an error.\nThe response from ACAEngine can be handled using the promise returned by the `exec` method.\n\n\n### HTTP API\n\nFor the HTTP API, `ACAEngine` provides a service for each of the root endpoints available on ACAEngine's RESTful API.\n\nDocs for the API can be found here https://docs.acaengine.com/api/control\n\nServices are provided for `drivers`, `modules`, `systems`, `users`, and `zones`\n\nEach service except for `users` provides CRUD methods. `users` provides _RUD.\n\n```typescript\n// Drivers CRUD\nACAEngine.drivers.add(driver_data).then((new_driver) =\u003e doSomething(new_driver));\nACAEngine.drivers.show(driver_id).then((driver) =\u003e doSomething(driver));\nACAEngine.drivers.update(driver_id, driver_data).then((updated_driver) =\u003e doSomething(updated_driver));\nACAEngine.drivers.delete(driver_id).then(() =\u003e doSomething());\n\n// Modules CRUD\nACAEngine.modules.add(module_data).then((new_module) =\u003e doSomething(new_module));\nACAEngine.modules.show(module_id).then((mod) =\u003e doSomething(mod));\nACAEngine.modules.update(module_id, module_data).then((updated_module) =\u003e doSomething(updated_module));\nACAEngine.modules.delete(module_id).then(() =\u003e doSomething());\n\n// Systems CRUD\nACAEngine.systems.add(system_data).then((new_system) =\u003e doSomething(new_system));\nACAEngine.systems.show(system_id).then((system) =\u003e doSomething(system));\nACAEngine.systems.update(system_id, system_data).then((updated_system) =\u003e doSomething(updated_system));\nACAEngine.systems.delete(system_id).then(() =\u003e doSomething());\n\n// Users CRUD\nACAEngine.users.add(user_data).then((new_user) =\u003e doSomething(new_user)); // This will error\nACAEngine.users.show(user_id).then((user) =\u003e doSomething(user));\nACAEngine.users.update(user_id, user_data).then((updated_user) =\u003e doSomething(updated_user));\nACAEngine.users.delete(user_id).then(() =\u003e doSomething());\n\n// Zones CRUD\nACAEngine.zones.add(zone_data).then((new_zone) =\u003e doSomething(new_zone));\nACAEngine.zones.show(zone_id).then((zone) =\u003e doSomething(zone));\nACAEngine.zones.update(zone_id, zone_data).then((updated_zone) =\u003e doSomething(updated_zone));\nACAEngine.zones.delete(zone_id).then(() =\u003e doSomething());\n```\n\nThe services also provide methods for the various item action endpoints\n\n```typescript\n// Driver Actions\nACAEngine.drivers.reload(driver_id);\n\n// Module Actions\nACAEngine.module.start(module_id);\nACAEngine.module.stop(module_id);\nACAEngine.module.ping(module_id);\nACAEngine.module.lookup(module_id, lookup);\nACAEngine.module.internalState(module_id);\n\n// System Actions\nACAEngine.system.remove(system_id, module_name);\nACAEngine.system.start(system_id);\nACAEngine.system.stop(system_id);\nACAEngine.system.execute(system_id, module_name, index, args);\nACAEngine.system.state(system_id, module_name, index, lookup);\nACAEngine.system.functionList(system_id, module_name, index);\nACAEngine.system.types(system_id, module_name);\nACAEngine.system.count(system_id);\n\n// User Actions\nACAEngine.users.current();\n```\n\nObjects returned by `show` and `query` methods are immutable,\nthough when reassigning value it will be saved under the `changes` property of that object.\nThese changes can be saved using the `save` method which will return a promise for the new object.\n\n```typescript\nACAEngine.zones.show(zone_id).then((zone) =\u003e {\n    console.log(zone.description); // Prints the current description\n    zone.description = 'New description';\n    console.log(zone.description); // Same a previous print\n    cosnole.log(zone.changes.description) // New description\n    zone.save().then((updated_zone) =\u003e {\n        cosnole.log(updated_zone.description) // New description\n    });\n});\n```\n\nYou can find more details about endpoint action on the API docs\n\nhttps://app.swaggerhub.com/apis/ACAprojects/ACAEngine/3.5.0#/\n\n## Writing mocks\n\nIf you don't have access to an ACAEngine server you can also write mocks so that you can still develop interfaces for ACAEngine.\n\nTo use the mock services you can pass `mock: true` into the initialisation object.\n\n### Websockets\n\nTo write mocks for the the realtime(websocket) API you'll need to add your systems to `window.control.systems` before initialising ACAEngine.\n\n```typescript\nwindow.control.systems = {\n    \"my-system\": {\n        \"MyModule\": [\n            {\n                power: true,\n                $power_on: function () { this.power = true },\n                $power_off: function () { this.power = false }\n            }\n        ]\n    }\n}\n```\n\nNote that executable methods on mock systems are namespaced with `$` as real systems in engine allow for methods to have the same name as variables.\n\nOnce initialised interactions with a system are performed in the same manner as the live system.\n\n```typescript\nconst my_mod = ACAEngine.bindings.module('my-system', 'MyModule', 1);\nconst my_variable = my_mod.binding('power');\nconst unbind = my_variable.bind();\nconst sub = my_variable.listen((value) =\u003e doSomething(value)); // Emits true\nmy_mod.exec('power_off'); // The listen callback will now emit false\n```\n\nSome methods may need access to other modules within the system, for this a property is appended on runtime called `_system` which allows for access to the parent system\n\n```typescript\nwindow.control.systems = {\n    \"my-system\": {\n        \"MyModule\": [\n            {\n                $lights_off: function () { this._system.MyOtherModule[0].lights = false; }\n            }\n        ]\n        \"MyOtherModule\": [\n            {\n                lights: true,\n            }\n        ]\n    }\n}\n```\n\n### HTTP Requests\n\nHTTP API Requests can be mocked in a similar way to the realtime API by adding handlers to `window.control.handlers`\n\n```typescript\nwindow.control.handlers = [\n    {\n        path: '/api/engine/v2/systems',\n        metadata: {},\n        method: 'GET',\n        callback: (request) =\u003e my_mock_systems\n    }\n]\n```\n\nPaths allow for route parameters and will pass the value in the callback input.\n\n```typescript\nwindow.control.handlers = [\n    {\n        path: '/api/engine/v2/systems/:system_id',\n        ...\n        callback: (request) =\u003e\n            my_mock_systems.find(sys =\u003e sys.id === request.route_params.system_id)\n    }\n]\n```\n\nQuery parameters are also available on the callback input.\n\n`GET`, `POST`, `PUT`, `PATCH` and `DELETE` requests can be mocked out.\n\nIf a request is made and there are no handlers it will attempt to make the live request.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facaengine%2Fts-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facaengine%2Fts-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facaengine%2Fts-client/lists"}