ValidonX Docs

Appearance

SDK Usage Examples ​

Reference SDK ergonomics for PHP and JavaScript. The supported integration path today is the plain REST API.

Integrate over REST — no SDK required

The official PHP and JavaScript SDKs are not currently published to Packagist or npm, so the composer require / npm install commands below won't resolve. We'll publish them when there's customer demand; this page shows the ergonomics they will follow.

Everything here works today over the REST API. Start with the Quickstart and the 5-minute guides (validate a license, activate a device).

PHP SDK ​

Install ​

Not currently published to Packagist — use the REST API today. Once released:

bash
composer require validonx/php-sdk

Until then, call the REST API directly (any HTTP client, e.g. Guzzle).

Validate a License Key ​

php
use ValidonX\Client;

$client = new Client('vx_your-secret-api-key');

$result = $client->licenses()->validate('XXXX-XXXX-XXXX-XXXX');

if ($result->valid) {
    echo "License is valid!";
    echo "Product: " . $result->product_name;
    echo "Plan: " . ($result->license->entitlements->plan ?? 'none');
    echo "Expires: " . $result->expires_at;
} else {
    echo "Invalid: " . $result->reason;
}

Create an Activation ​

php
$activation = $client->activations()->create([
    'license_key' => 'XXXX-XXXX-XXXX-XXXX',
    'hardware_id' => hash('sha256', php_uname('n') . php_uname('m')),
    'device_name' => gethostname(),
    'metadata' => [
        'os' => PHP_OS,
        'php_version' => PHP_VERSION,
    ],
]);

echo "Activation ID: " . $activation->id;
echo "Status: " . $activation->status; // 'active'

Validate an Activation ​

php
$validation = $client->activations()->validate($activation->id);

if ($validation->valid) {
    echo "Activation is valid";
} else {
    echo "Activation invalid: " . $validation->reason;
    // Possible reasons: 'expired', 'revoked', 'device_mismatch'
}

Check Entitlements ​

php
$check = $client->entitlements()->check([
    'license_key' => 'XXXX-XXXX-XXXX-XXXX',
    'entitlement_code' => 'api_access',
]);

if ($check->entitled) {
    echo "Feature is available";
    echo "Limit: " . $check->limit_value; // e.g., 1000
    echo "Used: " . $check->current_usage;
}

Record Usage ​

php
$client->usage()->record([
    'metric' => 'api_calls',
    'value' => 1,
    'metadata' => [
        'endpoint' => '/api/users',
    ],
]);

Error Handling ​

php
use ValidonX\Exceptions\ValidationException;
use ValidonX\Exceptions\RateLimitException;
use ValidonX\Exceptions\AuthenticationException;

try {
    $result = $client->licenses()->validate($licenseKey);
} catch (AuthenticationException $e) {
    // Invalid API key
    echo "Auth error: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Too many requests
    echo "Rate limited. Retry after: " . $e->retryAfter . " seconds";
} catch (ValidationException $e) {
    // Invalid request
    echo "Validation error: " . $e->getMessage();
}

JavaScript / Node.js SDK ​

Install ​

Not currently published to npm — use the REST API today. Once released:

bash
npm install @validonx/sdk

Until then, call the REST API directly with fetch or any HTTP client.

Validate a License Key ​

typescript
import { ValidonXClient } from '@validonx/sdk'

const client = new ValidonXClient({
  apiKey: 'vx_your-secret-api-key',
})

const result = await client.licenses.validate('XXXX-XXXX-XXXX-XXXX')

if (result.valid) {
  console.log('License is valid!')
  console.log('Product:', result.product_name)
  console.log('Plan:', result.license?.entitlements?.plan)
  console.log('Expires:', result.expires_at)
} else {
  console.log('Invalid:', result.reason)
}

Create an Activation ​

typescript
import { createHash } from 'crypto'
import { hostname } from 'os'

const activation = await client.activations.create({
  license_key: 'XXXX-XXXX-XXXX-XXXX',
  hardware_id: createHash('sha256').update(hostname()).digest('hex'),
  device_name: hostname(),
  metadata: {
    platform: process.platform,
    node_version: process.version,
  },
})

console.log('Activation ID:', activation.id)

Validate an Activation ​

typescript
const validation = await client.activations.validate(activation.id)

if (validation.valid) {
  console.log('Activation is valid')
} else {
  console.log('Invalid:', validation.reason)
}

Check Entitlements ​

typescript
const check = await client.entitlements.check({
  license_key: 'XXXX-XXXX-XXXX-XXXX',
  entitlement_code: 'api_access',
})

if (check.entitled) {
  console.log('Feature available')
  console.log('Limit:', check.limit_value)
  console.log('Used:', check.current_usage)
}

Record Usage ​

typescript
await client.usage.record({
  metric: 'api_calls',
  value: 1,
  metadata: {
    endpoint: '/api/users',
  },
})

Webhook Signature Verification ​

typescript
import { verifyWebhookSignature } from '@validonx/sdk'

// In your webhook handler (Express example)
app.post('/webhooks/validonx', (req, res) => {
  const signature = req.headers['x-validonx-signature']
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    'your-webhook-secret'
  )

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  const event = req.body
  switch (event.type) {
    case 'license.created':
      console.log('New license:', event.data.license_key)
      break
    case 'activation.created':
      console.log('New activation:', event.data.activation_id)
      break
  }

  res.json({ received: true })
})

Error Handling ​

typescript
import {
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from '@validonx/sdk'

try {
  const result = await client.licenses.validate(licenseKey)
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key')
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`)
  } else if (error instanceof ValidationError) {
    console.error('Validation:', error.message)
  }
}