README

A Laravel package for the NUKI Web API: list, lock and unlock smartlocks, read the activity log, manage keypad codes and receive webhooks, with a Livewire UI and optional users with permissions per lock.

Features

• A facade for the NUKI Web API - Nuki::smartlocks(), logs(), auths(), webhooks(), oauth() and account(), with answers as typed objects instead of arrays
• Personal API token or OAuth 2.0 - and more than one NUKI account in one application with Nuki::as('account-key'), tokens encrypted in the database
• Retries - a connection error, a 429 and a 5xx are tried again; a failure is an exception with the status and the body
• Webhook receiver - checks the HMAC-SHA256 signature, ignores a repeated event id and dispatches one event; rejects everything until a secret is set
• Livewire and Flux pages - dashboard, smartlocks, activity, keypad codes, webhooks and accounts, in English, Dutch, German and Spanish; closed outside local until you open them
• Optional users - its own guard with an emailed login code, main and sub users, and permissions per lock with a period and weekdays, stored in your database only
• Demo mode - the whole UI on made up data, without a NUKI account

Requirements

• PHP 8.2 or higher
• Laravel 11, 12 or 13
• Livewire 3.5 or higher, or Livewire 4
• Flux 2 (the free edition is enough)
• A NUKI account that is available in NUKI Web, with an API token or an OAuth application

Livewire and Flux are Composer requirements, so they are installed with the package.

Installation

composer require darvis/nuki
php artisan vendor:publish --tag=nuki-config
php artisan migrate

Create a personal API token on web.nuki.io under API and put it in .env:

NUKI_API_TOKEN=paste-the-token-here
NUKI_TOKEN_RESOLVER=config

The installation page has every step and a way to check that it works.

Who may open the bundled UI

The package registers pages under /nuki that lock and unlock doors. Outside the local environment they answer 403 until you say who may open them, the way Horizon and Telescope work. Define the viewNuki gate, for example in AppServiceProvider::boot():

Gate::define('viewNuki', fn (?User $user) => $user?->is_admin === true);

Keep the parameter nullable, or a guest never reaches the gate. With NUKI_AUTH_USERS_ENABLED=true the package's own login protects the pages and the gate is not asked. NUKI_UI_ENABLED=false removes the pages altogether. See Who may open the UI.

Quick start

use Darvis\Nuki\Exceptions\NukiException;
use Darvis\Nuki\Facades\Nuki;
use Illuminate\Http\Client\ConnectionException;

foreach (Nuki::smartlocks()->all() as $lock) {
    echo $lock->name.': '.($lock->stateName ?? 'unknown').PHP_EOL;
}

try {
    Nuki::smartlocks()->unlock($smartlockId);
} catch (NukiException|ConnectionException $e) {
    report($e);
}

all() returns a collection of SmartLock objects. unlock() returns nothing: no exception means NUKI accepted the command. The quick start builds a complete page with routes, a controller and a view.

Documentation

The full documentation is on arviddejong.github.io/nuki:

• Installation - the steps, and how to check that it works
• Quick start - a page that lists the locks and operates one
• Configuration - every key and NUKI_* variable
• API authentication - token or OAuth, several accounts, the callback route you build
• API reference - every method, object, command and exception
• Users and permissions - main and sub users, permissions per lock
• Auth routes - the routes and where a guest is sent
• Webhooks - the receiver and the event
• UI and localization - the pages, your own layout, the languages
• Demo mode - the UI on made up data
• Testing - test your code without calling NUKI
• Troubleshooting - the literal error messages, with cause and fix
• FAQ - the short answers

Laravel Boost

The package ships Laravel Boost resources: a guideline and a nuki-development skill. Run php artisan boost:install, or php artisan boost:update --discover in a project that already uses Boost.

Testing

composer test      # Pest
composer lint      # Pint, check only; composer format fixes
composer analyse   # Larastan

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

Report a vulnerability privately, as described in SECURITY.md.

License

MIT. See LICENSE.