Реализация Marketplace плагинов/интеграций для SaaS-приложения

Реализация Marketplace плагинов/интеграций для SaaS-приложения

Маркетплейс расширений превращает продукт в платформу: партнёры создают интеграции, пользователи устанавливают нужные. Atlassian Marketplace, Shopify App Store, Figma Plugins — примеры.

Архитектура: два типа расширений

Server-side интеграции — OAuth-приложения, которые взаимодействуют с вашим API от имени пользователя. Сторонний сервис (например, Zapier или n8n) авторизуется и дёргает ваш API.

Client-side плагины — JavaScript-код, исполняемый в iframe или Web Worker на стороне клиента. Figma Plugin Model — пример.

Реестр плагинов

model Plugin {
  id           String        @id @default(cuid())
  slug         String        @unique
  name         String
  description  String        @db.Text
  author       String
  authorUrl    String?
  iconUrl      String?
  category     PluginCategory
  installCount Int           @default(0)
  rating       Float?
  isVerified   Boolean       @default(false)
  isPublished  Boolean       @default(false)

  // Для server-side: OAuth credentials
  clientId     String?       @unique
  clientSecret String?       // зашифрован

  // Manifest
  permissions  String[]      // ['read:projects', 'write:tasks']
  webhookUrl   String?
  oauthConfig  Json?

  installations PluginInstallation[]
  reviews       PluginReview[]
}

model PluginInstallation {
  id          String   @id @default(cuid())
  pluginId    String
  tenantId    String
  installedAt DateTime @default(now())
  config      Json?    // настройки конкретной установки
  accessToken String?  // OAuth token тенанта для плагина

  plugin Plugin @relation(fields: [pluginId], references: [id])
  tenant Tenant @relation(fields: [tenantId], references: [id])

  @@unique([pluginId, tenantId])
}

Процесс установки плагина

// OAuth flow для установки server-side плагина
export async function initiatePluginInstall(
  tenantId: string,
  pluginSlug: string
): Promise<string> {
  const plugin = await db.plugin.findUniqueOrThrow({
    where: { slug: pluginSlug }
  });

  // Генерируем state для CSRF защиты
  const state = await generateState({
    tenantId,
    pluginId: plugin.id,
    action: 'install',
  });

  // Redirect на OAuth провайдера плагина
  const authUrl = new URL(plugin.oauthConfig?.authorizationUrl as string);
  authUrl.searchParams.set('client_id', plugin.clientId!);
  authUrl.searchParams.set('redirect_uri', `${process.env.APP_URL}/marketplace/callback`);
  authUrl.searchParams.set('scope', plugin.permissions.join(' '));
  authUrl.searchParams.set('state', state);
  authUrl.searchParams.set('response_type', 'code');

  return authUrl.toString();
}

// Callback после OAuth авторизации
export async function completePluginInstall(
  code: string,
  state: string
): Promise<void> {
  const { tenantId, pluginId } = await verifyState(state);

  const plugin = await db.plugin.findUniqueOrThrow({
    where: { id: pluginId }
  });

  // Обмениваем code на token
  const tokenResponse = await fetch(plugin.oauthConfig?.tokenUrl as string, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      code,
      client_id: plugin.clientId,
      client_secret: decryptToken(plugin.clientSecret!),
      redirect_uri: `${process.env.APP_URL}/marketplace/callback`,
      grant_type: 'authorization_code',
    }),
  });

  const tokens = await tokenResponse.json();

  await db.pluginInstallation.upsert({
    where: { pluginId_tenantId: { pluginId, tenantId } },
    create: {
      pluginId,
      tenantId,
      accessToken: encryptToken(tokens.access_token),
    },
    update: {
      accessToken: encryptToken(tokens.access_token),
    }
  });

  // Уведомляем плагин об установке
  if (plugin.webhookUrl) {
    await fetch(plugin.webhookUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        event: 'plugin.installed',
        tenantId,
        timestamp: new Date().toISOString(),
      }),
    });
  }

  await db.plugin.update({
    where: { id: pluginId },
    data: { installCount: { increment: 1 } }
  });
}

API для разработчиков плагинов

// Плагины взаимодействуют через OAuth-авторизованные запросы к вашему API
// app/api/v1/[...]/route.ts

export async function validatePluginRequest(request: Request): Promise<{
  plugin: Plugin;
  tenantId: string;
}> {
  const authHeader = request.headers.get('Authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    throw new ApiError(401, 'Missing authorization');
  }

  const token = authHeader.slice(7);

  // Проверяем токен
  const installation = await db.pluginInstallation.findFirst({
    where: {
      // В реальности: верифицируем JWT или ищем по hash токена
      accessToken: encryptToken(token),
    },
    include: { plugin: true }
  });

  if (!installation) {
    throw new ApiError(401, 'Invalid token');
  }

  return {
    plugin: installation.plugin,
    tenantId: installation.tenantId,
  };
}

Маркетплейс UI

// app/marketplace/page.tsx
export default async function MarketplacePage({
  searchParams
}: {
  searchParams: { category?: string; q?: string }
}) {
  const plugins = await db.plugin.findMany({
    where: {
      isPublished: true,
      ...(searchParams.category ? { category: searchParams.category as PluginCategory } : {}),
      ...(searchParams.q ? {
        OR: [
          { name: { contains: searchParams.q, mode: 'insensitive' } },
          { description: { contains: searchParams.q, mode: 'insensitive' } },
        ]
      } : {}),
    },
    orderBy: { installCount: 'desc' },
  });

  const tenant = await getCurrentTenant();
  const installedPluginIds = new Set(
    (await db.pluginInstallation.findMany({
      where: { tenantId: tenant!.id },
      select: { pluginId: true },
    })).map(i => i.pluginId)
  );

  return (
    <div>
      <MarketplaceSearch />
      <CategoryFilter />
      <PluginGrid
        plugins={plugins}
        installedIds={installedPluginIds}
      />
    </div>
  );
}

Разработка маркетплейса плагинов с OAuth установкой и API для разработчиков — 8–14 рабочих дней.