README

A modular, resilient, and type-safe PHP SDK for interacting with the ConnectWise PSA REST API. Built for modern PHP 8.3+ applications, with first-class support for Symfony and PSR standards.

Features

Modular Architecture: Middleware-based pipeline (Onion Model) for easy extension.
Resilient by Design: Intelligent retry policy with exponential backoff and jitter; respects Retry-After headers.
Multiple Auth Strategies: Support for standard API Keys and Member Hash (Hosted API/Pods) authentication.
Fluent Query Builder: Abstract away complex PSA query syntax with PsaCriteria.
Automated Pagination: Lazy-loading PsaIterator for both Navigable and high-performance Forward-Only paging.
Functional Results: Either-style PsaResult container for clean, exception-free logic.
Security: Automatic redaction of sensitive data in logs and source verification for webhooks.

Installation

composer require ncbp/psa-api-client

Quick Start

Basic Initialization (API Key)

use NCBP\Integration\ConnectWise\Psa\ApiClient\Core\PsaClient;
use NCBP\Integration\ConnectWise\Psa\ApiClient\Authentication\PsaApiKeyAuthenticator;
use Symfony\Component\HttpClient\HttpClient;

$httpClient = HttpClient::create();
$authenticator = new PsaApiKeyAuthenticator('your-company', 'public-key', 'private-key');

$client = new PsaClient(
    $httpClient,
    $authenticator,
    'https://na.myconnectwise.net',
    'your-client-id'
);

Automatic Environment Discovery

If you don't know the specific codebase or site URL for a partner:

$result = PsaClient::createDiscovered(
    $httpClient,
    $authenticator,
    'na.myconnectwise.net',
    'your-company',
    'your-client-id'
);

if ($result->isSuccess()) {
    $client = $result->value();
}

Usage

Querying with Criteria

use NCBP\Integration\ConnectWise\Psa\ApiClient\Query\PsaCriteria;
use NCBP\Integration\ConnectWise\Psa\ApiClient\Query\PsaOperator;

$criteria = PsaCriteria::create()
    ->where('status/name', PsaOperator::NotEquals, 'Closed')
    ->whereContains('summary', 'Urgent')
    ->orderBy('dateCreated', 'desc')
    ->setPageSize(100);

$result = $client->get('service/tickets', $criteria);

if ($result->isSuccess()) {
    $tickets = $result->value();
    // Use the data...
}

Automated Pagination

Iterate through thousands of records without worrying about page boundaries. The PsaIterator will automatically fetch subsequent pages as you iterate.

$tickets = $client->paginate('service/tickets', $criteria);

// Check for errors before or after iteration
if ($error = $tickets->getLastError()) {
    echo "Pagination failed: " . $error->getMessage();
}

foreach ($tickets as $ticket) {
    echo $ticket['summary'] . PHP_EOL;
}

Functional Composition

Transform results cleanly using map() and onFailure():

$client->get('service/tickets/123')
    ->map(fn(array $data) => new TicketDTO($data))
    ->onFailure(fn(PsaError $e) => $logger->error($e->getMessage()))
    ->value(); // Returns TicketDTO or null

Patch Operations

Use the PsaPatchBuilder to ensure correct formatting:

use NCBP\Integration\ConnectWise\Psa\ApiClient\Core\Util\PsaPatchBuilder;

$patch = PsaPatchBuilder::create()
    ->replace('summary', 'Updated Summary')
    ->add('notes', 'Added a note');

$client->patch('service/tickets/123', $patch);

Advanced Features

Webhook Verification

Verify the integrity and source of ConnectWise PSA callbacks:

use NCBP\Integration\ConnectWise\Psa\ApiClient\Callback\Authentication\PsaCallbackAuthenticator;

$authenticator = new PsaCallbackAuthenticator(
    'https://na.myconnectwise.net', 
    'your-company',
    'v4_6_release', // Optional
    $httpClient     // Optional
);

// Verify signature
$isValid = $authenticator->authenticate($rawPayload, $signatureHeader, $signingKey);

// Or fetch the signing key securely if you have the key_url from metadata
$result = $authenticator->fetchSigningKey($keyUrl);
if ($result->isSuccess()) {
    $signingKey = $result->value();
}

Hosted API Context Resolution

If building a custom Pod or Tab, resolve URI tokens easily:

use NCBP\Integration\ConnectWise\Psa\ApiClient\Core\Util\PsaContextResolver;

$context = PsaContextResolver::resolve($_GET);
$endpoint = $context->getEndpoint(); // e.g., 'service/tickets'
$recordId = $context->getRecordId();

Configuration

Custom Middleware

You can inject your own middleware into the pipeline:

$client = new PsaClient(
    $httpClient,
    $authenticator,
    $siteUrl,
    $clientId,
    'v4_6_release',
    [
        new MyCustomMiddleware(),
        // Note: Providing custom middleware replaces the default stack.
        // Include default middlewares manually if needed.
    ]
);

Requirements

PHP 8.3+
symfony/http-client (or any implementation of HttpClientInterface)
psr/log
psr/clock

License

MIT License. See LICENSE for details.

ncbp / psa-api-client

Maintainers

Details