misoapps

Guide for using Miso Apps SDKs (@misoapps/mail-sdk and @misoapps/shop-sdk) in Shopify apps. Use this skill when the user needs to send emails via SMTP or AWS SES, manage SMTP configurations, retrieve

SKILL.md

GitHub

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.