Venshack SDK

Official TypeScript/JavaScript SDK for the Venshack Developer API. Built with TypeScript for full type safety and IntelliSense support.

Installation

Install the SDK using your preferred package manager:

npm install @venshack/sdk

yarn add @venshack/sdk

pnpm add @venshack/sdk

Quick Start

import { Venshack } from '@venshack/sdk';

// Initialize with your API key
const vsk = new Venshack('vsk_test_xxxxxxxxxxxxx');

// Or with options
const vsk = new Venshack({
  apiKey: 'vsk_test_xxxxxxxxxxxxx',
  baseUrl: 'https://api-developers.venshack.io', // optional
  timeout: 30000, // optional, in ms
});

TypeScript Support

The SDK is written in TypeScript and provides full type definitions out of the box. No additional @types packages required.

import { Venshack, VendingResponse, MeterValidation } from '@venshack/sdk';

const vsk = new Venshack('vsk_test_xxx');

// Types are automatically inferred
const validation: MeterValidation = await vsk.vending.validate({
  meterNumber: '1234567890123',
});

// IntelliSense shows available properties
console.log(validation.customerName);
console.log(validation.customerAddress);

Vending Module

Purchase prepaid electricity tokens and manage vending transactions.

Validate Meter

const result = await vsk.vending.validate({
  meterNumber: '1234567890123',
});

console.log(result.customerName);    // "John Doe"
console.log(result.customerAddress); // "123 Main Street"
console.log(result.meterType);       // "prepaid"

Purchase Token

const purchase = await vsk.vending.purchase({
  meterNumber: '1234567890123',
  amount: 5000, // ₦5,000
  estateId: 'est_xxxxx', // optional
});

console.log(purchase.token);       // "1234-5678-9012-3456-7890"
console.log(purchase.units);       // "45.67 kWh"
console.log(purchase.transactionId); // "txn_xxxxx"

Get Transaction

const txn = await vsk.vending.getTransaction('txn_xxxxx');
console.log(txn.status); // "completed"

Access Codes Module

Generate and verify visitor access codes for gated communities.

Create Access Code

const code = await vsk.accessCodes.create({
  guestName: 'Jane Smith',
  guestPhone: '+2348012345678',
  purpose: 'Delivery',
  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
});

// Note: The actual code is sent directly to the guest via SMS
console.log(code.id);     // "ac_xxxxx"
console.log(code.status); // "pending"

Verify Access Code

const verification = await vsk.accessCodes.verify({
  code: 'ABC123',
  markAsUsed: true,
});

if (verification.valid) {
  console.log(`Welcome ${verification.guestName}`);
}

Meters Module

Register and manage meters for your organization.

Register Meter

const meter = await vsk.meters.register({
  meterNumber: '1234567890123',
  label: 'Unit A1 - Ground Floor',
});

console.log(meter.status); // "pending_approval"

List Meters

const meters = await vsk.meters.list({
  status: 'approved',
  page: 1,
  limit: 20,
});

for (const meter of meters.data) {
  console.log(meter.meterNumber, meter.label);
}

Webhooks Module

Manage webhook endpoints and verify signatures.

Create Webhook

const webhook = await vsk.webhooks.create({
  url: 'https://your-app.com/webhooks/venshack',
  events: ['vending.completed', 'access_code.used'],
});

console.log(webhook.secret); // Save this for verification!

Verify Signature

import { verifyWebhookSignature } from '@venshack/sdk';

const isValid = verifyWebhookSignature({
  payload: request.body,
  signature: request.headers['x-venshack-signature'],
  secret: 'whsec_xxxxx',
});

if (!isValid) {
  throw new Error('Invalid webhook signature');
}

Error Handling

The SDK throws typed errors that you can catch and handle appropriately.

import { Venshack, VenshackError, RateLimitError } from '@venshack/sdk';

try {
  const result = await vsk.vending.purchase({ ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof VenshackError) {
    console.log(`Error: ${error.code} - ${error.message}`);
  }
}

Need Help?