cwernert / swiftbar-zapier

A plugin for the SwiftBar app, which aims to present content collected by Zapier.

swiftbar-zapier

A plugin for the SwiftBar app, which presents content collected by Zapier.

1. Installation
2. Usage
   • Creating a Channel ID
   • Adding your Channel ID to swiftbar-zapier
   • Populating the Channel with content
3. Updates
4. Uninstallation
5. Troubleshooting

Installation:

Run the following command in Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/cwernert/swiftbar-zapier/main/install-swiftbar-zapier.sh)"

---

If you would like to check what the script will do before running it, you can review the source here. In summary it will:

1. Confirm that you are ready to proceed
2. Close SwiftBar if it is already running
3. Check for required dependencies (node, npm, swiftbar, homebrew)
4. Install any dependencies that weren't already present
5. Create the SwiftBar-Plugins directory and necessary subdirectories
6. Download necessary resources from this GitHub repo into those directories
7. Set executable permissions on the files which need to be executed
8. Use npm update to download the required node modules into respective locations
9. Hide all files except the main plugin script, to prevent SwiftBar from running them as plugins
10. Open the SwiftBar application

Usage:

Once installed, you should see "Please add a Channel ID" in the MenuBar like this:

If not, see troubleshooting.

Now, you're ready to set up a "Channel", which will hold the information to be presented in swiftbar-zapier. To do this, you'll need:

• A Zapier account
• Access to the SwiftBar Zapier integration (currently "Private")

The integration is functional, but still in development, so it remains Private for the time being. Please contact me on Slack if you would like access.

Creating a Channel ID:

1. Create a new Zap, and add a "Set Channel Title & Content in SwiftBar" action to it (any event will do, but this one will allow you to populate the channel with content to verify a successful setup).
2. At the "Choose Account" stage, click "Connect a new account" to see this page
3. Use a UUID4 Generator to create a Channel ID, and copy/paste it into the "Channel ID" field
4. (Optional) Enter a name for the channel. This will help to identify the connection in Zapier's UI and will be visible in SwiftBar when more than one Channel ID is configured, to differentiate content from each channel.
5. Proceed to add some content to the channel by testing the Zap action

Adding your Channel ID to swiftbar-zapier:

1. Click "Please add a Channel ID" in your MacOS MenuBar to open the submenu
2. Select "Add a new Channel ID" from the menu (see note below)
3. Paste your UUID4 into the Terminal prompt
4. Content set by Zapier will now be displayed in your MenuBar, and you can safely exit Terminal

During step 2 listed above, MacOS is likely to require that you grant SwiftBar permission to execute scripts in Terminal. In order to continue, please do so like this.

Populating the Channel with content:

A detailed guide on SwiftBar syntax can be found here.

SwiftBar content is comprised of two primary elements; header and body. For the purposes of swiftbar-zapier, these are referred to as title and content respectively.

A Channel can contain a single Title and many lines of Content. Titles are displayed in the MacOS menu bar, while lines of Content are listed in the submenu which opens when swiftbar-zapier is clicked.

If more than one Channel is added to your swiftbar-zapier, Titles will be displayed one at a time in a loop, while the submenu is populated with the Content from all Channels, separated by their respective Channel Names.

The simplest way to add content to a channel is by adding values to a "Set Channel Title & Content" action like this.

To add more advanced content, such as links, checkmarks, custom formatting etc. you can refer to SwiftBar's documentation, or use the "Prepare custom Title/Content" action to generate SwiftBar syntax automatically, like this.

Like any other mapped value in Zapier, the output from a "Prepare custom Title/Content" action can be mapped to the "Set Channel Title & Content" action, like this:

> *Shown above: a content item is generated by a "Prepare custom Title/Content" step and added to a channel. When clicked, the item will open zapier.com in the user's default browser. Also, examples of manually-typed SwiftBar syntax.*

Updates:

swiftbar-zapier automatically checks for updates each time it runs. If an update is available, your title content will be prepended with the update icon ⬆️ and a corresponding submenu item will be available:

Clicking this item will close SwiftBar, update swiftbar-zapier and reopen SwiftBar.

Uninstallation:

To remove swiftbar-zapier from your system, delete the directory at:

~/Applications/SwiftBar-Plugins/swiftbar-zapier

Note that this will not uninstall the dependencies (node, npm, swiftbar, homebrew) or any other SwiftBar plugins that you may have installed.

Troubleshooting:

SwiftBar is running, but I don't see anything in my MenuBar

1. Check to ensure that your SwiftBar Plugin Directory is set to:

   ~/Applications/SwiftBar-Plugins/swiftbar-zapier

   This can be done by opening SwiftBar preferences and clicking the "Change" button on the "General" tab.

2. Ensure that the plugin is enabled, by switching to the "Plugins" tab and checking the box beside "SwiftBar for Zapier".

3. Ensure that there is sufficient space available for SwiftBar in your MacOS MenuBar. I personally like to use Bartender to help with this, but other options are also available.

swiftbar-zapier's Issues

Add preferences > Update options

See also: Add preferences > Display options

Start by including a new menu item called "Preferences" with submenus as below:

First option would call a bash script (or the existing configscript with a param) and toggle the automatic updates setting by:

• Reading the current setting in config.json
• Inverting that setting
• Writing the new setting

The main plugin file would need to read that config key and optionally perform the update check based on it.

The second option would likewise write a value to the config.json, this time containing a number of seconds:

• Hourly = 3600
• Daily = 86400
• Weekly = 604800
• Custom = user input via terminal

If config.json includes one of those values, the option should have checked=true added after the pipe, while the others get a call to bash which would include the selected number as the input param. If custom is selected, user would be prompted to enter a number greater than 10 (to match the main plugin execution frequency).

The value would need to be stored in config.json, alongside a value to represent the last time an update check was performed.
In the main plugin:

• if auto updates are enabled
• read the two numbers (lastUpdateCheck & updateFrequency)
• compare them; if current unix time is greater than (lastUpdateCheck + updateFrequency)
• check for updates

"Inquirer" node module not present after new installation

Referring to Leo's feedback, somehow inquirer was not installed and therefore missing when trying to add a Channel ID.

This dependency is included with the package.json, and the installer does run npm update - not sure how this happened at the time of writing.

Wondering whether Leo was served a cached & outdated package.json (seems unlikely) or whether there might be an issue with the installer itself.

Call out permissions grant during install

Following Hanz's feedback, need to mention the requirement to grant MacOS permissions during installation. See this screenshot

Add preferences > Display options

See also: Add preferences > Update options

Start by including a new menu item called "Preferences" with submenus as below:

Under "Display", user can select "Compact" or "Expanded".
Compact keeps info from all channels in the one SwiftBar plugin (current behaviour).
If set to Expanded, the main swiftbar-zapier plugin would:

• Set it's title content to be a single icon (gear? SBZ icon?) plus another icon when an update is ready or no channels are set up
• Set it's menu content to be the footer material (add, remove, prefs, about etc.)
• Scan the config file for channel IDs, then create a file in the swiftbar plugins dir for each, named {channel_id}.10.js
• Check whether files exist already before creating of course
• If user selects "remove channel ID", remove the ID from the config AND delete the corresponding plugin file

This would present each channel as a seperate plugin, "expanded" across the menubar.

We'd probably need a template script in the config dir, which would only need a single input variable - the channel id.
Channel-specific plugins could then ignore the standard swiftbar footer content, since that would be present in the main plugin.

It's also possible to enable/disable/toggle plugins with Swiftbar URLs but I don't think this would be necessary if we're deleting the files. Maybe we could include a list of active channels in the main plugin's menu content, with an href to the toggle url for that plugin and a checkbox icon to indicate whether it is currently active or disabled. Might help with troubleshooting visibility for some folks.

Installer doesn't differentiate different node installations

MacOS can have node in various spots, and it looks like (verify) SwiftBar requires it to be in the standard dir:
/usr/local/bin/node
If Node is installed via NVM, it will be at:
~/.nvm/versions/node

Need to:

• Verify that swiftbar needs node in the standard dir
• Update the installer to check for and enforce this

Split "Creating a Channel ID" step 4 in two

Following Hanz's feedback, adding the channel name can be optional but populating the channel with content is not. Split step 4 in half, so that the former can remain optional while the latter is listed as a separate, required step.

Add "Client ID" to the frontend config

While "client" feels the most technically accurate, perhaps the noun could be "channel-related", such as "Viewer" or "Subscriber".

The idea here is to add some way of customising the frontend behaviour, such that a single channel ID can be shared with many clients, but those clients can identify themselves to the frontend in order to get a personalised subset of the data in the channel.

For example, a submenu item in the footer labelled, "Add a Client ID" which adds their ID to config/swiftbar-zapier-config.js. Then, a channel could send notifications to specific Client IDs, or personalised submenu content for each client (eg. tickets assigned to that person).

The concern here is that users would likely then need to put so much content in channels that they would overwhelm Storage by Zapier, trying to store more data than a single key can hold. Maybe this could be overcome by storing Client-specific details in storage keys defined with the Client ID? This might causing excessive complexity - need to think it through.

The functionality is also technically already possible, albeit pretty laborious for users on the Zapier side. A Channel ID could be configured for each client, and using Looping by Zapier, a Zap could set common content for a set of Channel IDs, then seperate Zaps could append that content with personalised details for each channel. ie. each client has their own personal Channel, rather than one channel for a whole team.

Remove app directory link

Following Hanz's feedback, remove the broken link to the app directory until the app is published.
Can probably keep the URL in the comments for convenience later.