Add events and API changes for invitations and Magic Auth (#221)

* Add events and API changes for invitations and Magic Auth

* Fix failing test

* Rename event data

Author: blairworkos

src/main/kotlin/com/workos/usermanagement/UserManagementApi.kt

@@ -20,12 +20,14 @@ import com.workos.usermanagement.models.EnrolledAuthenticationFactor
 import com.workos.usermanagement.models.Identity
 import com.workos.usermanagement.models.Invitation
 import com.workos.usermanagement.models.Invitations
+import com.workos.usermanagement.models.MagicAuth
 import com.workos.usermanagement.models.OrganizationMembership
 import com.workos.usermanagement.models.OrganizationMemberships
 import com.workos.usermanagement.models.RefreshAuthentication
 import com.workos.usermanagement.models.User
 import com.workos.usermanagement.models.Users
 import com.workos.usermanagement.types.AuthenticationAdditionalOptions
+import com.workos.usermanagement.types.CreateMagicAuthOptions
 import com.workos.usermanagement.types.CreateOrganizationMembershipOptions
 import com.workos.usermanagement.types.CreateUserOptions
 import com.workos.usermanagement.types.EnrolledAuthenticationFactorOptions
@@ -213,10 +215,29 @@ class UserManagementApi(private val workos: WorkOS) {
       .toString()
   }
 
+  /**
+   * Get the details of an existing Magic Auth code.
+   */
+  fun getMagicAuth(id: String): MagicAuth {
+    return workos.get("/user_management/magic_auth/$id", MagicAuth::class.java)
+  }
+
+  /**
+   * Creates a Magic Auth code that can be used to authenticate into your app.
+   */
+  fun createMagicAuth(options: CreateMagicAuthOptions): MagicAuth {
+    return workos.post(
+      "/user_management/magic_auth",
+      MagicAuth::class.java,
+      RequestConfig.builder().data(options).build()
+    )
+  }
+
   /**
    * Sends a one-time authentication code to the user’s email address. The code
    * expires in 10 minutes. To verify the code, authenticate the user with Magic Auth.
    */
+  @Deprecated("Please use `createMagicAuth` instead. This method will be removed in a future major version.")
   fun sendMagicAuthCode(email: String) {
     workos.post(
       "/user_management/magic_auth/send",

src/main/kotlin/com/workos/usermanagement/builders/CreateMagicAuthOptionsBuilder.kt

@@ -0,0 +1,39 @@
+package com.workos.usermanagement.builders
+
+import com.workos.usermanagement.types.CreateMagicAuthOptions
+
+/**
+ * Builder for options when creating a Magic Auth code.
+ *
+ * @param email The email address of the user.
+ * @param invitationToken The token of an invitation, if required.
+ */
+class CreateMagicAuthOptionsBuilder @JvmOverloads constructor(
+  private var email: String,
+  private var invitationToken: String? = null,
+) {
+  /**
+   * Invitation Token
+   */
+  fun invitationToken(value: String) = apply { invitationToken = value }
+
+  /**
+   * Generates the CreateMagicAuthOptions object.
+   */
+  fun build(): CreateMagicAuthOptions {
+    return CreateMagicAuthOptions(
+      email = this.email,
+      invitationToken = this.invitationToken,
+    )
+  }
+
+  /**
+   * @suppress
+   */
+  companion object {
+    @JvmStatic
+    fun create(email: String): CreateMagicAuthOptionsBuilder {
+      return CreateMagicAuthOptionsBuilder(email)
+    }
+  }
+}

src/main/kotlin/com/workos/usermanagement/models/Invitation.kt

@@ -16,6 +16,7 @@ import com.workos.usermanagement.types.InvitationStateEnumType
  * @param revokedAt The timestamp when the invitation was revoked.
  * @param expiresAt The timestamp when the invitation will expire.
  * @param token The token of an invitation.
+ * @param acceptInvitationUrl The URL where the user can accept the invitation.
  * @param organizationId The ID of the organization.
  * @param createdAt The timestamp when the invitation was created.
  * @param updatedAt The timestamp when the invitation was last updated.
@@ -42,6 +43,9 @@ data class Invitation @JsonCreator constructor(
   @JsonProperty("token")
   val token: String,
 
+  @JsonProperty("accept_invitation_url")
+  val acceptInvitationUrl: String,
+
   @JsonProperty("organization_id")
   val organizationId: String? = null,
 

src/main/kotlin/com/workos/usermanagement/models/InvitationEventData.kt

@@ -0,0 +1,49 @@
+package com.workos.usermanagement.models
+
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonProperty
+import com.workos.usermanagement.types.InvitationStateEnumType
+
+/**
+ * An email invitation allows the recipient to sign up for your app and join a
+ * specific organization. When an invitation is accepted, a user and a
+ * corresponding organization membership are created.
+ *
+ * @param id The unique ID of the invitation.
+ * @param email The email address of the user.
+ * @param state The state of the invitation (see enum values in [InvitationStateEnumType]).
+ * @param acceptedAt The timestamp when the invitation was accepted.
+ * @param revokedAt The timestamp when the invitation was revoked.
+ * @param expiresAt The timestamp when the invitation will expire.
+ * @param organizationId The ID of the organization.
+ * @param createdAt The timestamp when the invitation was created.
+ * @param updatedAt The timestamp when the invitation was last updated.
+ */
+data class InvitationEventData @JsonCreator constructor(
+  @JsonProperty("id")
+  val id: String,
+
+  @JsonProperty("email")
+  val email: String,
+
+  @JsonProperty("state")
+  val state: InvitationStateEnumType,
+
+  @JsonProperty("accepted_at")
+  val acceptedAt: String? = null,
+
+  @JsonProperty("revoked_at")
+  val revokedAt: String? = null,
+
+  @JsonProperty("expires_at")
+  val expiresAt: String,
+
+  @JsonProperty("organization_id")
+  val organizationId: String? = null,
+
+  @JsonProperty("created_at")
+  val createdAt: String,
+
+  @JsonProperty("updated_at")
+  val updatedAt: String
+)

src/main/kotlin/com/workos/usermanagement/models/MagicAuth.kt

@@ -0,0 +1,38 @@
+package com.workos.usermanagement.models
+
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonProperty
+
+/**
+ * A Magic Auth code that allows the recipient to authenticate to your app
+ *
+ * @param id The unique ID of the Magic Auth code.
+ * @param userId The unique ID of the user.
+ * @param email The email address of the user.
+ * @param expiresAt The timestamp when the Magic Auth code will expire.
+ * @param code The Magic Auth code.
+ * @param createdAt The timestamp when the Magic Auth code was created.
+ * @param updatedAt The timestamp when the Magic Auth code was last updated.
+ */
+data class MagicAuth @JsonCreator constructor(
+  @JsonProperty("id")
+  val id: String,
+
+  @JsonProperty("user_id")
+  val userId: String,
+
+  @JsonProperty("email")
+  val email: String,
+
+  @JsonProperty("expires_at")
+  val expiresAt: String,
+
+  @JsonProperty("code")
+  val code: String,
+
+  @JsonProperty("created_at")
+  val createdAt: String,
+
+  @JsonProperty("updated_at")
+  val updatedAt: String
+)

src/main/kotlin/com/workos/usermanagement/models/MagicAuthEventData.kt

@@ -0,0 +1,34 @@
+package com.workos.usermanagement.models
+
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonProperty
+
+/**
+ * A Magic Auth code that allows the recipient to authenticate to your app
+ *
+ * @param id The unique ID of the Magic Auth code.
+ * @param userId The unique ID of the user.
+ * @param email The email address of the user.
+ * @param expiresAt The timestamp when the Magic Auth code will expire.
+ * @param createdAt The timestamp when the Magic Auth code was created.
+ * @param updatedAt The timestamp when the Magic Auth code was last updated.
+ */
+data class MagicAuthEventData @JsonCreator constructor(
+  @JsonProperty("id")
+  val id: String,
+
+  @JsonProperty("user_id")
+  val userId: String,
+
+  @JsonProperty("email")
+  val email: String,
+
+  @JsonProperty("expires_at")
+  val expiresAt: String,
+
+  @JsonProperty("created_at")
+  val createdAt: String,
+
+  @JsonProperty("updated_at")
+  val updatedAt: String
+)

src/main/kotlin/com/workos/usermanagement/types/CreateMagicAuthOptions.kt

@@ -0,0 +1,21 @@
+package com.workos.usermanagement.types
+
+import com.fasterxml.jackson.annotation.JsonProperty
+
+class CreateMagicAuthOptions(
+  /**
+   * The email address of the user.
+   */
+  @JsonProperty("email")
+  val email: String,
+
+  /**
+   * The token of an invitation, if required.
+   */
+  @JsonProperty("invitation_token")
+  val invitationToken: String? = null,
+) {
+  init {
+    require(email.isNotBlank()) { "Email is required" }
+  }
+}

src/main/kotlin/com/workos/webhooks/models/EventType.kt

@@ -81,11 +81,21 @@ enum class EventType(
    */
   DirectoryGroupDeleted("dsync.group.deleted"),
 
+  /**
+   * Triggers when a user is invited to sign up or to join an organization.
+   */
+  InvitationCreated("invitation.created"),
+
   /**
    * Triggers when an organization membership is created.
    */
   OrganizationMembershipCreated("organization_membership.created"),
 
+  /**
+   * Triggers when a user initiates Magic Auth and an authentication code is created.
+   */
+  MagicAuthCreated("magic_auth.created"),
+
   /**
    * Triggers when an organization membership is deleted.
    */

src/main/kotlin/com/workos/webhooks/models/InvitationEvent.kt

@@ -0,0 +1,20 @@
+package com.workos.webhooks.models
+
+import com.workos.usermanagement.models.InvitationEventData
+
+/**
+ * Webhook Event for `invitation.*` events.
+ */
+class InvitationEvent(
+  @JvmField
+  override val id: String,
+
+  @JvmField
+  override val event: EventType,
+
+  @JvmField
+  override val data: InvitationEventData,
+
+  @JvmField
+  override val createdAt: String
+) : WebhookEvent(id, event, data, createdAt)

src/main/kotlin/com/workos/webhooks/models/MagicAuthEvent.kt

@@ -0,0 +1,20 @@
+package com.workos.webhooks.models
+
+import com.workos.usermanagement.models.MagicAuthEventData
+
+/**
+ * Webhook Event for `magic_auth.*` events.
+ */
+class MagicAuthEvent(
+  @JvmField
+  override val id: String,
+
+  @JvmField
+  override val event: EventType,
+
+  @JvmField
+  override val data: MagicAuthEventData,
+
+  @JvmField
+  override val createdAt: String
+) : WebhookEvent(id, event, data, createdAt)