@oneuptime/common 12.0.7 → 12.0.9

package/Types/Telemetry/EntityType.ts

@@ -7,7 +7,7 @@
  * entity data model (https://opentelemetry.io/docs/specs/otel/entities/).
  *
  * This is the broader *membership* vocabulary used by the `entityKeys`
- * column on signals and by the `TelemetryEntity` registry. It is distinct
+ * column on signals and by the `InventoryItem` registry. It is distinct
  * from `ServiceType`, which is the narrower discriminator for a signal's
  * single *primary* entity (`primaryEntityType`) and additionally covers
  * OneUptime-specific primary owners (Monitor, RealUserMonitor, Unknown,
@@ -51,6 +51,33 @@ enum EntityType {
   DockerSwarmService = "docker.swarm.service",
   DockerSwarmTask = "docker.swarm.task",
   TelemetrySdk = "telemetry.sdk",
+  /*
+   * Inventory-mirrored types. Unlike everything above, these are never
+   * derived from an OTLP resource — the estate they describe is collected
+   * by pollers (SNMP, cloud APIs, MQTT) into rich typed tables, and the
+   * registry row is a mirror of that row so the entity explorer can show
+   * one estate instead of one telemetry pipeline. Their identity is the
+   * owning row's own project-unique key, and their lifecycle follows it
+   * (see InventoryEntityRegistry); they carry EntitySource.Inventory and
+   * are deliberately absent from the prune TTL map.
+   */
+  NetworkDevice = "network.device",
+  CloudResource = "cloud.resource",
+  ServerlessFunction = "serverless.function",
+  RumApplication = "rum.application",
+  IoTDevice = "iot.device",
+  DockerHost = "docker.host",
+  PodmanHost = "podman.host",
+  /*
+   * Manual (user-authored) types, for the parts of an estate that emit no
+   * telemetry and appear in no inventory table: a third-party payment API,
+   * a vendor-managed database, a physical appliance. They exist so a
+   * dependency edge can terminate somewhere real instead of dangling at
+   * the boundary of what OneUptime can see. Carry EntitySource.Manual.
+   */
+  ExternalService = "external.service",
+  ExternalDatabase = "external.database",
+  Appliance = "appliance",
 }
 
 export default EntityType;

package/Types/Telemetry/EntityTypeGroups.ts

@@ -0,0 +1,65 @@
+import EntityType from "./EntityType";
+
+/*
+ * Partitions of the EntityType vocabulary by who creates and owns a row of
+ * that type. Isomorphic (plain Types, no server imports) because all three
+ * consumers need the same answer: the service enforcing what a user may
+ * create, the dashboard populating the type dropdown, and the tests pinning
+ * that the prune sweep cannot reach a type nothing re-bumps.
+ *
+ * Deliberately expressed as explicit sets rather than a string-prefix test.
+ * Prefix matching would silently absorb any future `external.*` or
+ * `*.device` type into the set that is exempt from pruning, which is the
+ * kind of default that goes unnoticed until a registry fills with rows
+ * nothing can ever reap.
+ */
+
+/**
+ * Types a user may create by hand. These describe things OneUptime cannot
+ * observe — a third-party API, a vendor-managed database, an appliance —
+ * so nothing will ever discover them and nothing will ever bump their
+ * `lastSeenAt`.
+ *
+ * Manual creation is confined to these on purpose. A hand-made row of an
+ * observable type (say `service`) would mint an entity key from the manual
+ * identity attribute, which by construction differs from the key ingest
+ * derives from `service.name` — so the manual row would sit beside the
+ * discovered one as a permanent near-duplicate rather than merging with it.
+ */
+export const MANUAL_ENTITY_TYPES: ReadonlySet<EntityType> = new Set<EntityType>(
+  [
+    EntityType.ExternalService,
+    EntityType.ExternalDatabase,
+    EntityType.Appliance,
+  ],
+);
+
+/**
+ * Types mirrored from a OneUptime inventory table. The owning row is the
+ * source of truth for both identity and liveness; the registry row is a
+ * projection kept in step by that table's create/delete hooks.
+ */
+export const INVENTORY_ENTITY_TYPES: ReadonlySet<EntityType> =
+  new Set<EntityType>([
+    EntityType.NetworkDevice,
+    EntityType.CloudResource,
+    EntityType.ServerlessFunction,
+    EntityType.RumApplication,
+    EntityType.IoTDevice,
+    EntityType.DockerHost,
+    EntityType.PodmanHost,
+  ]);
+
+/**
+ * True for types whose rows have no telemetry heartbeat, and which are
+ * therefore never eligible for `lastSeenAt`-based pruning. The prune job
+ * enforces this through the `source` column instead (a row's source is the
+ * authority, not its type); this predicate is what the tests assert the TTL
+ * map against, so a newly added type cannot quietly acquire a TTL.
+ */
+export function isNonInventoryItemType(entityType: EntityType): boolean {
+  return (
+    MANUAL_ENTITY_TYPES.has(entityType) ||
+    INVENTORY_ENTITY_TYPES.has(entityType)
+  );
+}

package/Types/Workflow/Component.ts

@@ -30,6 +30,35 @@ export enum ComponentInputType {
   WorkflowSelect = "Workflow Select",
 }
 
+/*
+ * Argument types whose value is a JSON document but is read with
+ * JSONFunctions.parse — that is, JSON5 — rather than JSON.parse. Unquoted keys,
+ * single quotes and trailing commas therefore work in these, and a workflow
+ * written that way runs fine today.
+ *
+ * The distinction matters wherever a JSON document is checked for syntax
+ * before it runs: applying JSON.parse's rules to one of these would report a
+ * mistake in a workflow that does not have one. The strict set is everything
+ * else — RunWorkflow.getComponentArguments calls JSON.parse directly on
+ * JSON, Query and Select, so those really must be JSON.
+ */
+const JSON5_TOLERANT_INPUT_TYPES: Array<ComponentInputType> = [
+  ComponentInputType.StringDictionary,
+  ComponentInputType.JSONArray,
+  ComponentInputType.BaseModel,
+  ComponentInputType.BaseModelArray,
+];
+
+export type IsJSON5ToleratedInputTypeFunction = (
+  type: ComponentInputType,
+) => boolean;
+
+export const isJSON5ToleratedInputType: IsJSON5ToleratedInputTypeFunction = (
+  type: ComponentInputType,
+): boolean => {
+  return JSON5_TOLERANT_INPUT_TYPES.includes(type);
+};
+
 export enum ComponentType {
   Trigger = "Trigger",
   Component = "Component",

package/Types/Workflow/Components/API.ts

@@ -37,6 +37,13 @@ const components: Array<ComponentMetadata> = [
         type: ComponentInputType.StringDictionary,
         required: false,
         isAdvanced: true,
+        /*
+         * Headers are where an Authorization bearer token gets typed, and
+         * without this the resolved value is written verbatim into the
+         * WorkflowLog for anyone with read access to the project. Only values
+         * that came from a variable marked secret were ever scrubbed.
+         */
+        isSensitive: true,
         placeholder:
           'Example: {"header1": "value1", "header2": "value2", ....}',
       },
@@ -123,6 +130,13 @@ const components: Array<ComponentMetadata> = [
         type: ComponentInputType.StringDictionary,
         required: false,
         isAdvanced: true,
+        /*
+         * Headers are where an Authorization bearer token gets typed, and
+         * without this the resolved value is written verbatim into the
+         * WorkflowLog for anyone with read access to the project. Only values
+         * that came from a variable marked secret were ever scrubbed.
+         */
+        isSensitive: true,
         placeholder:
           'Example: {"header1": "value1", "header2": "value2", ....}',
       },
@@ -209,6 +223,13 @@ const components: Array<ComponentMetadata> = [
         type: ComponentInputType.StringDictionary,
         required: false,
         isAdvanced: true,
+        /*
+         * Headers are where an Authorization bearer token gets typed, and
+         * without this the resolved value is written verbatim into the
+         * WorkflowLog for anyone with read access to the project. Only values
+         * that came from a variable marked secret were ever scrubbed.
+         */
+        isSensitive: true,
         placeholder:
           'Example: {"header1": "value1", "header2": "value2", ....}',
       },
@@ -295,6 +316,13 @@ const components: Array<ComponentMetadata> = [
         type: ComponentInputType.StringDictionary,
         required: false,
         isAdvanced: true,
+        /*
+         * Headers are where an Authorization bearer token gets typed, and
+         * without this the resolved value is written verbatim into the
+         * WorkflowLog for anyone with read access to the project. Only values
+         * that came from a variable marked secret were ever scrubbed.
+         */
+        isSensitive: true,
         placeholder:
           'Example: {"header1": "value1", "header2": "value2", ....}',
       },
@@ -381,6 +409,13 @@ const components: Array<ComponentMetadata> = [
         type: ComponentInputType.StringDictionary,
         required: false,
         isAdvanced: true,
+        /*
+         * Headers are where an Authorization bearer token gets typed, and
+         * without this the resolved value is written verbatim into the
+         * WorkflowLog for anyone with read access to the project. Only values
+         * that came from a variable marked secret were ever scrubbed.
+         */
+        isSensitive: true,
         placeholder:
           'Example: {"header1": "value1", "header2": "value2", ....}',
       },

package/Types/Workflow/Components/BaseModel.ts

@@ -19,9 +19,13 @@ export default class BaseModelComponent {
      * Every one of these arguments is keyed on column names, and the single
      * most common way to get one wrong is to write "id" - which is what an ID
      * is called everywhere else in the product - when the column is "_id".
-     * Both spellings work now, but the hint has to say so where the builder is
-     * actually typing, because the Query argument is a bare JSON editor with
-     * no field picker behind it.
+     * Both spellings work.
+     *
+     * Query, Select and the write payload all get an editor backed by the
+     * model's real column list, so the names are offered rather than
+     * remembered. The hint stays because those editors keep a JSON escape
+     * hatch for values rows cannot express, and because it is still the only
+     * thing explaining the two spellings.
      */
     const columnHint: string = `Keys are column names on ${model.singularName}. The ID column is "_id" (the "id" spelling is accepted too).`;
 
@@ -34,8 +38,45 @@ export default class BaseModelComponent {
 
     const dataDescription: string = `${model.singularName} fields to write, as a JSON object. ${columnHint}`;
 
-    const documentationLink: Route = Route.fromString(
-      "/workflow/docs/DatabaseComponents.md",
+    /*
+     * Skip and Limit are the same on every component that has them, and they
+     * are not what decides what a step does - so they sit behind the "advanced"
+     * disclosure rather than competing with Query for attention.
+     *
+     * Limit is worded as a cap rather than as pagination. Read as pagination it
+     * is why "Items Deleted: 10" gets taken to mean ten records matched: the
+     * runtime defaults it to 10 and stops there (DeleteManyBaseModel,
+     * UpdateManyBaseModel), so a query matching five hundred records still only
+     * touches ten.
+     */
+    const skipDescription: string = `Skip the first X ${model.pluralName} the query matched. Defaults to 0.`;
+
+    const limitDescription: string = `The most ${model.pluralName} this step will touch. Defaults to 10, so a query that matches 500 records still only affects 10. Raise this if you mean all of them.`;
+
+    /*
+     * One file per operation, rather than one shared file for all eleven
+     * components. Shared, it had to describe Query, Select, the write payload,
+     * Items Updated and Items Deleted at once - so on Create One, which has
+     * none of those but the payload, most of it was about something else, and
+     * its one concrete instruction ("use the Select Fields picker") named an
+     * argument that component does not have.
+     *
+     * The route serves any filename in the docs directory, so these need no
+     * registration anywhere.
+     */
+    const findDocs: Route = Route.fromString("/workflow/docs/DatabaseFind.md");
+    const createDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseCreate.md",
+    );
+    const updateDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseUpdate.md",
+    );
+    const deleteDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseDelete.md",
+    );
+    // The triggers had no documentation link at all, so their card never rendered.
+    const triggerDocs: Route = Route.fromString(
+      "/workflow/docs/DatabaseTriggers.md",
     );
 
     if (model.enableWorkflowOn.read) {
@@ -47,7 +88,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleDown,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: findDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -107,7 +148,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleDown,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: findDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -128,16 +169,18 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Number,
             name: "Skip",
-            description: `Skip the first X number of items. This can be helpful to implement pagination. Defaults to 0.`,
+            description: skipDescription,
             required: false,
             id: "skip",
+            isAdvanced: true,
           },
           {
             type: ComponentInputType.Number,
             name: "Limit",
-            description: `Limit to first X items. This can be helpful to implement pagination. Defaults to 10.`,
+            description: limitDescription,
             required: false,
             id: "limit",
+            isAdvanced: true,
           },
         ],
         returnValues: [
@@ -183,6 +226,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Bolt,
         tableName: model.tableName!,
         componentType: ComponentType.Trigger,
+        documentationLink: triggerDocs,
         runWorkflowManuallyArguments: [
           {
             type: ComponentInputType.Text,
@@ -222,11 +266,11 @@ export default class BaseModelComponent {
         iconProp: IconProp.Trash,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: deleteDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
-            name: "Delete by",
+            name: "Query",
             description: queryDescription,
             required: true,
             id: "query",
@@ -270,15 +314,15 @@ export default class BaseModelComponent {
         id: `${Text.pascalCaseToDashes(model.tableName!)}-delete-many`,
         title: `Delete Many ${model.pluralName}`,
         category: `${model.singularName}`,
-        description: `Database query to find many ${model.pluralName}`,
+        description: `Delete many ${model.pluralName} that match a query.`,
         iconProp: IconProp.Trash,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: deleteDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
-            name: "Delete by",
+            name: "Query",
             description: queryDescription,
             required: true,
             id: "query",
@@ -287,16 +331,18 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Number,
             name: "Skip",
-            description: `Skip the first X number of items. This can be helpful to implement pagination. Defaults to 0.`,
+            description: skipDescription,
             required: false,
             id: "skip",
+            isAdvanced: true,
           },
           {
             type: ComponentInputType.Number,
             name: "Limit",
-            description: `Limit to first X items. This can be helpful to implement pagination. Defaults to 10.`,
+            description: limitDescription,
             required: false,
             id: "limit",
+            isAdvanced: true,
           },
         ],
         returnValues: [
@@ -342,6 +388,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Bolt,
         tableName: model.tableName!,
         componentType: ComponentType.Trigger,
+        documentationLink: triggerDocs,
         runWorkflowManuallyArguments: [
           {
             type: ComponentInputType.Text,
@@ -390,7 +437,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Database,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: createDocs,
         arguments: [
           {
             id: "json",
@@ -405,8 +452,8 @@ export default class BaseModelComponent {
           {
             id: "model",
             name: `${model.singularName}`,
-            description: `${model.singularName} created in the database`,
-            type: ComponentInputType.JSON,
+            description: `${model.singularName} created in the database, including its new "_id"`,
+            type: ComponentInputType.BaseModel,
             required: false,
           },
         ],
@@ -442,7 +489,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Database,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: createDocs,
         arguments: [
           {
             id: "json-array",
@@ -457,8 +504,8 @@ export default class BaseModelComponent {
           {
             id: "models",
             name: `${model.pluralName}`,
-            description: "Models created in the database",
-            type: ComponentInputType.BaseModel,
+            description: `${model.pluralName} created in the database`,
+            type: ComponentInputType.BaseModelArray,
             required: false,
           },
         ],
@@ -496,6 +543,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.Bolt,
         tableName: model.tableName!,
         componentType: ComponentType.Trigger,
+        documentationLink: triggerDocs,
         runWorkflowManuallyArguments: [
           {
             type: ComponentInputType.Text,
@@ -510,7 +558,7 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Select,
             name: "Listen on",
-            description: `Workflow only executes when an upate happens to these fields on ${model.singularName}. If you leave this blank then the workflow will fire on any field that's updated on ${model.singularName}.`,
+            description: `Narrows this trigger to updates that touch these fields on ${model.singularName}. Leave it blank to fire on any change. When an update arrives without a record of which fields moved, this filter is skipped and the workflow runs anyway.`,
             required: false,
             id: "listen-on",
             placeholder: 'Example: {"columnName": true, ...}',
@@ -551,7 +599,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleUp,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: updateDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -611,7 +659,7 @@ export default class BaseModelComponent {
         iconProp: IconProp.ArrowCircleUp,
         tableName: model.tableName!,
         componentType: ComponentType.Component,
-        documentationLink: documentationLink,
+        documentationLink: updateDocs,
         arguments: [
           {
             type: ComponentInputType.Query,
@@ -632,16 +680,18 @@ export default class BaseModelComponent {
           {
             type: ComponentInputType.Number,
             name: "Skip",
-            description: `Skip the first X number of items. This can be helpful to implement pagination. Defaults to 0.`,
+            description: skipDescription,
             required: false,
             id: "skip",
+            isAdvanced: true,
           },
           {
             type: ComponentInputType.Number,
             name: "Limit",
-            description: `Limit to first X items. This can be helpful to implement pagination. Defaults to 10.`,
+            description: limitDescription,
             required: false,
             id: "limit",
+            isAdvanced: true,
           },
         ],
         returnValues: [

package/Types/Workflow/Components/Discord.ts

@@ -21,6 +21,7 @@ const components: Array<ComponentMetadata> = [
           "Need help creating a webhook? Check docs here: https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks",
         type: ComponentInputType.URL,
         required: true,
+        isSensitive: true,
         placeholder:
           "https://discord.com/api/webhooks/1234567890/XXXXXXXXXXXXXXXXXXXXXXXX",
       },

package/Types/Workflow/Components/Email.ts

@@ -64,6 +64,7 @@ const components: Array<ComponentMetadata> = [
         description: "SMTP Password to send emails from",
         required: false,
         id: "smtp-password",
+        isSensitive: true,
       },
       {
         type: ComponentInputType.Number,
@@ -74,14 +75,22 @@ const components: Array<ComponentMetadata> = [
       },
       {
         type: ComponentInputType.Boolean,
-        name: "Use TLS/SSL",
+        name: "Use Implicit TLS",
         description:
-          "Check this box if you would like to use TLS/SSL to send emails",
+          "Enable for implicit TLS, usually on port 465. Leave disabled for STARTTLS, usually on port 587.",
         required: false,
         id: "secure",
       },
     ],
-    returnValues: [],
+    returnValues: [
+      {
+        id: "error",
+        name: "Error",
+        description: "Error, if there is any.",
+        type: ComponentInputType.Text,
+        required: false,
+      },
+    ],
     inPorts: [
       {
         title: "In",

package/Types/Workflow/Components/JavaScript.ts

@@ -40,6 +40,13 @@ const components: Array<ComponentMetadata> = [
         required: false,
         id: "returnValue",
       },
+      {
+        type: ComponentInputType.Text,
+        name: "Error",
+        description: "Error message when the script follows the Error port",
+        required: false,
+        id: "error",
+      },
     ],
     inPorts: [
       {

package/Types/Workflow/Components/MicrosoftTeams.ts

@@ -18,10 +18,11 @@ const components: Array<ComponentMetadata> = [
         id: "webhook-url",
         name: "Teams Incoming Webhook URL",
         description:
-          "Need help creating a webhook? Check docs here: https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook",
+          "Create a channel webhook with Teams Workflows. See: https://support.microsoft.com/en-us/teams/apps-service/create-incoming-webhooks-with-workflows-for-microsoft-teams",
         type: ComponentInputType.URL,
         required: true,
-        placeholder: "https://xxxxx.webhook.office.com/xxxxxxxxx",
+        isSensitive: true,
+        placeholder: "https://...environment.api.powerplatform.com/...",
       },
       {
         id: "text",

package/Types/Workflow/Components/Slack.ts

@@ -21,6 +21,7 @@ const components: Array<ComponentMetadata> = [
           "Need help creating a webhook? Check docs here: https://api.slack.com/messaging/webhooks",
         type: ComponentInputType.URL,
         required: true,
+        isSensitive: true,
         placeholder:
           "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
       },

package/Types/Workflow/Components/Telegram.ts

@@ -21,6 +21,7 @@ const components: Array<ComponentMetadata> = [
           "Need help creating a bot? Check docs here: https://core.telegram.org/bots#how-do-i-create-a-bot",
         type: ComponentInputType.Text,
         required: true,
+        isSensitive: true,
         placeholder: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyZ",
       },
       {