Salesteer Php Sdk Laravel Package

Getting Started

Treat devua/salesteer-php-sdk as a thin, low-adoption API wrapper rather than a mature framework package. With 0 stars, 0 dependents, and a single package identity, your first job is to verify what the SDK actually exposes before designing around it.

1. Install and pin it

   composer require devua/salesteer-php-sdk
   

   Pin an exact version in composer.json until you have contract tests. Do not rely on floating ^ constraints for a package with no dependent ecosystem.

2. Audit the package before writing application code

   • Read README.md for auth, base URI, and example calls.
   • Inspect composer.json for PHP version, PSR-18/PSR-17 dependencies, and whether it uses Guzzle, Symfony HTTP Client, or a generated OpenAPI client.
   • Open src/ and find the main entrypoint: likely a client class, resource classes, and exception types.
   • Look for tests/, examples/, and CHANGELOG.md. If absent, assume you are the test suite.
   • Confirm the release tag you installed matches the code you reviewed.

3. Configure credentials outside code

   SALESTEER_BASE_URI=https://api.example.salesteer.tld
   SALESTEER_API_KEY=your-token
   SALESTEER_TIMEOUT=10
   

   // config/services.php
   'salesteer' => [
       'base_uri' => env('SALESTEER_BASE_URI'),
       'api_key' => env('SALESTEER_API_KEY'),
       'timeout' => env('SALESTEER_TIMEOUT', 10),
   ],
   

4. Bind the client once

   If the package ships a Laravel service provider, publish/use it. Otherwise bind the SDK client as a singleton:

   // app/Providers/AppServiceProvider.php
   $this->app->singleton(SalesteerClient::class, function () {
       return new SalesteerClient(
           config('services.salesteer.api_key'),
           config('services.salesteer.base_uri'),
           // adjust to the actual constructor exposed by src/
       );
   });
   

   Adjust class and constructor names to what src/ actually provides. Do not assume the README examples are current.

5. First use case: a read-only sync Start with a low-risk read endpoint, such as listing contacts, companies, or deals. A nightly read-only sync is the best first integration because it exercises authentication, pagination, DTO hydration, error handling, and rate limits without writing bad data into the CRM.

   Verify:

   • Authentication succeeds.
   • The response shape matches the SDK DTOs.
   • Pagination terminates correctly.
   • Errors return a usable status code and message.
   • Date and currency formats are what you expect.

Implementation Patterns

The highest-leverage pattern is to isolate the SDK behind your own adapter. The package is small and low-adoption; your application should not depend on its class names throughout controllers and jobs.

Client as singleton, adapter as boundary

interface SalesteerGateway
{
    public function contactsUpdatedSince(?string $cursor): ContactPage;
    public function upsertContact(ContactData $contact): string;
}

final class SdkSalesteerGateway implements SalesteerGateway
{
    public function __construct(private SalesteerClient $client) {}

    public function contactsUpdatedSince(?string $cursor): ContactPage
    {
        // Map SDK response objects into your own DTOs here.
    }
}

This lets you swap the SDK, patch around missing features, or replace it with direct HTTP calls without rewriting domain code.

Read sync pattern

• Use cursor or updated-at pagination where available; avoid offset pagination for large datasets.
• Upsert by the Salesteer external ID, not by email or name.
• Persist a checkpoint: last cursor, last successful updated_at, or last page token.
• Run the sync in queued jobs, chunked by page.
• Make handlers idempotent. A retried job must not duplicate records.

final class SyncSalesteerContacts implements ShouldQueue
{
    use InteractsWithQueue, Queueable;

    public function __construct(private ?string $cursor = null) {}

    public function handle(SalesteerGateway $salesteer, ContactRepository $contacts): void
    {
        $page = $salesteer->contactsUpdatedSince($this->cursor);

        foreach ($page->items() as $contact) {
            $contacts->upsertFromSalesteer($contact);
        }

        if ($page->nextCursor()) {
            self::dispatch($page->nextCursor());
        }
    }
}

Write pattern

• Prefer explicit create/update methods over generic “save” methods.
• If the API supports idempotency keys, send them on every write.
• If it does not, deduplicate locally before retrying.
• Never blindly retry non-idempotent writes after a timeout; the request may have succeeded.
• Validate locally before calling the API so obvious 4xx errors never leave your app.

Error handling and retries

Map SDK exceptions into your own exception hierarchy:

try {
    $salesteer->upsertContact($data);
} catch (SalesteerValidationException $e) {
    throw new ContactRejected($e->getMessage(), previous: $e);
} catch (SalesteerRateLimitException $e) {
    $this->release($e->retryAfter ?? 60);
} catch (SalesteerException $e) {
    report($e);
    throw $e;
}

Retry only network failures, 429, and 5xx. Use exponential backoff with jitter. Respect Retry-After when present.

Testing

Inject a mock PSR-18 client or the SDK’s HTTP client if it exposes one. If the SDK does not support injection, wrap it and test your adapter with recorded fixtures. Keep a small contract test suite that runs against a Salesteer sandbox before releases.

Observability

Log method, path, status code, latency, and any request ID returned by the API. Redact Authorization headers and API keys. Log Salesteer record IDs, not full payloads containing PII.

Gotchas and Tips

• Low adoption means low support surface. There are no dependents to learn from. Pin the version, keep the adapter boundary, and be prepared to fork or patch around missing behavior.
• Verify the release provenance. The reported release date is unusually recent for a 0-star package. Check tags, commit history, and Packagist metadata before trusting production credentials to it.
• Do not guess method names from the README. Inspect src/ and run one smoke call in a sandbox first. Generated SDKs often have unintuitive resource and method names.
• PSR-18 discovery can surprise you. If the SDK depends on psr/http-client-implementation, Composer may install a client you did not expect. Explicitly require your preferred client and configure timeouts.
• Pagination is the most common integration bug. Stop on empty pages, missing next cursor, repeated cursor, or a max-page guard. Log the cursor on every page.
• Money and dates. Store money as decimal strings or integer minor units, never floats. Store timestamps in UTC and convert at the edges.
• Partial payloads. Do not make DTO properties non-nullable unless the API guarantees them. List endpoints often return fewer fields than detail endpoints.
• Large datasets. Avoid “fetch all” helpers. Chunk by page and queue follow-up jobs so memory stays bounded.
• Retries can duplicate writes. Timeouts are ambiguous. Use idempotency keys where supported; otherwise reconcile by external ID before retrying.
• Rate limits may be undocumented. Add a small delay between pages, honor 429 responses, and make throttling configurable.
• Debugging HTTP issues. Add a logging middleware around the SDK’s HTTP client. Capture the raw request and response for one failing call, then reproduce with curl to separate SDK bugs from API behavior.
• Extension points are likely thin. If the SDK does not expose middleware or a custom HTTP client, wrap it rather than editing vendor/. Composer updates will erase vendor patches.
• Security. Keep API keys in environment variables or a secret manager. Use scoped tokens where possible and rotate them. Never log authorization headers.
• Versioning risk. A 0.x or single-maintainer package can ship breaking changes in minor releases. Read the changelog and run contract tests before upgrading.
• If there are no tests in the package, write your own smoke tests. At minimum: auth failure, list success, pagination, one validation error, and one rate-limit response.
• Have an exit plan. Because the SDK is a thin wrapper, keep the adapter small enough that replacing it with direct HTTP calls is a one-class change, not a refactor.