Update src/integrations.datto.ps1

src/integrations.datto.ps1

@@ -1,3 +1,161 @@
+<#
+.SYNOPSIS
+Installs the Datto RMM agent and/or performs Datto RMM site operations using API or webhook-provided credentials.
+
+.DESCRIPTION
+Install-DattoRMM can obtain Datto RMM API credentials either directly (ApiUrl/ApiKey/ApiSecretKey) or via a webhook
+(-UseWebhook). It then acquires an OAuth token and can:
+- Fetch sites (-FetchSites), optionally saving the list to CSV/JSON (-SaveSitesList, -OutputFile)
+- Pull a site's variables and write them to the registry (-PushSiteVars, -SiteUID, -SiteName)
+- Download and launch the RMM agent installer for a site (-InstallRMM, -SiteUID, -SiteName)
+- Download and save a copy of the installer (-SaveCopy, -SiteUID)
+
+.PARAMETER UseWebhook
+If specified, retrieves API credentials from the webhook endpoint specified by -WebhookUrl.
+If not specified, -ApiUrl/-ApiKey/-ApiSecretKey must be provided.
+
+.PARAMETER WebhookPassword
+Optional shared secret sent as the SAMYPW header when calling the webhook.
+If null, it is treated as a blank string (intended for allowlisted IP flows).
+
+.PARAMETER WebhookUrl
+Webhook endpoint to retrieve Datto RMM API credentials. Defaults to $Global:DattoWebhookUrl.
+
+.PARAMETER ApiUrl
+Base URL of the Datto RMM instance (for example, https://rmm.example.com).
+Required when -UseWebhook is not specified.
+
+.PARAMETER ApiKey
+Datto RMM API key (used as the OAuth username in the token request).
+Required when -UseWebhook is not specified.
+
+.PARAMETER ApiSecretKey
+Datto RMM API secret key (used as the OAuth password in the token request).
+Required when -UseWebhook is not specified.
+
+.PARAMETER FetchSites
+If specified, fetches the full site list from the Datto RMM API and returns objects with Name and UID.
+
+.PARAMETER SaveSitesList
+If specified, saves the fetched site list to disk. Requires -FetchSites.
+The output format is determined by -OutputFile extension:
+- .csv (default): CSV output
+- .json: JSON output
+
+.PARAMETER OutputFile
+Filename to write when using -SaveSitesList. Defaults to 'datto_sites.csv'.
+The file is written to the current user's Desktop.
+
+.PARAMETER PushSiteVars
+If specified, fetches variables for the specified site and writes them to the registry at:
+HKLM:\Software\SVS\Deployment
+Requires -SiteUID. -SiteName is used for logging.
+
+.PARAMETER InstallRMM
+If specified, downloads the Datto RMM agent installer for -SiteUID to %TEMP%\AgentInstall.exe and launches it.
+Requires -SiteUID. -SiteName is used for logging. Respects ShouldProcess/Confirm.
+
+.PARAMETER SaveCopy
+If specified, downloads the Datto RMM agent installer for -SiteUID and saves it to:
+C:\Temp\AgentInstall.exe
+Requires -SiteUID.
+
+.PARAMETER SiteUID
+Datto RMM Site UID used for site-scoped operations such as variable fetch, agent download/install, and save-copy.
+
+.PARAMETER SiteName
+Friendly site name used for logging/output messages for site-scoped operations. Not required by the API calls.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites
+
+Fetches the full site list from the Datto RMM API and returns objects containing Name and UID.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList
+
+Fetches the site list and saves it as a CSV named "datto_sites.csv" on the current user's Desktop (default -OutputFile),
+then returns the site list.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList -OutputFile "sites.csv"
+
+Fetches the site list and saves it as "sites.csv" on the Desktop.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites -SaveSitesList -OutputFile "sites.json"
+
+Fetches the site list and saves it as JSON ("sites.json") on the Desktop.
+
+.EXAMPLE
+Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -WebhookPassword "SuperSecret" -FetchSites -SaveSitesList
+
+Uses the webhook endpoint to retrieve API credentials, then fetches sites and saves "datto_sites.csv" to the Desktop.
+
+.EXAMPLE
+Install-DattoRMM -UseWebhook -WebhookUrl "https://internal.example.com/datto-creds" -FetchSites
+
+Uses the webhook endpoint to retrieve API credentials, then fetches and returns the site list.
+
+.EXAMPLE
+Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -FetchSites -SaveSitesList -OutputFile "customer_sites.csv"
+
+Same as the other webhook fetch, but writes the CSV as "customer_sites.csv" on the Desktop.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -PushSiteVars -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ"
+
+Fetches variables for the specified site and writes each variable name/value into:
+HKLM:\Software\SVS\Deployment
+
+.EXAMPLE
+Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -PushSiteVars -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ"
+
+Uses webhook-sourced credentials, then fetches and writes site variables to the registry.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ"
+
+Downloads the agent installer for the specified SiteUID to %TEMP%\AgentInstall.exe and launches it.
+Because SupportsShouldProcess is enabled, this may prompt unless -Confirm:$false is used.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" -Confirm:$false
+
+Installs the agent without prompting for confirmation.
+
+.EXAMPLE
+Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -InstallRMM -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab" -SiteName "Toronto-HQ" -Confirm:$false
+
+Uses webhook credentials, downloads the installer, and launches it without confirmation.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -SaveCopy -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab"
+
+Downloads the agent installer and saves a copy to:
+C:\Temp\AgentInstall.exe
+
+.EXAMPLE
+Install-DattoRMM -UseWebhook -WebhookUrl $Global:DattoWebhookUrl -SaveCopy -SiteUID "12345678-aaaa-bbbb-cccc-1234567890ab"
+
+Uses webhook credentials, then downloads and saves the installer copy to C:\Temp\AgentInstall.exe.
+
+.EXAMPLE
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET"
+
+If no action switch is specified (-FetchSites, -PushSiteVars, -InstallRMM, or -SaveCopy),
+the function logs a warning indicating that no action was selected.
+
+.EXAMPLE
+# Get the site list, then pick a site and install using its UID
+$sites = Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -FetchSites
+$site  = $sites | Where-Object Name -like "*Toronto*" | Select-Object -First 1
+Install-DattoRMM -ApiUrl "https://rmm.example.com" -ApiKey "APIKEY" -ApiSecretKey "SECRET" -InstallRMM -SiteUID $site.UID -SiteName $site.Name -Confirm:$false
+
+Demonstrates a common flow: fetch sites, select one, then install the agent for that site.
+#>
+
+
 function Install-DattoRMM {
     [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium')]
     param (