simtabi/netsapiens-api

Two badges, not four: the package is not on Packagist yet, so there is no registry version to show, and CI runs tests but no static analysis.

PHP SDK for the NetSapiens API v2: all 414 operations on docs.ns-api.com, typed, with API key, OAuth and JWT authentication.

Requires PHP 8.1 to 8.4 and Guzzle 7.

Install

The package is not on Packagist yet, so add the repository first:

composer config repositories.netsapiens-api vcs https://github.com/simtabi/netsapiens-api

composer require simtabi/netsapiens-api

Quick start guide and usage

Getting started

You need a NetSapiens server host and one credential: an API key (nss_…) from the Admin UI, or an OAuth client ID and secret plus a user login. Nothing needs publishing or migrating. The v2 base path /ns-api/v2 is added to the host for you.

Usage

use Simtabi\NetSapiens\Client;

$ns = Client::withApiKey('pbx.example.com', getenv('NETSAPIENS_API_KEY'));

$domains = $ns->domains()->getDomains(limit: 100);   // list<Data\Domain>
$total   = $ns->users()->countUsers('example.com')->total;

use Simtabi\NetSapiens\Auth\PasswordCredentials;
use Simtabi\NetSapiens\Client;

$ns = Client::withAccessToken('pbx.example.com', new PasswordCredentials(
    clientId: 'acme-portal',
    clientSecret: getenv('NETSAPIENS_CLIENT_SECRET'),
    username: '1001@example.com',
    password: getenv('NETSAPIENS_PASSWORD'),
));

$ns->users()->createUser('example.com', ['user' => '1002', 'name-first-name' => 'Ada']);

use Simtabi\NetSapiens\Exceptions\NotFoundException;

try {
    $ns->domains()->getDomain('missing.example.com');
} catch (NotFoundException $e) {
    echo $e->getMessage(); // GET /domains/missing.example.com returned 404: …
}

The full walkthrough is in docs/getting-started.md; everything else is under Documentation.

Documentation

Hosted at https://opensource.simtabi.com/documentation/simtabi/netsapiens-api/.

Guides

• Installation — requirements and the VCS repository entry
• Getting started — connect, read, write, handle errors
• Configuration — server, timeout, iNSight log tag, custom transports
• Architecture — how the client is put together, and why it is generated
• Release — versioning and the deprecation schedule

Reference

• Authentication — API keys, access tokens, JWT, MFA, token stores
• Resources — the 78 accessors and how methods are named
• Models — the 16 typed response models
• Errors — the exception for each status
• Pagination — start, limit and Paginator::each()
• Testing — FakeTransport, for this package and yours
• Legacy v1 client — the deprecated NetSapiens class

Recipes

• Walk every user in a domain
• Share tokens across workers
• Fake the API in your tests
• Call an endpoint the SDK does not cover
• Migrate from the v1 client

Contributing and security

See CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md, never in a public issue. Written by Imani Manyara and Easter Mukora, with all contributors.

License

MIT. See LICENSE.md.