Seat Comlink Laravel Package

Getting Started

seat-comlink is a SeAT plugin (SeAT is itself a Laravel app), so installation follows the standard SeAT package flow rather than a plain composer require.

1. Install into a SeAT instance — SeAT 4.x on PHP 8.1+ is the baseline:

   composer require proudly-snoring/seat-comlink
   

   SeAT auto-discovers the service provider via package.json/extra.laravel.providers; if not, add it to config/app.php.
2. Run the install steps the package documents — typically php artisan migrate for its tables, then publishing/refreshing SeAT permissions so the new Comlink permissions show up under Settings → Access Management (re-run the SeAT permission sync command after any upgrade; the plugin's permission classes are only picked up on a sync).
3. Configure the Discord side first — you need a bot token and a guild (server) ID. Put the bot in the server and grant at minimum Manage Roles + View Channels. The guild ID is not the invite code; grab it from Discord with Developer Mode on.
4. Grant yourself the Comlink permission, then open the Comlink page in the SeAT sidebar. This is the first thing to verify: the server name/icon renders and the role dropdown populates.

First use case: open the role-mapping screen, confirm the guild's icon and name resolve (the 1.0.1 icon fix), then map one low-risk SeAT role to one low-risk Discord role and test with a single character before touching any role that gates channel access.

Implementation Patterns

• Role mapping as the core loop. The plugin's job is SeAT role → Discord role. Treat the mapping table as configuration, not code: seed it via your deploy scripts or a one-off artisan command rather than clicking through the UI on every environment.
• Sync on event, not on page load. If you're extending the package, dispatch the sync from SeAT account/role-change events and from the OAuth callback, and queue it. Discord role writes are HTTP calls; doing them inline in a login request will make logins feel slow and will fall over on a 429.
• Linking accounts. The Discord account link is per SeAT user, not per character. If a user has multiple characters, decide up front whether role calculation is character-scoped (union of roles) or user-scoped — the package will have picked one, and your mapping design must match it.
• Reusing the Discord client in your own code. Resolve the client out of the container instead of instantiating your own Guzzle client, so you inherit the package's token handling, base URI, and rate-limit behaviour. Wrap your own calls in Http::retry()/backoff and fake them in tests with Http::fake().
• Gating your own UI on Comlink permissions. Register your own routes behind the Comlink permissions the package registers rather than auth alone; SeAT's ACL is the only thing standing between a line member and your bot token screen.
• Embedding the guild widget. If you render server name/icon elsewhere, prefer reusing the package's view partial or its cached server model over hitting the Discord API per request — otherwise you'll re-trigger the exact CDN fetch that 1.0.1 fixed.
• Upgrades. For a patch like 1.0.1 the workflow is composer update proudly-snoring/seat-comlink && php artisan migrate && php artisan config:clear — no new migrations are implied by the changelog, but always run migrate since SeAT plugins ship idempotent ones.

Gotchas and Tips

• Discord role hierarchy bites hardest. The bot can only assign roles below its own highest role. A mapping that looks correct in the UI will silently do nothing if the bot's role sits too low — put the bot role near the top and re-test.
• The 1.0.1 role dropdown rework changed what's listed. The dropdown now filters the guild's role list, so roles managed by integrations (bot roles, booster roles, @everyone) and possibly the bot's own role won't appear. If a role you mapped previously "vanished," check it isn't integration-managed, and re-save the mapping rather than assuming data loss. Any tooling of yours that parsed the old unfiltered list will need adjusting.
• Server icons (the other 1.0.1 fix) come from the Discord CDN. Two follow-on traps: your CSP needs img-src https://cdn.discordapp.com, and the icon URL contains a hash that changes whenever the server icon changes. Don't cache the URL indefinitely — cache the hash with a short TTL, or you'll show a stale 404 after an icon swap.
• Bot token storage. Tokens are typically stored encrypted in the settings table. After rotating the token you must clear config/opcache (php artisan config:clear, restart queue workers) or workers will keep using the old credential until they recycle.
• config:cache in production will freeze any published Comlink config values; anything the admin edits through the UI should be read from the database, not from cached config, which is also why settings changes appear to "not take" on some hosts.
• Rate limits and 429s are the most common runtime failure. Look for a Retry-After header in storage/logs/laravel.log, queue the sync, and avoid bulk re-syncs during busy hours — a full-guild resync will hit Discord's per-guild limits quickly.
• Debugging the API layer: Http::dd() or Http::fake() around the client is faster than reading logs. If the dropdown is empty, the failure is almost always auth (invalid token / bot not in guild) rather than the package — verify the token with a direct GET /guilds/{id} first.
• Patch-level upgrade risk is low. 1.0.0 → 1.0.1 is two view/logic fixes with no stated breaking changes; there's no reason to pin, but do smoke-test one account link and one role sync after upgrading, since both changed areas are exactly what a member-facing flow depends on.
• Extension points: the package's settings/permission classes and Blade partials are the intended seams. Forking controllers to change role-filtering behaviour will make the next patch painful — 1.0.1 is a good example of logic you'd rather not have copied into your app.