SDK Usage Examples

Copy-paste examples for the ValidonX PHP and JavaScript SDKs.

PHP SDK

Install

composer require validonx/php-sdk

Validate a License Key

use ValidonX\Client;

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

$result = $client->licenses()->validate('VALIDONX-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

$activation = $client->activations()->create([
    'license_key' => 'VALIDONX-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

$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

$check = $client->entitlements()->check([
    'license_key' => 'VALIDONX-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

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

Error Handling

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

npm install @validonx/sdk

Validate a License Key

import { ValidonXClient } from '@validonx/sdk'

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

const result = await client.licenses.validate('VALIDONX-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

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

const activation = await client.activations.create({
  license_key: 'VALIDONX-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

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

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

Check Entitlements

const check = await client.entitlements.check({
  license_key: 'VALIDONX-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

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

Webhook Signature Verification

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

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)
  }
}