@kohost/api-client 7.8.2 → 7.10.0

package/dist/schemas/sosEvent.d.ts

@@ -0,0 +1,413 @@
+import defs, { ISODateString } from "./definitions.js";
+import type { FromSchema } from "json-schema-to-ts";
+export declare const sosEventSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema";
+    readonly $id: "sosEvent.json";
+    readonly title: "SOS Event";
+    readonly description: "A durable record of a single SOS activation on a Property, with an append-only timeline of updates. Persists as audit history after the SOS is cleared.";
+    readonly type: "object";
+    readonly required: readonly ["id", "type", "sosTypeIds", "activatedAt", "timeline"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly id: {
+            readonly $ref: "definitions.json#/definitions/id";
+            readonly description: "Unique identifier for the SOS Event.";
+        };
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly ["sosEvent"];
+            readonly default: "sosEvent";
+        };
+        readonly propertyId: {
+            readonly type: "string";
+            readonly description: "ID of the Property this SOS was raised on. Used as a per-document filter inside the org-scoped database.";
+        };
+        readonly sosTypeIds: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "The SOS Type ids this event was raised for.";
+        };
+        readonly activatedAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+            readonly description: "When the SOS was raised.";
+        };
+        readonly activatedBy: {
+            readonly type: readonly ["object", "null"];
+            readonly additionalProperties: false;
+            readonly required: readonly ["id", "discriminator"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                };
+                readonly discriminator: {
+                    readonly type: "string";
+                    readonly enum: readonly ["user", "device", "automation"];
+                };
+            };
+            readonly description: "Actor that raised the SOS (user, device, or automation); null when unattributed.";
+        };
+        readonly deactivatedAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+            readonly description: "When the SOS was cleared. Absent while the event is active.";
+        };
+        readonly deactivatedBy: {
+            readonly type: readonly ["object", "null"];
+            readonly additionalProperties: false;
+            readonly required: readonly ["id", "discriminator"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                };
+                readonly discriminator: {
+                    readonly type: "string";
+                    readonly enum: readonly ["user", "device", "automation"];
+                };
+            };
+            readonly description: "Actor that cleared the SOS; null when unattributed. Absent while the event is active.";
+        };
+        readonly timeline: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly description: "Append-only timeline. The first entry is the `activation`; later entries are operator `update`s, automation runs, and a closing `final`.";
+            readonly items: {
+                readonly oneOf: readonly [{
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["id", "type", "message", "by", "at", "audience"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly description: "Unique identifier for the timeline entry.";
+                        };
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["activation", "update", "final"];
+                            readonly description: "`activation` opens the event, `update` is an interim message, `final` closes it.";
+                        };
+                        readonly message: {
+                            readonly type: "string";
+                            readonly description: "The entry's message body. May be empty for entries that carry only audience/delivery intent.";
+                        };
+                        readonly by: {
+                            readonly type: readonly ["object", "null"];
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "discriminator"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly discriminator: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["user", "device", "automation"];
+                                };
+                            };
+                            readonly description: "Actor that authored the entry; null when unattributed.";
+                        };
+                        readonly at: {
+                            readonly $ref: "definitions.json#/definitions/date";
+                            readonly description: "When the entry was recorded.";
+                        };
+                        readonly audience: {
+                            readonly $ref: "definitions.json#/definitions/audience";
+                            readonly description: "Who this entry was directed at, and who it resolved to. `activation` entries always carry the everyone wildcard; `update` and `final` entries carry whatever the sender named — an empty selector reaches nobody.";
+                        };
+                        readonly channels: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly enum: readonly ["sms", "email"];
+                            };
+                            readonly description: "Personal channels the sender selected for this entry. Absent on entries recorded before channel selection existed, which sent over both.";
+                        };
+                        readonly surfaces: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["targets", "sent", "failed", "skipped"];
+                            readonly description: "Rollup of the PA-surface dispatch, present when the entry named surfaces. `targets` is the devices the selectors resolved to; `skipped` counts drivers that cannot render content.";
+                            readonly properties: {
+                                readonly targets: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                };
+                                readonly sent: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                };
+                                readonly failed: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                };
+                                readonly skipped: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                };
+                            };
+                        };
+                        readonly deliveryStatus: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly description: "Computed on demand by DescribeSOSEvent (not persisted): live per-audience, per-channel outcome counts grouped from the sms/email collections by appData.sosUpdateId × status. Absent on the returned event until at least one matching message exists; only audiences/channels with data are present.";
+                            readonly properties: {
+                                readonly internal: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly description: "Per-channel live outcomes for one audience.";
+                                    readonly properties: {
+                                        readonly sms: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["sent", "delivered", "failed"];
+                                            readonly properties: {
+                                                readonly sent: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly delivered: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly failed: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                            };
+                                        };
+                                        readonly email: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["sent", "delivered", "failed"];
+                                            readonly properties: {
+                                                readonly sent: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly delivered: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly failed: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                                readonly external: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: false;
+                                    readonly description: "Per-channel live outcomes for one audience.";
+                                    readonly properties: {
+                                        readonly sms: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["sent", "delivered", "failed"];
+                                            readonly properties: {
+                                                readonly sent: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly delivered: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly failed: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                            };
+                                        };
+                                        readonly email: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: false;
+                                            readonly required: readonly ["sent", "delivered", "failed"];
+                                            readonly properties: {
+                                                readonly sent: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly delivered: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                                readonly failed: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["id", "type", "at", "by", "automationName", "runId", "trigger", "actions"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly description: "Unique identifier for the timeline entry.";
+                        };
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["automationRun"];
+                            readonly description: "Discriminator: an automation that ran in response to this SOS.";
+                        };
+                        readonly at: {
+                            readonly $ref: "definitions.json#/definitions/date";
+                            readonly description: "When the run started. The entry is stamped with pending actions up front and settled in place.";
+                        };
+                        readonly by: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "discriminator"];
+                            readonly description: "The Automation that ran. Its id is the automation's id — there is no separate automationId.";
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly discriminator: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["automation"];
+                                };
+                            };
+                        };
+                        readonly automationName: {
+                            readonly type: "string";
+                            readonly description: "The automation's name snapshotted at run time, so a later rename or delete leaves the timeline readable.";
+                        };
+                        readonly runId: {
+                            readonly type: "string";
+                            readonly description: "Groups this run's Activity records; one event matching several automations yields one runId each.";
+                        };
+                        readonly trigger: {
+                            readonly type: "string";
+                            readonly enum: readonly ["SOSActive", "SOSInactive"];
+                            readonly description: "The SOS event type that matched the automation's trigger.";
+                        };
+                        readonly actions: {
+                            readonly type: "array";
+                            readonly default: readonly [];
+                            readonly description: "Per-action outcome, in the automation's action order.";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["type", "status"];
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly description: "The use case the automation action invoked.";
+                                    };
+                                    readonly status: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["pending", "success", "failure"];
+                                        readonly description: "`pending` while the action is in flight; settles to `success` or `failure`.";
+                                    };
+                                    readonly error: {
+                                        readonly type: readonly ["string", "null"];
+                                        readonly description: "Failure message; absent when the action succeeded.";
+                                    };
+                                    readonly params: {
+                                        readonly type: "object";
+                                        readonly description: "Pruned snapshot of the action's configured params (e.g. SetDevices device states, StartSOS type ids), enough to render a human summary of what the action did. Absent when the use case has no summarizable params.";
+                                    };
+                                };
+                            };
+                        };
+                    };
+                }];
+            };
+        };
+        readonly notes: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly description: "Append-only, internal-only post-incident notes. Kept outside the timeline: a note is for the record, never something that was broadcast.";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "text", "by", "at"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly description: "Unique identifier for the note.";
+                    };
+                    readonly text: {
+                        readonly type: "string";
+                        readonly description: "Internal, plain-text note body. Never broadcast.";
+                    };
+                    readonly by: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["id", "discriminator"];
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly discriminator: {
+                                readonly type: "string";
+                                readonly enum: readonly ["user", "device", "automation"];
+                            };
+                        };
+                        readonly description: "Actor that wrote the note; null when unattributed.";
+                    };
+                    readonly at: {
+                        readonly $ref: "definitions.json#/definitions/date";
+                        readonly description: "When the note was recorded.";
+                    };
+                };
+            };
+        };
+        readonly report: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["fileId", "url", "filename", "contentHash", "renderedAt"];
+            readonly description: "The most recently minted incident-report PDF, kept so a re-export of an unchanged, ended incident can reuse the file instead of rendering again. `contentHash` fingerprints the rendered content (excluding the generated-at stamp).";
+            readonly properties: {
+                readonly fileId: {
+                    readonly type: "string";
+                };
+                readonly url: {
+                    readonly type: "string";
+                };
+                readonly filename: {
+                    readonly type: "string";
+                };
+                readonly contentHash: {
+                    readonly type: "string";
+                };
+                readonly renderedAt: {
+                    readonly $ref: "definitions.json#/definitions/date";
+                };
+            };
+        };
+        readonly createdAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+            readonly description: "When the SOS Event was created.";
+        };
+        readonly updatedAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+            readonly description: "When the SOS Event was last modified.";
+        };
+        readonly deletedAt: {
+            readonly type: readonly ["string", "object", "null"];
+            readonly format: "date-time";
+            readonly description: "Soft-delete tombstone.";
+        };
+    };
+};
+export type SOSEventSchema = FromSchema<typeof sosEventSchema, {
+    references: [typeof defs];
+    keepDefaultedPropertiesOptional: true;
+    deserialize: [
+        {
+            pattern: {
+                format: "date-time";
+            };
+            output: Date | ISODateString;
+        }
+    ];
+}>;