@laburen/delta-cli 0.2.0-canary.11 → 0.2.0-canary.12

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.
@@ -216,6 +216,46 @@ laburen mcp connections versions compare <connection_id> --from <version_id> --t
216
216
 
217
217
  Headers of an MCP connection are an object, name to value: `--headers '{"Authorization":"Bearer x"}'` or `@headers.json` (not the list of `{ key, value }` of the http tool). `mcp connections versions create` without `--headers` keeps the headers of the latest version; `--headers '{}'` removes them. If the server cannot be reached, listing its tools fails with `mcp_server_unreachable` (400); check the URL and headers. Saving an `--mcp-connections` item with `tools` does not fail: it saves and warns with `mcp_tools_unverified`.
218
218
 
219
+ ## Widgets
220
+
221
+ A widget puts an agent on a website as a chat. It belongs to an agent (an agent can have several, for example one per site) and the visitor talks to the agent's **active version**.
222
+
223
+ ```sh
224
+ laburen agents widgets create <agent_id> --name "Acme site" --allowed-domains '["acme.com","*.acme.com"]'
225
+ laburen agents widgets list <agent_id> # table: ID, NAME, ENABLED, DOMAINS, ANONYMOUS, UPDATED; newest first
226
+ laburen agents widgets get <agent_id> <widget_id>
227
+ laburen agents widgets update <agent_id> <widget_id> --no-enabled # turn it off; --enabled turns it on
228
+ laburen agents widgets rotate <agent_id> <widget_id> # new identity_secret; the old one stops working
229
+ laburen agents widgets delete <agent_id> <widget_id> # needs admin; the snippet stops working, conversations stay
230
+ ```
231
+
232
+ Every response carries the code to install it, with the public token and the URL already set: `web_widget_script` (the `<script>` of the chat bubble: paste it in the site's `<head>` or before `</body>`), `embed_iframe` (an `<iframe>` that shows the chat inside a page, 400×600 by default: change `width`/`height`) and `standalone_url` (a chat page of its own; open it to try the widget). Without `--json` the snippet is printed with its line breaks escaped (`\n`), so do not copy it from there: read it with `--json`, for example `laburen agents widgets get <agent_id> <widget_id> --json | jq -r .web_widget_script`. `token` is public (it goes in the snippet).
233
+
234
+ `create` and `rotate` also return `identity_secret`, **only in that response**: without `--json`, stderr says "Save the `identity_secret` now: it will not be shown again." It is what your site's backend uses to sign the visitor's identity token (below); it never goes in the browser. `create` and `rotate` are sent once, never retried (they are not idempotent); `rotate` does not ask for confirmation.
235
+
236
+ Flags of `create` and `update` (`update` changes only what you pass; `--data` takes the whole body):
237
+
238
+ | Flag | Default | What it does |
239
+ |---|---|---|
240
+ | `--name` | (required in `create`) | Name of the widget, 1 to 100 characters |
241
+ | `--enabled` / `--no-enabled` | on | `--no-enabled` turns it off: the chat answers `widget_not_found`, as if it did not exist |
242
+ | `--allowed-domains` | `[]` | JSON list of sites that can embed it (up to 50); empty = any site. Full host (`www.acme.com` does not include `acme.com`), wildcard only at the start (`*.acme.com` covers subdomains, not `acme.com`), optional port (1 to 65535). A wildcard cannot cover a whole public suffix (`*.com`, `*.com.ar`, `*.co.uk`, `*.github.io`: the list is the Public Suffix List) or an IP. Stored in lowercase, without scheme, path or repeats. `localhost` and its subdomains are rejected: use `127.0.0.1`. An invalid one fails with `invalid_request` on `allowed_domains[i]` |
243
+ | `--allows-anonymous` / `--no-allows-anonymous` | on | `--no-allows-anonymous`: a visitor your site did not identify cannot chat (`identity_required`) |
244
+ | `--max-attachments-per-message` | `5` | Files per visitor message, 1 to 10 |
245
+ | `--visitor-rate-limit` | `null` | JSON `{"max_messages":20,"interval_seconds":60}` (up to 100000 messages and 30 days): cap per visitor; `null` removes it |
246
+ | `--limit-reached-message` | `null` | Text the visitor sees at the cap (1 to 500 characters); `--limit-reached-message null` goes back to the default text |
247
+ | `--appearance` | `{}` | JSON with `widget_color` (`#rrggbb`), `welcome_title` (up to 100), `welcome_tagline` (up to 200), `position` (`left`/`right`), `theme` (`light`/`dark`/`auto`), `launcher_icon_url` (https). `update --appearance` replaces the whole object: send every field you want to keep |
248
+
249
+ `allowed_domains` limits who can **embed** the chat (a `Content-Security-Policy: frame-ancestors` header), not who calls the API. Each domain is allowed over `https://`, except `127.0.0.1` and `0.0.0.0`, which use `http://`: a page served over `http` on a public domain (a staging without a certificate) cannot embed the chat.
250
+
251
+ When changes show: the chat reads the widget on every message, so `--no-enabled` or `delete` stops it right away (`widget_not_found`). The widget **page** (`standalone_url` and the iframe's page) keeps the domains for up to 60 seconds, so a new `--allowed-domains`, turning the widget off or deleting it can take up to a minute to show there.
252
+
253
+ The widget answers with the agent's active version. If the agent has none, the widget is created anyway, but every visitor message fails with `invalid_agent_config` ("has no active version") until you activate one (`laburen agents versions activate`).
254
+
255
+ **Identify visitors (optional).** Without it every browser is an anonymous visitor. If the site has its own login, its backend signs an identity token with the `identity_secret` for the logged-in user (for example from an endpoint the page calls with `fetch`), and the page passes it to the widget with `window.$laburen.identify({ token })` (it can run right after the snippet: the snippet queues the call until the widget script loads); the visitor is then linked to a contact of the organization (found or created by `user_id`). The token is a JWT HS256: the key is the UTF-8 bytes of `identity_secret`; `user_id` (non-empty string) and `exp` are required; `email`, `name`, `phone` and `custom_attributes` (an object of strings) are optional. In a Worker or Node backend, `signIdentityToken({ secret, userId, expiresIn? })` from `@laburen/delta-sdk/platform` builds it (see `docs/platform/guide.md` of `@laburen/delta-sdk`, section 14). A bad, expired or incomplete token makes the chat fail with `invalid_identity_token`. The CLI has no command to sign one: signing happens in the site's backend. Other snippet calls: `$laburen.reset()` (on logout), `$laburen.toggle(open?)` and `$laburen.setAttributes(text)` (up to 1000 characters of unverified context sent with the visitor's messages).
256
+
257
+ The CLI and the API do not read or answer the widget's conversations (that is in the dashboard), and the API the chat itself uses in the browser is internal.
258
+
219
259
  ## Tokens
220
260
 
221
261
  ```sh
@@ -226,7 +266,7 @@ laburen tokens update <token_id> --description null # clears the description
226
266
  laburen tokens revoke <token_id>
227
267
  ```
228
268
 
229
- `tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again.
269
+ `tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again (`agents widgets create` and `rotate` do the same for `identity_secret`).
230
270
 
231
271
  ## Account and organization
232
272
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@laburen/delta-cli",
3
- "version": "0.2.0-canary.11",
3
+ "version": "0.2.0-canary.12",
4
4
  "description": "Laburen CLI to manage agents from the terminal",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -27,7 +27,7 @@
27
27
  },
28
28
  "dependencies": {
29
29
  "@clack/prompts": "1.8.1",
30
- "@laburen/delta-sdk": "1.5.0-canary.11",
30
+ "@laburen/delta-sdk": "1.5.0-canary.12",
31
31
  "@vercel/detect-agent": "1.2.7",
32
32
  "commander": "14.0.3",
33
33
  "picocolors": "1.1.1"
@@ -1,4 +0,0 @@
1
- import type { Command } from "commander";
2
- import type { CliContext } from "../context.js";
3
- /** Después de `tokens create` (sin --json) avisa en stderr que el `value` no se vuelve a mostrar. */
4
- export declare function registerTokenNotice(program: Command, _ctx: CliContext): void;
@@ -1,13 +0,0 @@
1
- import { extendOperation } from "../operations.js";
2
- import { notice } from "../output.js";
3
- /** Después de `tokens create` (sin --json) avisa en stderr que el `value` no se vuelve a mostrar. */
4
- export function registerTokenNotice(program, _ctx) {
5
- extendOperation(program, ["tokens", "create"], {
6
- afterResult: (ctx, mode) => {
7
- if (mode.json)
8
- return;
9
- notice(ctx, mode, "Save the token `value` now: it will not be shown again.");
10
- },
11
- });
12
- }
13
- //# sourceMappingURL=token-notice.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"token-notice.js","sourceRoot":"","sources":["../../src/commands/token-notice.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,OAAgB,EAAE,IAAgB;IACrE,eAAe,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;QAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YAC1B,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO;YACtB,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,yDAAyD,CAAC,CAAC;QAC9E,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}