Shoprime SDK

A production-grade Node.js SDK for the Shoprime.ng API. This SDK provides a simple, robust, and type-safe way to integrate social media marketing services into your Node.js applications.

Features

• 🚀 Easy to use - Simple and intuitive API
• 🔒 Type-safe - Built with TypeScript for better developer experience
• 🛡️ Robust error handling - Comprehensive error types and validation
• 🔄 Automatic retries - Built-in retry logic with exponential backoff
• 📱 Social Media Services - Support for Instagram, Facebook, Twitter, TikTok, YouTube and more
• 📊 Order Management - Create, track, and manage orders
• 🔄 Refill Support - Automatic refills for supported services
• 💰 Balance Management - Check account balance and spending
• ✅ Well tested - Comprehensive test suite with high coverage
• 📚 Full documentation - Complete API documentation and examples

Installation

npm install shoprime-sdk

Quick Start

import { ShoprimeClient } from 'shoprime-sdk';

// Initialize the client
const client = new ShoprimeClient('your-api-key');

// Get available services
async function getServices() {
    try {
        const services = await client.services.list();
        console.log('Available services:', services);
    } catch (error) {
        console.error('Error fetching services:', error.message);
    }
}

// Create an order
async function createOrder() {
    try {
        const order = await client.orders.add({
            service: 1, // Service ID from services list
            link: 'https://instagram.com/username',
            quantity: 1000
        });
        console.log('Order created:', order.order);
    } catch (error) {
        console.error('Error creating order:', error.message);
    }
}

getServices();
createOrder();

Configuration

Basic Configuration

const client = new ShoprimeClient('your-api-key');

Advanced Configuration

const client = new ShoprimeClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://shoprime.ng/api/v2', // Optional
    timeout: 30000, // Optional (30 seconds)
    retries: 3 // Optional (number of retries)
});

API Reference

Services

List All Services

const services = await client.services.list();
console.log('Available services:', services);

Get Service by ID

const service = await client.services.getById(1);
if (service) {
    console.log('Service found:', service.name);
} else {
    console.log('Service not found');
}

Search Services

// Search by name
const followerServices = await client.services.search('followers');

// Get services by category
const instagramServices = await client.services.getByCategory('Instagram');

// Get services that support refills
const refillableServices = await client.services.getRefillable();

// Get services that support cancellation
const cancellableServices = await client.services.getCancellable();

Orders

Create an Order

const order = await client.orders.add({
    service: 1,
    link: 'https://instagram.com/username',
    quantity: 1000,
    runs: 5, // Optional: for drip-feed orders
    interval: 60 // Optional: interval in minutes for drip-feed
});

Check Order Status

// Single order status
const status = await client.orders.status(12345);
console.log('Order status:', status.status);
console.log('Remaining:', status.remains);

// Multiple orders status
const statuses = await client.orders.multiStatus([12345, 12346, 12347]);
Object.entries(statuses).forEach(([orderId, status]) => {
    if ('error' in status) {
        console.log(`Order ${orderId} error:`, status.error);
    } else {
        console.log(`Order ${orderId} status:`, status.status);
    }
});

Cancel Orders

const results = await client.orders.cancel([12345, 12346]);
results.forEach(result => {
    if ('error' in result.cancel) {
        console.log(`Failed to cancel order ${result.order}:`, result.cancel.error);
    } else {
        console.log(`Order ${result.order} cancelled successfully`);
    }
});

Check if Order Exists

const exists = await client.orders.exists(12345);
if (exists) {
    console.log('Order exists');
} else {
    console.log('Order not found');
}

Refills

Create a Refill

// Single refill
const refill = await client.refills.create(12345);
console.log('Refill created:', refill.refill);

// Multiple refills
const results = await client.refills.multiCreate([12345, 12346]);
results.forEach(result => {
    if ('error' in result.refill) {
        console.log(`Failed to create refill for order ${result.order}:`, result.refill.error);
    } else {
        console.log(`Refill created for order ${result.order}:`, result.refill);
    }
});

Check Refill Status

// Single refill status
const status = await client.refills.status(123);
console.log('Refill status:', status.status);

// Multiple refills status
const statuses = await client.refills.multiStatus([123, 124, 125]);
statuses.forEach(status => {
    if ('error' in status.status) {
        console.log(`Refill ${status.refill} error:`, status.status.error);
    } else {
        console.log(`Refill ${status.refill} status:`, status.status);
    }
});

Balance

Get Account Balance

// Get full balance information
const balance = await client.balance.get();
console.log('Balance:', balance.balance, balance.currency);

// Get balance as number
const amount = await client.balance.getAmount();
console.log('Balance amount:', amount);

// Get formatted balance
const formatted = await client.balance.getFormatted();
console.log('Formatted balance:', formatted); // e.g., "$100.84"

// Check if sufficient balance
const hasSufficientBalance = await client.balance.hasSufficientBalance(10.50);
if (hasSufficientBalance) {
    console.log('Sufficient balance available');
} else {
    console.log('Insufficient balance');
}

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
    ShoprimeError, 
    ApiError, 
    ValidationError, 
    AuthenticationError, 
    NetworkError,
    OrderNotFoundError,
    ServiceNotFoundError,
    InsufficientBalanceError
} from 'shoprime-sdk';

try {
    await client.orders.add({
        service: 1,
        link: 'https://instagram.com/username',
        quantity: 1000
    });
} catch (error) {
    if (error instanceof ValidationError) {
        console.error('Validation error:', error.message);
        console.error('Field:', error.field);
    } else if (error instanceof AuthenticationError) {
        console.error('Authentication failed:', error.message);
    } else if (error instanceof OrderNotFoundError) {
        console.error('Order not found:', error.message);
    } else if (error instanceof InsufficientBalanceError) {
        console.error('Insufficient balance:', error.message);
    } else if (error instanceof ApiError) {
        console.error('API error:', error.message, 'Code:', error.code);
    } else if (error instanceof NetworkError) {
        console.error('Network error:', error.message);
    } else {
        console.error('Unknown error:', error.message);
    }
}

Validation

The SDK includes built-in validation for:

• API Key: Must be a non-empty string
• Service ID: Must be a positive integer
• Order ID: Must be a positive integer
• Refill ID: Must be a positive integer
• URLs: Must be valid HTTP/HTTPS URLs
• Quantity: Must be a positive integer
• Timeout: Must be a positive integer (max 5 minutes)
• Retries: Must be a non-negative integer (max 10)

Testing Connection

try {
    const isConnected = await client.testConnection();
    if (isConnected) {
        console.log('Connection successful!');
    } else {
        console.log('Connection failed');
    }
} catch (error) {
    console.error('Connection test failed:', error.message);
}

Environment Variables

For security, it's recommended to use environment variables:

# .env file
SHOPRIME_API_KEY=your-api-key

const client = new ShoprimeClient({
    apiKey: process.env.SHOPRIME_API_KEY!
});

TypeScript Support

This SDK is built with TypeScript and provides full type definitions. All API responses are properly typed:

import { 
    Service, 
    AddOrderResponse, 
    OrderStatusResponse, 
    BalanceResponse 
} from 'shoprime-sdk';

const services: Service[] = await client.services.list();
const order: AddOrderResponse = await client.orders.add({...});
const status: OrderStatusResponse = await client.orders.status(12345);
const balance: BalanceResponse = await client.balance.get();

Examples

Complete Order Management Example

import { ShoprimeClient, ValidationError, ApiError } from 'shoprime-sdk';

async function manageOrder() {
    const client = new ShoprimeClient({
        apiKey: process.env.SHOPRIME_API_KEY!
    });

    try {
        // Check balance first
        const balance = await client.balance.get();
        console.log(`Current balance: ${balance.balance} ${balance.currency}`);

        // Get available services
        const services = await client.services.search('followers');
        if (services.length === 0) {
            console.log('No follower services available');
            return;
        }

        const service = services[0];
        console.log(`Using service: ${service.name} (Rate: ${service.rate})`);

        // Create order
        const order = await client.orders.add({
            service: service.service,
            link: 'https://instagram.com/username',
            quantity: parseInt(service.min)
        });

        console.log(`Order created: ${order.order}`);

        // Check order status
        const status = await client.orders.status(order.order);
        console.log(`Order status: ${status.status}`);

        // If service supports refills and order is completed, create a refill
        if (service.refill && status.status === 'Completed') {
            const refill = await client.refills.create(order.order);
            console.log(`Refill created: ${refill.refill}`);
        }

    } catch (error) {
        if (error instanceof ValidationError) {
            console.error('Invalid input:', error.message);
        } else if (error instanceof ApiError) {
            console.error('API error:', error.message, 'Code:', error.code);
        } else {
            console.error('Unexpected error:', error.message);
        }
    }
}

manageOrder();

Bulk Order Processing Example

import { ShoprimeClient } from 'shoprime-sdk';

async function processBulkOrders() {
    const client = new ShoprimeClient(process.env.SHOPRIME_API_KEY!);

    const orderRequests = [
        { service: 1, link: 'https://instagram.com/user1', quantity: 1000 },
        { service: 2, link: 'https://instagram.com/user2', quantity: 500 },
        { service: 1, link: 'https://instagram.com/user3', quantity: 2000 }
    ];

    const orderIds: number[] = [];

    // Create all orders
    for (const request of orderRequests) {
        try {
            const order = await client.orders.add(request);
            orderIds.push(order.order);
            console.log(`Order created: ${order.order} for ${request.link}`);
        } catch (error) {
            console.error(`Failed to create order for ${request.link}:`, error.message);
        }
    }

    // Check status of all orders
    if (orderIds.length > 0) {
        const statuses = await client.orders.multiStatus(orderIds);
        Object.entries(statuses).forEach(([orderId, status]) => {
            if ('error' in status) {
                console.log(`Order ${orderId} error:`, status.error);
            } else {
                console.log(`Order ${orderId}: ${status.status} (${status.remains} remaining)`);
            }
        });
    }
}

processBulkOrders();

Client Information

// Get client information
const info = client.getInfo();
console.log('SDK version:', info.version);
console.log('Base URL:', info.baseUrl);
console.log('Timeout:', info.timeout);
console.log('Retries:', info.retries);
console.log('API Key:', info.apiKey); // Masked for security

// Get masked API key
const maskedKey = client.getApiKey();
console.log('API Key:', maskedKey); // e.g., "abc***xyz"

// Update API key
client.setApiKey('new-api-key');

Author

Timothy Dake

• Email: [email protected]
• Phone: +2348067841008
• GitHub: timdake4

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [email protected]
• 🌐 Website: https://shoprime.ng
• 📚 API Documentation: https://shoprime.ng/api

Changelog

v1.0.0

• Initial release
• Full API coverage for Shoprime.ng
• TypeScript support
• Comprehensive error handling
• Automatic retries with exponential backoff
• Complete documentation and examples