@thinger-io/cli-core 0.2.1 → 0.4.0

package/docs/thinger-product-code.md

@@ -0,0 +1,159 @@
+# Product code
+
+JavaScript that a product's profile calls to compute, transform or route data for its devices:
+resource values (including simulated devices), payload transforms, the device a product call is
+for. Platform concepts: the document `concepts`. It describes Thinger 7.5; what needs a later
+version says "since Thinger X" (a server's version: `GET /v1/server/version`).
+
+## Where it lives
+
+`PUT /v1/users/{user}/products/{product}/profile/code` with
+`{ "code": "<JavaScript>", "storage": "" }`, or `{ "storage": "<storage id>" }` to load
+`<storage>/index.js` from a file storage (with its `node_modules`). Since Thinger 7.5, add
+`"path": "<folder>"` to
+load `<storage>/<folder>/index.js` (and that folder's `node_modules`) instead: one storage can then
+hold a whole application, e.g. the dashboard in `app/` and each product's code in
+`code/<product>/`. Read it back with `GET` on the same path.
+
+The code takes effect at once: every change to the profile (code, any category or entry, or
+enabling the product) reloads it. Editing `index.js` in the storage does **not**: `PUT
+profile/code` again afterwards.
+
+## Runtime
+
+- Node.js embedded in the server, one instance per product.
+- Functions are found by name as globals: declare them with `function name(…) {}` (or
+  `var name = …`, `globalThis.name = …`). Top-level `const` / `let` / `class` names and
+  `module.exports` are not visible to the profile.
+- **Synchronous only.** There is no event loop: promises, `async` functions, timers, `fetch` and
+  network modules never complete (an `async` function returns `{}`). Synchronous built-ins
+  (`Math`, `Date`, `JSON`, `require('crypto')`…) work.
+- `Date` runs in **UTC** (`getHours()` is the UTC hour). For local time use `Intl`, which knows
+  time zones and daylight saving:
+  `new Intl.DateTimeFormat('en-GB', { timeZone: 'Europe/Madrid', hour: 'numeric', hourCycle: 'h23' }).formatToParts(new Date())`
+  gives the hour in Madrid.
+- Return JSON values: objects, arrays, numbers, strings, booleans. A `Date` or other class
+  instance becomes `{}`: return `Date.now()` (milliseconds) instead.
+- A function that throws returns `null`. There is no time limit: keep functions short.
+- No access to the filesystem except reading user storages, no processes, no environment.
+- The code cannot call Thinger directly (no API object). It talks to the platform only through
+  the profile: placeholders bring data in, targets send results out (below).
+
+`console.log` / `info` / `warn` / `error` are sent as `product_script_log` events while someone
+listens: the product's console in the web console, or the websocket
+`/v1/users/{user}/products/{product}/profile/console`.
+
+## Where functions are called
+
+A function receives one argument (two for `device_id_resolver`) and returns the new value.
+
+| Hook | Config | Receives | Returns |
+|---|---|---|---|
+| API resource, request target `function` | `api.<r>.request.data` `{ "target": "function", "function": "<name>" }` | the request payload, shaped by `payload_type` (below) | the resource result (with response `source: "request_response"`) |
+| API resource, response source `function` | `api.<r>.response.data` `{ "source": "function", "function": "<name>" }` | `{ user, device, resource, product }` | the resource result |
+| Payload transform | `payload_function: "<name>"` in a request, response, bucket, property or flow `data` | the payload after `payload_type` | the new payload (an empty result skips a bucket / property write or a flow) |
+| Device of a product call | `device_id_resolver: "<name>"` at the root of an API resource or flow | `(payload, placeholders)` | a device id (string) |
+| Placeholder converter | `{{<placeholder>:<name>}}` inside any template | the placeholder value | the replacement |
+
+`payload_type` decides what a function or target gets:
+
+- `template_payload` (default): the `payload` template with placeholders filled, parsed as JSON.
+  Without a `payload` it is empty, so a bucket or property entry writes nothing.
+- `source_payload`: the incoming value as is (in a response, the target's result); the same as
+  `"payload": "{{payload}}"`.
+- `source_event`: everything: `{ user, device, resource, product, payload }`.
+- `none`: nothing.
+
+Placeholders available in templates: `{{device}}`, `{{user}}`, `{{product}}`, `{{resource}}`,
+`{{payload}}` / `{{payload.<field>}}`, `{{property.<id>}}` (a device property's value, inherited
+like any device property: device → asset type → asset group → product, the first that defines it,
+whole value),
+`{{meta.<field>}}` (a field of the device document), `{{api.<resource>}}` (another API resource),
+and `{{x=default}}` for defaults.
+
+## Resources computed by code
+
+An API resource whose request target is a function makes a value out of nothing: the basis of
+simulated devices.
+
+```json
+"api": {
+  "climate": {
+    "enabled": true,
+    "request":  { "data": { "target": "function", "function": "simulateClimate", "payload_type": "source_event" } },
+    "response": { "data": { "source": "request_response", "payload_type": "source_payload" } }
+  }
+}
+```
+
+```js
+// ctx = { user, device, resource, product, payload }
+function simulateClimate(ctx) {
+  var day = Math.sin(((Date.now() / 3600000) % 24 - 6) / 24 * 2 * Math.PI);  // day/night cycle
+  return {
+    temperature: Math.round((22 + 6 * day + (Math.random() - 0.5)) * 10) / 10,
+    humidity: Math.round((60 - 15 * day + (Math.random() - 0.5) * 4) * 10) / 10
+  };
+}
+```
+
+`GET /v3/users/{user}/devices/{device}/resources/climate` then returns the object for any device
+of the product, including `Virtual` devices, which have no hardware and get every resource from
+their product. A profile bucket or property with `source: "resource"` and an interval calls the
+resource for every connected device of the product on that schedule (see
+the document `concepts`, Buckets).
+
+Without `"response": { "source": "request_response" }` the function runs but the resource
+returns nothing; without `payload_type: "source_payload"` (or `"payload": "{{payload}}"`) in the
+response, it returns `null`.
+
+## State between calls
+
+- **In memory**: globals survive between calls of the same product, so
+  `globalThis.state = globalThis.state || {}; state[ctx.device] = …` keeps per-device state.
+  It is lost when the profile reloads (any profile change) and when the server restarts. Code
+  that keeps "what happened since the last call" in memory starts over after each reload: it can
+  repeat or skip one step (e.g. emit an event twice). Keep that cursor in a property if it matters.
+- **Persistent**: keep the state in a device property. Read it with `{{property.<id>}}` in the
+  request payload template and write the function's result back with request target
+  `property`:
+
+```json
+"api": {
+  "tank": {
+    "enabled": true,
+    "request": { "data": {
+      "target": "property", "property": "tank",
+      "payload": "{\"prev\": {{property.tank}}, \"in\": {{payload}} }",
+      "payload_function": "stepTank" } },
+    "response": { "data": { "source": "request_response", "payload_type": "source_payload" } }
+  }
+}
+```
+
+```js
+// p = { prev: <last tank property or {}>, in: <input sent to the resource or null> }
+function stepTank(p) {
+  var s = typeof p.prev.level === 'number' ? p.prev : { level: 50, inflow: 1, outflow: 0.8, ts: Date.now() };
+  var now = Date.now(), minutes = (now - s.ts) / 60000;
+  var inflow = p.in && p.in.inflow !== undefined ? p.in.inflow : s.inflow;
+  var outflow = p.in && p.in.outflow !== undefined ? p.in.outflow : s.outflow;
+  var level = Math.min(100, Math.max(0, s.level + (inflow - outflow) * minutes));
+  return { level: level, inflow: inflow, outflow: outflow, ts: now };   // saved as property "tank"
+}
+```
+
+Each call advances the level from the stored state; calling the resource with
+`{ "inflow": 3 }` changes the flow. Do not combine it with a `{{payload=property.tank}}`
+default: defaults that read a property re-run the resource when that property changes, and this
+resource writes it.
+
+## Limits and pitfalls
+
+- No asynchronous work and no outgoing requests from code: to call an external service use an
+  endpoint (request target `endpoint_call`).
+- One argument per function (two for `device_id_resolver`); use `payload_type: "source_event"`
+  to get the device id and the rest of the context.
+- Keep per-call work small: functions run synchronously in the server, without a timeout.
+- A product must be `enabled`, and every API / bucket / property / flow entry needs
+  `"enabled": true`, or it is skipped.

package/docs/thinger-server-admin.md

@@ -0,0 +1,165 @@
+# Thinger server administration
+
+For agents acting as a server **admin**: host settings, domains and brands, user accounts,
+OAuth clients, identity providers and proxies. Every route here needs an admin session or
+token. Read the OpenAPI document for each body; this guide covers what the schemas cannot say:
+order of steps, side effects and risks. It describes Thinger 7.5; what needs a later version says
+"since Thinger X" (a server's version: `GET /v1/server/version`).
+
+Before changing anything, read the current value and tell the user what will change. Several
+actions here can take the server or a domain offline.
+
+## Hosts and server settings
+
+A host is one server process; its id is the machine's hostname (`GET /v1/hosts`).
+
+- `GET /v1/hosts/{host}/settings` returns the editable settings (database, plugins and similar
+  internals are hidden).
+- `PUT /v1/hosts/{host}/settings` is a **merge patch** (RFC 7386) over the host's custom
+  settings: send only the sections you change; `null` removes a custom value, so the provider
+  default applies again. Values are validated against the schema.
+- **Settings apply only after a restart**: `POST /v1/hosts/{host}/restart`. The process exits
+  and the container restarts it: every connection drops (devices, consoles, websockets) for a
+  few seconds or more. Ask the user before restarting, and prefer a quiet moment.
+- Ports are **strings** (`"1883"`), as the server reads them.
+- Logs: `GET /v1/hosts/{host}/logs?lines=200` returns the last lines as text; the same route
+  over a websocket streams them live.
+
+Main sections: `http_server`, `thing_server` (IOTMP), `mqtt_server`, `proxies` (dynamic port
+range), `email` (server mail: `smtp` or `ses`), `buckets.storage` / `buckets.export`, `ssl`,
+`accounts` (sign-up, login methods, password rules, `limits.<collection>.max_count` with -1 =
+unlimited and 0 = disabled), `deployment` (`contact_email`: whoever registers with it becomes
+admin), `scripting_engine`.
+
+Some features are off by default (`max_count` 0): projects, project members, domains, brands and
+identity providers. On Thinger cloud instances the subscription plan sets these limits; on a
+self-hosted server raise `accounts.limits.<collection>.max_count` (`projects`,
+`projects_members`, `domains`, `brands`, `identity_providers`) and restart. The domains and
+brands limits are not shown by `GET settings`.
+
+On cloud instances the plan owns `accounts.limits.{accounts,brands,domains,members}`, `database`,
+`plugins`, `rate_limiter` and `http_server.hosts`: since Thinger 7.5, writing them returns 403.
+To raise them, the customer changes the plan.
+
+## Custom domain with its own brand
+
+A **brand** is the look and login behaviour of the console for one hostname. Its id **is** the
+hostname (`console.example.com`); there is no other link between a domain and a brand. The
+**domain** resource only manages the TLS certificate of that hostname.
+
+1. **DNS (done by the user).** Make the hostname resolve to this server: an `A` / `AAAA` record
+   with the server's public IP, or a `CNAME` to the server's existing hostname (the one the user
+   already uses to reach the console). There is no special verification value or TXT record.
+   Port **80** must be reachable from the internet. Tell the user exactly which record to
+   create, then wait until it resolves (it can take minutes; up to the record's TTL).
+2. **Create the domain**: `POST /v1/domains` `{ "domain": "console.example.com" }`. No side
+   effects yet.
+3. **Verify**: `POST /v1/domains/{domain}/verify`. The server asks Let's Encrypt for a
+   certificate (HTTP-01: Let's Encrypt fetches `http://<domain>/.well-known/acme-challenge/...`
+   from this server). On failure the error carries Let's Encrypt's reason (DNS not found,
+   connection refused, rate limit…): report it to the user as is. A certificate with more than
+   30 days left counts as verified. Wildcards (`*.example.com`) use DNS-01 and only work on
+   instances hosted by Thinger.
+4. **Create the brand**: `POST /v1/brands` `{ "brand": "console.example.com", "name": ..., "config": {...} }`.
+5. **Configure it**: texts, logos, colors, login page, PWA, account options (`config`), and its
+   email (`email`). See below.
+6. Open `https://console.example.com` to check.
+
+Certificates renew automatically (daily check, 30 days before expiry). If the DNS record is
+later changed or removed, renewal fails silently and HTTPS breaks when the current certificate
+expires. Deleting a domain removes its certificate at once.
+
+Local or development builds may use Let's Encrypt **staging**, whose certificates browsers do not
+trust: verification "works" but the site shows a warning.
+
+### Brand configuration
+
+- `PUT /v1/brands/{brand}` **replaces** `config` and `email` as a whole, and deletes the logo
+  files missing from the new `config`. Use it only with the full object.
+- `PATCH /v1/brands/{brand}` **merges** into the stored ones (`null` removes a key). Prefer it:
+  `{ "config": { "title": "Acme IoT" } }` changes only the title.
+- Logos and icons (`favicon`, `share_image`, `dark_logo` for login and exports, `bright_logo`
+  for the menu, `icon` for the folded menu, `pwa.icons[].src`) are sent as **data URLs**
+  (`data:image/png;base64,...` or webp). The server stores the file and keeps a
+  `/brand/images/...` URL. Sending that URL back keeps the image; `null` or `""` deletes it.
+- `config.accounts` overrides the server's account settings for this hostname: public sign-up
+  (and its role), password / passkey login, 2FA, `cross_sign_in` (false: only users registered
+  on this hostname can log in), reCAPTCHA (`no_robot`), federated login and its identity
+  providers.
+- The brand is readable without login (login pages need it); secrets in it are only returned to
+  admins.
+
+### Brand email
+
+`email.custom: true` with `email.settings` makes this brand send its emails (account
+verification, password reset, account creation, device disabled) through its own server:
+`type: "smtp"` with `smtp.host`, `smtp.port` (string), `username`, `password`, `secure` (true
+for implicit TLS, e.g. 465; otherwise STARTTLS), or `type: "ses"` with AWS keys and region.
+`settings.from` / `from_name` are the sender. `email.templates.<name>` can override `subject`
+and `body` (HTML). Start from the defaults (`GET /v1/brands/{brand}/email` returns them) and keep
+their links:
+
+| Template | Link in the body |
+|---|---|
+| `email_verification` | `{{host_url}}/verify_email?code={{code}}` |
+| `forgot_password` | `{{host_url}}/password?code={{code}}` |
+| `create_password` | `{{host_url}}/create_password?code={{code}}` |
+| `device_disabled` | (no link; `{{device}}` is the device) |
+
+Placeholders filled when sending: `{{code}}`, `{{user}}`, `{{email}}`, `{{host}}`, `{{admin}}`
+(server contact email), `{{host_url}}`. `{{name}}`, `{{url}}`, `{{logo}}` and `{{description}}`
+only exist in the built-in defaults: in a custom template write the brand name and the logo URL
+(`https://<brand>/brand/images/dark_logo.png`) directly. Email clients do not load `data:` images,
+so use that public URL. The `enabled` flag of a template is not enforced yet.
+
+`POST /v1/brands/{brand}/email/test` `{ "template": "email_verification" }` sends that template to
+the **calling admin's** email address with the **saved** settings: save first, then test.
+
+## User accounts
+
+`POST /v1/users` creates an account; `role` is `user`, `member` (only inside projects, needs a
+default project), `domain_admin` (admin of the hostnames in its `host` list) or `admin`. Only
+admins create admins. An empty password sends the "create password" email instead. Per-user
+`limits` override the server limits. Deleting a user deletes **all** its resources (devices,
+buckets, plugins, files): confirm explicitly.
+
+## OAuth clients
+
+Applications that log users in with this server (authorization code or device flow).
+`redirect_uri` is a **newline-separated** list of exact URLs. The `secret` is stored and returned
+in plain text to admins: handle it as a credential. `enabled: false` blocks the client.
+
+## Identity providers (log in with Google, Microsoft…)
+
+OIDC providers users can log in with.
+
+1. Allow them: `accounts.limits.identity_providers.max_count` in the host settings (0 by
+   default), then restart.
+2. Register this server in the provider: callback URL `https://<brand or console host>/oauth/callback`.
+3. Create the provider with its `domain` (issuer), `client_id`, `client_secret`, provisioning
+   (`auto_provision` creates accounts, `match_only` only links existing ones; `allowed_domains`
+   limits email domains) and `email_trust_mode`.
+4. Test it: `POST /v1/identity_providers/{id}/test` checks discovery and keys.
+5. Turn on `federated_login` (host `accounts` or the brand's `config.accounts`) and optionally
+   restrict `identity_providers` to some ids.
+
+Auto-provisioning creates accounts even when public sign-up is off.
+
+## Proxies
+
+Expose a TCP / UDP service, a plugin, or a device service through this server.
+
+- Created and updated proxies start or replace a **live listener** at once; deleting one closes
+  the port. A wrong port can collide with other services.
+- `source.routing: "subdomain"` serves `https://<proxy id>.<server hostname>` and needs a
+  wildcard certificate for that hostname.
+- Send the full `config` on update: a partial one works until the next restart and then breaks.
+
+## Safety checklist
+
+- Read before write; describe the change; keep the previous value to undo it.
+- Never restart, delete a domain, delete a user or change login settings without the user's
+  explicit confirmation.
+- Changing `accounts` login options (password, 2FA, cross sign-in, sign-up) can lock users out:
+  make sure an admin can still log in.
+- Do not echo secrets (SMTP passwords, client secrets, AWS keys) back to the user unless asked.

package/lib/cli.js

@@ -9,27 +9,32 @@ import { registerProfileCommands } from './commands/profile.js';
 import { registerDeviceCommands } from './commands/device.js';
 import { registerProductCommands } from './commands/product.js';
 import { registerBucketCommands } from './commands/bucket.js';
+import { registerDashboardCommands } from './commands/dashboard.js';
 
 /**
  * Build and run a CLI on top of the core: global options, the generic
- * commands (login, logout, profile, device, product, bucket) and `mcp`.
+ * commands (login, logout, profile, device, product, bucket, dashboard) and `mcp`.
  * The identity must be defined before calling it.
  *
  * @param {{
  *   version: string,
  *   argv?: string[],
- *   register?: (program: Command, groups: { device: Command, product: Command, bucket: Command }) => void,
+ *   register?: (program: Command, groups: { device: Command, product: Command, bucket: Command, dashboard: Command }) => void,
  *   onNoCommand?: (program: Command) => Promise<void> | void,
  *   mcpTools?: Array<object>,
  *   mcpInstructions?: string,
  *   resourceHooks?: Record<string, import('./mcp/resource-hooks.js').ResourceHooks>,
+ *   resourceTypes?: Record<string, import('./mcp/tools-resource.js').LocalType>,
+ *   resourceActions?: Record<string, Record<string, import('./mcp/tools-resource.js').LocalAction>>,
  *   docs?: Parameters<typeof import('./docs.js').defineCliDocs>[0],
  * }} opts
  *   `register` adds the CLI's own commands, at the top level or inside the
  *   generic groups. `onNoCommand` runs when the CLI is called without
  *   arguments (default: print the help). `mcpTools` are the CLI's own MCP
  *   tools (see buildTools), and `resourceHooks` its hooks on the
- *   catalog types the generic `resource_*` tools serve. `docs` are guides
+ *   catalog types the generic `resource_*` tools serve; `resourceTypes` and
+ *   `resourceActions` are types and actions it adds to that catalog (its
+ *   platform's own things, served by the same tools). `docs` are guides
  *   the CLI ships, served by `doc_read` and as MCP resources next to the
  *   server's documentation.
  */
@@ -41,6 +46,8 @@ export async function runCli({
     mcpTools = [],
     mcpInstructions,
     resourceHooks,
+    resourceTypes,
+    resourceActions,
     docs,
 }) {
     const id = identity();
@@ -75,6 +82,7 @@ export async function runCli({
         device: registerDeviceCommands(program),
         product: registerProductCommands(program),
         bucket: registerBucketCommands(program),
+        dashboard: registerDashboardCommands(program),
     };
     registerAuthCommands(program);
     registerProfileCommands(program);
@@ -91,6 +99,8 @@ export async function runCli({
                     tools: mcpTools,
                     instructions: mcpInstructions,
                     resourceHooks,
+                    resourceTypes,
+                    resourceActions,
                     docs,
                 });
             } catch (error) {

package/lib/commands/auth.js

@@ -10,6 +10,7 @@ import {
     setActiveProfile,
 } from '../config.js';
 import { hint, info, warning } from '../format.js';
+import { env, identity } from '../identity.js';
 import { classifyError, createSpinner, printErr } from '../output.js';
 
 /**
@@ -46,6 +47,13 @@ export function registerAuthCommands(program) {
                     clientId: opts.clientId,
                 });
                 console.log(info(`Signed in (profile ${getActiveProfile()}).`));
+                if (env('TOKEN')) {
+                    console.log(
+                        warning(
+                            `${identity().envPrefix}_TOKEN is set: commands use it instead of this profile until you unset it.`,
+                        ),
+                    );
+                }
             } catch (error) {
                 const { message, code } = classifyError(error);
                 printErr(message, { code });
@@ -65,7 +73,18 @@ export function registerAuthCommands(program) {
                 console.log(warning('No configuration found. Already logged out.'));
                 return;
             }
-            const names = opts.all ? listProfiles() : [getActiveProfile()];
+            const active = getActiveProfile();
+            if (!opts.all && !active && env('TOKEN')) {
+                // <PREFIX>_TOKEN stands for the profile: there is nothing saved to forget.
+                const prefix = identity().envPrefix;
+                console.log(
+                    warning(
+                        `${prefix}_TOKEN is set and stands for the profile: unset it, or pass --profile to log out of a saved one.`,
+                    ),
+                );
+                return;
+            }
+            const names = opts.all ? listProfiles() : [active];
             for (const name of names) {
                 const spinner = createSpinner(`Logging out of ${name}...`).start();
                 if (!opts.keepToken) {