A free open source IT asset/license management system
<?php
namespace App\SyncAdapters\Addigy;
use App\SyncAdapters\Traits\RetriesTransientHttpErrors;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;
/**
* Thin wrapper around the Addigy API v2. Handles auth for the pull +
* push endpoints the sync adapter uses. Yields raw decoded JSON, no
* normalization (that's the adapter's job).
*
* Auth model: a single API key generated in the Addigy admin console
* under Integrations -> Addigy API. Passed in the `x-api-key` header
* on every request. Replaces v1's client-id + client-secret header
* pair, which Addigy retired in June 2026.
*
* The devices listing endpoint is a paginated POST ("Universal Search
* Devices"). We page by `page` + `per_page` and dig values out of each
* record's `facts` map keyed by fact identifier. The adapter owns the
* list of fact identifiers it wants. This client just hands them to
* `desired_fact_identifiers` on the request body and streams the
* decoded response pages back.
*
* Addigy API reference: https://api.addigy.com/api/v2/documentation/
*/
class AddigyClient
{
use RetriesTransientHttpErrors;
/**
* Addigy v2 lives at a fixed host. The admin doesn't configure
* the base URL on the adapter form (usesConfigurableUrl() = false),
* so we hardcode it here rather than threading it through the
* constructor from a non-existent credential.
*/
private const BASE_URL = 'https://api.addigy.com/api/v2';
/**
* Default page size for the paginated POST /devices endpoint.
* 100 matches what Addigy's console uses and keeps each page small
* enough to decode without pressure on the PHP memory limit.
*/
private const DEFAULT_PER_PAGE = 100;
public function __construct(
private readonly string $apiKey,
) {}
/**
* List every enrolled device in the Addigy tenant. Yields decoded
* device records (DeviceAudit shape: `agentid`, `orgid`,
* `audit_date`, `facts` keyed by identifier) one at a time so the
* caller can normalize + persist each without buffering the whole
* tenant.
*
* @param list<string> $desiredFactIdentifiers fact names to request on every device
* @return iterable<array<string, mixed>>
*/
public function devices(array $desiredFactIdentifiers): iterable
{
$page = 1;
while (true) {
$response = $this->request()
->post('/devices', [
'desired_fact_identifiers' => $desiredFactIdentifiers,
'page' => $page,
'per_page' => self::DEFAULT_PER_PAGE,
])
->throw()
->json();
$items = is_array($response['items'] ?? null) ? $response['items'] : [];
if ($items === []) {
return;
}
foreach ($items as $device) {
yield $device;
}
// Metadata.page_count is total number of pages. Stop when
// we've drained the last one. Fallback: if the server
// doesn't echo page_count, break when a page comes back
// with fewer items than we asked for.
$pageCount = (int) ($response['metadata']['page_count'] ?? 0);
if ($pageCount > 0 && $page >= $pageCount) {
return;
}
if ($pageCount === 0 && count($items) < self::DEFAULT_PER_PAGE) {
return;
}
$page++;
}
}
/**
* List every Policy in the Addigy tenant. Used by the adapter's
* fetchGroups() so admins can map Policies to Snipe-IT companies.
* Policies are Addigy's device-grouping concept. MSPs often use
* them as customer proxies.
*
* v2 moved policy listing to a POST with a filter body. An empty
* `policies` array in the body returns every policy.
*
* @return array<int, array<string, mixed>>
*/
public function policies(): array
{
$response = $this->request()
->post('/oa/policies/query', ['policies' => []])
->throw()
->json();
if (is_array($response['items'] ?? null)) {
return $response['items'];
}
return is_array($response) ? $response : [];
}
/**
* Rename an Addigy device via the Set Device Name MDM command.
* Addigy's doc: "available only on supervised devices or devices
* running macOS 10.10 or later". On macOS the command sets only
* the computer name and local hostname. iOS/iPadOS requires
* supervision. Addigy's response is an MDM command receipt, not a
* synchronous device state change.
*/
public function setDeviceName(string $agentId, string $deviceName): void
{
$this->request()
->post('/mdm/settings/device/name', [
'agent_id' => $agentId,
'device_name' => $deviceName,
])
->throw();
}
/**
* Resolve an Addigy end-user by email. Addigy's end-user query
* takes a free-form `search` string so an exact-email match isn't
* guaranteed. We filter the paged response client-side to pick
* only entries whose `emails[*].value` matches the queried email
* exactly (case-insensitive), returning the single id when
* exactly one survives and null for zero or multi-match. The
* caller logs the skip reason.
*/
public function findEndUserIdByEmail(string $organizationId, string $email): ?string
{
$response = $this->request()
->post('/o/'.$organizationId.'/end-users/query', [
'page' => 1,
'per_page' => 100,
'query' => ['search' => $email],
])
->throw()
->json();
$items = is_array($response['items'] ?? null) ? $response['items'] : [];
$matches = [];
foreach ($items as $item) {
if (! is_array($item) || empty($item['id'])) {
continue;
}
$emails = is_array($item['emails'] ?? null) ? $item['emails'] : [];
foreach ($emails as $entry) {
$value = is_array($entry) ? ($entry['value'] ?? null) : null;
if (is_string($value) && strcasecmp($value, $email) === 0) {
$matches[] = (string) $item['id'];
break;
}
}
}
$unique = array_values(array_unique($matches));
return count($unique) === 1 ? $unique[0] : null;
}
/**
* Assign a device to an Addigy end user. Addigy requires both the
* agent id (device) and the end-user id (resolved separately via
* findEndUserIdByEmail).
*/
public function assignDeviceToEndUser(string $organizationId, string $agentId, string $endUserId): void
{
$this->request()
->post('/o/'.$organizationId.'/end-users/devices', [
'agent_id' => $agentId,
'end_user_id' => $endUserId,
])
->throw();
}
private function request(): PendingRequest
{
return $this->withTransientRetry(
Http::baseUrl(self::BASE_URL)
->withOptions(['allow_redirects' => false])
->withHeaders(['x-api-key' => $this->apiKey])
->acceptJson()
->asJson()
->timeout(30)
);
}
}