Fasáda Connections

use RoundlyConsulting\Connections\DataTransferObjects\SyncTarget;
use RoundlyConsulting\Connections\Facades\Connections;

// Create the connection, or update the pair's existing one, with permissions and an expiry.
Connections::between($user, $team)
    ->withPermissions('view', 'edit')
    ->expiresIn(now()->addMonth())   // CarbonInterface, CarbonInterval, or seconds
    ->connect();

// Defer the connectable until later with from()->to().
Connections::from($user)->to($team)->withPermissions('view')->connect();

// Move the expiry, or clear it with null.
Connections::between($user, $team)->extend(now()->addYear());
Connections::between($user, $team)->extend(null);

// Look the pair up.
Connections::between($user, $team)->exists();   // bool — an active connection exists
Connections::between($user, $team)->find();     // ?Connection — in any status

// Remove the connection (soft delete).
Connections::between($user, $team)->disconnect();

// Reconcile a connector to exactly this set (connect missing, disconnect extras).
Connections::from($user)->sync([$teamA, new SyncTarget($teamB, permissions: ['read'])]); // SyncResult

// Connections expiring within 14 days, across every connector.
Connections::expiring(14)->with('connector')->get();

// Remove all expired connections, returning how many were removed.
$removed = Connections::prune();

// Drop the in-request permission cache mid-request (it already resets per request / job).
Connections::flushCache();

use Carbon\CarbonInterval;
use RoundlyConsulting\Connections\Facades\Connections;

$connection = Connections::from($user)
    ->to($team)                              // the connectable (or start with between())
    ->withPermissions('view', 'edit')        // staged permissions, de-duplicated
    ->withPermissions('publish')             // repeated calls add to the staged set
    ->expiresIn(CarbonInterval::days(30))    // CarbonInterface, CarbonInterval or seconds
    ->withMeta(['source' => 'signup'])       // merged into the meta bag
    ->connect();                             // terminal verb: returns the Connection

use RoundlyConsulting\Connections\Facades\Connections;

$permissions = Connections::between($user, $team)->permissions();

$permissions->grant('publish');          // Connection — creates the connection if absent
$permissions->revoke('publish');         // Connection — throws ConnectionNotFound if absent
$permissions->sync('view', 'edit');      // Connection — exact set, creates if absent
$permissions->clear();                   // Connection — remove every permission; throws ConnectionNotFound if absent

$permissions->all();                     // Collection<int, string> — what is stored
$permissions->has('edit');               // bool
$permissions->hasAny('view', 'edit');    // bool
$permissions->hasAll('view', 'edit');    // bool

Connections::between($user, $team)
    ->withPermissions('view', 'edit')
    ->expiresIn(now()->addMonth())
    ->connect();

// Re-connecting only changes what you stage: status, permissions and expiry are kept.
Connections::between($user, $team)->withMeta(['note' => 'hi'])->connect();   // merge; perms + expiry kept

// Config defaults (default_permissions, default_status, expiry.default) apply to new
// connections only. To clear an expiry or change one attribute, use its dedicated verb:
Connections::between($user, $team)->extend(null);
Connections::between($user, $team)->permissions()->grant('publish');
Connections::between($user, $team)->accept();

Connections::from($user)->connect();       // throws MissingConnectable — call to() first
Connections::from($user)->connectAll();    // throws MissingConnectable — call toMany() first