@thinremote/thinr-cli 1.1.0 → 1.2.0

package/lib/profile.js

@@ -0,0 +1,665 @@
+// @ts-check
+import api from './api.js';
+import { apiError, inputError } from './errors.js';
+import { requireConfig } from './config.js';
+
+/**
+ * Helpers for product *profile* configuration.
+ *
+ * Concept primer
+ * ──────────────
+ * A product `profile` is the server-side wiring of a product. It bundles
+ * the four declarative subsystems the platform consumes when a device of
+ * that product emits or receives data:
+ *
+ *   - `profile.api.<name>`        — REST API resources callable on every
+ *                                    device of the product (or invoked by
+ *                                    a script). Pick a `target` and the
+ *                                    platform proxies the request there.
+ *   - `profile.buckets.<name>`    — auto-managed time-series buckets fed
+ *                                    from a declared source (`resource`,
+ *                                    `resource_stream`, `product_stream`,
+ *                                    `topic`, `event`).
+ *   - `profile.properties.<name>` — auto-managed device properties fed
+ *                                    from the same family of sources, with
+ *                                    optional JSON-merge semantics via
+ *                                    `data.patch`.
+ *   - `profile.code`              — script-storage link (handled
+ *                                    elsewhere; not exposed here).
+ *
+ * REST endpoints these helpers wrap:
+ *   - GET    /v1/users/{user}/products/{p}/profile/api
+ *   - PUT    /v1/users/{user}/products/{p}/profile/api/{name}
+ *   - GET    /v1/users/{user}/products/{p}/profile/api/{name}
+ *   - DELETE /v1/users/{user}/products/{p}/profile/api/{name}
+ *   - …same shape for /buckets and /properties.
+ *
+ * IMPORTANT: do NOT confuse `profile/properties/<name>` with
+ * `/products/{p}/properties/{name}`. The former is a *handler* that fans
+ * incoming source data into device properties; the latter (handled by
+ * `getProductProperty`/`setProductProperty` in `product.js`) is a JSON
+ * value attached to the product itself. Same word, completely different
+ * concept — the helpers in this file consistently use the
+ * `getProductProfileProperty` naming to keep callers honest.
+ *
+ * Canonical end-to-end use case
+ * ─────────────────────────────
+ * Fan-out a `backup_complete` stream resource → `backups` bucket
+ * (history) and `backups` device property (last-known):
+ *
+ *   1. setProductApiResource(p, 'backup_complete', user, {
+ *        enabled: true,
+ *        request:  { data: { target: 'resource_stream', resource_stream: 'backup_complete', payload_type: 'source_payload', payload: '' } },
+ *        response: { data: { payload_type: 'none' } },
+ *      })
+ *   2. setProductBucket(p, 'backups', user, {
+ *        enabled: true, name: 'Backups', backend: 'mongodb',
+ *        retention: { period: 1, unit: 'years' },
+ *        data: { source: 'resource_stream', resource_stream: 'backup_complete', payload_type: 'source_payload', payload: '{{payload}}' },
+ *      })
+ *   3. setProductProfileProperty(p, 'backups', user, {
+ *        enabled: true, name: 'Backups',
+ *        data: { source: 'resource_stream', resource_stream: 'backup_complete', payload_type: 'source_payload', payload: '{{payload}}' },
+ *      })
+ *
+ * After this, every device of the product can call its own `backup_complete`
+ * stream resource. The platform fans the payload out to the bucket (history)
+ * and to the device property `backups` (last-known) automatically — no
+ * device code change.
+ */
+
+function resolveUser(user) {
+    return user || requireConfig().username;
+}
+
+function v1(user) {
+    return `/v1/users/${resolveUser(user)}`;
+}
+
+// ─── Listener config validators ──────────────────────────────────────
+//
+// Each `data.source` shape (for buckets/properties) and each request
+// `target` (for API resources) demands a matching key in the data block.
+// We enforce these client-side so the caller gets a clear error long
+// before the server returns a generic 400.
+
+/** Sources accepted by `profile.buckets[*].data.source` and `profile.properties[*].data.source`. */
+export const PROFILE_DATA_SOURCES = ['resource', 'resource_stream', 'product_stream', 'topic', 'event'];
+
+/** Targets accepted by `profile.api[*].request.data.target`. */
+export const PROFILE_API_TARGETS = [
+    'resource',
+    'resource_stream',
+    'product_stream',
+    'property',
+    'function',
+    'endpoint',
+    'topic',
+];
+
+/** Payload types recognised by the platform on both request and response sides. */
+export const PROFILE_PAYLOAD_TYPES = [
+    'template_payload',
+    'source_payload',
+    'source_event',
+    'none',
+];
+
+/** Required key in `source_args` for each `data.source` value. */
+const SOURCE_KEY = {
+    resource: 'resource',
+    resource_stream: 'resource_stream',
+    product_stream: 'product_stream',
+    topic: 'topic',
+    event: 'event',
+};
+
+/** Required key in `target_args` for each `request.data.target` value. */
+const TARGET_KEY = {
+    resource: 'resource',
+    resource_stream: 'resource_stream',
+    property: 'property',
+    function: 'function',
+    endpoint: 'endpoint',
+    topic: 'topic',
+    // product_stream needs BOTH `product` and `product_stream` — handled inline.
+    product_stream: 'product_stream',
+};
+
+function assertValidSource(source) {
+    if (!PROFILE_DATA_SOURCES.includes(source)) {
+        throw inputError(
+            `Invalid source "${source}". Allowed: ${PROFILE_DATA_SOURCES.join(', ')}.`,
+        );
+    }
+}
+
+function assertValidTarget(target) {
+    if (!PROFILE_API_TARGETS.includes(target)) {
+        throw inputError(
+            `Invalid target "${target}". Allowed: ${PROFILE_API_TARGETS.join(', ')}.`,
+        );
+    }
+}
+
+function assertValidPayloadType(value, label = 'payload_type') {
+    if (value === undefined || value === null) return;
+    if (!PROFILE_PAYLOAD_TYPES.includes(value)) {
+        throw inputError(
+            `Invalid ${label} "${value}". Allowed: ${PROFILE_PAYLOAD_TYPES.join(', ')}.`,
+        );
+    }
+}
+
+/**
+ * Build the `data` block for a bucket or property listener from the
+ * caller's source + source_args + payload bits. Returns a plain object
+ * the server will accept verbatim.
+ *
+ * @param {{
+ *   source: string,
+ *   source_args?: Record<string, unknown>,
+ *   payload_type?: string,
+ *   payload?: string,
+ *   payload_function?: string,
+ *   patch?: boolean,
+ * }} opts
+ */
+export function buildListenerDataBlock(opts) {
+    const source = opts.source;
+    assertValidSource(source);
+    const args = opts.source_args || {};
+
+    const data = { source };
+
+    const requiredKey = SOURCE_KEY[source];
+    if (requiredKey) {
+        const value = args[requiredKey];
+        if (typeof value !== 'string' || !value) {
+            throw inputError(
+                `source "${source}" requires source_args.${requiredKey} to be a non-empty string`,
+            );
+        }
+        data[requiredKey] = value;
+    }
+
+    if (source === 'resource') {
+        // `resource` source supports an optional polling cadence. When
+        // omitted, the server defaults to event mode (interval = 0).
+        const update = args.update;
+        if (update !== undefined) {
+            if (update !== 'interval' && update !== 'event') {
+                throw inputError(
+                    `source_args.update must be "interval" or "event" (got "${update}")`,
+                );
+            }
+            data.update = update;
+        }
+        if (args.interval !== undefined) {
+            const n = Number(args.interval);
+            if (!Number.isFinite(n) || n < 0) {
+                throw inputError('source_args.interval must be a non-negative number');
+            }
+            data.interval = n;
+        }
+        if (args.magnitude !== undefined) {
+            data.magnitude = String(args.magnitude);
+        }
+    }
+
+    if (source === 'product_stream') {
+        // The bucket/property listener listens on the *current* product's
+        // stream by default. A foreign-product listener is unusual — the
+        // server checks `data.product` only when present. Pass it through.
+        if (args.product !== undefined) {
+            if (typeof args.product !== 'string' || !args.product) {
+                throw inputError('source_args.product must be a non-empty string');
+            }
+            data.product = args.product;
+        }
+    }
+
+    if (source === 'event' && args.filter !== undefined) {
+        if (typeof args.filter !== 'object' || Array.isArray(args.filter)) {
+            throw inputError('source_args.filter must be an object');
+        }
+        data.filter = args.filter;
+    }
+
+    // Payload shape — common to every listener kind.
+    assertValidPayloadType(opts.payload_type);
+    if (opts.payload_type !== undefined) data.payload_type = opts.payload_type;
+    if (opts.payload !== undefined) {
+        if (typeof opts.payload !== 'string') {
+            throw inputError('payload must be a string (template or "{{payload}}")');
+        }
+        data.payload = opts.payload;
+    }
+    if (opts.payload_function !== undefined) {
+        if (typeof opts.payload_function !== 'string') {
+            throw inputError('payload_function must be a string');
+        }
+        data.payload_function = opts.payload_function;
+    }
+
+    // Property handler flag — only meaningful for property listeners but
+    // accepted on the base helper for symmetry; the bucket handler simply
+    // ignores it.
+    if (opts.patch !== undefined) {
+        data.patch = !!opts.patch;
+    }
+
+    return data;
+}
+
+/**
+ * Build the `request.data` block for a profile API resource.
+ *
+ * @param {{
+ *   target: string,
+ *   target_args?: Record<string, unknown>,
+ *   resource_name?: string,
+ *   payload_type?: string,
+ *   payload?: string,
+ *   payload_function?: string,
+ * }} opts
+ */
+export function buildApiRequestData(opts) {
+    const target = opts.target;
+    assertValidTarget(target);
+    const args = opts.target_args || {};
+    const data = { target };
+
+    if (target === 'product_stream') {
+        if (typeof args.product !== 'string' || !args.product) {
+            throw inputError(
+                'target "product_stream" requires target_args.product (the destination product id)',
+            );
+        }
+        if (typeof args.product_stream !== 'string' || !args.product_stream) {
+            throw inputError(
+                'target "product_stream" requires target_args.product_stream (the destination stream name)',
+            );
+        }
+        data.product = args.product;
+        data.product_stream = args.product_stream;
+    } else if (target === 'resource_stream') {
+        // resource_stream defaults to the API resource name itself, so the
+        // caller can omit target_args entirely for a self-named stream.
+        const stream = args.resource_stream || opts.resource_name;
+        if (!stream) {
+            throw inputError(
+                'target "resource_stream" needs target_args.resource_stream (defaults to the API resource name when omitted)',
+            );
+        }
+        data.resource_stream = stream;
+    } else {
+        const requiredKey = TARGET_KEY[target];
+        if (requiredKey) {
+            const value = args[requiredKey];
+            if (typeof value !== 'string' || !value) {
+                throw inputError(
+                    `target "${target}" requires target_args.${requiredKey} to be a non-empty string`,
+                );
+            }
+            data[requiredKey] = value;
+        }
+    }
+
+    assertValidPayloadType(opts.payload_type);
+    // template_payload is the platform default. The frontend encodes it
+    // as an empty string when round-tripping, but we accept the explicit
+    // value here too and pass it through unchanged.
+    if (opts.payload_type !== undefined) data.payload_type = opts.payload_type;
+    if (opts.payload !== undefined) {
+        if (typeof opts.payload !== 'string') {
+            throw inputError('payload must be a string');
+        }
+        data.payload = opts.payload;
+    }
+    if (opts.payload_function !== undefined) {
+        if (typeof opts.payload_function !== 'string') {
+            throw inputError('payload_function must be a string');
+        }
+        data.payload_function = opts.payload_function;
+    }
+
+    return data;
+}
+
+/**
+ * Build the `response.data` block for a profile API resource. `response`
+ * is optional on the wire; this helper produces a sensible default of
+ * `{ payload_type: 'none' }` when the caller wants a fire-and-forget
+ * resource, which matches the stream-style shape used by the
+ * `backup_complete` example.
+ *
+ * @param {{
+ *   payload_type?: string,
+ *   source?: string,
+ *   payload?: string,
+ *   payload_function?: string,
+ * } | undefined | null} response
+ */
+export function buildApiResponseData(response) {
+    if (!response) return { payload_type: 'none' };
+    const data = {};
+    assertValidPayloadType(response.payload_type, 'response.payload_type');
+    if (response.payload_type !== undefined) data.payload_type = response.payload_type;
+    if (response.source !== undefined) {
+        if (typeof response.source !== 'string') {
+            throw inputError('response.source must be a string');
+        }
+        data.source = response.source;
+    }
+    if (response.payload !== undefined) {
+        if (typeof response.payload !== 'string') {
+            throw inputError('response.payload must be a string');
+        }
+        data.payload = response.payload;
+    }
+    if (response.payload_function !== undefined) {
+        if (typeof response.payload_function !== 'string') {
+            throw inputError('response.payload_function must be a string');
+        }
+        data.payload_function = response.payload_function;
+    }
+    if (Object.keys(data).length === 0) {
+        return { payload_type: 'none' };
+    }
+    return data;
+}
+
+// ─── Low-level: profile/api/<name> ───────────────────────────────────
+
+/** Returns the `{ resourceName: definition }` map; `{}` when none. */
+export async function getProductApiResources(productId, user) {
+    try {
+        const res = await api.get(`${v1(user)}/products/${productId}/profile/api`);
+        return res.data || {};
+    } catch (e) {
+        if (e.response?.status === 404) return {};
+        throw apiError(e);
+    }
+}
+
+export async function getProductApiResource(productId, name, user) {
+    try {
+        const res = await api.get(
+            `${v1(user)}/products/${productId}/profile/api/${name}`,
+        );
+        return res.data || {};
+    } catch (e) {
+        throw apiError(e, {
+            notFound: `API resource not found: ${name} on product ${productId}`,
+        });
+    }
+}
+
+/**
+ * Upsert a profile API resource by passing the full `{request, response, ...}`
+ * document straight through. Use `setProfileApiResource` (below) for the
+ * higher-level builder that takes target/target_args/payload* fields and
+ * assembles the document for you.
+ */
+export async function setProductApiResource(productId, name, user, payload) {
+    try {
+        await api.put(
+            `${v1(user)}/products/${productId}/profile/api/${name}`,
+            payload,
+        );
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function deleteProductApiResource(productId, name, user) {
+    try {
+        await api.delete(
+            `${v1(user)}/products/${productId}/profile/api/${name}`,
+        );
+        return true;
+    } catch (e) {
+        if (e.response?.status === 404) return false;
+        throw apiError(e);
+    }
+}
+
+/**
+ * Upsert a profile API resource using the structured target/payload shape.
+ * Lets callers configure any of the platform's dispatch targets without
+ * hand-rolling the JSON. Required fields per target are validated client-
+ * side: missing `target_args.resource` for `target: "resource"` raises
+ * `inputError` instead of waiting for a 400 from the server.
+ *
+ * @param {string} productId
+ * @param {string} name  API resource name (becomes `profile.api.<name>`).
+ * @param {string|null|undefined} user
+ * @param {{
+ *   target: string,
+ *   target_args?: Record<string, unknown>,
+ *   payload_type?: string,
+ *   payload?: string,
+ *   payload_function?: string,
+ *   response?: {
+ *     payload_type?: string,
+ *     source?: string,
+ *     payload?: string,
+ *     payload_function?: string,
+ *   } | null,
+ *   enabled?: boolean,
+ * }} opts
+ */
+export async function setProfileApiResource(productId, name, user, opts) {
+    if (!productId) throw inputError('productId is required');
+    if (!name) throw inputError('name is required');
+    const requestData = buildApiRequestData({ ...opts, resource_name: name });
+    const responseData = buildApiResponseData(opts.response);
+    const payload = {
+        enabled: opts.enabled !== false,
+        request: { data: requestData },
+        response: { data: responseData },
+    };
+    await setProductApiResource(productId, name, user, payload);
+    return payload;
+}
+
+// ─── Low-level: profile/buckets/<name> ───────────────────────────────
+
+export async function getProductBuckets(productId, user) {
+    try {
+        const res = await api.get(`${v1(user)}/products/${productId}/profile/buckets`);
+        return res.data || {};
+    } catch (e) {
+        if (e.response?.status === 404) return {};
+        throw apiError(e);
+    }
+}
+
+export async function getProductBucket(productId, name, user) {
+    try {
+        const res = await api.get(
+            `${v1(user)}/products/${productId}/profile/buckets/${name}`,
+        );
+        return res.data || {};
+    } catch (e) {
+        throw apiError(e, {
+            notFound: `Profile bucket not found: ${name} on product ${productId}`,
+        });
+    }
+}
+
+export async function setProductBucket(productId, name, user, payload) {
+    try {
+        await api.put(
+            `${v1(user)}/products/${productId}/profile/buckets/${name}`,
+            payload,
+        );
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function deleteProductBucket(productId, name, user) {
+    try {
+        await api.delete(
+            `${v1(user)}/products/${productId}/profile/buckets/${name}`,
+        );
+        return true;
+    } catch (e) {
+        if (e.response?.status === 404) return false;
+        throw apiError(e);
+    }
+}
+
+const RETENTION_UNITS = ['minutes', 'hours', 'days', 'months', 'years'];
+
+function buildRetention(retention) {
+    if (retention === undefined || retention === null) return undefined;
+    if (typeof retention !== 'object' || Array.isArray(retention)) {
+        throw inputError('retention must be an object { period, unit }');
+    }
+    const period = Number(retention.period);
+    if (!Number.isFinite(period) || period <= 0) {
+        throw inputError('retention.period must be a positive number');
+    }
+    const unit = retention.unit;
+    if (!RETENTION_UNITS.includes(unit)) {
+        throw inputError(
+            `retention.unit must be one of: ${RETENTION_UNITS.join(', ')}`,
+        );
+    }
+    return { period, unit };
+}
+
+/**
+ * Upsert a profile bucket using the structured source/payload shape. The
+ * server creates / migrates the underlying time-series bucket lazily on
+ * the first event delivery (see `product_bucket_handler::initialize_bucket`).
+ *
+ * @param {string} productId
+ * @param {string} name
+ * @param {string|null|undefined} user
+ * @param {{
+ *   source: string,
+ *   source_args?: Record<string, unknown>,
+ *   payload_type?: string,
+ *   payload?: string,
+ *   payload_function?: string,
+ *   name_label?: string,
+ *   description?: string,
+ *   enabled?: boolean,
+ *   backend?: string,
+ *   retention?: { period: number, unit: string },
+ *   tags?: string[],
+ * }} opts
+ */
+export async function setProfileBucket(productId, name, user, opts) {
+    if (!productId) throw inputError('productId is required');
+    if (!name) throw inputError('name is required');
+
+    const data = buildListenerDataBlock(opts);
+    const payload = {
+        enabled: opts.enabled !== false,
+        name: opts.name_label || name,
+        description: opts.description || `Bucket for ${productId} product`,
+        backend: opts.backend || 'mongodb',
+        data,
+        tags: Array.isArray(opts.tags) ? opts.tags : [],
+    };
+    const retention = buildRetention(opts.retention);
+    if (retention) payload.retention = retention;
+
+    await setProductBucket(productId, name, user, payload);
+    return payload;
+}
+
+// ─── Low-level: profile/properties/<name> ────────────────────────────
+//
+// NOTE: `getProductProfileProperty` ≠ `getProductProperty`. The former
+// lives under `profile/properties/<name>` and configures a *handler* that
+// fans listener output into device properties. The latter (in product.js)
+// reads a JSON value attached to the product itself. See file header.
+
+export async function getProductProfileProperties(productId, user) {
+    try {
+        const res = await api.get(`${v1(user)}/products/${productId}/profile/properties`);
+        return res.data || {};
+    } catch (e) {
+        if (e.response?.status === 404) return {};
+        throw apiError(e);
+    }
+}
+
+export async function getProductProfileProperty(productId, name, user) {
+    try {
+        const res = await api.get(
+            `${v1(user)}/products/${productId}/profile/properties/${name}`,
+        );
+        return res.data || {};
+    } catch (e) {
+        throw apiError(e, {
+            notFound: `Profile property not found: ${name} on product ${productId}`,
+        });
+    }
+}
+
+export async function setProductProfileProperty(productId, name, user, payload) {
+    try {
+        await api.put(
+            `${v1(user)}/products/${productId}/profile/properties/${name}`,
+            payload,
+        );
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function deleteProductProfileProperty(productId, name, user) {
+    try {
+        await api.delete(
+            `${v1(user)}/products/${productId}/profile/properties/${name}`,
+        );
+        return true;
+    } catch (e) {
+        if (e.response?.status === 404) return false;
+        throw apiError(e);
+    }
+}
+
+/**
+ * Upsert a profile property handler using the structured source/payload
+ * shape. When `patch: true` is passed, the platform applies the resulting
+ * value as a JSON merge-patch on top of the existing device property
+ * instead of replacing it wholesale (see
+ * `product_property_handler::set_config` for the `data.patch` flag).
+ *
+ * @param {string} productId
+ * @param {string} name
+ * @param {string|null|undefined} user
+ * @param {{
+ *   source: string,
+ *   source_args?: Record<string, unknown>,
+ *   payload_type?: string,
+ *   payload?: string,
+ *   payload_function?: string,
+ *   name_label?: string,
+ *   description?: string,
+ *   enabled?: boolean,
+ *   patch?: boolean,
+ * }} opts
+ */
+export async function setProfileProperty(productId, name, user, opts) {
+    if (!productId) throw inputError('productId is required');
+    if (!name) throw inputError('name is required');
+
+    const data = buildListenerDataBlock(opts);
+    const payload = {
+        enabled: opts.enabled !== false,
+        name: opts.name_label || name,
+        description: opts.description || `Property handler for ${productId} product`,
+        data,
+    };
+    await setProductProfileProperty(productId, name, user, payload);
+    return payload;
+}