pico-engine 1.9.5 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -5
- package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
- package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
- package/demos/echo/com.example.echo.bootstrap.krl +10 -7
- package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
- package/demos/json_query/README.md +11 -0
- package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
- package/demos/json_query/com.example.json_query.krl +162 -0
- package/demos/json_query/try-it.md +5 -0
- package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
- package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
- package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
- package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
- package/demos/try-it-order.json +1 -1
- package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
- package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
- package/dist/cli.js +5 -1
- package/dist/engineConfig.js +1 -1
- package/dist/identity/portableMove.js +5 -1
- package/dist/index.js +44 -12
- package/dist/internalAccess.js +110 -0
- package/dist/oauth/OAuthService.js +172 -10
- package/dist/oauth/acg.js +194 -24
- package/dist/oauth/cimd.js +381 -0
- package/dist/oauth/discovery.js +175 -0
- package/dist/runMcp.js +1 -1
- package/dist/server.js +197 -48
- package/dist/subtreeWrangler.js +8 -5
- package/dist/uiChannelPolicies.js +2 -0
- package/krl/io.picolabs.pds.krl +109 -21
- package/krl/io.picolabs.pico-engine-ui.krl +13 -7
- package/krl/io.picolabs.wrangler.krl +21 -9
- package/mcp/devResources.js +52 -0
- package/mcp/devTools.js +40 -9
- package/mcp/docs/CLAUDE.md +3 -2
- package/mcp/docs/cookbook/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/README.md +23 -0
- package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
- package/mcp/docs/cookbook/child_tasks/README.md +20 -0
- package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
- package/mcp/docs/cookbook/collection/README.md +21 -0
- package/mcp/docs/cookbook/collection/instructions.md +93 -0
- package/mcp/docs/cookbook/echo/README.md +19 -0
- package/mcp/docs/cookbook/echo/instructions.md +59 -0
- package/mcp/docs/cookbook/guard_rules/README.md +22 -0
- package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
- package/mcp/docs/cookbook/json_query/README.md +26 -0
- package/mcp/docs/cookbook/json_query/instructions.md +64 -0
- package/mcp/docs/cookbook/kblog/README.md +60 -0
- package/mcp/docs/cookbook/kblog/instructions.md +102 -0
- package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
- package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
- package/mcp/docs/cookbook/moving_picos/README.md +44 -0
- package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
- package/mcp/docs/cookbook/score_tracker/README.md +19 -0
- package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
- package/mcp/docs/cookbook/secrets/README.md +25 -0
- package/mcp/docs/cookbook/secrets/instructions.md +98 -0
- package/mcp/docs/cookbook/two_picos/README.md +20 -0
- package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
- package/mcp/docs/cookbook/xmlui/README.md +23 -0
- package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
- package/mcp/docs/developing/README.md +28 -0
- package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
- package/mcp/docs/developing/arrays-and-maps.md +77 -0
- package/mcp/docs/developing/converting-time-formats.md +28 -0
- package/mcp/docs/developing/cookies-and-redirects.md +81 -0
- package/mcp/docs/developing/decoding-form-data.md +67 -0
- package/mcp/docs/developing/engine-log-files.md +34 -0
- package/mcp/docs/developing/event-loop.md +77 -0
- package/mcp/docs/developing/events-from-email.md +80 -0
- package/mcp/docs/developing/initializing-entity-variables.md +83 -0
- package/mcp/docs/developing/mcp-ai-tools.md +98 -0
- package/mcp/docs/developing/misconceptions.md +467 -0
- package/mcp/docs/developing/names-and-scope.md +44 -0
- package/mcp/docs/developing/postman.md +159 -0
- package/mcp/docs/developing/querying-another-pico.md +47 -0
- package/mcp/docs/developing/singleton-picos.md +36 -0
- package/mcp/docs/developing/tabular-data.md +67 -0
- package/mcp/docs/developing/tips.md +251 -0
- package/mcp/docs/developing/webhook-signatures.md +56 -0
- package/mcp/docs/developing/workflow.md +106 -0
- package/mcp/docs/exp/README.md +46 -0
- package/mcp/docs/exp/event.md +110 -0
- package/mcp/docs/exp/query.md +94 -0
- package/mcp/docs/lessons/README.md +59 -0
- package/mcp/docs/lessons/events-and-queries.md +247 -0
- package/mcp/docs/lessons/gossip.md +28 -0
- package/mcp/docs/lessons/modules-and-apis.md +270 -0
- package/mcp/docs/lessons/pico-based-systems.md +470 -0
- package/mcp/docs/lessons/pico-state.md +267 -0
- package/mcp/docs/lessons/pico-views.md +290 -0
- package/mcp/docs/lessons/quickstart.md +157 -0
- package/mcp/docs/lessons/relationships.md +530 -0
- package/mcp/docs/lessons/scatter-gather.md +362 -0
- package/mcp/docs/pico-engine.md +7 -5
- package/mcp/docs/pico-overview.md +3 -3
- package/mcp/docs/wrangler/README.md +47 -0
- package/mcp/docs/wrangler/channels.md +235 -0
- package/mcp/docs/wrangler/oauth.md +56 -0
- package/mcp/docs/wrangler/pds.md +423 -0
- package/mcp/docs/wrangler/portable-subtree.md +44 -0
- package/mcp/docs/wrangler/relationships.md +297 -0
- package/mcp/docs/wrangler/wrangler.md +253 -0
- package/mcp/docs/wrangler/xmlui.md +60 -0
- package/mcp/engineClient.js +57 -5
- package/mcp/mcpScopes.js +118 -0
- package/mcp/meshHttp.js +151 -45
- package/mcp/runStdio.js +2 -0
- package/mcp/subtreeTools.js +184 -0
- package/mcp/tryItTools.js +202 -0
- package/package.json +14 -8
- package/public/pico-engine-ui.js +26 -26
- package/src/cli.ts +6 -2
- package/src/engineConfig.ts +5 -2
- package/src/identity/portableMove.ts +6 -1
- package/src/index.ts +469 -430
- package/src/internalAccess.ts +127 -0
- package/src/oauth/OAuthService.ts +243 -11
- package/src/oauth/acg.ts +289 -25
- package/src/oauth/cimd.ts +508 -0
- package/src/oauth/discovery.ts +233 -0
- package/src/runMcp.ts +3 -1
- package/src/server.ts +252 -52
- package/src/subtreeWrangler.ts +17 -5
- package/src/uiChannelPolicies.ts +2 -0
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# Modules and External APIs
|
|
2
|
+
|
|
3
|
+
Real picos talk to the rest of the web: weather services, movie databases, SMS gateways. In this lesson you'll wrap a web API in a **module**, a ruleset that other rulesets `use`, give it a secret key without writing the key in any file, and call it from an app ruleset.
|
|
4
|
+
|
|
5
|
+
## Objectives
|
|
6
|
+
|
|
7
|
+
When you finish you will be able to:
|
|
8
|
+
|
|
9
|
+
- write a ruleset that works as a module, with `provides` and `configure using`
|
|
10
|
+
- use a module from another ruleset, with `use module … alias … with …`
|
|
11
|
+
- call a web API with the `http` library, as a function and as an action
|
|
12
|
+
- write a user-defined action with `defaction`
|
|
13
|
+
- get a secret into a ruleset with install configuration (`meta:rulesetConfig`), and know where it still shows
|
|
14
|
+
|
|
15
|
+
**Before you begin**, finish [Pico State](/lessons/pico-state). The examples call [The Movie Database (TMDB)](https://www.themoviedb.org/). To run them against the real service you need a free TMDB account and an API key (the v3 "API key"). Without one, everything here still runs: TMDB answers `401` and you can see how the rulesets handle it.
|
|
16
|
+
|
|
17
|
+
## Why modules
|
|
18
|
+
|
|
19
|
+
Two rulesets often want the same code. One of them wraps a service so the other doesn't have to know how it works: the app says `tmdb:getPopular()` and doesn't know about URLs, query strings, or JSON. Fix the wrapper, and every app that uses it gets the fix. A module is also **parameterized**: the same code can be used with different settings, such as different keys.
|
|
20
|
+
|
|
21
|
+
Any ruleset can be a module. A ruleset becomes a *useful* module when its `meta` block says what it `provides`:
|
|
22
|
+
|
|
23
|
+
```krl
|
|
24
|
+
meta {
|
|
25
|
+
configure using api_key = ""
|
|
26
|
+
provides getPopular, rateMovie
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- **`provides`** lists the global definitions (functions, actions, and values) that rulesets using this one may call. Rules are never shared.
|
|
31
|
+
- **`configure using`** declares the module's settings, with defaults. A user of the module overrides them with `with`.
|
|
32
|
+
|
|
33
|
+
And a ruleset uses one like this:
|
|
34
|
+
|
|
35
|
+
```krl
|
|
36
|
+
meta {
|
|
37
|
+
use module io.picolabs.tmdb alias tmdb
|
|
38
|
+
with api_key = "…"
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`io.picolabs.tmdb` is the **rid** of the module, which is what the engine knows it by, not the `name` in its `meta`. The `alias` gives it a short name to use in code: `tmdb:getPopular()`. You need one because a rid contains periods, and `io.picolabs.tmdb:getPopular()` isn't valid KRL. Don't pick the name of an engine library (`http`, `time`, `wrangler`, `event`, `meta`, `ent`, and so on) as an alias: inside your ruleset the name would mean the module and the library would be out of reach. The full reference, with the reserved names, is [User Defined Modules](/krl/user-defined-modules).
|
|
43
|
+
|
|
44
|
+
The module must be installed on the pico before the ruleset that uses it, and while a module is in use, it can't be uninstalled.
|
|
45
|
+
|
|
46
|
+
`shares` and `provides` are different: `shares` lists the functions that can be called from outside the pico as queries; `provides` lists what other rulesets on the pico can use. A ruleset can do both.
|
|
47
|
+
|
|
48
|
+
## A wrapper for TMDB
|
|
49
|
+
|
|
50
|
+
Save this as `io.picolabs.tmdb.krl`:
|
|
51
|
+
|
|
52
|
+
```krl
|
|
53
|
+
ruleset io.picolabs.tmdb {
|
|
54
|
+
meta {
|
|
55
|
+
name "TMDB"
|
|
56
|
+
description <<
|
|
57
|
+
A thin wrapper around The Movie Database (TMDB) API, for the Modules lesson.
|
|
58
|
+
>>
|
|
59
|
+
author "Phil Windley"
|
|
60
|
+
configure using
|
|
61
|
+
api_key = ""
|
|
62
|
+
provides getPopular, rateMovie
|
|
63
|
+
}
|
|
64
|
+
global {
|
|
65
|
+
base_url = "https://api.themoviedb.org/3"
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Today's popular movies from TMDB.
|
|
69
|
+
* @param page Number "which page of results"
|
|
70
|
+
* @returns Array
|
|
71
|
+
*/
|
|
72
|
+
getPopular = function(page = 1) {
|
|
73
|
+
response = http:get(base_url + "/movie/popular",
|
|
74
|
+
qs = {"api_key": api_key, "page": page})
|
|
75
|
+
response{"status_code"} == 200 => response{"content"}.decode(){"results"} | []
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
rateMovie = defaction(movie_id, rating, guest_session_id) {
|
|
79
|
+
http:post(base_url + "/movie/" + movie_id + "/rating",
|
|
80
|
+
qs = {"api_key": api_key, "guest_session_id": guest_session_id},
|
|
81
|
+
json = {"value": rating}) setting(response)
|
|
82
|
+
return response{"status_code"}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Read it in pieces.
|
|
89
|
+
|
|
90
|
+
**Configuration.** `api_key` is declared with a default of `""`. Inside the module it's an ordinary variable. It's not shared by `provides`, so no one can read it back through the module.
|
|
91
|
+
|
|
92
|
+
**`getPopular` is a function that calls the web.** `http:get(url, qs = {...})` makes the request when the expression is evaluated, and returns a map: `status_code`, `content` (the body, as a string), `content_type`, `headers`, and more. Because the body is a string, `decode()` turns the JSON into KRL data. If the call fails, the function returns an empty array. A function can call `http:get` and so can be shared as a query; it can't change state. The conditional expression `a => b | c` picks `b` when `a` is true. Read more in the [http library](/krl/libraries/http).
|
|
93
|
+
|
|
94
|
+
**`rateMovie` is an action.** Anything that changes the world, like posting a rating, is an action, and a rule runs it as its one action. `defaction` wraps an action (here `http:post`) so rules can call it by name. `http:post(url, qs = …, json = …)` sends the `json` map as the JSON body, with the right content type. `setting(response)` names the response, and `return` hands back a value to whoever used the action. See [User-Defined Actions](/krl/krl-expression-language/user-defined-actions).
|
|
95
|
+
|
|
96
|
+
> **Note:** If you have only TMDB's "API Read Access Token", pass it as a header instead of a query-string key: `headers = {"Authorization": "Bearer " + api_key}` in the `http:get` and `http:post` calls.
|
|
97
|
+
|
|
98
|
+
## An app that uses it
|
|
99
|
+
|
|
100
|
+
Save this as `com.example.my_movie_app.krl`:
|
|
101
|
+
|
|
102
|
+
```krl
|
|
103
|
+
ruleset com.example.my_movie_app {
|
|
104
|
+
meta {
|
|
105
|
+
name "My Movie App"
|
|
106
|
+
description <<
|
|
107
|
+
Uses the io.picolabs.tmdb module. The API key is install configuration.
|
|
108
|
+
>>
|
|
109
|
+
use module io.picolabs.tmdb alias tmdb
|
|
110
|
+
with api_key = meta:rulesetConfig{"tmdb_api_key"}
|
|
111
|
+
shares popular, ratings
|
|
112
|
+
}
|
|
113
|
+
global {
|
|
114
|
+
/**
|
|
115
|
+
* Titles of today's popular movies.
|
|
116
|
+
* @returns Array
|
|
117
|
+
*/
|
|
118
|
+
popular = function() {
|
|
119
|
+
tmdb:getPopular().map(function(m) { m{"title"} })
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Ratings this pico has sent.
|
|
124
|
+
* @returns Map
|
|
125
|
+
*/
|
|
126
|
+
ratings = function() {
|
|
127
|
+
ent:ratings.defaultsTo({})
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Rate a movie on TMDB and remember the rating.
|
|
133
|
+
* @attr movie_id String "TMDB movie id"
|
|
134
|
+
* @attr rating Number "0.5 to 10"
|
|
135
|
+
* @attr guest_session_id String "a TMDB guest session"
|
|
136
|
+
*/
|
|
137
|
+
rule rate_movie {
|
|
138
|
+
select when movie rating_given
|
|
139
|
+
pre {
|
|
140
|
+
movie_id = event:attr("movie_id")
|
|
141
|
+
rating = event:attr("rating").as("Number")
|
|
142
|
+
session = event:attr("guest_session_id")
|
|
143
|
+
}
|
|
144
|
+
tmdb:rateMovie(movie_id, rating, session) setting(status)
|
|
145
|
+
fired {
|
|
146
|
+
ent:ratings{[movie_id, "rating"]} := rating
|
|
147
|
+
ent:ratings{[movie_id, "status"]} := status
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- `popular` calls the module function like any function, and maps each movie to its title. It's in `shares`, so it's also a query on this pico's channels.
|
|
154
|
+
- The rule `rate_movie` selects `movie:rating_given`, and its one action is the module's `tmdb:rateMovie`. The `setting(status)` clause catches what the action returned, the HTTP status code. The `fired` postlude stores the rating and the status with path assignments, `ent:ratings{[movie_id, "rating"]} := rating`, so one movie's entry is updated without touching the others.
|
|
155
|
+
- `with api_key = meta:rulesetConfig{"tmdb_api_key"}` is where the key comes from. See the next section.
|
|
156
|
+
|
|
157
|
+
## Where the secret comes from
|
|
158
|
+
|
|
159
|
+
You never want an API key in a KRL file: source gets copied, committed to repositories, and served from web servers. This lesson's rulesets don't contain one. The key arrives when the ruleset is **installed**, in the **config** that accompanies the install request:
|
|
160
|
+
|
|
161
|
+
1. Make a child pico, say `movies`.
|
|
162
|
+
2. On its **Rulesets** tab, under **Install Ruleset by URL**, install `io.picolabs.tmdb.krl` first, with **Config** left alone. (From a file, use a `file://` URL, as in the [Quickstart](/lessons/quickstart).)
|
|
163
|
+
3. Install `com.example.my_movie_app.krl` with **Config** set to:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{"tmdb_api_key": "your key here"}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
In KRL, the ruleset reads this map as `meta:rulesetConfig`. A `with` clause can use it because the engine evaluates the clause when the ruleset is loaded, before any rule runs. Other forms of the install (the `wrangler:install_ruleset_request` event, which the Rulesets tab sends) take the same `config` attribute. See [The wrangler ruleset](/wrangler/wrangler). A bootstrap ruleset can install a whole app, modules first, each with its own `config`: [Bootstrap and channels](/cookbook/bootstrap/) shows how.
|
|
170
|
+
|
|
171
|
+
<img src="/lessons/_media/32148114-modules_overview.png" alt="The Rulesets tab showing my_movie_app installed, with its Config, last flushed time, and hash" width="50%">
|
|
172
|
+
|
|
173
|
+
Install configuration keeps the secret out of the source, but not out of sight. Anyone who can use the developer UI can see the config on the **Rulesets** tab, the install event's attributes show in the **Logging** tab and the engine's log file, and `wrangler:rulesetConfig(rid)` returns it to anyone whose channel permits the query. The [Configuration and secrets](/cookbook/secrets/) demo walks through where a secret can be seen, how to get one in by event instead, and how to keep a ruleset idle until it has one.
|
|
174
|
+
|
|
175
|
+
> **Older rulesets:** you may see a `keys` ruleset that holds `key twilio { … }` in its source, and `use module io.picolabs.lesson_keys` with `keys:twilio("account_sid")`. That puts the secret in a file. Prefer install configuration.
|
|
176
|
+
|
|
177
|
+
## Try it
|
|
178
|
+
|
|
179
|
+
On the `movies` pico, open the **Testing** tab and choose `com.example.my_movie_app`.
|
|
180
|
+
|
|
181
|
+
<img src="/lessons/_media/32148114-module_in_use.png" alt="The Testing tab with com.example.my_movie_app selected, showing its queries and its movie:rating_given event" width="50%">
|
|
182
|
+
|
|
183
|
+
1. Run the `popular` query. With a valid key you get a list of titles. With a missing or wrong key, TMDB answers `401` and the module's function returns `[]`.
|
|
184
|
+
2. Send `movie:rating_given` with `movie_id` `550`, `rating` `8`, and a `guest_session_id` (you can make a guest session with TMDB's API, see its [documentation](https://developer.themoviedb.org/); any string works for seeing the flow).
|
|
185
|
+
3. Run the `ratings` query. It shows `{"550": {"rating": 8, "status": …}}` with TMDB's status code: `201` on success, `401` for a bad key.
|
|
186
|
+
4. Open the **Logging** tab. Select the `rate_movie` transaction and see the `ent:` writes and the event's attributes. To trace the HTTP status yourself, add `.klog("TMDB status")` to `response{"status_code"}` in the module's `rateMovie` and flush the module.
|
|
187
|
+
|
|
188
|
+
To change the key, uninstall `com.example.my_movie_app` and install it again with the new config.
|
|
189
|
+
|
|
190
|
+
## Exercise: a Twilio module
|
|
191
|
+
|
|
192
|
+
Twilio sends SMS messages from a web API. Build a module for it, in two steps. Twilio's endpoint is `POST https://api.twilio.com/2010-04-01/Accounts/<account_sid>/Messages.json`, with HTTP basic authentication (account sid and auth token), and form fields `From`, `To`, and `Body`.
|
|
193
|
+
|
|
194
|
+
1. **Keys as parameters.** Write `io.picolabs.twilio_v1`, which `provides` a user-defined action `send_sms(to, from, message, account_sid, auth_token)`. Give the module a rule that selects `test:new_message` and calls the action with the attributes, so you can try it from the Testing tab with a Twilio test account.
|
|
195
|
+
2. **Keys as configuration.** Write `io.picolabs.twilio_v2`: `configure using account_sid = "" auth_token = ""` and `provides send_sms`, with action `send_sms(to, from, message)`. Then write `com.example.use_twilio`, which uses the module with `with account_sid = meta:rulesetConfig{"twilio_account_sid"}` and `auth_token = meta:rulesetConfig{"twilio_auth_token"}`, and has the `test:new_message` rule. Install both, with the keys in the config.
|
|
196
|
+
|
|
197
|
+
Compare the two. In which are the secrets in the event's attributes, and in which are they in install configuration? Use the Logging tab. The [http library](/krl/libraries/http) documents `auth`, `form`, and `setting`.
|
|
198
|
+
|
|
199
|
+
Use Twilio's test credentials so no real messages are sent, and don't commit keys.
|
|
200
|
+
|
|
201
|
+
<details>
|
|
202
|
+
<summary>One solution to step 2</summary>
|
|
203
|
+
|
|
204
|
+
```krl
|
|
205
|
+
ruleset io.picolabs.twilio_v2 {
|
|
206
|
+
meta {
|
|
207
|
+
name "Twilio SMS Module"
|
|
208
|
+
description <<
|
|
209
|
+
Send an SMS with Twilio. Exercise for the Modules lesson.
|
|
210
|
+
>>
|
|
211
|
+
author "Phil Windley"
|
|
212
|
+
configure using
|
|
213
|
+
account_sid = ""
|
|
214
|
+
auth_token = ""
|
|
215
|
+
provides send_sms
|
|
216
|
+
}
|
|
217
|
+
global {
|
|
218
|
+
send_sms = defaction(to, from, message) {
|
|
219
|
+
base_url = <<https://api.twilio.com/2010-04-01/Accounts/#{account_sid}/>>
|
|
220
|
+
http:post(base_url + "Messages.json",
|
|
221
|
+
auth = {"username": account_sid, "password": auth_token},
|
|
222
|
+
form = {"From": from, "To": to, "Body": message}) setting(response)
|
|
223
|
+
return response{"status_code"}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
```krl
|
|
230
|
+
ruleset com.example.use_twilio {
|
|
231
|
+
meta {
|
|
232
|
+
name "Use Twilio"
|
|
233
|
+
use module io.picolabs.twilio_v2 alias twilio
|
|
234
|
+
with account_sid = meta:rulesetConfig{"twilio_account_sid"}
|
|
235
|
+
auth_token = meta:rulesetConfig{"twilio_auth_token"}
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* Send a text message.
|
|
239
|
+
* @attr to String "number to text"
|
|
240
|
+
* @attr from String "your Twilio number"
|
|
241
|
+
* @attr message String "text of the message"
|
|
242
|
+
*/
|
|
243
|
+
rule test_send_sms {
|
|
244
|
+
select when test new_message
|
|
245
|
+
twilio:send_sms(event:attr("to"), event:attr("from"), event:attr("message")) setting(status)
|
|
246
|
+
fired {
|
|
247
|
+
ent:last_status := status
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Twilio answers `201` when it accepts the message.
|
|
254
|
+
|
|
255
|
+
</details>
|
|
256
|
+
|
|
257
|
+
## What you learned
|
|
258
|
+
|
|
259
|
+
- A module is a ruleset with `provides`. `configure using` declares settings with defaults, and `use module … alias … with …` uses it.
|
|
260
|
+
- Modules can provide functions, actions, and plain values. Rules are never shared.
|
|
261
|
+
- `http:get` and the other `http` calls are functions and actions. A module can wrap them to give a service a small, clean API.
|
|
262
|
+
- Secrets go in install configuration (`meta:rulesetConfig`), not in source, and are still visible to people who can see the developer UI and logs.
|
|
263
|
+
|
|
264
|
+
## Next
|
|
265
|
+
|
|
266
|
+
The lessons so far build up one pico. Next come picos that show themselves to people (**Pico views**), and systems of many picos: [Pico-Based Systems](/lessons/pico-based-systems) and [Relationships](/lessons/relationships). For a pico that actually calls other picos, see the [Two picos talking](/cookbook/two_picos/) demo, and the [Querying JSON](/cookbook/json_query/) demo for working with the kind of nested data web APIs return.
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
<small>Ported from the [Pico Labs wiki](https://picolabs.atlassian.net/wiki/spaces/docs/pages/32148114/Modules+and+External+APIs+Lesson) (last edited there 2022-01-18), and updated for this engine.</small>
|