@fayz-ai/core 0.9.0 → 0.10.0

package/README.md

@@ -40,7 +40,7 @@ export const crmPlugin = definePlugin({
 ```
 
 ## Part of the Fayz SDK
-The headless core. `@fayz-ai/auth`, `@fayz-ai/ui`, and `@fayz-ai/saas` build the running app on top of it.
+The headless core. `@fayz-ai/auth`, `@fayz-ai/ui`, and `@fayz-ai/admin` build the running app on top of it.
 
 ## Roadmap & contributing
-Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/ROADMAP.md#core) for current gaps, missing features, and good first issues.
+Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/platform/ROADMAP.md#core) for current gaps, missing features, and good first issues.

package/dist/access/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/access/engine.ts","../../src/access/denial.ts","../../src/access/limits.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { PermissionProfile, PermissionAction, SystemPermission } from '../types/permissions'\nimport type { Plan } from '../types/billing'\n\n// ---------------------------------------------------------------------------\n// The access engine — the ONE implementation of the role × plan × limit\n// decision, shared by every runtime that gates anything:\n//\n//   - browser (saas AccessProvider / PermissionsProvider re-export from here)\n//   - headless client-plane (saas access/headless.ts)\n//   - the Fayz broker (server-side agent authorization imports this package)\n//\n// Hard constraint: this module (and everything under core/src/access) must stay\n// free of React, zustand and supabase — pure functions over plain data — so the\n// exact same code runs in Node/edge. Guarded by scripts/check-access-purity.mjs.\n// ---------------------------------------------------------------------------\n\n/** Why an access request was denied. `limit` only occurs on guarded writes. */\nexport type DenyReason = 'role' | 'plan' | 'limit'\n\nexport interface AccessDecision {\n  allowed: boolean\n  reason?: DenyReason\n}\n\n/** The minimal subject a decision needs — a projection of any richer session. */\nexport interface AccessSubject {\n  /** Effective RBAC profile — the previewed role during impersonation. */\n  profile: PermissionProfile | null\n  /** The tenant's currently-active plan. */\n  plan: Plan | null\n}\n\n/**\n * The org owner has every permission implicitly. Owner is represented by the\n * canonical role id `owner` across adapters (see org/adapters/supabase.ts\n * buildPermissionProfiles, which also grants owner all catalog perms, and the\n * mock adapter's `owner` fallback). We match by id first, falling back to the\n * (possibly localized) name for safety.\n */\nexport function isOwnerProfile(profile: PermissionProfile): boolean {\n  return profile.id === 'owner' || profile.name?.toLowerCase() === 'owner'\n}\n\n/**\n * The single role-side permission check. The plan axis composes ON TOP of it in\n * {@link resolveAccess} instead of reimplementing owner-bypass / `manage`\n * semantics.\n */\nexport function profileHasPermission(\n  profile: PermissionProfile | null,\n  feature: string,\n  action?: string,\n): boolean {\n  if (!profile) return true\n\n  // Owner bypass: never lock the owner out, even if the RBAC catalog is empty\n  // or still loading. Because permission checks read the *effective* profile,\n  // an owner previewing a non-owner role correctly loses this bypass — the\n  // preview stays honest.\n  if (isOwnerProfile(profile)) return true\n\n  const actions = profile.grants[feature]\n  if (!actions) return false\n\n  if (!action) return actions.length > 0\n\n  return actions.includes(action) || actions.includes('manage')\n}\n\n/**\n * The org-management side of a profile: managing team, billing, settings and\n * permissions themselves. Separate axis from `grants` — these gate the settings\n * tabs, not a feature's rows — and it follows the same owner bypass, so the one\n * person who can hand out access is never locked out of doing it.\n */\nexport function profileHasSystemPermission(\n  profile: PermissionProfile | null,\n  permission: SystemPermission,\n): boolean {\n  if (!profile) return true\n  if (isOwnerProfile(profile)) return true\n  return profile.systemPermissions?.includes(permission) ?? false\n}\n\n/**\n * Does the current plan entitle `feature`? A plan gates a feature ONLY with an\n * explicit `false`; absent means \"not gated by this plan\" (allowed). This keeps\n * entitlements additive and safe: a feature the plan has never heard of stays\n * open rather than silently locking.\n */\nexport function isEntitledByPlan(plan: Plan | null, feature: string): boolean {\n  return plan?.entitlements?.features?.[feature] !== false\n}\n\n/**\n * The single access decision: role FIRST, then plan.\n *\n * 1. Role — reuses `profileHasPermission` (owner bypass + `manage` semantics\n *    live there, and impersonation composes for free because `profile` is the\n *    previewed role). Denied → `{ allowed:false, reason:'role' }`.\n * 2. Plan — even the owner does NOT bypass the plan: upgrading is the tenant's\n *    decision, not a role power. Denied → `{ allowed:false, reason:'plan' }`.\n */\nexport function resolveAccess(\n  subject: AccessSubject,\n  feature: string,\n  action?: PermissionAction,\n): AccessDecision {\n  if (!profileHasPermission(subject.profile, feature, action)) {\n    return { allowed: false, reason: 'role' }\n  }\n  if (!isEntitledByPlan(subject.plan, feature)) {\n    return { allowed: false, reason: 'plan' }\n  }\n  return { allowed: true }\n}\n\n/**\n * Pure numeric side of a limit: given the plan cap, whether a countable\n * declaration exists, and the current usage, derive the limit math. Unlimited\n * when there's no declaration to count, no cap on the plan, or the cap is `-1`.\n */\nexport function resolveLimit(params: { cap: number | undefined; hasDeclaration: boolean; used: number }): {\n  max: number\n  used: number\n  remaining: number\n  atLimit: boolean\n  unlimited: boolean\n} {\n  const { cap, hasDeclaration, used } = params\n  const unlimited = !hasDeclaration || cap === undefined || cap === -1\n  const max = unlimited ? Infinity : cap\n  const remaining = unlimited ? Infinity : Math.max(0, max - used)\n  const atLimit = !unlimited && used >= max\n  return { max, used, remaining, atLimit, unlimited }\n}\n","import type { DenyReason } from './engine'\n\n// ---------------------------------------------------------------------------\n// The structured denial an AGENT surface returns instead of failing silently\n// (docs/ENTITLEMENTS.md § \"Superfície de agentes de IA\"). One shape for every\n// executor — FAB client-plane, the Fayz broker, and the pool RPCs (which emit\n// its jsonb mirror in their `denial` field) — so the model can explain the\n// denial and offer the upgrade path conversationally.\n// ---------------------------------------------------------------------------\n\n/** Where a denied tenant goes to upgrade — the conversational UpgradeModal. */\nexport const UPGRADE_URL = '/settings/subscription'\n\nexport interface AgentDenialLimit {\n  key: string\n  max: number\n  used: number\n}\n\nexport interface AgentDenial {\n  allowed: false\n  reason: DenyReason\n  /** Present when `reason === 'limit'`. */\n  limit?: AgentDenialLimit\n  upgradeUrl: string\n}\n\nexport type AgentGuardResult = { allowed: true } | AgentDenial\n\n/** Build a denial with the canonical upgrade URL attached. */\nexport function agentDenial(reason: DenyReason, limit?: AgentDenialLimit): AgentDenial {\n  return { allowed: false, reason, ...(limit ? { limit } : {}), upgradeUrl: UPGRADE_URL }\n}\n","import type { LimitDeclaration } from '../types/entitlements'\n\n/**\n * The 4-layer limit-declaration merge, extracted so the browser AccessProvider\n * and the manifest derivation (`fayz manifest emit`) resolve the EXACT same\n * final set: core built-ins < entity-derived < plugin `declaredLimits` < app\n * overrides. Later layers win by key. Pure: pass the layers in, get the merge\n * out — deriving a declaration FROM an entity stays at the call site.\n */\nexport function mergeLimitDeclarations(\n  ...layers: Array<LimitDeclaration[] | undefined>\n): LimitDeclaration[] {\n  const byKey = new Map<string, LimitDeclaration>()\n  for (const layer of layers) {\n    for (const decl of layer ?? []) byKey.set(decl.key, decl)\n  }\n  return Array.from(byKey.values())\n}\n"]}
+{"version":3,"sources":["../../src/access/engine.ts","../../src/access/denial.ts","../../src/access/limits.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { PermissionProfile, PermissionAction, SystemPermission } from '../types/permissions'\nimport type { Plan } from '../types/billing'\n\n// ---------------------------------------------------------------------------\n// The access engine — the ONE implementation of the role × plan × limit\n// decision, shared by every runtime that gates anything:\n//\n//   - browser (saas AccessProvider / PermissionsProvider re-export from here)\n//   - headless client-plane (saas access/headless.ts)\n//   - the Fayz broker (server-side agent authorization imports this package)\n//\n// Hard constraint: this module (and everything under core/src/access) must stay\n// free of React, zustand and supabase — pure functions over plain data — so the\n// exact same code runs in Node/edge. Guarded by scripts/check-access-purity.mjs.\n// ---------------------------------------------------------------------------\n\n/** Why an access request was denied. `limit` only occurs on guarded writes. */\nexport type DenyReason = 'role' | 'plan' | 'limit'\n\nexport interface AccessDecision {\n  allowed: boolean\n  reason?: DenyReason\n}\n\n/** The minimal subject a decision needs — a projection of any richer session. */\nexport interface AccessSubject {\n  /** Effective RBAC profile — the previewed role during impersonation. */\n  profile: PermissionProfile | null\n  /** The tenant's currently-active plan. */\n  plan: Plan | null\n}\n\n/**\n * The org owner has every permission implicitly. Owner is represented by the\n * canonical role id `owner` across adapters (see org/adapters/supabase.ts\n * buildPermissionProfiles, which also grants owner all catalog perms, and the\n * mock adapter's `owner` fallback). We match by id first, falling back to the\n * (possibly localized) name for safety.\n */\nexport function isOwnerProfile(profile: PermissionProfile): boolean {\n  return profile.id === 'owner' || profile.name?.toLowerCase() === 'owner'\n}\n\n/**\n * The single role-side permission check. The plan axis composes ON TOP of it in\n * {@link resolveAccess} instead of reimplementing owner-bypass / `manage`\n * semantics.\n */\nexport function profileHasPermission(\n  profile: PermissionProfile | null,\n  feature: string,\n  action?: string,\n): boolean {\n  if (!profile) return true\n\n  // Owner bypass: never lock the owner out, even if the RBAC catalog is empty\n  // or still loading. Because permission checks read the *effective* profile,\n  // an owner previewing a non-owner role correctly loses this bypass — the\n  // preview stays honest.\n  if (isOwnerProfile(profile)) return true\n\n  const actions = profile.grants[feature]\n  if (!actions) return false\n\n  if (!action) return actions.length > 0\n\n  return actions.includes(action) || actions.includes('manage')\n}\n\n/**\n * The org-management side of a profile: managing team, billing, settings and\n * permissions themselves. Separate axis from `grants` — these gate the settings\n * tabs, not a feature's rows — and it follows the same owner bypass, so the one\n * person who can hand out access is never locked out of doing it.\n */\nexport function profileHasSystemPermission(\n  profile: PermissionProfile | null,\n  permission: SystemPermission,\n): boolean {\n  if (!profile) return true\n  if (isOwnerProfile(profile)) return true\n  return profile.systemPermissions?.includes(permission) ?? false\n}\n\n/**\n * Does the current plan entitle `feature`? A plan gates a feature ONLY with an\n * explicit `false`; absent means \"not gated by this plan\" (allowed). This keeps\n * entitlements additive and safe: a feature the plan has never heard of stays\n * open rather than silently locking.\n */\nexport function isEntitledByPlan(plan: Plan | null, feature: string): boolean {\n  return plan?.entitlements?.features?.[feature] !== false\n}\n\n/**\n * The single access decision: role FIRST, then plan.\n *\n * 1. Role — reuses `profileHasPermission` (owner bypass + `manage` semantics\n *    live there, and impersonation composes for free because `profile` is the\n *    previewed role). Denied → `{ allowed:false, reason:'role' }`.\n * 2. Plan — even the owner does NOT bypass the plan: upgrading is the tenant's\n *    decision, not a role power. Denied → `{ allowed:false, reason:'plan' }`.\n */\nexport function resolveAccess(\n  subject: AccessSubject,\n  feature: string,\n  action?: PermissionAction,\n): AccessDecision {\n  if (!profileHasPermission(subject.profile, feature, action)) {\n    return { allowed: false, reason: 'role' }\n  }\n  if (!isEntitledByPlan(subject.plan, feature)) {\n    return { allowed: false, reason: 'plan' }\n  }\n  return { allowed: true }\n}\n\n/**\n * Pure numeric side of a limit: given the plan cap, whether a countable\n * declaration exists, and the current usage, derive the limit math. Unlimited\n * when there's no declaration to count, no cap on the plan, or the cap is `-1`.\n */\nexport function resolveLimit(params: { cap: number | undefined; hasDeclaration: boolean; used: number }): {\n  max: number\n  used: number\n  remaining: number\n  atLimit: boolean\n  unlimited: boolean\n} {\n  const { cap, hasDeclaration, used } = params\n  const unlimited = !hasDeclaration || cap === undefined || cap === -1\n  const max = unlimited ? Infinity : cap\n  const remaining = unlimited ? Infinity : Math.max(0, max - used)\n  const atLimit = !unlimited && used >= max\n  return { max, used, remaining, atLimit, unlimited }\n}\n","import type { DenyReason } from './engine'\n\n// ---------------------------------------------------------------------------\n// The structured denial an AGENT surface returns instead of failing silently\n// (docs/saas/ENTITLEMENTS.md § \"Superfície de agentes de IA\"). One shape for every\n// executor — FAB client-plane, the Fayz broker, and the pool RPCs (which emit\n// its jsonb mirror in their `denial` field) — so the model can explain the\n// denial and offer the upgrade path conversationally.\n// ---------------------------------------------------------------------------\n\n/** Where a denied tenant goes to upgrade — the conversational UpgradeModal. */\nexport const UPGRADE_URL = '/settings/subscription'\n\nexport interface AgentDenialLimit {\n  key: string\n  max: number\n  used: number\n}\n\nexport interface AgentDenial {\n  allowed: false\n  reason: DenyReason\n  /** Present when `reason === 'limit'`. */\n  limit?: AgentDenialLimit\n  upgradeUrl: string\n}\n\nexport type AgentGuardResult = { allowed: true } | AgentDenial\n\n/** Build a denial with the canonical upgrade URL attached. */\nexport function agentDenial(reason: DenyReason, limit?: AgentDenialLimit): AgentDenial {\n  return { allowed: false, reason, ...(limit ? { limit } : {}), upgradeUrl: UPGRADE_URL }\n}\n","import type { LimitDeclaration } from '../types/entitlements'\n\n/**\n * The 4-layer limit-declaration merge, extracted so the browser AccessProvider\n * and the manifest derivation (`fayz manifest emit`) resolve the EXACT same\n * final set: core built-ins < entity-derived < plugin `declaredLimits` < app\n * overrides. Later layers win by key. Pure: pass the layers in, get the merge\n * out — deriving a declaration FROM an entity stays at the call site.\n */\nexport function mergeLimitDeclarations(\n  ...layers: Array<LimitDeclaration[] | undefined>\n): LimitDeclaration[] {\n  const byKey = new Map<string, LimitDeclaration>()\n  for (const layer of layers) {\n    for (const decl of layer ?? []) byKey.set(decl.key, decl)\n  }\n  return Array.from(byKey.values())\n}\n"]}

package/dist/{chunk-L4TLMYGC.js → chunk-6RBW2Y5K.js}

@@ -1,4 +1,4 @@
-// src/integrations/index.ts
+// src/integrations.ts
 function connectorPlanes(def) {
   return def.planes?.length ? def.planes : ["sync"];
 }
@@ -38,5 +38,5 @@ function withAfterHooks(target, methods) {
 }
 
 export { connectorDirection, connectorPlanes, preferredPlane, withAfterHooks };
-//# sourceMappingURL=chunk-L4TLMYGC.js.map
-//# sourceMappingURL=chunk-L4TLMYGC.js.map
+//# sourceMappingURL=chunk-6RBW2Y5K.js.map
+//# sourceMappingURL=chunk-6RBW2Y5K.js.map

package/dist/chunk-6RBW2Y5K.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/integrations.ts"],"names":[],"mappings":";AA6LO,SAAS,gBAAgB,GAAA,EAA4D;AAC1F,EAAA,OAAO,IAAI,MAAA,EAAQ,MAAA,GAAS,GAAA,CAAI,MAAA,GAAS,CAAC,MAAM,CAAA;AAClD;AAOO,SAAS,eAAe,GAAA,EAA0D;AACvF,EAAA,OAAO,gBAAgB,GAAG,CAAA,CAAE,QAAA,CAAS,SAAS,IAAI,SAAA,GAAY,MAAA;AAChE;AAGO,SAAS,mBAAmB,GAAA,EAAiE;AAClG,EAAA,OAAO,IAAI,SAAA,IAAa,UAAA;AAC1B;AASO,SAAS,cAAA,CACd,QACA,OAAA,EACG;AACH,EAAA,OAAO,IAAI,MAAM,MAAA,EAAQ;AAAA,IACvB,GAAA,CAAI,GAAA,EAAK,IAAA,EAAM,QAAA,EAAU;AACvB,MAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,GAAA,CAAI,GAAA,EAAK,MAAM,QAAQ,CAAA;AAC5C,MAAA,MAAM,IAAA,GAAQ,QAA8G,IAAI,CAAA;AAChI,MAAA,IAAI,OAAO,IAAA,KAAS,UAAA,IAAc,CAAC,MAAM,OAAO,IAAA;AAChD,MAAA,OAAO,IAAI,IAAA,KAAoB;AAC7B,QAAA,MAAM,MAAA,GAAU,IAAA,CAAsC,KAAA,CAAM,GAAA,EAAK,IAAI,CAAA;AACrE,QAAA,IAAI,kBAAkB,OAAA,EAAS;AAC7B,UAAA,OAAO,MAAA,CAAO,IAAA,CAAK,CAAC,KAAA,KAAU;AAC5B,YAAA,IAAI;AAAE,cAAA,KAAK,OAAA,CAAQ,QAAQ,IAAA,CAAK,IAAA,EAAM,KAAK,CAAC,CAAA,CAAE,MAAM,MAAM;AAAA,cAAC,CAAC,CAAA;AAAA,YAAE,CAAA,CAAA,MAAQ;AAAA,YAA6B;AACnG,YAAA,OAAO,KAAA;AAAA,UACT,CAAC,CAAA;AAAA,QACH;AACA,QAAA,IAAI;AAAE,UAAA,KAAK,OAAA,CAAQ,QAAQ,IAAA,CAAK,IAAA,EAAM,MAAM,CAAC,CAAA,CAAE,MAAM,MAAM;AAAA,UAAC,CAAC,CAAA;AAAA,QAAE,CAAA,CAAA,MAAQ;AAAA,QAAa;AACpF,QAAA,OAAO,MAAA;AAAA,MACT,CAAA;AAAA,IACF;AAAA,GACD,CAAA;AACH","file":"chunk-6RBW2Y5K.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Integration Connector spine\n// ---------------------------------------------------------------------------\n// An integration is a connector that keeps canonical Fayz data in agreement\n// with an external provider (Google Calendar, open banking, Shopify, …). This\n// module is the thin shared contract both native (SDK) and client-built\n// connectors implement. The heavy lifting (auth, fetch/push, idempotent\n// upserts) runs in the data plane — typically a Supabase Edge Function — while\n// the control plane (a settings tab + this contract) lives in the app/plugin.\n//\n// Design notes live in docs/integrations/bling-integration-brief.md. Proven precedents:\n// the Fayz runtime OAuth broker (packages/core/src/runtime/oauth.ts) and the\n// bank-statement edge functions in the predecessor app.\nimport type * as React from 'react'\n\n/** How a connector authenticates to its provider. */\nexport type IntegrationAuthKind = 'oauth' | 'api-key' | 'mtls'\n\n// ---------------------------------------------------------------------------\n// Planes — the two ways a connector gets honoured\n// ---------------------------------------------------------------------------\n// \"Integração\" and \"conector\" are the same noun. What differs is the plane it\n// runs on:\n//\n//   - 'agentic' — the provider's tools are handed to the assistant. Nothing is\n//     copied: the agent calls the provider at the moment it needs the answer,\n//     so there is no mirror to drift and no de-para to maintain. Preferred\n//     whenever the provider offers it.\n//   - 'sync'    — the old-school pipeline: authorize, map, run, keep an audit\n//     trail. Required when the data must exist *inside* Fayz — to be listed,\n//     filtered, reported on, or read while the provider is unreachable.\n//\n// A connector may support both; `preferredPlane` encodes the house rule.\nexport type ConnectorPlane = 'agentic' | 'sync'\n\n/** Which side reaches for the other, from this app's point of view. */\nexport type ConnectorDirection = 'inbound' | 'outbound'\n\n/** A tool the assistant gains once a connector is resolved on the agentic plane. */\nexport interface ConnectorAgentTool {\n  name: string\n  description?: string\n}\n\n/** Which way data flows for a given capability. */\nexport type SyncDirection = 'inbound' | 'outbound' | 'bidirectional'\n\n/** What causes a sync to run. */\nexport type SyncTrigger = 'on-write' | 'scheduled' | 'manual' | 'webhook'\n\n/** One thing a connector can sync (an entity + its direction + triggers). */\nexport interface ConnectorCapability {\n  /** Canonical entity synced, e.g. 'booking', 'movement'. */\n  entity: string\n  direction: SyncDirection\n  triggers: SyncTrigger[]\n}\n\n/** The state of a tenant's connection to a provider (one row in a *_integrations table). */\nexport interface ConnectionConfig {\n  /** Provider key, e.g. 'google', 'plugbank'. */\n  provider: string\n  /** Whether the connection is active and should sync. */\n  active: boolean\n  /** Opaque, provider-specific config (calendar id, account id, cursor, …). Never secrets. */\n  settings?: Record<string, unknown>\n  /** Last successful sync, ISO timestamp. */\n  lastSyncAt?: string\n}\n\n/** Audit record of one sync execution (generalizes *_sync_log / *_sync_runs). */\nexport interface SyncRun {\n  id?: string\n  provider: string\n  direction: SyncDirection\n  trigger: SyncTrigger\n  status: 'success' | 'partial' | 'error'\n  /** Items pulled/pushed and how many were written. */\n  fetched?: number\n  written?: number\n  /** Pagination/incremental cursor advanced by this run. */\n  cursor?: string\n  error?: string\n  startedAt?: string\n  finishedAt?: string\n}\n\nexport interface TestConnectionResult {\n  ok: boolean\n  message?: string\n}\n\n/**\n * A connector's control-plane descriptor. The data-plane verbs (testConnection,\n * sync) are usually thin clients that invoke a Supabase Edge Function — the\n * function holds credentials and does the real work.\n */\nexport interface Connector {\n  /** Stable connector id, e.g. 'google-calendar', 'plugbank'. */\n  id: string\n  /** Provider key matching ConnectionConfig.provider. */\n  provider: string\n  /** Plugin this connector extends, e.g. 'agenda', 'financial'. */\n  pluginId: string\n  authKind: IntegrationAuthKind\n  capabilities: ConnectorCapability[]\n  /** Validate the stored credentials/config without syncing. */\n  testConnection?(config: ConnectionConfig): Promise<TestConnectionResult>\n  /** Run a sync for the given direction; returns the audit record. */\n  sync?(input: { config: ConnectionConfig; direction: SyncDirection; trigger: SyncTrigger }): Promise<SyncRun>\n}\n\n// ---------------------------------------------------------------------------\n// Connector UI contract — how an addon plugin EXTENDS a host plugin's settings\n// ---------------------------------------------------------------------------\n// An addon plugin declares one or more ConnectorDefinitions on its manifest\n// (`connectors: [...]`). The runtime groups them by `hostPluginId`, and the host\n// plugin's settings panel renders them in a unified \"Integrations\" tab — the\n// same connect/credentials experience for every connector. The connector-\n// specific bits (import a statement, sync now, history) live in `ExtraPanel`.\n\n/** A credential input the unified setup form renders for an api-key/mtls connector. */\nexport interface ConnectorField {\n  key: string\n  label: string\n  type: 'text' | 'password'\n  placeholder?: string\n}\n\nexport interface ConnectorStatus {\n  connected: boolean\n  detail?: string\n  /** Which plane the live connection is running on (when connected). */\n  plane?: ConnectorPlane\n}\n\n/**\n * UI-facing connector descriptor. Built on the data-plane `Connector` concept\n * (`pluginId` → `hostPluginId`), plus the control-plane hooks the unified\n * Integrations hub calls. Lives in core so `PluginManifest.connectors` can type\n * it; the rendering hub lives in `@fayz-ai/admin`.\n */\nexport interface ConnectorDefinition {\n  /** Stable connector id, e.g. 'google-calendar', 'plugbank'. */\n  id: string\n  /** The plugin this connector extends, e.g. 'financial', 'agenda'. */\n  hostPluginId: string\n  name: string\n  description?: string\n  /** Lucide icon name. */\n  icon?: string\n  /**\n   * The connector's own brand mark — a URL or an inline data URI. Preferred\n   * over the catalogue's icon and over `icon`, so a connector the Fayz\n   * directory doesn't carry still shows up as itself.\n   */\n  logoUrl?: string\n  authKind: IntegrationAuthKind\n  /** Planes this connector can be honoured on. Default: `['sync']`. */\n  planes?: ConnectorPlane[]\n  /** Default `'outbound'` — this app reaching a provider. */\n  direction?: ConnectorDirection\n  /** What the assistant gains on the agentic plane — shown before connecting. */\n  agentTools?: ConnectorAgentTool[]\n  /** Canonical entities this connector touches ('booking', 'movement'). */\n  entities?: string[]\n  /** Catalog category ('scheduling', 'payments', …) — matches the Fayz catalog. */\n  category?: string\n  /** Provider documentation, linked from the connector's detail. */\n  docsUrl?: string\n  /** Declarative credentials — the unified form renders these (api-key / mtls). */\n  fields?: ConnectorField[]\n  /** Current connection state for the status badge. */\n  getStatus(): Promise<ConnectorStatus>\n  /** Validate credentials without persisting (api-key / mtls). */\n  testConnection?(values: Record<string, string>): Promise<TestConnectionResult>\n  /** Persist the connection (api-key / mtls). */\n  saveConnection?(values: Record<string, string>): Promise<void>\n  /** Begin an OAuth connect flow — returns the consent URL to redirect to. */\n  startOAuth?(redirectTo?: string): Promise<string>\n  /** Tear down the connection. */\n  disconnect?(): Promise<void>\n  /** Move an existing connection between planes (only when `planes` has both). */\n  setPlane?(plane: ConnectorPlane): Promise<void>\n  /** Optional connector-specific UI below the connect panel (import / sync / history). */\n  ExtraPanel?: React.ComponentType\n}\n\n/** Planes a connector supports — the contract's default is the sync pipeline. */\nexport function connectorPlanes(def: Pick<ConnectorDefinition, 'planes'>): ConnectorPlane[] {\n  return def.planes?.length ? def.planes : ['sync']\n}\n\n/**\n * The plane to offer first. Agentic wins whenever the connector supports it:\n * handing the assistant a tool costs nothing to keep in agreement, while a sync\n * pipeline is a copy that has to be maintained for as long as it exists.\n */\nexport function preferredPlane(def: Pick<ConnectorDefinition, 'planes'>): ConnectorPlane {\n  return connectorPlanes(def).includes('agentic') ? 'agentic' : 'sync'\n}\n\n/** Direction a connector moves data in — outbound unless it says otherwise. */\nexport function connectorDirection(def: Pick<ConnectorDefinition, 'direction'>): ConnectorDirection {\n  return def.direction ?? 'outbound'\n}\n\n/**\n * Wrap an object's async methods so a handler fires AFTER selected methods\n * resolve — the non-invasive hook for outbound, event-driven sync when there's\n * no app-level event bus. Example: wrap an AgendaDataProvider so that after\n * createBooking/updateBooking/deleteBooking succeed, an external calendar is\n * updated. The handler runs fire-and-forget; its failures never break the call.\n */\nexport function withAfterHooks<T extends object>(\n  target: T,\n  methods: Partial<Record<keyof T, (args: unknown[], result: unknown) => void | Promise<void>>>,\n): T {\n  return new Proxy(target, {\n    get(obj, prop, receiver) {\n      const orig = Reflect.get(obj, prop, receiver)\n      const hook = (methods as Record<string | symbol, ((args: unknown[], result: unknown) => void | Promise<void>) | undefined>)[prop]\n      if (typeof orig !== 'function' || !hook) return orig\n      return (...args: unknown[]) => {\n        const result = (orig as (...a: unknown[]) => unknown).apply(obj, args)\n        if (result instanceof Promise) {\n          return result.then((value) => {\n            try { void Promise.resolve(hook(args, value)).catch(() => {}) } catch { /* never break the call */ }\n            return value\n          })\n        }\n        try { void Promise.resolve(hook(args, result)).catch(() => {}) } catch { /* noop */ }\n        return result\n      }\n    },\n  })\n}\n"]}