Package Exports

shoprime-sdk
shoprime-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (shoprime-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: timdake4@gmail.com
Phone: +2348067841008
GitHub: timdake4

Contributing

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

License

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

Support

📧 Email: support@shoprime.ng
🌐 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