Nova Kustomer Laravel Package

Getting Started

This is a Laravel Nova tool (sidebar panel), not a full CRUD resource package. It was last released in December 2019, which puts it squarely in the Nova 2 / Laravel 6 era. Before installing, check your composer.json for laravel/nova — if you're on Nova 3+ expect to fork or at least relax the version constraint.

Minimal install:

composer require mydnic/nova-kustomer

Publish whatever the service provider exposes (config and/or compiled assets):

php artisan vendor:publish --provider="Mydnic\NovaKustomer\NovaKustomerServiceProvider"

Register the tool so it appears in the Nova sidebar:

// app/Providers/NovaServiceProvider.php
public function tools()
{
    return [
        new \Mydnic\NovaKustomer\Kustomer(),
    ];
}

Set credentials in .env (names depend on the config file that was published — confirm before guessing):

KUSTOMER_API_KEY=...
KUSTOMER_SUBDOMAIN=yourcompany

Where to look first, in this order:

1. src/ — the Tool subclass and any controllers/routes. This tells you whether the tool calls Kustomer server-side or just renders a frontend widget.
2. config/ — API key, subdomain, base URL.
3. resources/js/tool.js and dist/js/tool.js — the actual Vue component that Nova mounts. The dist file is what ships; the source tells you what it does.
4. composer.json — the laravel/nova constraint, which is your biggest compatibility signal.

First use case: give support agents a one-click jump from Nova into a customer's Kustomer profile — either as an embedded view in the tool panel or (more robustly) as a deep link carrying the user's email or Kustomer ID.

Implementation Patterns

Gate the tool by role. Support tooling shouldn't be visible to every Nova user:

// In the Tool class, or wrap registration
public function canSee(Request $request)
{
    return $request->user()->hasRole('support');
}

If the published Tool doesn't expose canSee, subclass it in app/Nova/Tools/Kustomer.php and add the method.

Keep the API key server-side. If the shipped Vue component calls api.kustomerapp.com directly from the browser with a token, that token is in your JS bundle. The safe pattern is a thin package-route proxy:

// routes/web.php or the package's own routes, behind nova middleware
Route::middleware(['nova'])->get('/nova-vendor/kustomer/customers', function (Request $request) {
    return Http::withToken(config('nova-kustomer.api_key'))
        ->get('https://api.kustomerapp.com/v1/customers/search', [
            'email' => $request->query('email'),
        ])->json();
});

Then have the Vue tool hit /nova-vendor/kustomer/... instead. This also sidesteps CORS entirely.

Deep-link from a resource. A custom field or a detail-page link is often more useful than the sidebar panel:

Text::make('Kustomer', function () {
    $url = 'https://'.config('nova-kustomer.subdomain').'.kustomerapp.com/app/customers/'.$this->kustomer_id;
    return "<a href='{$url}' target='_blank'>Open in Kustomer</a>";
})->asHtml(),

Push data on create. Pair the tool with an observer or Nova action so new users are mirrored into Kustomer, rather than asking agents to create records twice. Keep it queued — Kustomer API latency shouldn't block a Nova form submission.

Environment separation. Point sandbox and production at different subdomains/keys via .env; never let a staging Nova install write to the production Kustomer tenant. Assert this in a test if the tool has write paths.

Gotchas and Tips

• Nova 4/5 will break it. Nova 4 moved to Vue 3 and a different manifest.json / asset pipeline; a 2019 tool using laravel-nova imports and Vue 2 SFCs won't mount. Budget a fork rather than expecting a smooth composer require.
• Composer resolution failures are usually the laravel/nova constraint. Fork to packages/nova-kustomer with a path repository and loosen the constraint — don't edit vendor/.
• Stale dist/. Like most Nova tools, the compiled tool.js is committed. If you change resources/js, you must run the package's build (npm install && npm run prod). Forgetting this is the #1 "my changes don't show up" cause.
• Cached config. php artisan config:clear after touching .env — Nova tools read config at boot.
• Iframe blockers. If the tool embeds the Kustomer app, X-Frame-Options: DENY and SameSite=Lax cookies on the Kustomer session will silently produce a blank panel. Check the browser console first; fall back to an external link if embedding is disallowed.
• Rate limits. Kustomer enforces per-key limits on its API. Handle 429 with backoff and cache lookups (e.g., Cache::remember keyed by email, 5 minutes) for any list/search view.
• Debugging routes. php artisan route:list | grep -i kustomer quickly shows whether the package registered server-side endpoints or is purely frontend.
• No tests, no dependents, no recent commits. Treat it as a reference implementation. Read the Tool class (it's small), copy what's useful into app/Nova/Tools/, and drop the dependency if you need to maintain it long-term.
• Extension points: the config file (publish it and commit it), the Vue component (publish assets, then override), and subclassing the Tool for canSee/menu ordering via Nova::tools() ordering or Nova::mainMenu().