Laravel Savvycal Laravel Package

Getting Started

1. Install the package with Composer and publish its config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=savvycal-config
   

2. Set the API token in .env:

   SAVVYCAL_API_KEY=your-token
   SAVVYCAL_TIMEOUT=10
   

   The package also falls back to services.savvycal.token, so existing service config can be reused.
3. Clear cached config after changing env values:

   php artisan config:clear
   

4. Start with SavvyCalClient::me() in a Tinker session or a simple health-check route to confirm the token and network path work:

   $me = SavvyCalClient::me();
   
   if ($me === null) {
       // Token, network, or API failure
   }
   

The first practical use case is usually listing scheduling links and slots so you can render booking options or create a link for a user.

Implementation Patterns

Use the client in a small application service rather than spreading API calls across controllers:

final class SavvyCalSchedulingService
{
    public function linksForCurrentUser(): array
    {
        $links = SavvyCalClient::schedulingLinks()->list();

        return is_array($links) ? $links : [];
    }
}

Common workflows:

• Verify identity: call SavvyCalClient::me() during setup or in an admin diagnostics page.
• Scheduling links: use list/get for display, create/update for provisioning, duplicate for templates, toggle for enabling/disabling, and slots for availability.
• Events: list/get events for reporting or dashboards; create/cancel events from booking flows.
• Webhooks: create webhooks during tenant or account setup, list them for administration, and delete them during offboarding.

Handle the package’s null-safe contract explicitly:

$link = SavvyCalClient::schedulingLinks()->get($linkId);

if ($link === null) {
    Log::warning('SavvyCal scheduling link lookup failed', ['link_id' => $linkId]);

    abort(404);
}

For mutating calls, treat false as failure and avoid assuming success:

$deleted = SavvyCalClient::webhooks()->delete($webhookId);

if ($deleted === false) {
    // Surface a user-facing error or queue a retry
}

Keep API calls behind queued jobs when they are part of user-facing writes. Since failures are returned rather than thrown, jobs should inspect the result and decide whether to retry, log, or fail.

For webhook endpoints, store the remote webhook identifier returned by create so you can later list/delete it. The release notes do not mention signature verification helpers, so plan to verify authenticity at the application layer according to SavvyCal’s webhook documentation.

Gotchas and Tips

• Null-safe means silent failures by default. Every call can return null or false on network failure or non-2xx responses. Log failures and add metrics; otherwise broken integrations can look like empty data.
• Use strict checks. Prefer === null and === false over if (!$result), because an empty list or valid falsey value may be mistaken for failure depending on the endpoint.
• Do not expect exceptions. Existing Laravel error handling will not catch API failures from this client. Wrap calls in your own service layer if you need retry or alerting behavior.
• Config fallback can surprise you. If SAVVYCAL_API_KEY is missing, the package falls back to services.savvycal.token. Check both locations when debugging authentication.
• Set a sensible timeout. SAVVYCAL_TIMEOUT controls request timeouts. Use a short timeout for request/response paths and a longer timeout for background jobs if needed.
• Remember config caching. After changing .env or config/services.php, run php artisan config:clear in local development and deploy with a fresh config cache.
• Check list result shape before iterating. Treat non-array list responses as failures and return an empty collection only when that is acceptable for your UI.
• Guard mutating operations. Duplicate, toggle, create, cancel, and delete calls are not described as idempotent. Prevent double-submits and record remote IDs after successful creates.
• Pagination is not mentioned in the release notes. If you need complete lists for large accounts, confirm pagination behavior against the SavvyCal API and the package source before relying on a single list call.
• Start debugging at the client boundary. Log the operation name, relevant IDs, result type, and timeout. Avoid logging the API token.