esauti-php

Official PHP 7.4+ SDK for eSauti – covering both the REST API (OpenAPI-backed) and the Event Injection API.

---

Requirements

• PHP 7.4 or later
• Composer
• ext-json

---

Installation

composer require esauti/esauti-php

---

Quick Start

REST API

use Esauti\EsautiClient;

$client = new EsautiClient(
    'https://your-mautic-host.com/api',
    ['bearer_token' => 'your-api-token'],
    ['timeout' => 30, 'max_retries' => 3]
);

// List contacts
$result = $client->api->contacts()->list(['limit' => 10]);
echo $result['total'];

// Create a contact
$contact = $client->api->contacts()->create([
    'firstname' => 'Jane',
    'lastname'  => 'Doe',
    'email'     => 'jane@example.com',
]);

// Update a contact
$client->api->contacts()->update($contact['contact']['id'], ['city' => 'Montreal']);

Event Injection

use Esauti\EsautiClient;
use Esauti\Events\EventType;

$client = new EsautiClient(
    'https://your-mautic-host.com/api',
    ['bearer_token' => 'your-api-token'],
    ['source' => 'my-app']
);

$client->events->send(EventType::CUSTOMER_CREATED, [
    'occurred_at' => date('c'),
    'source'      => 'my-shop',
    'customer'    => [
        'id'    => 'cus_001',
        'email' => 'user@example.com',
    ],
]);

HMAC Signing

$client = new EsautiClient(
    'https://your-mautic-host.com/api',
    [
        'bearer_token' => 'your-api-token',
        'hmac_secret'  => 'your-hmac-secret',  // enables HMAC on all event requests
    ]
);

---

Constructor Options

new EsautiClient(
    string $baseUrl,
    array $auth = [
        'bearer_token' => '...',   // Bearer token
        'hmac_secret'  => '...',   // HMAC signing secret (optional)
    ],
    array $options = [
        'timeout'          => 30,          // Request timeout (seconds)
        'connect_timeout'  => 10,          // Connection timeout (seconds)
        'max_retries'      => 3,           // Retry attempts (408, 429, 5xx, network)
        'debug'            => false,       // Write debug logs to STDERR
        'redact_pii'       => false,       // Redact email/phone in logs
        'events_endpoint'  => '/v1/inbound/event',
        'source'           => 'sdk',       // X-eSauti-Source header
        'logger'           => $myLogger,   // Custom LoggerInterface
        'transport'        => $myTransport, // Custom HttpTransportInterface
    ]
);

---

API Resources

Resource	Methods
contacts()	list, get, create, update, replace, delete, segments, campaigns, addUtm, removeUtm, addDnc, removeDnc
campaigns()	list, get, create, update, replace, delete, addContact, removeContact
assets()	list, get, create, update, replace, delete
categories()	list, get, create, update, replace, delete
forms()	list, get, create, update, replace, delete, submissions
notifications()	list, get, create, update, replace, delete
fields()	listContact, getContact, createContact, updateContact, deleteContact, listCompany, getCompany, createCompany, updateCompany, deleteCompany
pointGroups()	list, get, create, update, delete
reports()	list, get
sms()	list, get, create, update, replace, delete, sendToContact

---

Event Types

All 225 canonical event types are available as constants in EventType:

use Esauti\Events\EventType;

EventType::CUSTOMER_CREATED     // 'customer.created'
EventType::ORDER_PAID           // 'order.paid'
EventType::SUBSCRIPTION_CREATED // 'subscription.created'
// ... 225 total

---

Dead-Letter Sink

Failed event deliveries (after all retries) are written to ./deadletter/events.jsonl. Override:

use Esauti\Events\DeadLetterSink;
use Esauti\Events\EventRegistry;
use Esauti\Events\EventsClient;

$sink = new DeadLetterSink(function (array $envelope, \Throwable $reason) {
    // Send to your own queue, log, alert, etc.
    myErrorTracker()->capture($reason, ['envelope' => $envelope]);
});

---

Custom HTTP Transport

use Esauti\Http\HttpTransportInterface;
use Esauti\Http\Response;

class MyTransport implements HttpTransportInterface {
    public function request(string $method, string $path, array $headers = [], array $query = [], ?array $body = null): Response {
        // your implementation
    }
}

$client = new EsautiClient('https://…', [], ['transport' => new MyTransport()]);

---

Running Tests

composer install
composer test

---

Project Structure

esauti-php/
├── composer.json
├── phpunit.xml
├── LICENSE
├── README.md
├── CHANGELOG.md
├── src/
│   ├── EsautiClient.php
│   ├── Config.php
│   ├── Auth/
│   │   ├── AuthInterface.php
│   │   ├── BearerAuth.php
│   │   ├── HmacAuth.php
│   │   ├── CompositeAuth.php
│   │   └── NoAuth.php
│   ├── Http/
│   │   ├── HttpTransportInterface.php
│   │   ├── GuzzleTransport.php
│   │   └── Response.php
│   ├── Api/
│   │   ├── ApiClient.php
│   │   ├── AbstractResource.php
│   │   ├── Contacts.php
│   │   ├── Campaigns.php
│   │   ├── Assets.php
│   │   ├── Categories.php
│   │   ├── Forms.php
│   │   ├── Notifications.php
│   │   ├── Fields.php
│   │   ├── PointGroups.php
│   │   ├── Reports.php
│   │   └── Sms.php
│   ├── Events/
│   │   ├── EventsClient.php
│   │   ├── EventType.php
│   │   ├── EventRegistry.php
│   │   ├── EventValidator.php
│   │   ├── EventEnvelope.php
│   │   └── DeadLetterSink.php
│   ├── Exception/
│   │   ├── ApiException.php
│   │   ├── NetworkException.php
│   │   └── ValidationException.php
│   ├── Logger/
│   │   ├── LoggerInterface.php
│   │   ├── NullLogger.php
│   │   └── DebugLogger.php
│   └── Retry/
│       └── RetryPolicy.php
├── tests/
│   ├── ApiClientTest.php
│   ├── EventValidationTest.php
│   ├── HmacAuthTest.php
│   ├── IdempotencyTest.php
│   └── RetryTest.php
└── examples/
    ├── api_contacts.php
    ├── send_event.php
    └── hmac_event.php