Miso Apps SDK

SDKs for email services and shop management in Shopify applications.

Installation

npm install @misoapps/mail-sdk @misoapps/shop-sdk

Mail SDK (@misoapps/mail-sdk)

Setup

import { createMailClient } from '@misoapps/mail-sdk';

const mailClient = createMailClient({
  endpoint: 'https://mail-service.example.com',
  shopDomain: 'my-shop.myshopify.com', // Required for User SMTP APIs
});

Send Email (User SMTP)

const result = await mailClient.sendEmail({
  to: 'customer@example.com',
  fromEmail: 'shop@example.com',
  fromName: 'My Shop',        // optional
  replyTo: ['support@example.com'], // optional
  subject: 'Hello!',
  html: '<h1>Welcome!</h1>',
  text: 'Welcome!',           // optional
});
// { success: true, messageId: '...', logId: '...' }

Send Email (System SMTP - AWS SES)

fromEmail is fixed from server's AWS_SMTP_FROM_EMAIL env:

const result = await mailClient.sendSystemEmail({
  to: 'customer@example.com',
  fromName: 'Miso Apps',      // optional
  replyTo: ['support@example.com'], // optional
  subject: 'Hello!',
  html: '<h1>Welcome!</h1>',
  text: 'Welcome!',           // optional
});

Get Email Logs

const logs = await mailClient.getEmailLogs({
  status: 'sent',   // optional: 'pending' | 'sent' | 'failed'
  type: 'user',     // optional: 'user' | 'system'
  page: 1,          // optional
  limit: 20,        // optional
});
// { logs: [...], total: 100, page: 1, pages: 5 }

SMTP Configuration

// Create/Update (upsert)
const config = await mailClient.upsertSmtpConfig({
  host: 'smtp.gmail.com',
  port: 587,        // optional, default: 587
  secure: false,    // optional, default: false
  username: 'user@gmail.com',
  password: 'app-password',
});

// Get
const config = await mailClient.getSmtpConfig(); // SmtpConfig | null

// Update (partial)
await mailClient.updateSmtpConfig({
  port: 465,
  secure: true,
  isActive: true,
});

// Delete
await mailClient.deleteSmtpConfig();
// { success: true, message: '...' }

// Test connection
const result = await mailClient.testSmtpConnection();
// { success: true, message: 'SMTP connection successful' }
// or { success: false, message: '...', error: '...' }

Mail SDK Types

import type {
  MailClientConfig, MailClient,
  SendEmailRequest, SendSystemEmailRequest, SendEmailResponse,
  EmailLog, GetEmailLogsParams, GetEmailLogsResponse,
  EmailStatus, EmailType,
  SmtpConfig, CreateSmtpConfigRequest, UpdateSmtpConfigRequest, TestSmtpResponse,
} from '@misoapps/mail-sdk';

Shop SDK (@misoapps/shop-sdk)

Setup

import { createShopServices, Platform, AppID } from '@misoapps/shop-sdk';

const shopService = createShopServices(
  'http://localhost:5000',
  'shopify'  // Platform: 'shopify' | 'shopline'
);

Install App

const result = await shopService.installApp({
  shop: 'example.myshopify.com',
  shopName: 'Example Shop',
  contactEmail: 'contact@example.com',
  themeId: 'theme-123',       // optional
  app: {
    appId: 'llmstxt',         // AppID
    plan: 'basic',
    accessToken: 'token',     // optional
  },
});
// { message: 'App installed successfully', status: 'NEW' | 'INSTALLED' | 'REINSTALLED', shop: IShop }

Uninstall App

const result = await shopService.uninstallApp({
  shop: 'example.myshopify.com',
  appId: 'llmstxt',
});
// { message: 'App uninstalled successfully', shop: IShop }

Get App

const { shop, app } = await shopService.getApp('example.myshopify.com', 'llmstxt');
// shop: IShop (without apps array), app: IAppInfo

Update App

const { shop, app } = await shopService.updateApp(
  'example.myshopify.com',
  'llmstxt',
  {
    plan: 'premium',          // optional
    isReviewed: true,         // optional
    accessToken: 'new-token', // optional
  }
);

Shop Queries

// Get single shop
const { shop } = await shopService.getShop('example.myshopify.com');

// Get shop's apps
const { apps } = await shopService.getShopApps('example.myshopify.com');

// List shops (paginated)
const { shops, total, page, pages } = await shopService.listShops({
  page: 1,          // default: 1
  limit: 10,        // default: 10
  platform: 'shopify', // optional filter
});

// Find recently uninstalled (last 10 days)
const { shops } = await shopService.findUninstalledShops('llmstxt');

// Get stats
const stats = await shopService.getStats();
// { totalShops, totalInstalls, activeInstalls }

Shop SDK Types

import type {
  Platform, AppID, Shop, AppInfo,
  InstallAppPayload, InstallAppResponse,
  UninstallAppPayload, UninstallAppResponse,
  UpdateAppPayload, UpdateAppResponse,
  GetAppResponse, GetShopResponse, GetShopAppsResponse,
  ListShopsResponse, FindUninstalledShopsResponse, GetStatsResponse,
} from '@misoapps/shop-sdk';

Environment Variables

MAIL_SERVICE_ENDPOINT=https://mail-api.misoapps.com
SHOP_SERVICE_ENDPOINT=https://shop-api.misoapps.com

Integration with Remix

See references/remix-integration.md for Remix loader/action patterns.