@oneuptime/common 14.0.8 → 14.0.10

package/Server/Utils/Workspace/MicrosoftTeams/MicrosoftTeamsReplies.ts

@@ -0,0 +1,251 @@
+import { Activity, TurnContext } from "botbuilder";
+import URL from "../../../../Types/API/URL";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import NotAuthorizedException from "../../../../Types/Exception/NotAuthorizedException";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import DatabaseConfig from "../../../DatabaseConfig";
+import { ProjectScopedReferenceException } from "../../Database/ProjectScopedReferenceValidator";
+import logger, { LogAttributes } from "../../Logger";
+import MicrosoftTeamsMessageSize, {
+  MICROSOFT_TEAMS_CARD_SIZE_BUDGETS_IN_BYTES,
+} from "./MicrosoftTeamsMessageSize";
+
+/*
+ * Replies the Microsoft Teams bot sends, and the rule they follow: an inbound
+ * message gets one answer, and an answer that cannot be sent never turns into
+ * a second one.
+ *
+ * Issue #4111: a failed command replied "Sorry, I encountered an error..."
+ * and then rethrew, the adapter answered Teams with HTTP 500, and Teams
+ * delivered the message again, so every error showed up twice. Replies that
+ * are not the point of the turn (an error text, removing a submitted form) are
+ * therefore sent best-effort: a failure is logged, never thrown.
+ */
+
+export const MICROSOFT_TEAMS_ADAPTIVE_CARD_CONTENT_TYPE: string =
+  "application/vnd.microsoft.card.adaptive";
+
+/*
+ * The reply for a submit that references a record the project does not have
+ * (deleted since the form was sent, or another project's id in a tampered
+ * submit). Fixed text: the validator's own message names the other project's
+ * record, which is not for this chat.
+ */
+export const MICROSOFT_TEAMS_UNAVAILABLE_REFERENCE_MESSAGE: string =
+  "One of the values you picked (a monitor, label, on-call policy, severity or status) is not available in this project any more. Please pick it again.";
+
+export default class MicrosoftTeamsReplies {
+  // Sends a reply; logs instead of throwing. Returns whether Teams took it.
+  public static async sendBestEffort(
+    turnContext: TurnContext,
+    reply: string | Partial<Activity>,
+  ): Promise<boolean> {
+    try {
+      await turnContext.sendActivity(reply);
+      return true;
+    } catch (error) {
+      logger.error(
+        `Could not send a Microsoft Teams reply: ${this.describeError(error)}`,
+      );
+      return false;
+    }
+  }
+
+  /*
+   * Removes a message the bot posted, such as the form a user just submitted;
+   * logs instead of throwing. It runs after the record the form created
+   * exists, so a failure here must never be reported as a failed create.
+   */
+  public static async deleteBestEffort(
+    turnContext: TurnContext,
+    activityId: string | undefined,
+  ): Promise<void> {
+    if (!activityId) {
+      return;
+    }
+
+    try {
+      await turnContext.deleteActivity(activityId);
+    } catch (error) {
+      logger.debug(
+        `Could not remove a submitted Microsoft Teams card: ${this.describeError(error)}`,
+      );
+    }
+  }
+
+  /*
+   * Sends an adaptive card built for each size budget in turn, until Teams
+   * accepts one. Only a "too large" refusal moves on to the next, smaller
+   * budget; any other error is thrown at once, and so is the last "too
+   * large". A budget whose card is no different from the one just refused
+   * is skipped.
+   */
+  public static async sendCardWithinSizeLimit(data: {
+    turnContext: TurnContext;
+    buildCard: (budgetInBytes: number) => JSONObject;
+    budgetsInBytes?: ReadonlyArray<number> | undefined;
+  }): Promise<void> {
+    const budgetsInBytes: ReadonlyArray<number> =
+      data.budgetsInBytes || MICROSOFT_TEAMS_CARD_SIZE_BUDGETS_IN_BYTES;
+
+    let lastError: unknown = undefined;
+    let lastRefusedCard: string | null = null;
+
+    for (const budgetInBytes of budgetsInBytes) {
+      const card: JSONObject = data.buildCard(budgetInBytes);
+      const serializedCard: string = JSON.stringify(card);
+
+      if (serializedCard === lastRefusedCard) {
+        continue;
+      }
+
+      try {
+        await data.turnContext.sendActivity({
+          attachments: [
+            {
+              contentType: MICROSOFT_TEAMS_ADAPTIVE_CARD_CONTENT_TYPE,
+              content: card,
+            },
+          ],
+        });
+        return;
+      } catch (error) {
+        if (!MicrosoftTeamsMessageSize.isMessageTooLargeError(error)) {
+          throw error;
+        }
+
+        logger.warn(
+          `Microsoft Teams refused a ${MicrosoftTeamsMessageSize.getSizeInBytes(
+            serializedCard,
+          )} byte card as too large (budget ${budgetInBytes} bytes); trying a smaller one.`,
+        );
+
+        lastError = error;
+        lastRefusedCard = serializedCard;
+      }
+    }
+
+    throw lastError;
+  }
+
+  /*
+   * One line that says what went wrong, for the log. Bot Framework errors
+   * carry the HTTP status and Teams' error code, e.g.
+   * "RestError 413 MessageSizeTooBig: Message size too large.".
+   */
+  public static describeError(error: unknown): string {
+    if (!error || typeof error !== "object") {
+      return String(error);
+    }
+
+    /*
+     * OneUptime's exceptions keep Error's name, so the class they were thrown
+     * as comes from the constructor instead.
+     */
+    const errorName: string =
+      ((error as { name?: unknown }).name as string | undefined) || "";
+    const constructorName: string =
+      ((error as { constructor?: { name?: unknown } }).constructor?.name as
+        | string
+        | undefined) || "";
+    const name: string =
+      errorName && errorName !== "Error"
+        ? errorName
+        : constructorName && constructorName !== "Object"
+          ? constructorName
+          : errorName || "Error";
+    const message: string = String(
+      (error as { message?: unknown }).message ?? "",
+    );
+    const statusCode: number | undefined =
+      MicrosoftTeamsMessageSize.getErrorStatusCode(error);
+    const code: string | undefined =
+      MicrosoftTeamsMessageSize.getErrorCode(error);
+
+    return [name, statusCode, code]
+      .filter((part: string | number | undefined) => {
+        return part !== undefined && part !== "";
+      })
+      .join(" ")
+      .concat(`: ${message}`);
+  }
+
+  /*
+   * Logs a failure: one line that says what failed and why, then the error
+   * itself, which keeps its stack and lets the log tell a refusal from a
+   * fault. A Bot Framework HTTP error is left at the one line: its status and
+   * code say it all, and the object carries the whole request and response.
+   */
+  public static logFailure(
+    summary: string,
+    error: unknown,
+    attributes?: LogAttributes | undefined,
+  ): void {
+    logger.error(`${summary}: ${this.describeError(error)}`, attributes);
+
+    if (MicrosoftTeamsMessageSize.getErrorStatusCode(error) === undefined) {
+      logger.error(error, attributes);
+    }
+  }
+
+  /*
+   * The message of an error OneUptime writes for the person who caused it: a
+   * validation or a permission refusal. Null for anything else, whose text is
+   * meant for operators.
+   */
+  public static getUserFacingErrorMessage(error: unknown): string | null {
+    if (error instanceof ProjectScopedReferenceException) {
+      return MICROSOFT_TEAMS_UNAVAILABLE_REFERENCE_MESSAGE;
+    }
+
+    if (
+      (error instanceof BadDataException ||
+        error instanceof NotAuthorizedException) &&
+      error.message
+    ) {
+      return error.message;
+    }
+
+    return null;
+  }
+
+  // A link into the project in the OneUptime dashboard, or null if unknown.
+  public static async getDashboardLink(data: {
+    projectId: ObjectID;
+    route: string; // below the project, e.g. "/incidents/create"
+  }): Promise<string | null> {
+    try {
+      const dashboardUrl: URL = await DatabaseConfig.getDashboardUrl();
+
+      return URL.fromString(dashboardUrl.toString())
+        .addRoute(`/${data.projectId.toString()}${data.route}`)
+        .toString();
+    } catch (error) {
+      logger.debug("Could not build a OneUptime dashboard link");
+      logger.debug(error);
+      return null;
+    }
+  }
+
+  /*
+   * What to tell a Teams user who has not connected their Microsoft Teams
+   * account to OneUptime yet: where to do it. `purpose` completes "To ...",
+   * e.g. "create incidents from Microsoft Teams".
+   */
+  public static async getAccountNotLinkedMessage(data: {
+    projectId: ObjectID;
+    purpose: string;
+  }): Promise<string> {
+    const settingsLink: string | null = await this.getDashboardLink({
+      projectId: data.projectId,
+      route: "/user-settings/microsoft-teams-integration",
+    });
+
+    const where: string = settingsLink
+      ? `in [OneUptime → User Settings → Microsoft Teams](${settingsLink})`
+      : "in OneUptime under User Settings → Microsoft Teams";
+
+    return `To ${data.purpose}, first connect your Microsoft Teams account to OneUptime ${where}, then try again.`;
+  }
+}

package/Server/Utils/Workspace/MicrosoftTeams/MicrosoftTeamsTimezone.ts

@@ -0,0 +1,214 @@
+import moment from "moment-timezone";
+import { JSONObject } from "../../../../Types/JSON";
+
+/*
+ * The time zone a Microsoft Teams user typed a date and a time in.
+ *
+ * Input.Date and Input.Time submit a bare "2026-10-01" and "14:00", with no
+ * zone. Those used to be read in the server's time zone (UTC in the
+ * containers), so 14:00 typed in New York became 10:00 in New York. Teams
+ * tells the bot the sender's zone on the activity (localTimezone, an IANA
+ * name, and the clientInfo entity), though not from every client: iOS has
+ * been seen to leave localTimezone out.
+ *
+ * The form names the zone of whoever asked for it and carries that zone in
+ * its submit data, and the submitted times are read in it: in a channel the
+ * person who fills the form in may be somewhere else, and they typed the times
+ * the form asked for. A form that named no zone is read in the submitter's own
+ * zone, then at the UTC offset of their activity's local timestamp, then in
+ * UTC. Whichever zone is used is named back to the user.
+ */
+
+export interface MicrosoftTeamsUserTimezone {
+  // IANA name, when known.
+  timezone?: string | undefined;
+  // Offset from UTC in minutes, when only an offset is known.
+  utcOffsetInMinutes?: number | undefined;
+  // How the zone is named to the user, e.g. "America/New_York" or "UTC+05:30".
+  label: string;
+}
+
+const DATE_TIME_FORMATS: Array<string> = [
+  "YYYY-MM-DD HH:mm",
+  "YYYY-MM-DD HH:mm:ss",
+];
+
+const UTC_OFFSET_SUFFIX: RegExp = /(?:[+-]\d{2}:?\d{2}|Z)$/i;
+
+export default class MicrosoftTeamsTimezone {
+  public static readonly UTC: MicrosoftTeamsUserTimezone = {
+    timezone: "UTC",
+    label: "UTC",
+  };
+
+  // The name, when it is an IANA time zone moment-timezone knows.
+  public static getKnownTimezone(value: unknown): string | undefined {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+
+    const name: string = value.trim();
+
+    if (!name || !moment.tz.zone(name)) {
+      return undefined;
+    }
+
+    return name;
+  }
+
+  // The IANA zone an activity says its sender is in.
+  public static getTimezoneFromActivity(
+    activity: JSONObject,
+  ): string | undefined {
+    const fromLocalTimezone: string | undefined = this.getKnownTimezone(
+      activity["localTimezone"],
+    );
+
+    if (fromLocalTimezone) {
+      return fromLocalTimezone;
+    }
+
+    const entities: Array<JSONObject> =
+      (activity["entities"] as Array<JSONObject> | undefined) || [];
+
+    for (const entity of entities) {
+      if (entity && entity["type"] === "clientInfo") {
+        const fromClientInfo: string | undefined = this.getKnownTimezone(
+          entity["timezone"],
+        );
+
+        if (fromClientInfo) {
+          return fromClientInfo;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /*
+   * The UTC offset of the activity's local timestamp, in minutes. botbuilder
+   * turns localTimestamp into a Date, which drops the offset, and keeps the
+   * original string as rawLocalTimestamp.
+   */
+  public static getUtcOffsetFromActivity(
+    activity: JSONObject,
+  ): number | undefined {
+    for (const field of ["rawLocalTimestamp", "localTimestamp"]) {
+      const value: unknown = activity[field];
+
+      if (typeof value !== "string" || !UTC_OFFSET_SUFFIX.test(value.trim())) {
+        continue;
+      }
+
+      const parsed: moment.Moment = moment.parseZone(
+        value.trim(),
+        moment.ISO_8601,
+        true,
+      );
+
+      if (parsed.isValid()) {
+        return parsed.utcOffset();
+      }
+    }
+
+    return undefined;
+  }
+
+  /*
+   * The zone to read a submitted date and time in: the zone the form named,
+   * which is what its reader was told, then the submitting activity's own
+   * zone, then its UTC offset, then UTC.
+   */
+  public static resolve(data: {
+    activity: JSONObject;
+    timezoneFromCard?: unknown;
+  }): MicrosoftTeamsUserTimezone {
+    const timezone: string | undefined =
+      this.getKnownTimezone(data.timezoneFromCard) ||
+      this.getTimezoneFromActivity(data.activity);
+
+    if (timezone) {
+      return { timezone: timezone, label: timezone };
+    }
+
+    const utcOffsetInMinutes: number | undefined =
+      this.getUtcOffsetFromActivity(data.activity);
+
+    if (utcOffsetInMinutes !== undefined) {
+      return {
+        utcOffsetInMinutes: utcOffsetInMinutes,
+        label: this.formatUtcOffset(utcOffsetInMinutes),
+      };
+    }
+
+    return this.UTC;
+  }
+
+  /*
+   * Whether only a UTC offset is known. The offset is today's, so a date past
+   * a daylight saving change can be an hour out, and the reply says so.
+   */
+  public static isUtcOffsetOnly(timezone: MicrosoftTeamsUserTimezone): boolean {
+    return !timezone.timezone && timezone.utcOffsetInMinutes !== undefined;
+  }
+
+  // "UTC", "UTC+05:30", "UTC-04:00".
+  public static formatUtcOffset(utcOffsetInMinutes: number): string {
+    if (utcOffsetInMinutes === 0) {
+      return "UTC";
+    }
+
+    const sign: string = utcOffsetInMinutes > 0 ? "+" : "-";
+    const absolute: number = Math.abs(utcOffsetInMinutes);
+    const hours: string = String(Math.floor(absolute / 60)).padStart(2, "0");
+    const minutes: string = String(absolute % 60).padStart(2, "0");
+
+    return `UTC${sign}${hours}:${minutes}`;
+  }
+
+  /*
+   * The instant a date ("YYYY-MM-DD") and a time ("HH:mm") mean in the zone,
+   * or null when either is not in that form.
+   */
+  public static toDate(data: {
+    date: string;
+    time: string;
+    timezone: MicrosoftTeamsUserTimezone;
+  }): Date | null {
+    const text: string = `${data.date.trim()} ${data.time.trim()}`;
+
+    if (data.timezone.timezone) {
+      const zoned: moment.Moment = moment.tz(
+        text,
+        DATE_TIME_FORMATS,
+        true,
+        data.timezone.timezone,
+      );
+
+      return zoned.isValid() ? zoned.toDate() : null;
+    }
+
+    const wallClock: moment.Moment = moment.utc(text, DATE_TIME_FORMATS, true);
+
+    if (!wallClock.isValid()) {
+      return null;
+    }
+
+    return wallClock
+      .subtract(data.timezone.utcOffsetInMinutes || 0, "minutes")
+      .toDate();
+  }
+
+  // A date as the user reads it back, e.g. "Oct 1, 2026, 14:00 (America/New_York)".
+  public static format(
+    date: Date,
+    timezone: MicrosoftTeamsUserTimezone,
+  ): string {
+    const zoned: moment.Moment = timezone.timezone
+      ? moment(date).tz(timezone.timezone)
+      : moment(date).utcOffset(timezone.utcOffsetInMinutes || 0);
+
+    return `${zoned.format("MMM D, YYYY, HH:mm")} (${timezone.label})`;
+  }
+}