@use-voltra/android 2.3.1 → 2.4.0

package/src/ongoing-notification/renderer.ts

@@ -6,20 +6,48 @@ import { ANDROID_ONGOING_NOTIFICATION_COMPONENT_TAG } from './components.js'
 import type {
   AndroidOngoingNotificationActionPayload,
   AndroidOngoingNotificationActionProps,
+  AndroidOngoingNotificationBigPicturePayload,
+  AndroidOngoingNotificationBigPictureProps,
   AndroidOngoingNotificationBigTextPayload,
   AndroidOngoingNotificationBigTextProps,
+  AndroidOngoingNotificationCommonDisplayProps,
   AndroidOngoingNotificationContent,
+  AndroidOngoingNotificationInboxPayload,
+  AndroidOngoingNotificationInboxProps,
+  AndroidOngoingNotificationMetricPayload,
+  AndroidOngoingNotificationMetricProps,
+  AndroidOngoingNotificationMetricSemanticStyle,
+  AndroidOngoingNotificationMetricValuePayload,
   AndroidOngoingNotificationPayload,
   AndroidOngoingNotificationProgressPayload,
   AndroidOngoingNotificationProgressPoint,
   AndroidOngoingNotificationProgressProps,
   AndroidOngoingNotificationProgressSegment,
+  AndroidOngoingNotificationPublicVersion,
 } from './types.js'
 
 void getAndroidComponentId
 
 const PAYLOAD_VERSION = 1 as const
 
+/**
+ * InboxStyle only renders six lines, so more than that is rejected at render time instead of being
+ * silently truncated. Kept in sync with MAX_INBOX_LINES in the Android client.
+ */
+const MAX_INBOX_LINES = 6
+
+/**
+ * Size of an inline picture that is still reasonable to hand to a native post. Push providers cap
+ * data payloads at a few kilobytes (FCM allows 4096 bytes), so no inline picture travels through a
+ * push message. Warns instead of failing: local starts and self-hosted transports can legitimately
+ * carry more. Compared against the decoded size, because a base64 string is four characters per
+ * three bytes and its length flatters the image.
+ */
+const MAX_INLINE_PICTURE_BYTES = 256 * 1024
+
+/** Bytes a base64 string holds once decoded. Padding leaves this at most two bytes high. */
+const decodedBase64Bytes = (base64: string): number => Math.ceil((base64.length * 3) / 4)
+
 const flattenChildren = (node: ReactNode): ReactNode[] => {
   if (node === null || node === undefined || typeof node === 'boolean') {
     return []
@@ -123,6 +151,16 @@ const assertOptionalImageSource = (value: unknown, propName: string): ImageSourc
   return value
 }
 
+const assertRequiredImageSource = (value: unknown, propName: string): ImageSource => {
+  const source = assertOptionalImageSource(value, propName)
+
+  if (source === undefined) {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" is required.`)
+  }
+
+  return source
+}
+
 const assertBoolean = (value: unknown, propName: string): boolean | undefined => {
   if (value === undefined) {
     return undefined
@@ -211,15 +249,45 @@ const normalizeProgressPoints = (value: unknown): AndroidOngoingNotificationProg
   })
 }
 
-const normalizeWhen = (value: unknown): number | undefined => {
-  if (value === undefined) {
-    return undefined
+const normalizeInboxLines = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "lines" must be an array of non-empty strings.')
+  }
+
+  if (value.length === 0) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "lines" must contain at least one line.')
+  }
+
+  if (value.length > MAX_INBOX_LINES) {
+    throw new Error(
+      `[Voltra] [Android] Ongoing notification prop "lines" must contain at most ${MAX_INBOX_LINES} lines, got ${value.length}.`
+    )
+  }
+
+  return value.map((line, index) => assertString(line, `lines[${index}]`))
+}
+
+const warnInlinePicture = (picture: ImageSource): void => {
+  const base64 = 'base64' in picture ? picture.base64 : undefined
+
+  if (base64 === undefined) {
+    return
+  }
+
+  const pictureBytes = decodedBase64Bytes(base64)
+
+  if (pictureBytes > MAX_INLINE_PICTURE_BYTES) {
+    console.warn(
+      `[Voltra] [Android] Ongoing notification prop "picture" carries a ${pictureBytes}-byte image, which exceeds ${MAX_INLINE_PICTURE_BYTES} bytes. Inline pictures cannot travel through push messages: preload the image and reference it with assetName instead.`
+    )
   }
+}
 
+const normalizeEpoch = (value: unknown, propName: string): number => {
   if (value instanceof Date) {
     const timestamp = value.getTime()
     if (!Number.isFinite(timestamp)) {
-      throw new Error('[Voltra] [Android] Ongoing notification prop "when" must be a valid Date or timestamp.')
+      throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a valid Date or timestamp.`)
     }
 
     return timestamp
@@ -229,7 +297,66 @@ const normalizeWhen = (value: unknown): number | undefined => {
     return value
   }
 
-  throw new Error('[Voltra] [Android] Ongoing notification prop "when" must be a valid Date or timestamp.')
+  throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a valid Date or timestamp.`)
+}
+
+const normalizeWhen = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  return normalizeEpoch(value, 'when')
+}
+
+// `true` keeps meaning "count up" for payloads and props written before the
+// chip gained a direction; only 'countDown' sets chronometerCountDown, and a
+// countdown without `when` has nothing to count down to.
+const normalizeChronometer = (
+  value: unknown,
+  when: number | undefined
+): { chronometer?: boolean; chronometerCountDown?: boolean } => {
+  if (value === undefined) {
+    return {}
+  }
+
+  if (typeof value === 'boolean') {
+    return { chronometer: value }
+  }
+
+  if (value === 'countUp') {
+    return { chronometer: true }
+  }
+
+  if (value === 'countDown') {
+    if (when === undefined) {
+      throw new Error(
+        '[Voltra] [Android] Ongoing notification prop "chronometer" set to "countDown" requires the "when" prop.'
+      )
+    }
+
+    return { chronometer: true, chronometerCountDown: true }
+  }
+
+  throw new Error(
+    '[Voltra] [Android] Ongoing notification prop "chronometer" must be a boolean, "countUp" or "countDown".'
+  )
+}
+
+const normalizePublicVersion = (value: unknown): AndroidOngoingNotificationPublicVersion | undefined => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "publicVersion" must be an object with a title.')
+  }
+
+  const { title, text } = value as { title?: unknown; text?: unknown }
+
+  return {
+    title: assertString(title, 'publicVersion.title'),
+    text: assertOptionalString(text, 'publicVersion.text'),
+  }
 }
 
 const getElementKind = (element: ReactElement<Record<string, unknown>>) => {
@@ -250,6 +377,33 @@ const normalizeActionPayload = (
   }
 }
 
+const normalizeCommonDisplayFields = (
+  props: AndroidOngoingNotificationCommonDisplayProps & { largeIcon?: ImageSource }
+): {
+  title?: string
+  subText?: string
+  shortCriticalText?: string
+  when?: number
+  chronometer?: boolean
+  chronometerCountDown?: boolean
+  showWhen?: boolean
+  largeIcon?: ImageSource
+  publicVersion?: AndroidOngoingNotificationPublicVersion
+} => {
+  const when = normalizeWhen(props.when)
+
+  return {
+    title: assertOptionalNonEmptyString(props.title, 'title'),
+    subText: assertOptionalString(props.subText, 'subText'),
+    shortCriticalText: assertOptionalString(props.shortCriticalText, 'shortCriticalText'),
+    when,
+    ...normalizeChronometer(props.chronometer, when),
+    showWhen: assertBoolean(props.showWhen, 'showWhen'),
+    largeIcon: assertOptionalImageSource(props.largeIcon, 'largeIcon'),
+    publicVersion: normalizePublicVersion(props.publicVersion),
+  }
+}
+
 const normalizeActions = (value: ReactNode): AndroidOngoingNotificationActionPayload[] | undefined => {
   const actions: AndroidOngoingNotificationActionPayload[] = []
 
@@ -293,16 +447,11 @@ const normalizeProgressPayload = (
   return {
     v: PAYLOAD_VERSION,
     kind: 'progress',
-    title: assertOptionalNonEmptyString(props.title, 'title'),
-    subText: assertOptionalString(props.subText, 'subText'),
+    ...normalizeCommonDisplayFields(props),
     text: assertOptionalString(props.text, 'text'),
     value,
     max,
     indeterminate: assertBoolean(props.indeterminate, 'indeterminate'),
-    shortCriticalText: assertOptionalString(props.shortCriticalText, 'shortCriticalText'),
-    when: normalizeWhen(props.when),
-    chronometer: assertBoolean(props.chronometer, 'chronometer'),
-    largeIcon: assertOptionalImageSource(props.largeIcon, 'largeIcon'),
     progressTrackerIcon: assertOptionalImageSource(props.progressTrackerIcon, 'progressTrackerIcon'),
     progressStartIcon: assertOptionalImageSource(props.progressStartIcon, 'progressStartIcon'),
     progressEndIcon: assertOptionalImageSource(props.progressEndIcon, 'progressEndIcon'),
@@ -320,14 +469,286 @@ const normalizeBigTextPayload = (
   return {
     v: PAYLOAD_VERSION,
     kind: 'bigText',
-    title: assertOptionalNonEmptyString(props.title, 'title'),
-    subText: assertOptionalString(props.subText, 'subText'),
+    ...normalizeCommonDisplayFields(props),
     text,
     bigText: assertOptionalString(props.bigText, 'bigText') ?? text,
-    shortCriticalText: assertOptionalString(props.shortCriticalText, 'shortCriticalText'),
-    when: normalizeWhen(props.when),
-    chronometer: assertBoolean(props.chronometer, 'chronometer'),
-    largeIcon: assertOptionalImageSource(props.largeIcon, 'largeIcon'),
+    actions: normalizeActions(props.children),
+  }
+}
+
+const METRIC_TIME_PATTERN = /^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/
+
+const METRIC_SEMANTIC_STYLES = ['unspecified', 'info', 'safe', 'caution', 'danger'] as const
+
+const METRIC_TIME_FORMATS = ['adaptive', 'chronometer'] as const
+
+const assertMetricNonEmptyString = (value: unknown, propName: string): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be a non-empty string.`)
+  }
+
+  return value
+}
+
+const normalizeMetricTimeFormat = (value: unknown, propName: string) => {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (!(METRIC_TIME_FORMATS as readonly unknown[]).includes(value)) {
+    throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}" must be "adaptive" or "chronometer".`)
+  }
+
+  return value as (typeof METRIC_TIME_FORMATS)[number]
+}
+
+const normalizeMetricValue = (
+  value: unknown,
+  unit: unknown,
+  propName: string
+): AndroidOngoingNotificationMetricValuePayload => {
+  const topLevelUnit = assertOptionalString(unit, `${propName}.unit`)
+  const rejectTopLevelUnit = () => {
+    if (topLevelUnit !== undefined) {
+      throw new Error(
+        `[Voltra] [Android] Ongoing notification prop "${propName}.unit" only applies to "int", "float" and "text" values.`
+      )
+    }
+  }
+
+  // Shorthands: an integer reads as int, any other number as float, a string as text.
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}.value" must be a finite number.`)
+    }
+
+    return Number.isInteger(value)
+      ? { type: 'int', value, unit: topLevelUnit }
+      : { type: 'float', value, unit: topLevelUnit }
+  }
+
+  if (typeof value === 'string') {
+    return { type: 'text', value: assertMetricNonEmptyString(value, `${propName}.value`), unit: topLevelUnit }
+  }
+
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(
+      `[Voltra] [Android] Ongoing notification prop "${propName}.value" must be a number, a string, or a metric value object.`
+    )
+  }
+
+  const source = value as Record<string, unknown>
+  const type = source.type
+
+  switch (type) {
+    case 'int': {
+      const numberValue = assertFiniteNumber(source.value, `${propName}.value`)
+      if (!Number.isInteger(numberValue)) {
+        throw new Error(`[Voltra] [Android] Ongoing notification prop "${propName}.value" must be an integer.`)
+      }
+
+      return {
+        type: 'int',
+        value: numberValue,
+        unit: assertOptionalString(source.unit, `${propName}.unit`) ?? topLevelUnit,
+      }
+    }
+    case 'float': {
+      const numberValue = assertFiniteNumber(source.value, `${propName}.value`)
+      const min = source.min === undefined ? undefined : assertFiniteNumber(source.min, `${propName}.min`)
+      const max = source.max === undefined ? undefined : assertFiniteNumber(source.max, `${propName}.max`)
+
+      if (min !== undefined && min < 0) {
+        throw new Error(
+          `[Voltra] [Android] Ongoing notification prop "${propName}.min" must be greater than or equal to 0.`
+        )
+      }
+
+      if (max !== undefined && max < 0) {
+        throw new Error(
+          `[Voltra] [Android] Ongoing notification prop "${propName}.max" must be greater than or equal to 0.`
+        )
+      }
+
+      if (min !== undefined && max !== undefined && min > max) {
+        throw new Error(
+          `[Voltra] [Android] Ongoing notification prop "${propName}.min" must not exceed "${propName}.max".`
+        )
+      }
+
+      let fractionDigits: number | undefined
+      if (source.fractionDigits !== undefined) {
+        fractionDigits = assertFiniteNumber(source.fractionDigits, `${propName}.fractionDigits`)
+        if (!Number.isInteger(fractionDigits) || fractionDigits < 0) {
+          throw new Error(
+            `[Voltra] [Android] Ongoing notification prop "${propName}.fractionDigits" must be an integer greater than or equal to 0.`
+          )
+        }
+      }
+
+      return {
+        type: 'float',
+        value: numberValue,
+        unit: assertOptionalString(source.unit, `${propName}.unit`) ?? topLevelUnit,
+        min,
+        max,
+        fractionDigits,
+      }
+    }
+    case 'text':
+      return {
+        type: 'text',
+        value: assertMetricNonEmptyString(source.value, `${propName}.value`),
+        unit: assertOptionalString(source.unit, `${propName}.unit`) ?? topLevelUnit,
+      }
+    case 'time': {
+      rejectTopLevelUnit()
+      const timeValue = assertMetricNonEmptyString(source.value, `${propName}.value`)
+      if (!METRIC_TIME_PATTERN.test(timeValue)) {
+        throw new Error(
+          `[Voltra] [Android] Ongoing notification prop "${propName}.value" must be a time in "HH:mm" or "HH:mm:ss" form.`
+        )
+      }
+
+      return { type: 'time', value: timeValue }
+    }
+    case 'timer':
+      rejectTopLevelUnit()
+      return {
+        type: 'timer',
+        endsAt: normalizeEpoch(source.endsAt, `${propName}.endsAt`),
+        format: normalizeMetricTimeFormat(source.format, `${propName}.format`),
+      }
+    case 'stopwatch':
+      rejectTopLevelUnit()
+      return {
+        type: 'stopwatch',
+        startedAt: normalizeEpoch(source.startedAt, `${propName}.startedAt`),
+        format: normalizeMetricTimeFormat(source.format, `${propName}.format`),
+      }
+    case 'pausedTimer': {
+      rejectTopLevelUnit()
+      const remainingMillis = assertFiniteNumber(source.remainingMillis, `${propName}.remainingMillis`)
+      if (remainingMillis < 0) {
+        throw new Error(
+          `[Voltra] [Android] Ongoing notification prop "${propName}.remainingMillis" must be greater than or equal to 0.`
+        )
+      }
+
+      return { type: 'pausedTimer', remainingMillis }
+    }
+    case 'pausedStopwatch': {
+      rejectTopLevelUnit()
+      const elapsedMillis = assertFiniteNumber(source.elapsedMillis, `${propName}.elapsedMillis`)
+      if (elapsedMillis < 0) {
+        throw new Error(
+          `[Voltra] [Android] Ongoing notification prop "${propName}.elapsedMillis" must be greater than or equal to 0.`
+        )
+      }
+
+      return { type: 'pausedStopwatch', elapsedMillis }
+    }
+    default:
+      throw new Error(
+        `[Voltra] [Android] Ongoing notification prop "${propName}.type" must be "int", "float", "text", "time", "timer", "stopwatch", "pausedTimer", or "pausedStopwatch".`
+      )
+  }
+}
+
+const normalizeMetricPayload = (
+  props: AndroidOngoingNotificationMetricProps
+): AndroidOngoingNotificationMetricPayload => {
+  if (!Array.isArray(props.metrics)) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "metrics" must be an array.')
+  }
+
+  if (props.metrics.length < 1 || props.metrics.length > 3) {
+    throw new Error('[Voltra] [Android] Ongoing notification prop "metrics" must contain between 1 and 3 metrics.')
+  }
+
+  const metrics = props.metrics.map((descriptor, index) => {
+    if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+      throw new Error(`[Voltra] [Android] Ongoing notification prop "metrics[${index}]" must be an object.`)
+    }
+
+    const label = assertMetricNonEmptyString(descriptor.label, `metrics[${index}].label`)
+    if (label.length > 10) {
+      throw new Error(
+        `[Voltra] [Android] Ongoing notification prop "metrics[${index}].label" must be at most 10 characters long.`
+      )
+    }
+
+    return { label, value: normalizeMetricValue(descriptor.value, descriptor.unit, `metrics[${index}]`) }
+  })
+
+  let criticalMetric: number | undefined
+  if (props.criticalMetric !== undefined) {
+    criticalMetric = assertFiniteNumber(props.criticalMetric, 'criticalMetric')
+    if (!Number.isInteger(criticalMetric) || criticalMetric < 0 || criticalMetric >= metrics.length) {
+      throw new Error(
+        `[Voltra] [Android] Ongoing notification prop "criticalMetric" must be an index between 0 and ${
+          metrics.length - 1
+        }.`
+      )
+    }
+  }
+
+  let semanticStyle: AndroidOngoingNotificationMetricSemanticStyle | undefined
+  if (props.semanticStyle !== undefined) {
+    if (!(METRIC_SEMANTIC_STYLES as readonly string[]).includes(props.semanticStyle)) {
+      throw new Error(
+        '[Voltra] [Android] Ongoing notification prop "semanticStyle" must be "unspecified", "info", "safe", "caution", or "danger".'
+      )
+    }
+
+    semanticStyle = props.semanticStyle
+  }
+
+  return {
+    v: PAYLOAD_VERSION,
+    kind: 'metric',
+    ...normalizeCommonDisplayFields(props),
+    metrics,
+    criticalMetric,
+    semanticStyle,
+    actions: normalizeActions(props.children),
+  }
+}
+
+const normalizeBigPicturePayload = (
+  props: AndroidOngoingNotificationBigPictureProps
+): AndroidOngoingNotificationBigPicturePayload => {
+  const picture = assertRequiredImageSource(props.picture, 'picture')
+  warnInlinePicture(picture)
+
+  return {
+    v: PAYLOAD_VERSION,
+    kind: 'bigPicture',
+    ...normalizeCommonDisplayFields(props),
+    text: assertOptionalString(props.text, 'text'),
+    picture,
+    summaryText: assertOptionalNonEmptyString(props.summaryText, 'summaryText'),
+    pictureContentDescription: assertOptionalNonEmptyString(
+      props.pictureContentDescription,
+      'pictureContentDescription'
+    ),
+    showPictureWhenCollapsed: assertBoolean(props.showPictureWhenCollapsed, 'showPictureWhenCollapsed'),
+    bigLargeIcon: assertOptionalImageSource(props.bigLargeIcon, 'bigLargeIcon'),
+    hideLargeIconWhenExpanded: assertBoolean(props.hideLargeIconWhenExpanded, 'hideLargeIconWhenExpanded'),
+    actions: normalizeActions(props.children),
+  }
+}
+
+const normalizeInboxPayload = (props: AndroidOngoingNotificationInboxProps): AndroidOngoingNotificationInboxPayload => {
+  const lines = normalizeInboxLines(props.lines)
+
+  return {
+    v: PAYLOAD_VERSION,
+    kind: 'inbox',
+    ...normalizeCommonDisplayFields(props),
+    text: props.text === undefined ? lines[0] : assertString(props.text, 'text'),
+    lines,
+    summaryText: assertOptionalNonEmptyString(props.summaryText, 'summaryText'),
     actions: normalizeActions(props.children),
   }
 }
@@ -346,8 +767,20 @@ export const renderAndroidOngoingNotificationPayloadToJson = (
     return normalizeBigTextPayload(element.props as AndroidOngoingNotificationBigTextProps)
   }
 
+  if (kind === 'bigPicture') {
+    return normalizeBigPicturePayload(element.props as AndroidOngoingNotificationBigPictureProps)
+  }
+
+  if (kind === 'inbox') {
+    return normalizeInboxPayload(element.props as AndroidOngoingNotificationInboxProps)
+  }
+
+  if (kind === 'metric') {
+    return normalizeMetricPayload(element.props as AndroidOngoingNotificationMetricProps)
+  }
+
   throw new Error(
-    '[Voltra] [Android] Ongoing notification content must use AndroidOngoingNotification.Progress or AndroidOngoingNotification.BigText.'
+    '[Voltra] [Android] Ongoing notification content must use AndroidOngoingNotification.Progress, AndroidOngoingNotification.BigText, AndroidOngoingNotification.BigPicture, AndroidOngoingNotification.Inbox, or AndroidOngoingNotification.Metric.'
   )
 }