Plugin System (Integrations)

import { definePlugin } from '../plugin-kit'

export const myPlugin = definePlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  description: 'Sync widgets from MyService as sessions.',
  category: 'sessions',
  icon: { src: '/logos/my-plugin.svg' },
  multiInstance: true,

  auth: {
    type: 'api_key',
    fields: [
      { id: 'apiKey', label: 'API Key', secret: true, required: true },
    ],
    test: async (credentials, ctx) => {
      // Validate credentials against the provider. Throw on failure.
      return {
        externalAccountId: 'workspace-id',
        accountLabel: 'Acme Workspace',
        credentials: { apiKey: credentials.apiKey },
      }
    },
  },

  streams: {
    widgets: {
      kind: 'sessions',
      label: 'Widgets',
      sync: async (ctx) => {
        // Pull data from the provider and call ctx.ingest.session(...)
      },
    },
  },
})

auth: {
  type: 'api_key',
  fields: [
    { id: 'subdomain', label: 'Subdomain', placeholder: 'acme', required: true },
    { id: 'email', label: 'Admin Email', required: true },
    { id: 'apiToken', label: 'API Token', secret: true, required: true },
  ],
  test: async (credentials, ctx) => {
    // Call the provider to verify. Return the external account id + label + credentials to persist.
    return {
      externalAccountId: credentials.subdomain,
      accountLabel: `${credentials.subdomain}.zendesk.com`,
      credentials: { ...credentials },
    }
  },
}

auth: {
  type: 'oauth2',
  scopes: ['read', 'write'],
  authorizeUrl: 'https://provider.com/oauth/authorize',
  tokenUrl: 'https://api.provider.com/oauth/token',
  clientIdEnv: 'MY_PROVIDER_CLIENT_ID',
  clientSecretEnv: 'MY_PROVIDER_CLIENT_SECRET',
  onTokenExchanged: async (tokens, ctx) => {
    // Typically: call /me to get account id + label.
    return {
      externalAccountId: org.id,
      accountLabel: org.name,
      credentials: {
        accessToken: tokens.accessToken,
        refreshToken: tokens.refreshToken,
        expiresAt: tokens.expiresAt?.toISOString(),
      },
    }
  },
  refresh: async (credentials, ctx) => {
    // Optional. If absent, the runtime refreshes via standard grant_type=refresh_token.
  },
}

auth: {
  type: 'github_app',
  onInstallation: async (installationId, ctx) => { ... },
}

auth: {
  type: 'custom',
  connect: async (req, ctx) => {
    // Handle the connect request directly.
    // Call ctx.saveConnection(...) on success.
    return NextResponse.json({ connectionId: result.connectionId })
  },
}

streams: {
  meetings: {
    kind: 'sessions',
    label: 'Meetings',
    description: 'Recorded meetings with transcripts.',
    frequencies: ['manual', '1h', '6h', '24h'],
    filterSchema: z.object({ fromDate: z.string().optional() }),
    defaultFilters: {},
    sync: async (ctx) => { ... },
  },
}

issues: {
  kind: 'issues',
  instances: async (ctx) => {
    const teams = await listTeams(ctx.credentials)
    return teams.map((t) => ({ id: t.id, label: t.name }))
  },
  sync: async (ctx) => {
    // ctx.instanceId is set per instance.
  },
}

sync: async (ctx: SyncCtx<MySettings, MyFilters>) => {
  ctx.credentials   // persisted credentials (refreshed OAuth tokens, etc)
  ctx.settings      // validated stream settings
  ctx.filters       // validated stream filters
  ctx.lastSyncAt    // incremental cursor
  ctx.syncMode      // 'incremental' | 'full'
  ctx.triggeredBy   // 'manual' | 'cron' | 'webhook'
  ctx.signal        // AbortSignal for cancellation
  ctx.logger        // structured logger

  // Ingestion primitives - the only way a plugin writes data.
  await ctx.ingest.session({ ... })
  await ctx.ingest.contact({ ... })
  await ctx.ingest.company({ ... })
  await ctx.ingest.issue({ ... })
  await ctx.ingest.knowledge({ ... })

  // Deduplication helpers.
  if (await ctx.isSynced(externalId)) continue
  const synced = await ctx.getSyncedIds()

  // Progress emission (streams to SSE for manual triggers).
  ctx.progress({ type: 'synced', externalId, hissunoId, message: '...' })

  // Persist refreshed credentials mid-sync.
  await ctx.saveCredentials(nextCredentials)
}

resolveConnection: async ({ payload, rawBody, request }) => {
  // 1. Verify signature against the raw body. Return null on mismatch.
  if (!verifySignature(rawBody, request.headers)) return null

  // 2. Handle setup challenges by returning a Response directly.
  if (payload.type === 'url_verification') {
    return NextResponse.json({ challenge: payload.challenge })
  }

  // 3. Resolve which connection this event belongs to.
  const connection = await findConnectionByExternalId('my-plugin', payload.team_id)
  return connection?.id ?? null
}

customHandlers: {
  teams: async (req, ctx) => {
    // GET /api/plugins/[pluginId]/[connectionId]/teams
    const teams = await listTeams(ctx.credentials)
    return NextResponse.json({ teams })
  },
}

ui: {
  ConfigDialog: lazy(() => import('./my-plugin-dialog')),
}

// app/src/lib/integrations/registry.ts
import { myPlugin } from './plugins/my-plugin'

const ALL_PLUGINS: PluginDef[] = [
  // ...existing plugins
  myPlugin,
]

app/src/lib/integrations/
  plugin-kit.ts          # PluginDef types + definePlugin()
  registry.ts            # the list of all plugins
  plugins/
    fathom.ts            # one file per plugin
    github.ts
    linear.ts
    slack.ts
    ...
  shared/                # runtime: ingestion, dedup, connections, oauth helpers
  <provider>/            # provider-specific clients (GitHub JWT, Fathom client, ...)