❤
npm
Sign UpSign In

toolbeam-cli

0.1.5 • Public • Published

Toolbeam

Convert your API to a native mobile tool

NPM Version Chat on Gitter License

Toolbeam converts your API into a native cross-platform mobile tool. A quick example:

  1. Take a GET API resource that returns a list of movies

    https://toolbeam-example-api-gqzlijbklg.now.sh/top_movies

  2. Add it to Toolbeam and create a tool

    > tb init https://toolbeam-example-api-gqzlijbklg.now.sh
    > tb add /top_movies
    > tb push

  3. Navigate to the tool on your phone

    📲   https://toolbeam.com/t/tnqjurvz

    Example Gif

Contents

Features

  • Native and Cross Platform

    Tools run natively on iOS or Android without any additional setup.

  • Simple Notification API

    Send iOS or Android notifications to your tools using our simple notification API.

  • Mobile Specific Form Fields

    Form fields designed for mobile including geolocation, image, and video.

  • Instant Updates

    Updates made via the CLI are reflected immediately on your phone.

  • Share via a Link

    Share your tool with anybody via a link immediately after you create it.

Get Started

  1. Install Node.js
  2. Install the Toolbeam CLI: npm install -g toolbeam-cli
  3. Sign up for a Toolbeam account: tb signup

Examples

Continuing with the movie example, we are going to create a set of tools to explore some of the features of Toolbeam. We are going to use a very simple JSON API that is publicly accessible and you can see the source for it here. The resources in the API are for demo purposes only and don't make any real changes to the underlying data.

Setting API Parameters

To start off, let's create a tool to get a movie given its id. We'll use the API GET /movies/{id}.

> tb init https://toolbeam-example-api-gqzlijbklg.now.sh
> tb add /movies/{id} --set-param name:id in:path field:number

The id parameter above is passed in through the path using path templating but can be passed through the query string, header, or form data. Read more about setting API Parameters using the tb add command here.

We are also setting the field type for the id parameter to number to use the number keypad. We'll go over field types in a little more detail in the next example.

Running the two above commands create a Open API Spec file called toolbeam.json in the current directory.

(Optionally, we'll edit the spec manually to change our project name, tool name, field label, etc.)

And now running tb push will push the spec to Toolbeam; creating the project and the tool.

> tb push
Loading toolbeam.json
Validating spec
Pushing toolbeam.json
Tools added:

  + Get a Movie
    -> https://toolbeam.com/t/oevonxry

Project created 'Classic Movies'
Run 'tb messageme' to send the links to your phone

Go ahead and navigate to https://toolbeam.com/t/oevonxry or run tb messageme to send the link to your phone. Now if you enter an Id, it should return a movie object.

Example Screenshot

Setting Field Types and Handling File Uploads

Let's make something a bit more complicated and explore the different field types. We'll create a new tool to edit the genre of the movie and upload a new poster. We are going to use the API PUT /movies/{id}. The API takes the id of the movie, the genre, and an image as the poster.

> tb add PUT /movies/{id} --set-param name:id in:path field:number \
                          --set-param name:genre in:formData field:select enum:Romance,Mystery,Fantasy,Thriller,Action \
                          --set-param name:poster in:formData field:image

We're using the select field type for the genre parameter and passing in the possible values using the enum option as a comma separated list.

To upload the poster we are using the image field type. When using a file field type (image or video) the API request uses the multipart/form-data encoding. Without a file field type, the API request is made using the application/x-www-form-urlencoded header for formData parameters. You can read more about the different field options below.

(Optionally, we'll edit the spec to change the appearance of the tool.)

Let's create the tool:

> tb push

And now navigate to https://toolbeam.com/t/kldgocfm and try taking a photo from your camera or uploading an image from your camera roll.

Example Screenshot

Using Basic Auth

Now let's look at deleting a movie and making it so that the user needs to authenticate to do so. We'll use the API DELETE /movies/{id} that requires basic auth with the username admin and password password.

> tb add DELETE /movies/{id} --set security:basic \
                             --set-param name:id in:path field:number

Notice that we are setting the tool option security. You can read further about the other tool options below.

(Optionally, we'll edit the spec to tweak the appearance of the tool.)

Create the tool:

> tb push

Navigate to https://toolbeam.com/t/moqulqnk and try it with the basic auth info admin:password.

Example Screenshot

Sending Notifications

To explore how to use notifications, let's create a tool that'll notify us when a movie is playing near our location. We'll use the API POST /movies/{id}/subscribe; that takes the id of the movie and location of the user.

> tb add POST /movies/{id}/subscribe --set needsNotificationPermission:true \
                                     --set-param name:id in:path field:number \
                                     --set-param name:location in:formData field:geolocation

Notice that we set the flag needsNotificationPermission to indicate that we'd like to send the user notifications. Toolbeam makes it easy to send notifications using the Toolbeam Notification API. Simply, send us the uuid of the tool and user you'd like to send the notification to, along with your API Key. You can get the user uuid and the tool uuid from the request headers and your API Key by running tb whoami. You can read more about the Notification API here.

Parameters sent using formData are passed into the API using the application/x-www-form-urlencoded header. Also, the location of the user is passed in as a JSON object containing latitude and longitude. You can read more about the geolocation field type for the tb add command here.

(Optionally, we'll edit the spec to change the appearance of the tool.)

Let's create the tool:

> tb push

And head over to https://toolbeam.com/t/bcgrjtcu to give it a try. Now after you subscribe to a movie, you should get a notification on your phone after about 5s!

Note: If you are working through this example yourself and you are connecting to the example API; you will not receive a notification. This is because the API Key used in the sample API belongs to a demo account. To test out notifications, you can run the example API yourself and use your own API Key.

Example Screenshot

Linking Tools Together

While, the tools on their own are useful; linking them together allows us to create more complicated CRUD-like tools. We'll use the API GET /movies; that takes a keyword to search for matching movies and returns a list of movies. For the sake of the example it always returns the same list. In addition to the movie object, it also returns a couple fields with links to the tools we created in the above examples. Here are the extra fields returned by the API:

{
  'edit': 'https://toolbeam.com/t/kldgocfm?id=${movie.id}&genre=${movie.genre}',
  'delete': 'https://toolbeam.com/t/moqulqnk/response?id=${movie.id}',
  'subscribe': 'https://toolbeam.com/t/bcgrjtcu?id=${movie.id}'
}

We are linking to the Edit, Delete, and Subscribe tools from above and passing in the info for the movie that is returned. By doing so Toolbeam will convert these fields into buttons that'll link to the specified tools. And the query string parameters in these URLs are used as the default values in the linked tools.

Notice that unlike the others, the delete tool is linking to /response. By doing so, it links directly to the response screen of the Delete tool and skips the form screen. You can read further about linking tools below.

Now let's add the API resource:

> tb add /movies --set-param name:keyword in:query

(Optionally, edit the spec to change the appearance of the tool.)

And create the tool:

> tb push

Head over to https://toolbeam.com/t/dbgfrxpi and search for a movie to give linking a try. If you are building your own tools by connecting to the example API, remember that the tools that are linked are the ones from a demo account.

Example Screenshot

How it Works

Running tb init and tb add creates an Open API Spec JSON file called toolbeam.json describing the API resource in the current directory. And tb push uploads this to Toolbeam.com and creates the tools. The tools talk directly to your API and the data transferred is not stored on the device or on our servers.

Flowchart

Documentation

Toolbeam CLI

Usage: tb <command>

Commands:
  signup             Sign up for Toolbeam
  login              Login to Toolbeam
  init <url>         Initialize your Toolbeam project
  add [oprn] <path>  Add an API resource as a tool
  rm [oprn] <path>   Remove the given API resource
  push               Push your current project spec to Toolbeam
  pull [id]          Pull your current project spec from Toolbeam
  project            View and manage your projects
  messageme          Send a text message with your recently created tools
  whoami             Info about current logged in user
  logout             Logout from Toolbeam

tb init <url>

Initialize a new Toolbeam project with the given base URL. Group all your API resources that are under the same base URL into a single project.

Arguments

  • <url>

    The base URL of your API.

Examples

  • Initilize your Example API project.

    tb init http://api.example.com

  • Include the base path of your API.

    tb init http://api.example.com/v1

tb add oprn <path> [options]

Add an API resource with the given path as a tool. The path is relative to the base URL of the current project.

Arguments

  • The HTTP operation of the resource. Defaults to GET.

  • <path>

    The path of your API resource. Supports path templating. Use curly braces ({}) to mark a section of a URL path as replaceable using path parameters.

Options

  • --set

    Set <key>:<value> options for the tool [array]

    Option Description
    security Type of security; basic for basic auth or none for no authentication. Defaults to none.
    needsNotificationPermission Set to true if your tool needs to send notifications to the user. It will prompt the user for permission. Defaults to false.

  • --set-param

    Set a parameter for the tool and <key>:<value> options [array]

    Option Description
    name Required The name of the parameter. This will be used in path templating and in the headers depending on where it is used.
    in Required The type of the parameter and where it will be used.
    • path: Used to replace the parameter in path templating. The parameter foo will be applied to the API path /movies/{foo}.
    • query: Parameter will be added to the query string for the request using the query string format foo=1&bar=value.
    • header: Parameter will be added as a custom header for the request.
    • formData: The request will be made using application/x-www-form-urlencoded or multipart/form-data. If there are no parameters with field type image or video, then the parameters will be passed in the request body similar to the query string format of foo=1&bar=value using application/x-www-form-urlencoded. But in the presence of a parameter with field type image or video; the request will be encoded using multipart/form-data.
    field The type of field used in the UI. Defaults to text.
    • text: Displays the standard alphanumeric keypad on field focus.
    • number: Displays the number keypad on field focus.
    • email: Displays the email keypad on field focus.
    • hidden: The field is not displayed to the user.
    • select: The field is displayed as a picker. Use in conjunction with enum to display a list of options.
    • image: Lets the user upload an image from their camera roll or take a photo with their camera. The API request is made using multipart/form-data.
    • video: Similar to image but lets the user upload a video.
    • geolocation: Prompts the user for their current location and passes that to the API as a JSON object with latitude and longitude (ex:{"latitude":43.64,"longitude":-79.37}).
    enum Comma separated list of options in a select picker. Used in conjunction with field type select.

Examples

  • Add a GET resource with no parameters as a tool.

    tb add /movies

  • Add a POST resource as a tool.

    tb add POST /movies/31/like

  • Add a GET resource with security type basic auth.

    tb add /movies/upload --set security:basic

  • Add a POST resource with security type basic auth that needs to send notifications.

    tb add POST /movies/upload --set security:basic needsNotificationPermission:true

  • Add a GET resource with a parameter using path templating.

tb add /movies/{id} --set-param name:id in:path

  • Add a GET resource with two query string parameters.

    tb add /movies/search \
       --set-param name:keyword in:query \
       --set-param name:sort in:query

  • Add a DELETE resource with a header parameter.

    tb add DELETE /movies/1/remove \
       --set-param name:session_key in:header

  • Add a POST resource with three form data parameters and one with field type select.

    tb add POST /movies/add \
       --set-param name:title in:formData field:text \
       --set-param name:year in:formData field:number \
       --set-param name:genre in:formData field:select enum:comedy,drama,romance,action

tb rm oprn <path>

Remove an API resource with the given path from the spec. This does the opposite of tb add.

Arguments

  • The HTTP operation of the resource. Defaults to GET.

  • <path>

    The path of the API resource to remove.

Examples

  • Remove the /movies GET resource from the spec.

    tb add /movies

  • Remove a POST resource from the spec.

    tb add POST /movies/{id}/like

tb push

Push your current spec to Toolbeam. Looks for the toolbeam.json in the current directory. Creates or removes the tools in your spec.

tb pull [id]

Pull the spec for your current project. Optionally, pull a specific project spec by passing in a project id. You can get the id of a project by using the tb project ls command.

Examples

  • Pull the current project spec

    tb pull

  • Pull the spec of the given project

    tb pull stqpliww

tb project ls

List all your projects along with their project ids. And all the tools with their shareable URLs.

tb project rm <id>

Removes a project and all their tools. The tools in the project will also be removed from any users that have them. This command cannot be undone; please use with caution.

Arguments

  • <id>

    The id of the project. You can look up a project's id using tb project ls.

Examples

  • Remove the project with the given id

    tb project rm stqpliww

tb messageme

Sends a text message to the given number with the 3 most recently created tools. Uses TextBelt to send the messages.

tb whoami

Shows information about the user currently logged in. Also, shows the API key of the user.

Toolbeam Spec

Under the hood, running tb init and tb add creates an Open API Spec JSON file describing the API in the current directory. To further customize your tools you can directly edit the spec and then run tb push to update your tools. Below is an annotated spec as an example.

{
  // <!--- Project options go here --->
  "swagger": "2.0",
  "info": {
    "title": "Acme Api", // A name for your Toolbeam project
    "version": "1.0.0",
    "x-tb-uuid": "e5433e29" // The UUID for the project, do not change
  },
  "host": "api.example.com", // API Host
  "basePath": "/v1", // API Basepath
  "schemes": [
    "https" // Supported URL Schemes
  ],
  // Add a definition for the security type used
  "securityDefinitions": {
    "basic_auth": {
      "type": "basic"
    }
  },
  "paths": {
    // Add a Resource
    "/users/{id}": {
      // Specify the Operation Type
      // This block represents a tool
      "get": {
        // <!--- Tool options go here --->
        "x-tb-name": "List of Users", // Name of the tool
        "x-tb-color": "red", // Color of the tool
        "summary": "This tool gets the info about the given user", // Helpful description for the tool
        "operationId": "a10khwea", // Unique identifier for the tool, do not change
        "security": [
          {
            "basic_auth": [] // Use the security definition from above
          }
        ],
        "parameters": [
          {
            // <!--- Field options go here --->
            "name": "id", // Parameter name
            "in": "path", // Where the param is used
            "required": true, // If the user needs to enter it
            "type": "string",
            "default": "819", // Default value for the field
            "x-tb-fieldType": "text", // Type of the field in the tool
            "x-tb-fieldLabel": "User Id", // Label for the field in the tool
            "x-tb-fieldPlaceholder": "Ex: 314159" // Placeholder for the field
          }
        ],
        "responses": {
          "200": {
            "description": "Results"
          }
        },
        "x-tb-actionLabel": "Get User", // Label for the button in the tool
        "x-tb-needsConfirm": false, // Confirm before submitting the tool
        "x-tb-needsNotificationPermission": false // Request notification permission from the user
      }
    }
  }
}

Below is a more detailed explanation of the fields that are used.

Project Options

  • info.title:[string]

    The name of the current project.

  • info.x-tb-uuid:[string]

    The UUID for the project generated after the first tb push. Do not change.

  • host:[string]

    The host name of your API

  • basePath:[string]

    The base path of your API, relative to the API host.

Tool Options

  • x-tb-name:[string]

    The name of the tool. If not provided, Toolbeam generates a name.

  • **x-tb-color:**red|blue|orange|green|purple

    The color of the tool. If not provided, one is randomly picked.

  • summary:[string]

    A small summary of the tool that is displayed at the top. Can be used to provide the user with a helpful description.

  • operationId:[string]

    A unique id that is generated to identify the tool. Please do not change.

  • x-tb-actionLabel:[string]

    The label of the submit button of the tool.

  • x-tb-needsConfirm:[boolean]

    True if a confirm dialog should be presented on submit. Defaults to false.

  • x-tb-needsNotificationPermission:[boolean]

    True if the tool needs to ask the user permission to send notifications. Defaults to false.

Field Options

  • name:[string]

    The name of the parameter. This will be used in path templating and in the headers depending on where it is used. This option is required.

  • in:path|query|header|formData

    The type of the parameter and where it will be used. This option is required.

    • path

      Used to replace the parameter in path templating. The parameter foo will be applied to the base API path /movies/{foo}.

    • query

      Parameter will be added to the query string for the request using the query string format foo=1&bar=value.

    • header

      Parameter will be added as a custom header for the request.

    • formData

      The request will be made using application/x-www-form-urlencoded or multipart/form-data. If there are no parameters with field type image or video, then the parameters will be passed in the request body similar to the query string format of foo=1&bar=value using application/x-www-form-urlencoded. But in the presence of a parameter with field type image or video; the request will be encoded using multipart/form-data.

  • required:[boolean]

    True if this is a required field.

  • default:[string]

    The default value of the field.

  • x-tb-fieldLabel:[string]

    The label for the field. If not provided, the name is used as the label.

  • x-tb-fieldType:text|number|email|select|hidden

    The type of field used in the UI. Defaults to text.

    • text

      Displays the standard alphanumeric keypad on field focus.

    • number

      Displays the number keypad on field focus.

    • email

      Displays the email keypad on field focus.

    • hidden

      The field is not displayed to the user. Can be used in conjunction with setting a default to pass some data in the request that does not change.

    • select

      The field is displayed as a picker. Use in conjunction with enum and x-tb-fieldEnumLabel. As an example here is a param block for a select:

      {
        "name": "type",
        "in": "query",
        "type": "string",
        "x-tb-fieldType": "select",
        "enum": ["casual_users", "paying_users"], // This is sent in the API request
        "x-tb-fieldEnumLabel": ["Casual Users", "Paying Users"] // This is shown to the user
      }

    • image

      Lets the user upload an image from their camera roll or take a photo with their camera. The API request is made using multipart/form-data.

    • video

      Similar to image but lets the user upload a video.

    • geolocation

      Prompts the user for their current location and passes that to the API as a JSON object with latitude and longitude. For example, a geolocation field will pass in the following in the API request; {"latitude":43.64,"longitude":-79.37}.

  • enum:[array]

    An array of values used by the picker if the x-tb-fieldType is select. The index corresponding the selected item in the picker is passed in the request.

  • x-tb-fieldEnumLabel:[array]

    An array of values displayed as the options in the picker. If not provided, enum is displayed as the options.

  • x-tb-fieldPlaceholder:[string]

    The placeholder text for the field. If not provided, a placeholder based on the x-tb-fieldType is used as the placeholder.

Linking Tools

Toolbeam auto converts https://toolbeam.com/t/{toolUuid} URLs in an API response into a button that directs users to the specified tool. By using these links we can chain tools together. This is useful for cases where you want a user to execute an action based on what is returned from a tool.

Types of Links

  • Link to the tool

    Link to a tool by returning https://toolbeam.com/t/{toolId}?paramName={defaultValue} in your API. In the query string of the URL you can add the parameters of the tool that you would like to initialize with.

  • Link directly to the tool response screen

    You can also directly link to the response screen of a tool by returning the URL https://toolbeam.com/t/{toolId}/response?paramName={defaultValue}. This is effectively making the API request of the tool with the passed in parameters.

Examples

Suppose your API responded with a user object. And you had an Edit User Info tool @ https://toolbeam.com/t/whvhltqmi.

{
  "user_id": 512,
  "username": "jdoe",
  "email": "jdoe@example.com",
  "edit": <link>
}

Then you could do the following by returning these links:

  • Link to the Edit User Info tool

    https://toolbeam.com/t/whvhltqmi

  • Link to the tool with parameter user_id initialized to 512

    https://toolbeam.com/t/whvhltqmi?user_id=512

  • Link to the tool with parameter user_id and type initialized

    https://toolbeam.com/t/whvhltqmi?user_id=512&type=admin

  • Link directly to the response screen of a tool with parameters user_id and type

    https://toolbeam.com/t/whvhltqmi/response?user_id=512&type=admin

Toolbeam Notification API

To send notifications to your tools in Toolbeam we have a simplified API to use. Set needsNotificationPermission to true while creating your tool with tb add. Refer to tb add for further details. By setting this flag, Toolbeam asks the user permission to send notifications and stores the user's preference. You can then make requests to the Toolbeam Notification API below to send your users notifications.

POST https://api.toolbeam.com/v1/app/send_notifications

The notifications API needs your API Key, you can get this by running tb whoami. And it needs the uuid's of the tool and user we are going to be sending notifications to. This is passed in the request headers when Toolbeam makes a request to your API. Here is a sample of the headers that are a part of a Toolbeam request.

Content-Type: application/x-www-form-urlencoded
User-Agent: Toolbeam/1.12.20 CFNetwork/808.0.2 Darwin/15.6.0
Connection: keep-alive
Accept: */*
Accept-Language: en-us
TB-User-UUID: adqlymds
TB-Tool-UUID: bcgrjtcu
Accept-Encoding: gzip, deflate

The notification API ensures that you own the tool you are sending notifications to. And that the user you are sending to is subscribed to the tool.

Request Parameters

  • message in:query

    The message to be sent in the notification.

  • user_uuid in:query

    The UUID of the recipient user. An identifier for a user. This is passed in through the header of every single request made to your API by Toolbeam. Passed in as TB-User-UUID.

  • tool_uuid in:query

    The uuid of the tool that we are sending notifications to. This is passed in through the header of every single request made to your API by Toolbeam. Passed in as TB-Tool-UUID.

  • TB-API-KEY in:header

    The API key of your account. You can find this by running tb whoami. This needs to be passed in through the header of your request, unlike the other parameters.

Error Response

In the case of an error, the API responds with a non 200 HTTP status code and a JSON response of the following format:

{
  "error": <Error Status>,
  "message": <Error Message>,
  "code": <Error Code>
}

Below are the Error codes returned:

  • 1014

    The notification message is empty.

  • 1016

    The tool UUID is empty.

  • 1018

    The API Key is empty.

  • 2009

    The user uuid does not exist.

  • 3001

    The tool uuid does not exist.

  • 4001

    Your API Key is not authorized to send notifications to the given tool. Check if you own this tool.

  • 4002

    The given user is not subscribed to this tool.

Examples

  • Send a simple "hello world" message using cURL

    > curl -X POST -H "TB-API-KEY: <Your API KEY>" \
       -d "message=hello%20world&user_uuid=<Recipient User UUID>&tool_uuid=<Recipient Tool UUID>" \
       https://api.toolbeam.com/v1/app/send_notifications

Pricing

Toolbeam is free to use. Tools can be accessed by anybody via the share URL.

If you'd like to create private tools, please get in touch with us here.

Support

Need help to figure something out? Chat with us on Gitter or send us an email.

Have a feature request or find a bug? Open a new issue.

Credits

Thanks to TextBelt for their text messaging service.

License

Copyright (c) 2016 Anomaly Innovations

Distributed under the MIT license. See LICENSE for more information.

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 0.1.5
    1
    • latest

Version History

Package Sidebar

Install

npm i toolbeam-cli

Repository

github.com/AnomalyInnovations/toolbeam-cli

Homepage

github.com/AnomalyInnovations/toolbeam-cli#readme

Weekly Downloads

1

Version

0.1.5

License

MIT

Last publish

Collaborators

  • jayair
Try on RunKit
Report malware