Merge branch 'feature/build_info'

temerity/build.gradle.kts

@@ -17,6 +17,11 @@
  */
 import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import io.github.andreabrighi.gradle.gitsemver.conventionalcommit.ConventionalCommit
+import io.github.z4kn4fein.semver.Version
+import io.github.z4kn4fein.semver.toVersion
+import kotlinx.datetime.Clock
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
 import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier.Public
 
 plugins {
@@ -41,12 +46,29 @@ buildscript {
     dependencies {
         classpath(libs.dokka.base)
         classpath(libs.build.conventionalCommits)
+        classpath(libs.kotlinx.datetime)
+        classpath(libs.kotlinSemver)
     }
 }
 
+internal val buildTz = TimeZone.currentSystemDefault()
+
+internal fun currentDateTime() = Clock.System.now().toLocalDateTime(buildTz)
+
 buildConfig {
     buildConfigField("LIB_VERSION", provider { "${project.version}" })
     buildConfigField("PACKAGE_NAME", provider { "edu.ucsc.its.${project.name}" })
+    // TODO: Allow user to change TZ config
+    buildConfigField("BUILD_DATE", provider { "${currentDateTime()}" })
+    buildConfigField("BUILD_TIMEZONE", provider { "$buildTz" })
+    buildConfigField("BUILD_VARIANT", provider {
+        with (Version.parse(project.version.toString())) {
+            when {
+                isStable -> "RELEASE"
+                else -> "DEBUG"
+            }
+        }
+    })
 }
 
 gitSemVer {

temerity/src/commonMain/kotlin/edu/ucsc/its/temerity/TemerityApi.kt

@@ -41,19 +41,13 @@ import kotlinx.datetime.plus
 /**
  * This interface defines top-level library functions for interacting with the enterprise video platform API.
  * The functions defined in this interface are implemented by the [edu.ucsc.its.temerity.core.Temerity] class.
+ * Users wishing to create their own library version should implement this interface.
  * @see [edu.ucsc.its.temerity.core.Temerity]
  */
 
 public interface TemerityApi {
 
-  // User API public library functions
-
-  /**
-   * Fetches the version of the Temerity client library.
-   * @return The version of the client library as a semantic versioning formatted string.
-   */
-  @Suppress("PropertyName")
-  public val version: String
+  // User API library functions
 
   /**
    * Fetches the list of users from the platform.
@@ -293,3 +287,21 @@ public fun ArrayList<AuditLogEntry>.sortByCreationDate(sortOrder: AuditLogSortOr
     AuditLogSortOrder.OLD_FIRST -> sortBy { auditLogEntry -> auditLogEntry.creationTimestamp }
   }
 }
+
+/**
+ * Enum class used to define the build variant of the library.
+ * For debugging purposes.
+ */
+public enum class BuildVariant(public val variant: String) {
+  RELEASE("RELEASE"),
+  DEBUG("DEBUG"),
+  ;
+
+  internal companion object {
+    internal fun of(variant: String): BuildVariant = when (variant) {
+      "RELEASE" -> RELEASE
+      "DEBUG" -> DEBUG
+      else -> throw IllegalArgumentException("Invalid build variant: $variant")
+    }
+  }
+}

temerity/src/commonMain/kotlin/edu/ucsc/its/temerity/core/Temerity.kt

@@ -27,6 +27,11 @@ import com.skydoves.sandwich.onSuccess
 import edu.ucsc.its.temerity.AuditLogSortOrder
 import edu.ucsc.its.temerity.AuditLogSortOrder.NEW_FIRST
 import edu.ucsc.its.temerity.BuildConfig
+import edu.ucsc.its.temerity.BuildConfig.BUILD_DATE
+import edu.ucsc.its.temerity.BuildConfig.BUILD_TIMEZONE
+import edu.ucsc.its.temerity.BuildConfig.BUILD_VARIANT
+import edu.ucsc.its.temerity.BuildConfig.LIB_VERSION
+import edu.ucsc.its.temerity.BuildVariant
 import edu.ucsc.its.temerity.TemClientConfig
 import edu.ucsc.its.temerity.TemerityApi
 import edu.ucsc.its.temerity.api.PlatformApi
@@ -71,7 +76,9 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.withContext
 import kotlinx.datetime.DateTimeUnit
 import kotlinx.datetime.LocalDate
+import kotlinx.datetime.LocalDateTime
 import kotlinx.datetime.LocalTime
+import kotlinx.datetime.TimeZone
 import kotlinx.datetime.minus
 import kotlinx.serialization.SerializationException
 import kotlinx.serialization.json.Json
@@ -109,6 +116,11 @@ public class Temerity internal constructor(
    */
   internal constructor(temApiToken: String) : this(TemClientConfig.withToken(temApiToken))
 
+  /**
+   * The following are the static public properties and utility functions of the Temerity library.
+   * They should also be provided by any re-implementations of the library as companion object fields as well,
+   * to allow for easy access to the version and build information without creating an instance of the library.
+   */
   public companion object {
     @JvmStatic
     public val DEFAULT_WEB_TIMEOUT: Duration = 2.minutes
@@ -131,13 +143,55 @@ public class Temerity internal constructor(
       supportKtxNotebook = supportKtxNotebook,
     )
 
+    /**
+     * Get the current date as a [LocalDate] object
+     * @return The current date as a [LocalDate] object
+     */
     @JvmStatic
     @Suppress("MemberVisibilityCanBePrivate")
     public fun currentDate(): LocalDate = DateTimeExt.currentDate()
 
+    /**
+     * Get the current time as a [LocalTime] object
+     * @return The current time as a [LocalTime] object
+     */
     @JvmStatic
     @Suppress("MemberVisibilityCanBePrivate")
     public fun currentTime(): LocalTime = DateTimeExt.currentTime()
+
+    /**
+     * The version of the Temerity library.
+     * This is updated with each release of the library and should not be modified.
+     * @return The version of the Temerity library as a semantic versioning-formatted [String]
+     */
+    @JvmStatic
+    @Suppress("MemberVisibilityCanBePrivate")
+    public val version: String = LIB_VERSION
+
+    /**
+     * The date & time when the Temerity library was built.
+     * @return The date & time when the Temerity library was built as a [LocalDateTime] object
+     */
+    @JvmStatic
+    @Suppress("MemberVisibilityCanBePrivate")
+    public val buildDate: LocalDateTime = LocalDateTime.parse(BUILD_DATE)
+
+    /**
+     * The timezone where the library was built.
+     * @return The timezone where the library was built as a [TimeZone] object
+     */
+    @JvmStatic
+    @Suppress("MemberVisibilityCanBePrivate")
+    public val buildTimeZone: TimeZone = TimeZone.of(BUILD_TIMEZONE)
+
+    /**
+     * The build variant of the library.
+     * Either [BuildVariant.DEBUG] or [BuildVariant.RELEASE].
+     * @return The build variant of the library as a [BuildVariant] enum
+     */
+    @JvmStatic
+    @Suppress("MemberVisibilityCanBePrivate")
+    public val buildVariant: BuildVariant = BuildVariant.valueOf(BUILD_VARIANT)
   }
 
   /**
@@ -173,8 +227,6 @@ public class Temerity internal constructor(
     abstract val logger: KermitLogger
   }
 
-  override val version: String = BuildConfig.LIB_VERSION
-
   /**
    * Kotlinx-serialization [Json] encoder/decoder object used for serializing/deserializing JSON object responses
    */

temerity/src/commonMain/kotlin/edu/ucsc/its/temerity/extensions/datetime/DateTimeExt.kt

@@ -29,7 +29,9 @@ internal object DateTimeExt {
 
   internal fun thisInstant() = Clock.System.now()
 
+  // TODO: Allow user to change TZ config
   internal fun currentDate(): LocalDate = Clock.System.todayIn(currentTz())
 
+  // TODO: Allow user to change TZ config
   internal fun currentTime(): LocalTime = thisInstant().toLocalDateTime(currentTz()).time
 }