From 21f6185c2c66178e1f2fe7c0109bf9d23484c023 Mon Sep 17 00:00:00 2001
From: Ivan Tustanivskyi <tustanivsky@gmail.com>
Date: Thu, 2 Jul 2026 16:41:31 +0300
Subject: [PATCH] Add session replay API helpers

Add Get-SentryReplay to the Sentry API client (fetches a replay
instance via /projects/{org}/{project}/replays/{replay_id}/) and a
Get-SentryTestReplay polling wrapper for integration tests, following
the existing event/log/metric helper patterns.

Needed by sentry-unreal session replay integration tests.
---
 sentry-api-client/Public/Get-SentryReplay.ps1 | 37 ++++++++++++++
 sentry-api-client/SentryApiClient.psd1        |  1 +
 utils/Integration.TestUtils.psm1              | 51 ++++++++++++++++++-
 3 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 sentry-api-client/Public/Get-SentryReplay.ps1

diff --git a/sentry-api-client/Public/Get-SentryReplay.ps1 b/sentry-api-client/Public/Get-SentryReplay.ps1
new file mode 100644
index 0000000..d968d8d
--- /dev/null
+++ b/sentry-api-client/Public/Get-SentryReplay.ps1
@@ -0,0 +1,37 @@
+function Get-SentryReplay {
+    <#
+    .SYNOPSIS
+    Retrieves a specific session replay from Sentry.
+
+    .DESCRIPTION
+    Fetches detailed information about a specific Sentry session replay by its ID
+    (duration, segment count, associated trace IDs, timestamps, etc.).
+    Automatically removes hyphens from GUID-formatted replay IDs.
+
+    .PARAMETER ReplayId
+    The unique identifier of the replay to retrieve. Can be provided with or without hyphens.
+
+    .EXAMPLE
+    Get-SentryReplay -ReplayId "7acc9c0d4a2e0a85187fe9b75e6b05ac"
+    # Retrieves the replay with the given ID
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ReplayId
+    )
+
+    # Remove hyphens from GUID-formatted replay IDs
+    $ReplayId = $ReplayId -replace '-', ''
+
+    $Uri = Get-SentryProjectUrl -Resource "replays/$ReplayId/"
+
+    $Response = Invoke-SentryApiRequest -Uri $Uri -Method 'GET'
+
+    # The replay instance endpoint wraps the payload in a 'data' envelope
+    if ($Response -is [hashtable] -and $Response.ContainsKey('data')) {
+        return $Response.data
+    }
+
+    return $Response
+}
diff --git a/sentry-api-client/SentryApiClient.psd1 b/sentry-api-client/SentryApiClient.psd1
index cda7ffe..a3aa9a7 100644
--- a/sentry-api-client/SentryApiClient.psd1
+++ b/sentry-api-client/SentryApiClient.psd1
@@ -40,6 +40,7 @@
         'Get-SentryLogsByAttribute',
         'Get-SentryMetrics',
         'Get-SentryMetricsByAttribute',
+        'Get-SentryReplay',
         'Get-SentrySpans',
         'Invoke-SentryCLI'
     )
diff --git a/utils/Integration.TestUtils.psm1 b/utils/Integration.TestUtils.psm1
index 6ef4dc6..588b790 100644
--- a/utils/Integration.TestUtils.psm1
+++ b/utils/Integration.TestUtils.psm1
@@ -514,5 +514,54 @@ function Get-SentryTestEventAttachments {
     throw "Expected at least $ExpectedCount attachment(s) for event $EventId but found $foundCount within $TimeoutSeconds seconds. Last error: $lastError"
 }
 
+function Get-SentryTestReplay {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$ReplayId,
+
+        [Parameter()]
+        [int]$TimeoutSeconds = 300
+    )
+
+    Write-Host "Fetching Sentry replay by ID: $ReplayId" -ForegroundColor Yellow
+    $progressActivity = "Waiting for Sentry replay $ReplayId"
+
+    $startTime = Get-Date
+    $endTime = $startTime.AddSeconds($TimeoutSeconds)
+    $lastError = $null
+    $elapsedSeconds = 0
+
+    try {
+        do {
+            $sentryReplay = $null
+            $elapsedSeconds = [int]((Get-Date) - $startTime).TotalSeconds
+            $percentComplete = [math]::Min(100, ($elapsedSeconds / $TimeoutSeconds) * 100)
+
+            Write-Progress -Activity $progressActivity -Status "Elapsed: $elapsedSeconds/$TimeoutSeconds seconds" -PercentComplete $percentComplete
+
+            try {
+                $sentryReplay = Get-SentryReplay -ReplayId $ReplayId
+            } catch {
+                $lastError = $_.Exception.Message
+                Write-Debug "Replay $ReplayId not found yet: $lastError"
+            }
+
+            if ($sentryReplay) {
+                Write-Host "Replay $($sentryReplay.id) fetched from Sentry" -ForegroundColor Green
+                $sentryReplay | ConvertTo-Json -Depth 10 | Out-File -FilePath (Get-OutputFilePath "replay-$($sentryReplay.id).json")
+                return $sentryReplay
+            }
+
+            Start-Sleep -Milliseconds 500
+            $currentTime = Get-Date
+        } while ($currentTime -lt $endTime)
+    } finally {
+        Write-Progress -Activity $progressActivity -Completed
+    }
+
+    throw "Replay $ReplayId not found in Sentry within $TimeoutSeconds seconds: $lastError"
+}
+
 # Export module functions
-Export-ModuleMember -Function Invoke-CMakeConfigure, Invoke-CMakeBuild, Set-OutputDir, Get-OutputFilePath, Get-EventIds, Get-SentryTestEvent, Get-SentryTestEventAttachments, Get-SentryTestLog, Get-SentryTestMetric, Get-SentryTestTransaction, Get-PackageAumid
+Export-ModuleMember -Function Invoke-CMakeConfigure, Invoke-CMakeBuild, Set-OutputDir, Get-OutputFilePath, Get-EventIds, Get-SentryTestEvent, Get-SentryTestEventAttachments, Get-SentryTestLog, Get-SentryTestMetric, Get-SentryTestTransaction, Get-SentryTestReplay, Get-PackageAumid