Local Development

Starting The App Locally¶

To start developing our app, we can start it up locally. Out of the box, we provide a simple server that exposes your actions on a local port (5050).

npm run start

# > test-app@1.0.0 start
# > nodemon --watch "src/**/*.ts" --exec ts-node src/main.ts
# 
# [nodemon] 1.19.4
# [nodemon] to restart at any time, enter `rs`
# [nodemon] watching dir(s): src/**/*.ts
# [nodemon] watching extensions: ts,json
# [nodemon] starting `ts-node src/main.ts`
# Initializing module...
# Registered 1 action(s):
#         - @vibeiq/seasonal-forecaster:logItem # (1)
# Mock server listening on port 5050

This is your action identifier when running locally. You will use this identifier to make requests later on.

To send to your actions locally and authenticate to the platform, you will need your org slug and your app's api token.

App API token¶

To get the app api token, you can run contrail app getApiKey.

contrail app getApiKey --appIdentifier="@vibeiq/seasonal-forecaster"
# 2024-01-08T23:13:52.913Z info: App API key: (app:uEL7GCBZ7Xhd4w2z)

Org Slug¶

Your org slug can be found either by going to the Org Details page in the admin console or inspecting the URL on your browser. URL Org Slug

Sending a request locally¶

To send a request to the local app server, you can send a request using your favorite HTTP tool. Here, we use the universal cURL command line utility present on most operating system distributions.

curl --location 'http://localhost:5050/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "@vibeiq/seasonal-forecaster:forecastWeather",
    "apiKey": "app:uEL7GCBZ7Xhd4w2z", 
    "orgSlug": "YOUR-ORG-SLUG", 
    "event": {}
}'

Event Data

Because our simple forecastWeather action does not use any event data, we do not need to pass information in the event object. However, in actions that respond to a system event (e.g. an item update), the event object will include data that corresponds to the triggering event.

The server will respond with a JSON indicating the action's success or failure, and the associated logs

{
    "statusCode": 200,
    "body": {
        "logs": [
            "2024-01-08T23:16:37.083Z: App Info:  @vibeiq/seasonal-forecaster : 1.0.0",
            "2024-01-08T23:16:37.083Z: action:  @vibeiq/seasonal-forecaster:forecastWeather forecastWeather",
            "2024-01-08T23:16:37.086Z: Starting Forecast Weather Action",
            "2024-01-08T23:16:37.495Z: request status: 200",
            "2024-01-08T23:16:37.505Z: response: {\n  \"latitude\": 42.339344,\n  \"longitude\": -71.07211,\n  \"generationtime_ms\": 0.03409385681152344,\n  \"utc_offset_seconds\": 0,\n  \"timezone\": \"GMT\",\n  \"timezone_abbreviation\": \"GMT\",\n  \"elevation\": 8,\n  \"current_units\": {\n    \"time\": \"iso8601\",\n    \"interval\": \"seconds\",\n    \"temperature_2m\": \"°C\"\n  },\n  \"current\": {\n    \"time\": \"2024-01-08T23:15\",\n    \"interval\": 900,\n    \"temperature_2m\": -2.3\n  }\n}"
        ],
        "status": "SUCCESS",
        "output": {
            "response": {}
        }
    }
}

Additionally, you can view the logs of the process running your server, and should see similar logs

[nodemon] starting `ts-node src/main.ts`
Initializing module...
Registered 1 action(s):
        - @vibeiq/seasonal-forecaster:forecastWeather
Mock server listening on port 5050
App Info:  @vibeiq/seasonal-forecaster : 1.0.0
action:  @vibeiq/seasonal-forecaster:forecastWeather forecastWeather
Starting Forecast Weather Action
request status: 200
response: {
  "latitude": 42.339344,
  "longitude": -71.07211,
  "generationtime_ms": 0.03409385681152344,
  "utc_offset_seconds": 0,
  "timezone": "GMT",
  "timezone_abbreviation": "GMT",
  "elevation": 8,
  "current_units": {
    "time": "iso8601",
    "interval": "seconds",
    "temperature_2m": "°C"
  },
  "current": {
    "time": "2024-01-08T23:15",
    "interval": 900,
    "temperature_2m": -2.3
  }
}

Once you have made enough local iterations on your app's code, you can up-rev the app's version and publish it!

contrail app version patch
contrail app publish

Upgrading Apps

Do not forget to upgrade your app once you publish it! When you are developing an app, you are acting as two people: the app developer and the app user. The app developer is responsible for publishing the app, and the app user is responsible for installing/upgrading the app in their org.

Let's upgrade our app to the latest version we just published!

contrail app upgrade --appIdentifier="@vibeiq/seasonal-forecaster" --latest

Upgrade on Publish

If you are working on developing an app in your org, you can pass a handy option to the publish command which will automatically upgrade the app in your org.

contrail app publish --upgrade