// README.md

Shopify Order Alerts

A Node.js package for monitoring Shopify orders and sending email alerts. Perfect for managing multiple stores and getting real-time notifications about new orders, order status changes, and custom order criteria.

Features

• Multi-store support: Manage multiple Shopify stores in one instance
• API version validation: Ensures correct Shopify API version format
• Email alerts: Send customized email notifications
• Real-time monitoring: Continuous order monitoring with configurable intervals
• Custom criteria: Filter orders by status, date, customer, and more
• Error handling: Comprehensive error handling with detailed messages

Installation

npm install shopify-order-alerts

Quick Start

const ShopifyOrderAlerts = require('shopify-order-alerts');

// Initialize
const orderAlerts = new ShopifyOrderAlerts();

// Add store
orderAlerts.addStore('mystore', 'mystore.myshopify.com', 'your-access-token', '2023-10');

// Configure email
orderAlerts.setEmailConfig({
  host: 'smtp.gmail.com',
  port: 587,
  secure: false,
  auth: {
    user: '[email protected]',
    pass: 'your-app-password'
  },
  from: '[email protected]'
});

// Start monitoring
const monitor = orderAlerts.startOrderMonitoring('mystore', ['[email protected]'], 15);

API Reference

Constructor

const orderAlerts = new ShopifyOrderAlerts();

Store Management

addStore(storeName, shopDomain, accessToken, apiVersion)

Add a new Shopify store configuration.

• storeName (string): Unique identifier for the store
• shopDomain (string): Shopify domain (e.g., 'mystore.myshopify.com')
• accessToken (string): Shopify Admin API access token
• apiVersion (string): API version in YYYY-MM format (e.g., '2023-10')

orderAlerts.addStore('store1', 'store1.myshopify.com', 'shpat_xxxxx', '2023-10');

getStoreInfo(storeName)

Get store configuration details.

const storeInfo = orderAlerts.getStoreInfo('store1');

getStoreNames()

Get all configured store names.

const stores = orderAlerts.getStoreNames();

Email Configuration

setEmailConfig(emailConfig)

Configure email settings for sending alerts.

orderAlerts.setEmailConfig({
  host: 'smtp.gmail.com',
  port: 587,
  secure: false,
  auth: {
    user: '[email protected]',
    pass: 'your-app-password'
  },
  from: '[email protected]'
});

testEmailConfig()

Test email configuration.

const result = await orderAlerts.testEmailConfig();

Order Retrieval

getOrders(storeName, params)

Get orders with optional parameters.

const orders = await orderAlerts.getOrders('store1', {
  status: 'open',
  limit: 50
});

getRecentOrders(storeName, hours)

Get recent orders (default: last 24 hours).

const recentOrders = await orderAlerts.getRecentOrders('store1', 12);

getOrdersByStatus(storeName, status, limit)

Get orders by status.

const openOrders = await orderAlerts.getOrdersByStatus('store1', 'open', 100);

Email Alerts

sendEmailAlert(recipients, subject, htmlContent, textContent)

Send custom email alert.

await orderAlerts.sendEmailAlert(
  ['[email protected]', '[email protected]'],
  'Custom Alert',
  '<h1>Alert Message</h1>',
  'Alert Message'
);

sendNewOrderAlert(storeName, recipients, orders)

Send new order notification.

await orderAlerts.sendNewOrderAlert('store1', ['[email protected]'], orders);

sendCustomOrderAlert(storeName, recipients, criteria, alertTitle)

Send alert based on custom criteria.

await orderAlerts.sendCustomOrderAlert(
  'store1',
  ['[email protected]'],
  { status: 'open', financial_status: 'paid' },
  'Paid Orders Alert'
);

Monitoring

startOrderMonitoring(storeName, recipients, checkInterval)

Start continuous order monitoring.

const monitor = orderAlerts.startOrderMonitoring('store1', ['[email protected]'], 10);

// Stop monitoring
monitor.stop();

// Get status
const status = monitor.getStatus();

Examples

Basic Usage

const ShopifyOrderAlerts = require('shopify-order-alerts');

async function basicExample() {
  const orderAlerts = new ShopifyOrderAlerts();

  // Add store
  orderAlerts.addStore('mystore', 'mystore.myshopify.com', 'shpat_xxxxx', '2023-10');

  // Configure email
  orderAlerts.setEmailConfig({
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: '[email protected]',
      pass: 'app-password'
    },
    from: '[email protected]'
  });

  // Get recent orders
  const recentOrders = await orderAlerts.getRecentOrders('mystore');
  console.log(`Found ${recentOrders.orders.length} recent orders`);

  // Send alert for new orders
  if (recentOrders.orders.length > 0) {
    await orderAlerts.sendNewOrderAlert('mystore', ['[email protected]'], recentOrders.orders);
  }
}

Multi-Store Monitoring

async function multiStoreExample() {
  const orderAlerts = new ShopifyOrderAlerts();

  // Add multiple stores
  orderAlerts.addStore('store1', 'store1.myshopify.com', 'token1', '2023-10');
  orderAlerts.addStore('store2', 'store2.myshopify.com', 'token2', '2024-01');

  // Configure email once
  orderAlerts.setEmailConfig({
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: '[email protected]',
      pass: 'app-password'
    },
    from: '[email protected]'
  });

  // Monitor all stores
  const monitors = [];
  for (const storeName of orderAlerts.getStoreNames()) {
    const monitor = orderAlerts.startOrderMonitoring(storeName, ['[email protected]'], 15);
    monitors.push(monitor);
  }

  // Stop all monitors after 1 hour
  setTimeout(() => {
    monitors.forEach(monitor => monitor.stop());
  }, 60 * 60 * 1000);
}

Custom Alert Criteria

async function customAlertExample() {
  const orderAlerts = new ShopifyOrderAlerts();

  // Setup (store and email config)
  orderAlerts.addStore('mystore', 'mystore.myshopify.com', 'token', '2023-10');
  orderAlerts.setEmailConfig({ /* email config */ });

  // Alert for high-value orders
  await orderAlerts.sendCustomOrderAlert(
    'mystore',
    ['[email protected]'],
    { 
      status: 'open',
      financial_status: 'paid'
    },
    'High Priority Orders'
  );

  // Alert for orders needing fulfillment
  await orderAlerts.sendCustomOrderAlert(
    'mystore',
    ['[email protected]'],
    { 
      status: 'open',
      fulfillment_status: 'unfulfilled'
    },
    'Orders Ready for Fulfillment'
  );
}

Error Handling

The package provides comprehensive error handling:

try {
  // Invalid API version
  orderAlerts.addStore('store1', 'store1.myshopify.com', 'token', '2023-1'); // Will throw error
} catch (error) {
  console.error('API Version Error:', error.message);
}

try {
  // Store not found
  const orders = await orderAlerts.getOrders('nonexistent-store');
} catch (error) {
  console.error('Store Error:', error.message);
}

try {
  // Email configuration issues
  await orderAlerts.sendEmailAlert(['invalid-email'], 'Test', 'Content');
} catch (error) {
  console.error('Email Error:', error.message);
}

Requirements

• Node.js >= 14.0.0
• Valid Shopify Admin API access token
• SMTP email server credentials

License

MIT