AstraGuard SDK

Official SDK for integrating AstraGuard license management into your applications.

Features

• License validation & activation
• Automatic HWID generation
• Session management
• Product variables
• Update checking
• File downloads
• Full TypeScript support
• Event system for real-time updates

Installation

npm install @astraguard/sdk
# or
yarn add @astraguard/sdk
# or
pnpm add @astraguard/sdk

Quick Start

import { createClient } from '@astraguard/sdk'

// Initialize the client
const astra = createClient({
  apiUrl: 'https://api.astraguard.io',
  productId: 'your-product-id',
  debug: true // Enable for development
})

// Validate a license
async function checkLicense(licenseKey: string) {
  const result = await astra.validate(licenseKey)

  if (result.valid) {
    console.log('License is valid!')
    console.log('Expires in:', result.remainingDays, 'days')
    console.log('Features:', result.features)
  } else {
    console.log('Invalid license:', result.message)
  }
}

Usage Examples

License Validation

import { createClient, AstraGuardError } from '@astraguard/sdk'

const astra = createClient({
  apiUrl: 'https://api.astraguard.io',
  productId: 'prod_xxx'
})

try {
  const result = await astra.validate('XXXX-XXXX-XXXX-XXXX')

  if (result.valid) {
    // License is valid - start your app
    console.log('Welcome!')
    console.log('License type:', result.license?.type)
    console.log('Days remaining:', result.remainingDays)

    // Access variables
    if (result.variables) {
      console.log('API Key:', result.variables.apiKey)
    }
  } else {
    // Show error to user
    console.error(result.message)
    process.exit(1)
  }
} catch (error) {
  if (error instanceof AstraGuardError) {
    switch (error.code) {
      case 'INVALID_LICENSE':
        console.error('The license key is invalid')
        break
      case 'LICENSE_EXPIRED':
        console.error('Your license has expired')
        break
      case 'HWID_MISMATCH':
        console.error('This license is bound to another device')
        break
      case 'NETWORK_ERROR':
        console.error('Could not connect to license server')
        break
      default:
        console.error('Error:', error.message)
    }
  }
}

License Activation (First Use)

// Activate binds the license to this machine's HWID
const result = await astra.activate('XXXX-XXXX-XXXX-XXXX')

if (result.success) {
  console.log('License activated!')
  console.log('Session token:', result.sessionToken)
} else {
  console.error('Activation failed:', result.message)
}

Customer Login & Session

// Login creates a session for subsequent API calls
const session = await astra.login('XXXX-XXXX-XXXX-XXXX')

console.log('Logged in! Session expires:', session.expiresAt)

// Check if still authenticated
if (astra.isAuthenticated()) {
  // Get customer info
  const info = await astra.getCustomerInfo()
  console.log('License status:', info.status)
  console.log('Expires:', info.expiresAt)
}

// Logout when done
astra.logout()

Product Variables

// Must be logged in first
await astra.login('XXXX-XXXX-XXXX-XXXX')

// Get all variables
const variables = await astra.getVariables()
variables.forEach(v => {
  console.log(`${v.key}: ${v.value}`)
})

// Get specific variable
const apiKey = await astra.getVariable('apiKey')
const maxUsers = await astra.getVariable('maxUsers')

Check for Updates

const update = await astra.checkForUpdate('1.0.0')

if (update.available) {
  console.log('New version available:', update.latestVersion)
  console.log('Changelog:', update.changelog)
  console.log('Download:', update.downloadUrl)

  if (update.mandatory) {
    console.log('This update is mandatory!')
  }
}

Get Releases & Files

await astra.login('XXXX-XXXX-XXXX-XXXX')

// Get latest release
const release = await astra.getLatestRelease()
if (release) {
  console.log('Latest version:', release.version)
  console.log('Download:', release.downloadUrl)
}

// Get all files
const files = await astra.getFiles()
files.forEach(file => {
  console.log(`${file.name} (${file.size} bytes)`)
  console.log('Download:', astra.getDownloadUrl(file.id))
})

HWID Management

await astra.login('XXXX-XXXX-XXXX-XXXX')

// Get HWID info
const hwidInfo = await astra.getHwidInfo()
console.log('HWID bound:', hwidInfo.bound)
console.log('Resets remaining:', hwidInfo.resetsRemaining)

// Request HWID reset (e.g., new computer)
if (hwidInfo.canReset) {
  const result = await astra.requestHwidReset('Upgraded to new computer')
  console.log(result.message)
}

// Get current machine's HWID
const hwid = await astra.getHwid()
console.log('This machine:', hwid)

Event Handling

// Subscribe to events
astra.on('license:validated', (event) => {
  console.log('License validated at:', event.timestamp)
})

astra.on('license:expired', (event) => {
  console.log('License expired!')
  // Show renewal dialog
})

astra.on('update:available', (event) => {
  console.log('Update available:', event.data.latestVersion)
})

astra.on('session:expired', () => {
  console.log('Session expired, please login again')
})

astra.on('error', (event) => {
  console.error('SDK Error:', event.data)
})

// Unsubscribe
const handler = (event) => console.log(event)
astra.on('license:validated', handler)
astra.off('license:validated', handler)

Announcements

await astra.login('XXXX-XXXX-XXXX-XXXX')

const announcements = await astra.getAnnouncements()
announcements.forEach(a => {
  console.log(`[${a.type}] ${a.title}`)
  console.log(a.content)
})

Configuration Options

const astra = createClient({
  // Required
  apiUrl: 'https://api.astraguard.io',
  productId: 'prod_xxx',

  // Optional
  timeout: 10000,        // Request timeout in ms (default: 10000)
  debug: false,          // Enable debug logging (default: false)
  headers: {             // Custom headers for all requests
    'X-Custom-Header': 'value'
  }
})

Error Handling

All SDK methods can throw AstraGuardError with these codes:

| Code | Description | |------|-------------| | INVALID_LICENSE | License key is invalid or not found | | LICENSE_EXPIRED | License has expired | | LICENSE_REVOKED | License was revoked by admin | | LICENSE_BANNED | License is banned | | HWID_MISMATCH | License bound to different device | | MAX_ACTIVATIONS | Maximum activations reached | | NETWORK_ERROR | Network/connection error | | SERVER_ERROR | Server-side error | | INVALID_CONFIG | Invalid SDK configuration | | UNAUTHORIZED | Not authenticated or session expired | | RATE_LIMITED | Too many requests | | MAINTENANCE_MODE | Server is under maintenance |

import { AstraGuardError } from '@astraguard/sdk'

try {
  await astra.validate(key)
} catch (error) {
  if (error instanceof AstraGuardError) {
    console.log('Error code:', error.code)
    console.log('Message:', error.message)
    console.log('Status:', error.statusCode)
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  License,
  LicenseStatus,
  LicenseValidationResult,
  CustomerSession,
  UpdateInfo,
  ProductVariable,
  AstraGuardConfig
} from '@astraguard/sdk'

Browser Usage

For browser environments, use the browser-compatible HWID generator:

import { createClient, generateBrowserHwid } from '@astraguard/sdk'

const hwid = await generateBrowserHwid()
const result = await astra.validate(licenseKey, hwid)

Best Practices

1. Store the license key securely - Don't hardcode license keys
2. Handle offline gracefully - Cache validation results for offline use
3. Validate periodically - Re-validate licenses every session or daily
4. Use events - Subscribe to events for real-time license status changes
5. Don't expose the SDK in production - Obfuscate your code

Support

• Documentation: https://docs.astraguard.io
• Dashboard: https://astraguard.io/dashboard
• Email: [email protected]

License

MIT