Fix incomplete Portal intent documentation and add validation (#310)

Update PHPDoc to include missing intent values (certificate_renewal,
domain_verification) and add runtime validation for $intent parameter
to provide better error messages before API calls. Includes test
coverage for all intent values and invalid intent handling.

Fixes #295

Author: blobaugh

lib/Portal.php

@@ -13,18 +13,33 @@ class Portal
      * Generate a Portal Link scoped to an Organization.
      *
      * @param string $organization An Organization identifier.
-     * @param string $intent The intent of the Admin Portal. Possible values are ["audit_logs", "dsync", "log_streams", "sso",].
+     * @param string $intent The intent of the Admin Portal. Possible values are ["audit_logs", "certificate_renewal", "domain_verification", "dsync", "log_streams", "sso"].
      * @param null|string $returnUrl The URL to which WorkOS should send users when they click on
      *      the link to return to your website. (Optional).
      * @param null|string $successUrl The URL to which WorkOS will redirect users to
      *      upon successfully setting up Single Sign On or Directory Sync. (Optional).
      *
+     * @throws Exception\UnexpectedValueException
      * @throws Exception\WorkOSException
      *
      * @return Resource\PortalLink
      */
     public function generateLink($organization, $intent, ?string $returnUrl = null, ?string $successUrl = null)
     {
+        $validIntents = [
+            'audit_logs',
+            'certificate_renewal',
+            'domain_verification',
+            'dsync',
+            'log_streams',
+            'sso'
+        ];
+
+        if (!in_array($intent, $validIntents)) {
+            $msg = "Invalid intent. Valid values are: " . implode(", ", $validIntents);
+            throw new Exception\UnexpectedValueException($msg);
+        }
+
         $generateLinkPath = "portal/generate_link";
         $params = [
             "organization" => $organization,

tests/WorkOS/PortalTest.php

@@ -135,6 +135,70 @@ public function testGenerateLinkLogStreams()
         $this->assertSame($expectation, $response->link);
     }
 
+    public function testGenerateLinkCertificateRenewal()
+    {
+        $generateLinkPath = "portal/generate_link";
+
+        $result = $this->generatePortalLinkFixture();
+
+        $params = [
+            "organization" => "org_01EHZNVPK3SFK441A1RGBFSHRT",
+            "intent" => "certificate_renewal",
+            "return_url" => null,
+            "success_url" => null
+        ];
+
+        $this->mockRequest(
+            Client::METHOD_POST,
+            $generateLinkPath,
+            null,
+            $params,
+            true,
+            $result
+        );
+
+        $expectation = "https://id.workos.com/portal/launch?secret=secret";
+
+        $response = $this->ap->generateLink("org_01EHZNVPK3SFK441A1RGBFSHRT", "certificate_renewal");
+        $this->assertSame($expectation, $response->link);
+    }
+
+    public function testGenerateLinkDomainVerification()
+    {
+        $generateLinkPath = "portal/generate_link";
+
+        $result = $this->generatePortalLinkFixture();
+
+        $params = [
+            "organization" => "org_01EHZNVPK3SFK441A1RGBFSHRT",
+            "intent" => "domain_verification",
+            "return_url" => null,
+            "success_url" => null
+        ];
+
+        $this->mockRequest(
+            Client::METHOD_POST,
+            $generateLinkPath,
+            null,
+            $params,
+            true,
+            $result
+        );
+
+        $expectation = "https://id.workos.com/portal/launch?secret=secret";
+
+        $response = $this->ap->generateLink("org_01EHZNVPK3SFK441A1RGBFSHRT", "domain_verification");
+        $this->assertSame($expectation, $response->link);
+    }
+
+    public function testGenerateLinkWithInvalidIntent()
+    {
+        $this->expectException(Exception\UnexpectedValueException::class);
+        $this->expectExceptionMessage("Invalid intent. Valid values are:");
+
+        $this->ap->generateLink("org_01EHZNVPK3SFK441A1RGBFSHRT", "invalid_intent");
+    }
+
     // Fixtures
 
     private function generatePortalLinkFixture()