{"id":13469545,"url":"https://github.com/Worie/btt","last_synced_at":"2025-03-26T07:30:45.394Z","repository":{"id":32597442,"uuid":"137778901","full_name":"Worie/btt","owner":"Worie","description":"Low level MacOS management in JavaScript via BetterTouchTool","archived":false,"fork":false,"pushed_at":"2024-07-12T18:53:12.000Z","size":7378,"stargazers_count":113,"open_issues_count":20,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-07-31T15:11:10.840Z","etag":null,"topics":["applescript","automation","bettertouchtool","es6","gesture","gesture-recognition","haptic-feedback","javascript","keyboard-shortcuts","low-level","mac","macos","node","notifications","system-programming","touchbar","typescript","webview","workflow-automation"],"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/Worie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"custom":"https://paypal.me/wopolow"}},"created_at":"2018-06-18T16:38:36.000Z","updated_at":"2024-07-31T15:11:12.420Z","dependencies_parsed_at":"2024-07-12T21:11:40.614Z","dependency_job_id":null,"html_url":"https://github.com/Worie/btt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Worie%2Fbtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Worie%2Fbtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Worie%2Fbtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Worie%2Fbtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Worie","download_url":"https://codeload.github.com/Worie/btt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222121829,"owners_count":16934973,"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":["applescript","automation","bettertouchtool","es6","gesture","gesture-recognition","haptic-feedback","javascript","keyboard-shortcuts","low-level","mac","macos","node","notifications","system-programming","touchbar","typescript","webview","workflow-automation"],"created_at":"2024-07-31T15:01:44.261Z","updated_at":"2024-10-29T22:31:18.470Z","avatar_url":"https://github.com/Worie.png","language":"TypeScript","readme":"# btt\n\u003cp align=\"center\"\u003e\u003cimg width=\"100\" src=\"https://user-images.githubusercontent.com/6313514/42529852-d9c76ab0-847f-11e8-8d8c-323d1d995b2d.png\" alt=\"Package logo\"\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://badge.fury.io/js/btt.svg\" alt=\"Package version\"\u003e\n  \u003cimg src=\"https://snyk.io/test/github/worie/btt/badge.svg\" alt=\"Vunerabilities\"\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://nodei.co/npm/btt/\"\u003e\n  \u003cimg src=\"https://nodei.co/npm/btt.png?downloads=true\u0026downloadRank=true\" alt=\"Vunerabilitiesn\"\u003e\u003c/a\u003e\n\u003c/p\u003e\u003cp align=\"center\"\u003e\u003ch2 align=\"center\"\u003eManage your BetterTouchTool in JavaScript, easily.\n\u003c/h2\u003e\u003c/p\u003e\n\n## Get started \n\nSee the [guide](https://worie.github.io/btt/guide/introduction.html) and [api](https://worie.github.io/btt/api) for `btt.js`. \n\n## About \nThis package is a handy wrapper over [BetterTouchTool](https://folivora.ai/) built in webserver API. (by [@Andreas Hegenberg](https://github.com/fifafu))\n\nThis package will allow you to automate you MacOS-running machine using JavaScript. You'll be able to:\n\n* Create event listeners that'll run within an operating system, outside the browser!\n* Toggle your do-not-disturb state\n* Show a system notification\n* Toggle Night Shift\n* Sleep your computer after timeout\n* Create your own **touchbar widgets**\n* Feel a notification via **haptic engine**\n* Control the brightness of the screen and keyboard\n* Control the volume levels\n* Use the content of your clipboard to be opened in a specific url or application\n* Create your own UIs \"within system\" using web view \n* Trigger a system-wide keyboard shortcut\n* Send a shortcut to a specific application\n* Show / Hide / Open / Quit a specific applcation\n* Move your mouse to a specific position and click\n* Hide your cursor\n* Lock / Unlock your MacOS machine\n* Integrate your flow / touchbar with various APIs ...\n\n*and anything else that BetterTouchTool or the JavaScript specification will allow you to do!*\n\n## Typed, browser/server side library\nThis package provides its own type definitions and can be run both on browser (using module bundlers) and in a nodejs environment.\n\n## Requirements\n\nThis package depends on the application [BetterTouchTool](https://folivora.ai/) in at least version v2.0.0, you need to have it installed and running before going further.\n\nThen, please enable and configure the webserver in the BetterTouchTool preferences. You're now ready to go!\n\n## Installation\n\n`npm install btt`\n\n## Example usage\n\nFirst, create a btt instance passing the required data for BTT webserver.\n\n```ts\n// import Btt class from the package\nimport { Btt } from 'btt';\n\n// create an instance representing btt webserver\n// can be remote or local\nconst btt = new Btt({\n  domain: '127.0.0.1',\n  port: 8000,\n  protocol: 'http',\n  version: '2.525',\n});\n```\n\nNow you can invoke the actions - there are plenty of ways to do it, and all are promise-based.\n\n```ts\n// sequentially run three actions - spotlight, type text and night shift\n// as all actions are promise-based, you can use async/await notation without hassle\nbtt\n  .triggerShortcut('cmd+space').invoke()\n  .then(() =\u003e btt.sendText({ text: 'Hello world!'}).invoke())\n  .then(() =\u003e btt.toggleNightShift().invoke());\n\n```\n\n## Response structure for every action\n\n```ts\n// every single action returns a CallResult object containing information about the Call\n\ninterface CallResult {\n  time: number;     // contains time in MS that this action took to perform (including fetch time)\n  status: number;   // contains an HTTP status / string\n  value: any;       // depending on the method used, may return an array, object or fetch result\n  note?: string;    // an additional note for the user\n}\n```\n\n## Chaining methods\n\n```ts\n// you can also use a custom chain method to simplify even more and avoid using async/await\nbtt\n  .invokeChain()                      // 1)\n  .triggerShortcut('cmd+space')       // 2)\n  .sendText({text: 'Hello world!'})   // 3)\n  .wait(1000)                         // 4)\n  .toggleNightShift()                 // 5)\n  .call()                             // 6)\n  .then(v =\u003e console.info(v))         // 7)\n\n// Explanation:\n// 1) Starts method chaining\n// 2) Action that a user wants to perform\n// 3) Action that a user wants to perform\n// 4) Additional method available in chain only - wait before triggering next action\n// 5) Action that a user wants to perform\n// 6) Invokes all previously-defined actions, ensuring the execution order\n// 7) Returns a promise that resolves once all of the actions are fulfilled. \n//    Contains information about the status of the chain (time, value, status)\n```\n\n## Event listeners\n\nYou can even register a system-wide event listener within BTT that'll trigger particular actions\n\n```ts\n// creates a trigger in BetterTouchTool. Keep in mind that this is persistent until you manually delete it!\nbtt.addTriggerAction('oneFingerForceClick', (ev) =\u003e {\n\n  // create a list of actions that you want to perform on single finger force click\n  const actionsToInvoke = [\n    btt.showHUD({\n      title: 'Wow!',\n      details: 'I triggered! 😍',\n    }),\n  ];\n  \n  // and push them to `actions` property in the event object.\n  ev.actions.push(...actionsToInvoke);\n});\n\n// you can also delete an event listener - trigger: \nbtt.removeTriggerAction('oneFingerForceClick', callbackFuntion);\n```\n\nThe above method will trigger the callback upon running your script, not when a particular event really occurs. If you need to call a function upon event recognition, you need to use [btt-node-server](https://github.com/Worie/btt-node-server) and use the `addEventListener` and `removeEventListener` methods on the btt instance. The callback you provide will run in the nodejs environment, within `vm`.\n\n```ts\nconst btt = new Btt({\n  domain: '127.0.0.1',\n  port: 8000,\n  protocol: 'http',\n  version: '2.525',\n  // pass eventServer to use this part of the lib\n  eventServer: {\n    domain: 'localhost',\n    port: 8888,\n  },\n});\n\n// adds real event listener, that'll run once event occurs\nbtt.addEventListener('cmd+ctrl+alt+u', async (ev) =\u003e {\n  // write the code as you'd normally do -\u003e trigger the action for some interval\n  const intervalID = setInterval(() =\u003e {\n    btt.showHUD({ title: 'It works!'}).invoke();\n  }, 1000);\n\n  // you can use fetch API here or anything that your node version will support\n\n  // stops the interval after 10 seconds\n  await new Promise((res, rej) =\u003e {\n    setTimeout(() =\u003e {\n      clearTimeout(intervalID);\n      res();\n    }, 10000);\n  });\n  \n  // the value you return from the callback will be the response of the btt-node-server \n  return { messsage: 'Hello world!' };\n});\n```\n\nTo get all available events, you have to look in the enums (list of all valid events will be available soon).\nMost of the time you can just guess because all event names are the lowercased equivalent of the triggers from within `BetterTouchTool`.\n\n### Additional action information\n\nFor use within the browser, you can get the `url` that lies behind all actions and assign it to some `\u003ca href=\"${link}\"\u003eLink\u003c/a\u003e`. To get `link` you simply need to read the `.url` property of any action: \n\n\n```ts\nconsole.log(\n  btt.triggerShortcut('cmd+space').url\n);\n```\n\nIf you want to have a peak at the generated action JSON, or want to share it with others who use `BetterTouchTool` you can read the `.json` property of any action. \n\n\n```ts\nconsole.log(\n  btt.showHUD({ title: 'Hello!' }).json\n);\n```\n\n## More examples \n\nFor more advanced examples visit [the example section](https://github.com/Worie/btt/tree/master/examples)\n\n## Notice\n\nKeep in mind that this module only provides handy utility functions that send requests to BTT built in webserver.\nSo depending on your BTT version, some actions may be glitchy. Do not hestitate to report those issues here or in the [official BTT community forum](https://community.folivora.ai/categories). \n\nAlso, keep in mind that accessing any kind of low level APIs from JS may be dangerous, make sure to [stay secure](#)\n\n### Related projects:\n\n* [btt](https://github.com/Worie/btt) - BetterTouchTool management in JS\n\u003c!-- * [btt-json-loader](https://github.com/Worie/btt-json-loader) - JSON loader for BTT --\u003e\n* [btt-node-server](https://github.com/Worie/btt-node-server) - Simple express server, required for advanced event listener handling\n\u003c!-- * [btt-touchbar-widgets](https://github.com/Worie/btt-touchbar-widgets) - Working touchbar widgets, based on [btt](https://github.com/Worie/btt) --\u003e\n* [btt-node](https://github.com/Worie/btt-node) Premature version of this package ([btt](https://github.com/Worie/btt)) - deprecated\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n","funding_links":["https://paypal.me/wopolow"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWorie%2Fbtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWorie%2Fbtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWorie%2Fbtt/lists"}