@fayz-ai/core 0.1.7 → 0.2.0

package/src/integrations/index.ts

@@ -0,0 +1,170 @@
+// ---------------------------------------------------------------------------
+// Integration Connector spine
+// ---------------------------------------------------------------------------
+// An integration is a connector that keeps canonical Fayz data in agreement
+// with an external provider (Google Calendar, open banking, Shopify, …). This
+// module is the thin shared contract both native (SDK) and client-built
+// connectors implement. The heavy lifting (auth, fetch/push, idempotent
+// upserts) runs in the data plane — typically a Supabase Edge Function — while
+// the control plane (a settings tab + this contract) lives in the app/plugin.
+//
+// Design notes live in docs/bling-integration-brief.md. Proven precedents:
+// the Fayz runtime OAuth broker (packages/core/src/runtime/oauth.ts) and the
+// bank-statement edge functions in the predecessor app.
+import type * as React from 'react'
+
+/** How a connector authenticates to its provider. */
+export type IntegrationAuthKind = 'oauth' | 'api-key' | 'mtls'
+
+/** Which way data flows for a given capability. */
+export type SyncDirection = 'inbound' | 'outbound' | 'bidirectional'
+
+/** What causes a sync to run. */
+export type SyncTrigger = 'on-write' | 'scheduled' | 'manual' | 'webhook'
+
+/** One thing a connector can sync (an entity + its direction + triggers). */
+export interface ConnectorCapability {
+  /** Canonical entity synced, e.g. 'booking', 'movement'. */
+  entity: string
+  direction: SyncDirection
+  triggers: SyncTrigger[]
+}
+
+/** The state of a tenant's connection to a provider (one row in a *_integrations table). */
+export interface ConnectionConfig {
+  /** Provider key, e.g. 'google', 'plugbank'. */
+  provider: string
+  /** Whether the connection is active and should sync. */
+  active: boolean
+  /** Opaque, provider-specific config (calendar id, account id, cursor, …). Never secrets. */
+  settings?: Record<string, unknown>
+  /** Last successful sync, ISO timestamp. */
+  lastSyncAt?: string
+}
+
+/** Audit record of one sync execution (generalizes *_sync_log / *_sync_runs). */
+export interface SyncRun {
+  id?: string
+  provider: string
+  direction: SyncDirection
+  trigger: SyncTrigger
+  status: 'success' | 'partial' | 'error'
+  /** Items pulled/pushed and how many were written. */
+  fetched?: number
+  written?: number
+  /** Pagination/incremental cursor advanced by this run. */
+  cursor?: string
+  error?: string
+  startedAt?: string
+  finishedAt?: string
+}
+
+export interface TestConnectionResult {
+  ok: boolean
+  message?: string
+}
+
+/**
+ * A connector's control-plane descriptor. The data-plane verbs (testConnection,
+ * sync) are usually thin clients that invoke a Supabase Edge Function — the
+ * function holds credentials and does the real work.
+ */
+export interface Connector {
+  /** Stable connector id, e.g. 'google-calendar', 'plugbank'. */
+  id: string
+  /** Provider key matching ConnectionConfig.provider. */
+  provider: string
+  /** Plugin this connector extends, e.g. 'agenda', 'financial'. */
+  pluginId: string
+  authKind: IntegrationAuthKind
+  capabilities: ConnectorCapability[]
+  /** Validate the stored credentials/config without syncing. */
+  testConnection?(config: ConnectionConfig): Promise<TestConnectionResult>
+  /** Run a sync for the given direction; returns the audit record. */
+  sync?(input: { config: ConnectionConfig; direction: SyncDirection; trigger: SyncTrigger }): Promise<SyncRun>
+}
+
+// ---------------------------------------------------------------------------
+// Connector UI contract — how an addon plugin EXTENDS a host plugin's settings
+// ---------------------------------------------------------------------------
+// An addon plugin declares one or more ConnectorDefinitions on its manifest
+// (`connectors: [...]`). The runtime groups them by `hostPluginId`, and the host
+// plugin's settings panel renders them in a unified "Integrations" tab — the
+// same connect/credentials experience for every connector. The connector-
+// specific bits (import a statement, sync now, history) live in `ExtraPanel`.
+
+/** A credential input the unified setup form renders for an api-key/mtls connector. */
+export interface ConnectorField {
+  key: string
+  label: string
+  type: 'text' | 'password'
+  placeholder?: string
+}
+
+export interface ConnectorStatus {
+  connected: boolean
+  detail?: string
+}
+
+/**
+ * UI-facing connector descriptor. Built on the data-plane `Connector` concept
+ * (`pluginId` → `hostPluginId`), plus the control-plane hooks the unified
+ * Integrations hub calls. Lives in core so `PluginManifest.connectors` can type
+ * it; the rendering hub lives in `@fayz-ai/saas`.
+ */
+export interface ConnectorDefinition {
+  /** Stable connector id, e.g. 'google-calendar', 'plugbank'. */
+  id: string
+  /** The plugin this connector extends, e.g. 'financial', 'agenda'. */
+  hostPluginId: string
+  name: string
+  description?: string
+  /** Lucide icon name. */
+  icon?: string
+  authKind: IntegrationAuthKind
+  /** Declarative credentials — the unified form renders these (api-key / mtls). */
+  fields?: ConnectorField[]
+  /** Current connection state for the status badge. */
+  getStatus(): Promise<ConnectorStatus>
+  /** Validate credentials without persisting (api-key / mtls). */
+  testConnection?(values: Record<string, string>): Promise<TestConnectionResult>
+  /** Persist the connection (api-key / mtls). */
+  saveConnection?(values: Record<string, string>): Promise<void>
+  /** Begin an OAuth connect flow — returns the consent URL to redirect to. */
+  startOAuth?(redirectTo?: string): Promise<string>
+  /** Tear down the connection. */
+  disconnect?(): Promise<void>
+  /** Optional connector-specific UI below the connect panel (import / sync / history). */
+  ExtraPanel?: React.ComponentType
+}
+
+/**
+ * Wrap an object's async methods so a handler fires AFTER selected methods
+ * resolve — the non-invasive hook for outbound, event-driven sync when there's
+ * no app-level event bus. Example: wrap an AgendaDataProvider so that after
+ * createBooking/updateBooking/deleteBooking succeed, an external calendar is
+ * updated. The handler runs fire-and-forget; its failures never break the call.
+ */
+export function withAfterHooks<T extends object>(
+  target: T,
+  methods: Partial<Record<keyof T, (args: unknown[], result: unknown) => void | Promise<void>>>,
+): T {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      const orig = Reflect.get(obj, prop, receiver)
+      const hook = (methods as Record<string | symbol, ((args: unknown[], result: unknown) => void | Promise<void>) | undefined>)[prop]
+      if (typeof orig !== 'function' || !hook) return orig
+      return (...args: unknown[]) => {
+        const result = (orig as (...a: unknown[]) => unknown).apply(obj, args)
+        if (result instanceof Promise) {
+          return result.then((value) => {
+            try { void Promise.resolve(hook(args, value)).catch(() => {}) } catch { /* never break the call */ }
+            return value
+          })
+        }
+        try { void Promise.resolve(hook(args, result)).catch(() => {}) } catch { /* noop */ }
+        return result
+      }
+    },
+  })
+}

package/src/manifest/index.ts

@@ -129,7 +129,7 @@ export function migrateManifest(input: AnyManifest): AppManifest {
   let version = typeof m.manifestVersion === 'number' ? m.manifestVersion : 1
   if (version > CURRENT_MANIFEST_VERSION) {
     throw new Error(
-      `Manifest version ${version} is newer than this SDK supports (${CURRENT_MANIFEST_VERSION}). Upgrade @fayz-ai/app-runtime.`,
+      `Manifest version ${version} is newer than this SDK supports (${CURRENT_MANIFEST_VERSION}). Upgrade @fayz-ai/core.`,
     )
   }
   while (version < CURRENT_MANIFEST_VERSION) {

package/src/plugin/runtime.ts

@@ -20,6 +20,7 @@ import type {
   DashboardSurface,
 } from '../types/plugins'
 import type { FeatureDeclaration } from '../types/permissions'
+import type { ConnectorDefinition } from '../integrations'
 import { getComponent } from '../registry'
 
 /** The plugin contract version this runtime understands. A plugin declaring a
@@ -107,6 +108,7 @@ function createEmptyRuntime(context: PluginRuntimeContext = EMPTY_CONTEXT): Plug
     capabilities: [],
     aiTools: [],
     registries: new Map(),
+    connectorsByHost: new Map(),
     pluginFeatures: [],
     issues: [],
   }
@@ -136,7 +138,7 @@ export function resolvePluginRuntime({
       issues.push({
         type: 'incompatible_api_version',
         pluginId: plugin.id,
-        message: `Plugin "${plugin.id}" requires plugin API v${plugin.apiVersion}, but this runtime supports v${PLUGIN_API_VERSION}. Upgrade @fayz-ai/app-runtime.`,
+        message: `Plugin "${plugin.id}" requires plugin API v${plugin.apiVersion}, but this runtime supports v${PLUGIN_API_VERSION}. Upgrade @fayz-ai/core.`,
       })
       continue
     }
@@ -238,6 +240,7 @@ export function resolvePluginRuntime({
   const capabilities: PluginCapability[] = []
   const aiTools: PluginAITool[] = []
   const registries = new Map<string, PluginRegistryDef[]>()
+  const connectorsByHost = new Map<string, ConnectorDefinition[]>()
   const pluginFeatures: FeatureDeclaration[] = []
 
   for (const plugin of activePlugins) {
@@ -251,6 +254,12 @@ export function resolvePluginRuntime({
     capabilities.push(...(plugin.capabilities ?? []))
     aiTools.push(...plugin.resolvedAITools)
     if (plugin.resolvedRegistries.length > 0) registries.set(plugin.id, plugin.resolvedRegistries)
+    // Group each addon's connectors under the host plugin they extend.
+    for (const connector of plugin.connectors ?? []) {
+      const list = connectorsByHost.get(connector.hostPluginId) ?? []
+      list.push(connector)
+      connectorsByHost.set(connector.hostPluginId, list)
+    }
     if (plugin.declaredFeatures) pluginFeatures.push(...plugin.declaredFeatures)
     widgets.push(...plugin.widgets.map((w, i) => ({
       ...w,
@@ -274,7 +283,7 @@ export function resolvePluginRuntime({
   widgets.sort((a, b) => a.zone !== b.zone ? a.zone.localeCompare(b.zone) : a.order - b.order)
   dashboardWidgets.sort((a, b) => a.order - b.order)
 
-  return { context, plugins: resolvedPlugins, activePlugins, routes, navigation, settingsTabs, widgets, dashboardWidgets, capabilities, aiTools, issues, registries, pluginFeatures }
+  return { context, plugins: resolvedPlugins, activePlugins, routes, navigation, settingsTabs, widgets, dashboardWidgets, capabilities, aiTools, issues, registries, connectorsByHost, pluginFeatures }
 }
 
 export function getWidgetsForZone(
@@ -311,3 +320,8 @@ export function usePluginRuntime(): PluginRuntime {
 export function usePluginRuntimeOptional(): PluginRuntime | null {
   return React.useContext(PluginRuntimeContext)
 }
+
+/** Connectors contributed by addon plugins that extend the given host plugin. */
+export function useConnectorsForPlugin(hostPluginId: string): ConnectorDefinition[] {
+  return usePluginRuntime().connectorsByHost.get(hostPluginId) ?? []
+}

package/src/router/history.ts

@@ -0,0 +1,86 @@
+import { create } from 'zustand'
+
+/**
+ * Global, cross-module navigation history.
+ *
+ * Per-module nav hooks (useModuleNavigation) only remember views *within* one
+ * module, so they can't tell you where you came from after crossing a module
+ * boundary (e.g. Financial statements → a client/person page). This store sits
+ * above all modules: the app shell records every route change here with a
+ * human label, and the shared SubpageHeader reads it to render a context-aware
+ * "back to {where you came from}" link that returns to the actual previous page.
+ */
+
+export interface NavHistoryEntry {
+  /** Route path without the leading '#', e.g. '/financial/statements'. */
+  path: string
+  /** Human, module-level label for the page, e.g. 'Financeiro'. */
+  label: string
+}
+
+interface NavHistoryState {
+  stack: NavHistoryEntry[]
+  /** Record a visit. Consecutive visits to the same path collapse (label refreshes). */
+  record: (entry: NavHistoryEntry) => void
+}
+
+const MAX_ENTRIES = 20
+
+export const useNavHistoryStore = create<NavHistoryState>((set) => ({
+  stack: [],
+  record: (entry) =>
+    set((s) => {
+      const top = s.stack[s.stack.length - 1]
+      if (top && top.path === entry.path) {
+        if (top.label === entry.label) return s
+        const next = s.stack.slice()
+        next[next.length - 1] = entry
+        return { stack: next }
+      }
+      const next = [...s.stack, entry]
+      return { stack: next.length > MAX_ENTRIES ? next.slice(-MAX_ENTRIES) : next }
+    }),
+}))
+
+/** Record a route visit. Call from the app shell whenever the route changes. */
+export function recordNavigation(path: string, label: string): void {
+  useNavHistoryStore.getState().record({ path, label })
+}
+
+// Dev-only debug handle: inspect history in the console via `__navHistory.getState().stack`.
+if (typeof window !== 'undefined') {
+  ;(window as unknown as { __navHistory?: typeof useNavHistoryStore }).__navHistory = useNavHistoryStore
+}
+
+/**
+ * The page the user most recently came from, relative to `currentPath`.
+ *
+ * Returns the latest recorded entry whose path differs from `currentPath`. This
+ * is intentionally robust to ordering: it gives the right referrer whether or
+ * not the current page has been recorded yet, avoiding a stale first paint.
+ */
+export function useNavReferrer(currentPath: string): NavHistoryEntry | null {
+  return useNavHistoryStore((s) => {
+    for (let i = s.stack.length - 1; i >= 0; i--) {
+      if (s.stack[i].path !== currentPath) return s.stack[i]
+    }
+    return null
+  })
+}
+
+/**
+ * Return to the actual previous page via the browser history. Falls back to the
+ * provided callback when there's no in-app history to pop (e.g. a deep link).
+ */
+export function navHistoryBack(fallback?: () => void): void {
+  if (useNavHistoryStore.getState().stack.length >= 2) {
+    window.history.back()
+  } else {
+    fallback?.()
+  }
+}
+
+/** Top-level module segment of a route path ('/financial/statements' → 'financial'). */
+export function routeModule(path: string): string {
+  return path.replace(/^\/+/, '').split('/')[0] ?? ''
+}

package/src/testing/index.ts

@@ -0,0 +1,116 @@
+// ---------------------------------------------------------------------------
+// Plugin contract assertions — the integrity half of the deploy gate.
+// ---------------------------------------------------------------------------
+// Framework-agnostic runtime checks (no test-runner dependency) that any
+// plugin's *.test.ts calls to prove its manifest/connector conform to the
+// platform contract BEFORE it can ship. A plugin that fails these would break
+// the host app at mount time (missing route component, duplicate ids, malformed
+// settings tab). Pair with a capability test (does the plugin do its job?) — see
+// PLUGIN_PATTERNS.md → capability anatomy. These throw on the first violation.
+import type { PluginManifest } from '../types/plugins'
+import type { Connector } from '../integrations'
+
+export class PluginContractError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'PluginContractError'
+  }
+}
+
+function fail(scope: string, msg: string): never {
+  throw new PluginContractError(`[${scope}] ${msg}`)
+}
+
+function nonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim().length > 0
+}
+
+/**
+ * Assert a PluginManifest is structurally sound enough to mount safely.
+ * Checks identity, navigation/route wiring, settings tabs, declared features,
+ * and id uniqueness. Throws PluginContractError on the first problem.
+ */
+export function assertPluginManifestContract(manifest: PluginManifest): void {
+  const id = manifest?.id
+  const scope = nonEmptyString(id) ? id : '<unknown plugin>'
+
+  for (const field of ['id', 'name', 'icon', 'version'] as const) {
+    if (!nonEmptyString(manifest?.[field])) fail(scope, `manifest.${field} must be a non-empty string`)
+  }
+
+  if (!Array.isArray(manifest.navigation)) fail(scope, 'manifest.navigation must be an array (use [] for settings-only plugins)')
+  if (!Array.isArray(manifest.routes)) fail(scope, 'manifest.routes must be an array (use [] for settings-only plugins)')
+
+  // Every nav entry must point at a route; every route needs a path + component.
+  for (const [i, nav] of manifest.navigation.entries()) {
+    if (!nonEmptyString((nav as any)?.route)) fail(scope, `navigation[${i}].route must be a non-empty string`)
+  }
+  const routePaths = new Set<string>()
+  for (const [i, route] of manifest.routes.entries()) {
+    if (!nonEmptyString((route as any)?.path)) fail(scope, `routes[${i}].path must be a non-empty string`)
+    if (typeof (route as any)?.component !== 'function') fail(scope, `routes[${i}].component must be a component`)
+    if (routePaths.has((route as any).path)) fail(scope, `duplicate route path "${(route as any).path}"`)
+    routePaths.add((route as any).path)
+  }
+  // A nav entry that links to a route the plugin doesn't declare is dead UI.
+  for (const [i, nav] of manifest.navigation.entries()) {
+    const r = (nav as any).route
+    if (routePaths.size > 0 && !routePaths.has(r)) {
+      fail(scope, `navigation[${i}].route "${r}" has no matching route in manifest.routes`)
+    }
+  }
+
+  // Settings tabs (the only UI surface integrations need) must be renderable.
+  const settingIds = new Set<string>()
+  for (const [i, tab] of (manifest.settings ?? []).entries()) {
+    if (!nonEmptyString((tab as any)?.id)) fail(scope, `settings[${i}].id must be a non-empty string`)
+    if (!nonEmptyString((tab as any)?.label)) fail(scope, `settings[${i}].label must be a non-empty string`)
+    if (typeof (tab as any)?.component !== 'function') fail(scope, `settings[${i}].component must be a component`)
+    if (settingIds.has((tab as any).id)) fail(scope, `duplicate settings tab id "${(tab as any).id}"`)
+    settingIds.add((tab as any).id)
+  }
+
+  for (const [i, feat] of (manifest.declaredFeatures ?? []).entries()) {
+    if (!nonEmptyString((feat as any)?.id)) fail(scope, `declaredFeatures[${i}].id must be a non-empty string`)
+  }
+
+  // A plugin that contributes nothing mountable is almost always a mistake.
+  // (Connector-only addon plugins contribute via `connectors` instead.)
+  if (
+    manifest.navigation.length === 0 &&
+    manifest.routes.length === 0 &&
+    (manifest.settings ?? []).length === 0 &&
+    (manifest.connectors ?? []).length === 0
+  ) {
+    fail(scope, 'plugin contributes no navigation, routes, settings, or connectors — it would mount but do nothing')
+  }
+}
+
+const AUTH_KINDS = new Set(['oauth', 'api-key', 'mtls'])
+const DIRECTIONS = new Set(['inbound', 'outbound', 'bidirectional'])
+const TRIGGERS = new Set(['on-write', 'scheduled', 'manual', 'webhook'])
+
+/**
+ * Assert an integration Connector descriptor is well-formed: identity present,
+ * a known auth kind, and at least one capability with a valid direction +
+ * trigger set. This is the contract a connector must satisfy BEFORE its
+ * data-plane (edge function) exists — the TDD anchor for an integration.
+ */
+export function assertConnectorContract(connector: Connector): void {
+  const scope = nonEmptyString(connector?.id) ? `connector:${connector.id}` : '<unknown connector>'
+  for (const field of ['id', 'provider', 'pluginId'] as const) {
+    if (!nonEmptyString(connector?.[field])) fail(scope, `connector.${field} must be a non-empty string`)
+  }
+  if (!AUTH_KINDS.has(connector.authKind)) fail(scope, `connector.authKind "${connector.authKind}" is not one of ${[...AUTH_KINDS].join(', ')}`)
+  if (!Array.isArray(connector.capabilities) || connector.capabilities.length === 0) {
+    fail(scope, 'connector.capabilities must list at least one capability')
+  }
+  for (const [i, cap] of connector.capabilities.entries()) {
+    if (!nonEmptyString(cap?.entity)) fail(scope, `capabilities[${i}].entity must be a non-empty string`)
+    if (!DIRECTIONS.has(cap.direction)) fail(scope, `capabilities[${i}].direction "${cap.direction}" is invalid`)
+    if (!Array.isArray(cap.triggers) || cap.triggers.length === 0) fail(scope, `capabilities[${i}].triggers must be non-empty`)
+    for (const trig of cap.triggers) {
+      if (!TRIGGERS.has(trig)) fail(scope, `capabilities[${i}] has unknown trigger "${trig}"`)
+    }
+  }
+}

package/src/types/crud.ts

@@ -5,10 +5,30 @@ export type FieldType =
   | 'text' | 'email' | 'phone' | 'url' | 'image'
   | 'number' | 'currency'
   | 'select' | 'multiselect' | 'segmented'
+  | 'relation'
   | 'date' | 'datetime' | 'time'
   | 'boolean' | 'textarea'
   | 'color' | 'computed'
 
+/** Foreign-key source for a `relation` field: the option list is loaded from a
+ *  table at runtime ({value→label}) so the stored value is a real id (e.g. a
+ *  uuid), not a static string. Use for FK columns the user must pick from a
+ *  seeded/managed table (e.g. payment_method_type_id → payment_method_types). */
+export interface FieldRelation {
+  /** Table to read options from (e.g. 'payment_method_types'). */
+  table: string
+  /** Column stored as the field value. Default 'id'. */
+  valueField?: string
+  /** Column shown as the option label. Default 'name'. */
+  labelField?: string
+  /** Scope options to the active tenant via tenant_id. Default true. */
+  tenantScoped?: boolean
+  /** Schema the table lives in (e.g. 'saas_core'). Default public. */
+  schema?: string
+  /** Extra equality filters applied to the option query. */
+  filter?: Record<string, unknown>
+}
+
 /** Read-only display produced by a `computed` field's `compute()`. */
 export interface ComputedFieldValue {
   display: string
@@ -27,6 +47,8 @@ export interface FieldDef {
   /** Options for `select` / `multiselect` / `segmented`. The optional
    *  `description` is shown under the label on `segmented` radio-cards. */
   options?: string[] | { label: string; value: string; description?: string }[]
+  /** Required for `relation` fields — where to load the option list from. */
+  relation?: FieldRelation
   min?: number
   max?: number
   /** ISO currency code for `currency` fields (e.g. 'BRL'). */
@@ -71,6 +93,9 @@ export interface DetailTab {
   componentId?: string
   visibleFor?: string[]
   props?: Record<string, unknown>
+  /** Only show this tab when a plugin has contributed a widget to this zone (e.g. a
+   *  financial plugin enabling a per-person statement tab). Hidden when no widget. */
+  requiresWidgetZone?: string
 }
 
 export type FormLayout = 'person' | 'product' | 'service' | 'location' | 'order' | 'subject' | 'generic'

package/src/types/index.ts

@@ -1,7 +1,7 @@
 // Re-export all core types
 export type { EntityArchetype, BaseEntity, PersonEntity, ProductEntity, ServiceEntity, OrderEntity, TransactionEntity, LocationEntity, ScheduleEntity, CategoryEntity } from './entities'
-export type { EntityDef, FieldDef, FieldType, FieldGroup, DetailTab, FormLayout, ComputedFieldValue } from './crud'
-export type { PluginManifest, PluginScope, PluginStatus, ResolvedPluginManifest, PluginRuntime, PluginRuntimeContext, PluginWidgetZone, PluginWidgetDefinition, PluginNavigationEntry, PluginSettingsTab, PluginRouteDefinition, PluginAITool, PluginRegistryDef, PluginMigration, VerticalId, ScaffoldType } from './plugins'
+export type { EntityDef, FieldDef, FieldType, FieldRelation, FieldGroup, DetailTab, FormLayout, ComputedFieldValue } from './crud'
+export type { PluginManifest, PluginScope, PluginStatus, ResolvedPluginManifest, PluginRuntime, PluginRuntimeContext, PluginWidgetZone, PluginWidgetDefinition, PluginNavigationEntry, PluginSettingsTab, PluginRouteDefinition, PluginAITool, PluginRegistryDef, PluginMigration, PluginServerAction, PluginCustomFieldsDef, PluginDiagnostic, VerticalId, ScaffoldType } from './plugins'
 export type { AuthAdapter, AuthUser, AuthSession } from './auth'
 export type { OrgAdapter, Organization, OrgMember } from './org'
 export type { PermissionsConfig, FeatureDeclaration, PermissionAction } from './permissions'

package/src/types/plugins.ts

@@ -1,6 +1,7 @@
 import type React from 'react'
-import type { EntityDef } from './crud'
+import type { EntityDef, FieldDef } from './crud'
 import type { FeatureDeclaration, PermissionAction } from './permissions'
+import type { ConnectorDefinition } from '../integrations'
 
 export type VerticalId = 'beauty' | 'food' | 'health' | 'services' | 'retail' | 'education' | (string & {})
 export type PluginScope = 'core' | 'vertical' | 'universal' | 'addon' | 'tenant'
@@ -260,6 +261,65 @@ export interface PluginOnboarding {
   description?: string
 }
 
+/**
+ * A server-side action or workflow a plugin exposes. The action runs *behind the
+ * Fayz boundary* — a Supabase Edge Function or an RPC, never in the app — so
+ * provider credentials stay server-side (see docs/architecture-boundaries.md §4).
+ * Declared as data so the AppManifest can bind triggers→actions and the AI can
+ * call them safely. Implementation wiring is intentionally lazy; this reserves the
+ * contract shape.
+ */
+export interface PluginServerAction {
+  id: string
+  name: string
+  description?: string
+  /** How the action is executed behind the Fayz boundary. */
+  kind: 'edge-function' | 'rpc'
+  /** Edge function name or RPC name to invoke. */
+  handler: string
+  /** JSON Schema for the action input (editor / AI / validation). */
+  inputSchema?: Record<string, unknown>
+  /** JSON Schema for the action result. */
+  outputSchema?: Record<string, unknown>
+  permission?: PluginPermissionRequirement
+  /** Event name(s) that trigger this action when emitted on the bus. */
+  triggers?: string[]
+}
+
+/**
+ * Custom fields a plugin adds to an entity *without editing that entity's owner*.
+ * The fields are persisted on an extension table / JSONB column resolved by the
+ * data provider — the declarative seam behind layer-C (private extension) custom
+ * fields. See docs/architecture-boundaries.md §5.
+ */
+export interface PluginCustomFieldsDef {
+  /** Entity key these fields extend, e.g. 'crm.client'. */
+  entity: string
+  fields: FieldDef[]
+  /** Extension table that stores them; provider convention applies when omitted. */
+  table?: string
+}
+
+/**
+ * A health check a plugin contributes to the diagnostics / boot report surfaced by
+ * `fayz doctor`. Declared as data so the platform can verify a plugin's backend
+ * prerequisites are present without running it.
+ */
+export interface PluginDiagnostic {
+  id: string
+  description?: string
+  /** What the runtime should verify exists for this plugin to work. */
+  requires: {
+    rpcs?: string[]
+    views?: string[]
+    tables?: string[]
+    migrations?: string[]
+    env?: string[]
+  }
+  /** Severity when the requirement is missing. Defaults to 'warn'. */
+  level?: 'error' | 'warn' | 'info'
+}
+
 export interface PluginManifest {
   id: string
   name: string
@@ -291,7 +351,19 @@ export interface PluginManifest {
   permissions?: string[]
   declaredFeatures?: FeatureDeclaration[]
   registries?: PluginRegistryDef[]
+  /**
+   * Connectors this plugin contributes. An ADDON plugin declares its connector(s)
+   * here, each naming the `hostPluginId` it extends; the runtime groups them by
+   * host and the host plugin's settings render them in a unified Integrations tab.
+   */
+  connectors?: ConnectorDefinition[]
   migrations?: PluginMigration[]
+  /** Server-side actions/workflows the plugin exposes behind the Fayz boundary. */
+  serverActions?: PluginServerAction[]
+  /** Custom fields this plugin adds to entities it does not own. */
+  customFields?: PluginCustomFieldsDef[]
+  /** Backend prerequisites the plugin needs; surfaced by `fayz doctor`. */
+  diagnostics?: PluginDiagnostic[]
   onboarding?: PluginOnboarding
   locales?: Record<string, Record<string, string>>
   /** Marketplace metadata for npm discovery */
@@ -359,5 +431,7 @@ export interface PluginRuntime {
   aiTools: PluginAITool[]
   issues: PluginRuntimeIssue[]
   registries: Map<string, PluginRegistryDef[]>
+  /** Connectors contributed by active plugins, grouped by the host plugin they extend. */
+  connectorsByHost: Map<string, ConnectorDefinition[]>
   pluginFeatures: FeatureDeclaration[]
 }