Safebase Sdk Development

Get all accounts

use LaravelGtm\SafebaseSdk\Requests\GetAccountsRequest;
use LaravelGtm\SafebaseSdk\Responses\AccountsResponse;
use LaravelGtm\SafebaseSdk\Responses\Account;

// Via the SDK class
$response = $sdk->getAccounts(
    name: 'Acme',
    domain: 'acme.com',
    reviewStatus: 'approved',
    sortField: 'lastSeen',
    sortDirection: 'desc',
    pageNumber: 1,
    pageSize: 25,
);

// $response->accounts — array<int, Account>
// $response->total    — int (total matching records)
// $response->pageNumber — int
// $response->pageSize   — int

foreach ($response->accounts as $account) {
    $account->id;             // string (UUID)
    $account->name;           // string
    $account->description;    // ?string
    $account->domain;         // ?string
    $account->reviewStatus;   // ?string
    $account->sfdcAccountId;  // ?string
}

Available filter parameters:

Planned resources (not yet implemented)

The SafeBase API (v1.19.2) exposes additional resources that can be added following the same pattern as Accounts. All endpoints live under the base path /api/ext/v1/rest.

Account management (CRUD)

Edit account accepts: name, description, sfdcAccountId, ndaProvider, ndaDocusign, accessExpiresAt.

Account members

Add members accepts an array of { firstName, lastName, email, message } objects. Notify accepts email (string or array) and an optional message.

Knowledge base

Entries have question, answer, comments, and accessLevel (public, private, internal). Search accepts query (max 512 chars), products (comma-separated IDs), pageNumber, pageSize.

Access requests

Get requests accepts a status filter: pending, approved, declined. Approve accepts either accountId (existing) or account (new account object).

Organization

Portals

Products

Questionnaires

Upload is multipart: qnr (file — xlsx, pdf, docx, csv, json, txt), accountId (UUID, required), productId (optional), dueDate (ISO 8601, optional). The completed endpoint returns a signed URL valid for 60 minutes.

Trust center updates

Topics have subject (string), category (compliance, vulnerabilities, incidents, subprocessors, general), and hidden (bool). Updates have message (string) and channels (object with statusPage, email.subscribers, email.audience).

Adding a new endpoint

1. Create a request class in src/Requests/ extending Saloon\Http\Request:

   • Set $method (e.g. Method::GET, Method::POST)
   • Implement resolveEndpoint() returning the path (e.g. /accounts/{id})
   • For GET requests, override defaultQuery() for query parameters
   • For POST/PATCH, implement HasBody + HasJsonBody and override defaultBody()
   • Implement createDtoFromResponse() to return a response DTO

2. Create response DTOs in src/Responses/ as readonly class with fromArray().

3. Add a public method on SafebaseSdk that sends the request and returns the DTO via ->dtoOrFail().

4. Write tests with MockClient / MockResponse (see testing section below).

Rate limits

The connector enforces 60 requests per minute via Saloon\RateLimitPlugin. The SafeBase API returns 429 when rate-limited; the connector backs off for 60 seconds on 429 responses.

In Laravel, the rate limit store uses LaravelCacheStore (bound via the service provider). Standalone usage falls back to MemoryStore.

Testing with the SDK

use LaravelGtm\SafebaseSdk\Requests\GetAccountsRequest;
use LaravelGtm\SafebaseSdk\Responses\Account;
use LaravelGtm\SafebaseSdk\Responses\AccountsResponse;
use LaravelGtm\SafebaseSdk\SafebaseConnector;
use LaravelGtm\SafebaseSdk\SafebaseSdk;
use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;

$connector = new SafebaseConnector('https://example.test/api/ext/v1/rest', 'test-token');
$mockClient = new MockClient([
    GetAccountsRequest::class => MockResponse::make([
        'data' => [
            [
                'id' => '550e8400-e29b-41d4-a716-446655440000',
                'name' => 'Acme Corp',
                'description' => 'Enterprise customer',
                'domain' => 'acme.com',
                'reviewStatus' => 'approved',
                'sfdcAccountId' => '001ABC123',
            ],
        ],
        'total' => 1,
        'pageNumber' => 1,
        'pageSize' => 10,
    ], 200),
]);
$connector->withMockClient($mockClient);

$sdk = new SafebaseSdk($connector);
$response = $sdk->getAccounts(name: 'Acme');

expect($response)->toBeInstanceOf(AccountsResponse::class)
    ->and($response->accounts[0])->toBeInstanceOf(Account::class)
    ->and($response->accounts[0]->name)->toBe('Acme Corp');

$mockClient->assertSent(GetAccountsRequest::class);

tests/Pest.php calls Config::preventStrayRequests() — any request without a mock will throw, preventing accidental live API calls.

Conventions

• PHP 8.4+, declare(strict_types=1) in every file
• PHPStan level 8 — nullable types must be checked before access
• laravel/pint with Laravel preset: composer lint to check, composer format to fix
• Rule files: .claude/rules/saloon.md, .claude/rules/php-package-phpstan.md, .claude/rules/laravel-package.md
• All response DTOs are readonly class with typed constructor properties and fromArray()
• Use dtoOrFail() (not dto()) to ensure the response was successful before creating the DTO