feat(cli): add inbox email commands (MR !20486)

https://gitlab.com/escape.tech/product/-/merge_requests/20486

Author: QuentinN42

README.md

@@ -39,6 +39,9 @@ export ESCAPE_API_KEY=your_api_key_here
 # Start a scan and wait for results
 escape-cli scans start <profile-id> --watch
 
+# List emails received by a scan inbox
+escape-cli emails list --email test.00000000-0000-0000-0000-000000000000@scan.escape.tech
+
 # Review discovered issues
 escape-cli issues list --severity CRITICAL,HIGH --status OPEN
 ```
@@ -71,6 +74,7 @@ Optional inputs: `schema` (path or URL to update the API schema before the scan)
 
 ```text
 scans       Run and manage security scans
+emails      List and read scan inbox emails
 issues      Manage and track security vulnerabilities
 problems    View scan problems and failures
 profiles    Configure security testing profiles

helm/Chart.yaml

@@ -3,5 +3,5 @@ apiVersion: v2
 name: private-location
 description: Escape Private Location
 type: application
-version: 1.1.1
-appVersion: 1.1.1
+version: 1.2.0
+appVersion: 1.2.0

pkg/api/escape/emails.go

@@ -0,0 +1,73 @@
+package escape
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	v3 "github.com/Escape-Technologies/cli/pkg/api/v3"
+)
+
+// ListInboxEmailsFilters holds the supported inbox email list filters.
+type ListInboxEmailsFilters struct {
+	Email  string
+	IDs    []string
+	Before *time.Time
+	After  *time.Time
+	Size   int
+}
+
+// ListInboxEmails lists inbox emails for a target scan email address.
+func ListInboxEmails(ctx context.Context, cursor string, filters *ListInboxEmailsFilters) (*v3.ListInboxEmails200Response, error) {
+	if filters == nil {
+		return nil, errors.New("email is required")
+	}
+	email := strings.TrimSpace(filters.Email)
+	if email == "" {
+		return nil, errors.New("email is required")
+	}
+
+	client, err := newAPIV3Client()
+	if err != nil {
+		return nil, fmt.Errorf("unable to init client: %w", err)
+	}
+
+	req := client.EmailsAPI.ListInboxEmails(ctx).Email(email)
+	if cursor != "" {
+		req = req.Cursor(cursor)
+	}
+	if filters.Size > 0 {
+		req = req.Size(filters.Size)
+	}
+	if len(filters.IDs) > 0 {
+		req = req.Ids(strings.Join(filters.IDs, ","))
+	}
+	if filters.Before != nil {
+		req = req.Before(*filters.Before)
+	}
+	if filters.After != nil {
+		req = req.After(*filters.After)
+	}
+
+	data, _, err := req.Execute()
+	if err != nil {
+		return nil, fmt.Errorf("unable to list inbox emails: %w", err)
+	}
+	return data, nil
+}
+
+// ReadInboxEmail reads the full raw content of an inbox email by ID.
+func ReadInboxEmail(ctx context.Context, id string) (*v3.ScanEmailDetails, error) {
+	client, err := newAPIV3Client()
+	if err != nil {
+		return nil, fmt.Errorf("unable to init client: %w", err)
+	}
+
+	data, _, err := client.EmailsAPI.ReadInboxEmail(ctx, id).Execute()
+	if err != nil {
+		return nil, fmt.Errorf("unable to read inbox email: %w", err)
+	}
+	return data, nil
+}

pkg/cli/cmd/capabilities.go

@@ -88,6 +88,9 @@ func commandSchemaRegistry() map[string]commandSchemas {
 		"escape-cli scans watch":                   {output: v3.ScanDetailed1{}},
 		"escape-cli scans issues":                  {output: []v3.IssueSummarized{}},
 		"escape-cli scans targets":                 {output: []v3.TargetDetailed{}},
+		"escape-cli emails list":                   {output: []v3.ScanEmailSummary{}},
+		"escape-cli emails read":                   {output: v3.ScanEmailDetails{}},
+		"escape-cli emails wait":                   {output: v3.ScanEmailDetails{}},
 		"escape-cli authentications start":         {input: v3.StartAuthenticationRequest{}, output: v3.StartAuthentication200Response{}},
 		"escape-cli authentications get":           {output: v3.GetAuthentication200Response{}},
 		"escape-cli jobs trigger-export":           {output: v3.TriggerExport200Response{}},