@fayz-ai/core 0.9.0 → 0.11.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-BEGXYHS4.js

@@ -0,0 +1,566 @@
+import { getSupabaseClientOptional, getActiveTenantId } from './chunk-LARZWDHA.js';
+
+// src/integrations/events.ts
+function eventKeyMatches(pattern, key) {
+  if (pattern === "*") return true;
+  if (!pattern.endsWith("*")) return pattern === key;
+  const prefix = pattern.slice(0, -1);
+  return key.startsWith(prefix);
+}
+
+// src/integrations/permissions.ts
+var DATA_ACTIONS = ["read", "write"];
+var EVENT_ACTIONS = ["read", "listen", "emit"];
+function permissionActions(kind) {
+  return kind === "data" ? DATA_ACTIONS : EVENT_ACTIONS;
+}
+function isDataPermission(permission) {
+  return permission.kind === "data";
+}
+function isEventPermission(permission) {
+  return permission.kind === "event";
+}
+function grants(permission, action) {
+  return permission.actions.includes(action);
+}
+function connectorPermissions(def) {
+  return def?.permissions ?? [];
+}
+function connectorEntities(def) {
+  const declared = connectorPermissions(def).filter(isDataPermission).map((p) => p.resource);
+  if (declared.length > 0) return unique(declared);
+  return unique(def?.entities ?? []);
+}
+function connectorSubscribesTo(def) {
+  const declared = connectorPermissions(def).filter((p) => isEventPermission(p) && grants(p, "listen")).map((p) => p.resource);
+  if (declared.length > 0) return unique(declared);
+  return unique(def?.subscribesTo ?? []);
+}
+function connectorSubscribes(def, key) {
+  return connectorSubscribesTo(def).some((pattern) => eventKeyMatches(pattern, key));
+}
+function permissionsWrite(def) {
+  return connectorPermissions(def).some((p) => grants(p, "write") || grants(p, "emit"));
+}
+function hasSensitivePermission(def) {
+  return connectorPermissions(def).some((p) => p.sensitive === true);
+}
+function sortedPermissions(def) {
+  return [...connectorPermissions(def)].sort((a, b) => {
+    if (a.kind !== b.kind) return a.kind === "data" ? -1 : 1;
+    const sensitivity = Number(b.sensitive ?? false) - Number(a.sensitive ?? false);
+    if (sensitivity !== 0) return sensitivity;
+    const mutating = Number(mutates(b)) - Number(mutates(a));
+    if (mutating !== 0) return mutating;
+    return a.resource.localeCompare(b.resource);
+  });
+}
+function mutates(permission) {
+  return grants(permission, "write") || grants(permission, "emit");
+}
+function groupedPermissions(def) {
+  const sorted = sortedPermissions(def);
+  return {
+    data: sorted.filter(isDataPermission),
+    events: sorted.filter(isEventPermission)
+  };
+}
+function connectorGrantScopes(def) {
+  const scopes = [];
+  for (const permission of connectorPermissions(def)) {
+    for (const action of permission.actions) scopes.push(`${permission.kind}:${permission.resource}:${action}`);
+  }
+  return unique(scopes).sort();
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+
+// src/integrations/runtime-token.ts
+var ConnectorRuntimeTokenUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectorRuntimeTokenUnavailableError";
+  }
+};
+var _source = null;
+function setConnectorRuntimeTokenSource(source) {
+  _source = source;
+}
+function getConnectorRuntimeTokenSource() {
+  return _source;
+}
+async function connectorRuntimeToken(request) {
+  const source = _source;
+  if (!source) {
+    throw new ConnectorRuntimeTokenUnavailableError(
+      "This app installed no connector runtime-token source, so the data plane cannot prove which tenant it is for"
+    );
+  }
+  const value = typeof source === "function" ? await source(request) : source;
+  const token = typeof value === "string" ? value.trim() : "";
+  if (!token) {
+    throw new ConnectorRuntimeTokenUnavailableError(
+      "No runtime token is available for this session, so the call was not made"
+    );
+  }
+  return token;
+}
+
+// src/integrations/settings.ts
+function isSettingSet(value) {
+  if (value === void 0 || value === null) return false;
+  if (typeof value === "string") return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+function connectorSettings(def) {
+  return def.settings ?? [];
+}
+function missingRequiredSettings(settings, values) {
+  return (settings ?? []).filter((setting) => setting.requiredToOperate && !isSettingSet(values?.[setting.key])).map((setting) => setting.key);
+}
+function settingsStatus(settings, connection) {
+  if (!connection?.active) return { needsSetup: false };
+  const missing = missingRequiredSettings(settings, connection.settings);
+  return missing.length > 0 ? { needsSetup: true, missingSettings: missing } : { needsSetup: false };
+}
+function setupStatusDetail(missing) {
+  return `setup: ${missing.join(", ")}`;
+}
+
+// src/integrations/store.ts
+var CONNECTIONS_TABLE = "plg_connections";
+var SYNC_RUNS_TABLE = "plg_sync_runs";
+var ConnectionSettingsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionSettingsError";
+  }
+};
+function assertSettingsAllowed(settings, options, connectorId = "connector") {
+  const secret = new Set((options.fields ?? []).filter((f) => f.type === "password").map((f) => f.key));
+  const allowed = /* @__PURE__ */ new Set([
+    ...(options.fields ?? []).filter((f) => f.type !== "password").map((f) => f.key),
+    // A declared setting IS its own allow-list entry. Requiring it in
+    // `settingsKeys` as well is two places to add a key and one place to forget.
+    ...(options.settings ?? []).map((s) => s.key),
+    ...options.settingsKeys ?? []
+  ]);
+  for (const key of Object.keys(settings)) {
+    if (secret.has(key)) {
+      throw new ConnectionSettingsError(
+        `[${connectorId}] "${key}" is a credential field \u2014 credentials never reach plg_connections.settings.`
+      );
+    }
+    if (!allowed.has(key)) {
+      throw new ConnectionSettingsError(
+        `[${connectorId}] unknown settings key "${key}". Declare it in the connector's fields or settingsKeys.`
+      );
+    }
+  }
+}
+function toConnection(row) {
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    connectorId: row.connector_id,
+    instanceKey: row.instance_key ?? "",
+    displayName: row.display_name ?? null,
+    active: row.active,
+    status: row.status,
+    statusDetail: row.status_detail ?? null,
+    settings: row.settings ?? {},
+    providerAccountKey: row.provider_account_key ?? null,
+    cursors: row.cursors ?? {},
+    lastSyncAt: row.last_sync_at ?? null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function toRun(row) {
+  const stats = row.stats ?? {};
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    connectionId: row.connection_id,
+    connectorId: row.connector_id,
+    direction: row.direction,
+    triggerKind: row.trigger_kind,
+    status: row.status,
+    stream: row.stream ?? null,
+    fetched: row.fetched ?? 0,
+    written: row.written ?? 0,
+    stats,
+    cursor: row.cursor ?? null,
+    correlationId: row.correlation_id ?? null,
+    // `stats.message` is the pre-031 home; read it so a pool that has not
+    // applied 031 yet still shows the sentence rather than a blank row.
+    message: row.message ?? stats.message ?? null,
+    error: row.error ?? null,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at ?? null
+  };
+}
+function unwrap(answer, what) {
+  if (answer.error) throw new Error(`[@fayz-ai/core] ${what}: ${answer.error.message}`);
+  return answer.data;
+}
+function createConnectionStore(connectorId, options = {}) {
+  const instanceKey = options.instanceKey ?? "";
+  function client() {
+    const c = options.client ?? getSupabaseClientOptional();
+    if (!c) throw new Error("[@fayz-ai/core] Supabase client not available. Call createFayzApp with a provider first.");
+    return c;
+  }
+  function tenantId() {
+    const id = options.tenantId ?? getActiveTenantId();
+    if (!id) throw new Error(`[@fayz-ai/core] createConnectionStore(${connectorId}): no active tenant.`);
+    return id;
+  }
+  function scoped(q) {
+    return q.eq("tenant_id", tenantId()).eq("connector_id", connectorId).eq("instance_key", instanceKey);
+  }
+  const store = {
+    connectorId,
+    instanceKey,
+    async get() {
+      const row = unwrap(
+        await scoped(client().from(CONNECTIONS_TABLE).select("*")).maybeSingle(),
+        `read ${CONNECTIONS_TABLE}`
+      );
+      return row ? toConnection(row) : null;
+    },
+    async save(input = {}) {
+      const patch = input.settings ?? {};
+      assertSettingsAllowed(patch, options, connectorId);
+      const current = await store.get();
+      const settings = { ...current?.settings ?? {}, ...patch };
+      const row = {
+        tenant_id: tenantId(),
+        connector_id: connectorId,
+        instance_key: instanceKey,
+        settings,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      if (input.displayName !== void 0) row.display_name = input.displayName;
+      if (input.active !== void 0) row.active = input.active;
+      if (input.providerAccountKey !== void 0) row.provider_account_key = input.providerAccountKey;
+      if (current?.id) row.id = current.id;
+      const missing = options.settings?.length ? missingRequiredSettings(options.settings, settings) : [];
+      const reactivating = input.active === true;
+      if (missing.length > 0) {
+        row.status = "pending";
+        row.status_detail = setupStatusDetail(missing);
+      } else if (!current || current.status === "pending" || reactivating && current.status === "revoked") {
+        row.status = "connected";
+        row.status_detail = null;
+      }
+      const saved = unwrap(
+        await client().from(CONNECTIONS_TABLE).upsert(row, { onConflict: "tenant_id,connector_id,instance_key" }).select("*").single(),
+        `write ${CONNECTIONS_TABLE}`
+      );
+      if (!saved) throw new Error(`[@fayz-ai/core] write ${CONNECTIONS_TABLE}: no row returned.`);
+      return toConnection(saved);
+    },
+    async disconnect() {
+      const answer = await scoped(
+        client().from(CONNECTIONS_TABLE).update({
+          active: false,
+          status: "revoked",
+          settings: {},
+          cursors: {},
+          updated_at: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+      unwrap(answer, `disconnect ${CONNECTIONS_TABLE}`);
+    },
+    async listRuns(opts = {}) {
+      const connection = await store.get();
+      if (!connection?.id) return [];
+      const answer = await client().from(SYNC_RUNS_TABLE).select("*").eq("connection_id", connection.id).order("started_at", { ascending: false }).limit(opts.limit ?? 20);
+      const rows = unwrap(answer, `read ${SYNC_RUNS_TABLE}`);
+      return (rows ?? []).map(toRun);
+    }
+  };
+  return store;
+}
+function connectionKey(connectorId, instanceKey = "") {
+  return `${connectorId}\0${instanceKey}`;
+}
+async function listConnections(connectorIds, options = {}) {
+  const found = /* @__PURE__ */ new Map();
+  const ids = [...new Set(connectorIds)].filter(Boolean);
+  if (ids.length === 0) return found;
+  const c = options.client ?? getSupabaseClientOptional();
+  if (!c) throw new Error("[@fayz-ai/core] Supabase client not available. Call createFayzApp with a provider first.");
+  const tenantId = options.tenantId ?? getActiveTenantId();
+  if (!tenantId) throw new Error("[@fayz-ai/core] listConnections: no active tenant.");
+  const rows = unwrap(
+    await c.from(CONNECTIONS_TABLE).select("*").eq("tenant_id", tenantId).in("connector_id", ids),
+    `read ${CONNECTIONS_TABLE}`
+  );
+  for (const row of rows ?? []) {
+    const connection = toConnection(row);
+    found.set(connectionKey(connection.connectorId, connection.instanceKey), connection);
+  }
+  return found;
+}
+function connectionSettings(store) {
+  return {
+    async getSettings() {
+      return (await store.get())?.settings ?? {};
+    },
+    async saveSettings(values) {
+      await store.save({ settings: values });
+    }
+  };
+}
+function connectionRuns(store) {
+  return {
+    async listRuns(options) {
+      try {
+        return await (typeof store === "function" ? store() : store).listRuns(options);
+      } catch {
+        return [];
+      }
+    }
+  };
+}
+function connectionStatus(connectorId, derive, options = {}) {
+  const instanceKey = options.instanceKey ?? "";
+  return {
+    instanceKey,
+    statusFromConnection: derive,
+    async getStatus() {
+      try {
+        const store = options.store?.() ?? createConnectionStore(connectorId, { instanceKey });
+        return derive(await store.get());
+      } catch {
+        return { connected: false };
+      }
+    }
+  };
+}
+
+// src/integrations/request.ts
+var RequestBlockedError = class extends Error {
+  constructor(connectorId, reason, elapsedMs, detail) {
+    super(`[${connectorId}] request plane blocked: ${reason}${detail ? ` \u2014 ${detail}` : ""}`);
+    this.name = "RequestBlockedError";
+    this.connectorId = connectorId;
+    this.reason = reason;
+    this.elapsedMs = elapsedMs;
+  }
+};
+var RequestPlaneError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RequestPlaneError";
+  }
+};
+function requestPlaneSpec(def) {
+  const planes = def.planes ?? ["sync"];
+  if (!planes.includes("request")) {
+    throw new RequestPlaneError(`[${def.id}] is not on the request plane \u2014 declare planes: ['request'].`);
+  }
+  if (typeof def.latencyBudgetMs !== "number" || !Number.isFinite(def.latencyBudgetMs) || def.latencyBudgetMs <= 0) {
+    throw new RequestPlaneError(
+      `[${def.id}] request-plane connector must declare latencyBudgetMs \u2014 how long the buyer may wait.`
+    );
+  }
+  if (def.onFailure !== "degrade" && def.onFailure !== "block") {
+    throw new RequestPlaneError(
+      `[${def.id}] request-plane connector must declare onFailure: 'degrade' | 'block'. Shipping degrades (the sale continues); payment blocks (the order does not confirm).`
+    );
+  }
+  return { latencyBudgetMs: def.latencyBudgetMs, onFailure: def.onFailure };
+}
+function hasRequestPlane(def) {
+  try {
+    requestPlaneSpec(def);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runRequest(def, attempt) {
+  const spec = requestPlaneSpec(def);
+  const now = attempt.now ?? (() => Date.now());
+  const started = now();
+  const degradeOrBlock = async (reason, detail) => {
+    const elapsedMs = now() - started;
+    if (spec.onFailure === "block") throw new RequestBlockedError(def.id, reason, elapsedMs, detail);
+    if (!attempt.fallback) {
+      throw new RequestPlaneError(
+        `[${def.id}] declares onFailure: 'degrade' but the call supplied no fallback. Degrading requires an answer to degrade to.`
+      );
+    }
+    return {
+      value: await attempt.fallback(reason, detail),
+      source: "fallback",
+      elapsedMs,
+      degraded: { reason, detail }
+    };
+  };
+  if (attempt.skip) return degradeOrBlock("not-connected");
+  const controller = new AbortController();
+  let timer;
+  const budget = new Promise((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), spec.latencyBudgetMs);
+  });
+  try {
+    const raced = await Promise.race([
+      attempt.call(controller.signal).then((value) => ({ ok: true, value })),
+      budget
+    ]);
+    if (raced === "timeout") {
+      controller.abort();
+      return await degradeOrBlock("timeout", `budget of ${spec.latencyBudgetMs}ms spent`);
+    }
+    return { value: raced.value, source: "provider", elapsedMs: now() - started };
+  } catch (error) {
+    if (error instanceof RequestBlockedError || error instanceof RequestPlaneError) throw error;
+    return await degradeOrBlock("provider-error", error instanceof Error ? error.message : String(error));
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function runEffect(ledger, input, perform) {
+  if (!input.idempotencyKey) {
+    throw new RequestPlaneError("runEffect requires an idempotencyKey \u2014 an effect nobody can name twice is an effect that runs twice.");
+  }
+  const claim = await ledger.claim(input);
+  if (!claim.claimed) return { runId: claim.runId, performed: false };
+  try {
+    const value = await perform(claim.runId);
+    await ledger.settle({ runId: claim.runId, status: "success" });
+    return { runId: claim.runId, performed: true, value };
+  } catch (error) {
+    await ledger.settle({
+      runId: claim.runId,
+      status: "error",
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+function createRpcEffectLedger(client) {
+  const call = async (fn, args) => {
+    const { data, error } = await client.rpc(fn, args);
+    if (error) throw new Error(`[@fayz-ai/core] ${fn}: ${error.message}`);
+    return data;
+  };
+  return {
+    async claim(input) {
+      const rows = await call("plg_claim_effect", {
+        p_connection_id: input.connectionId,
+        p_idempotency_key: input.idempotencyKey,
+        p_direction: input.direction,
+        p_trigger_kind: input.triggerKind,
+        p_stream: input.stream ?? null
+      });
+      const row = Array.isArray(rows) ? rows[0] : rows;
+      if (!row?.run_id) throw new Error("[@fayz-ai/core] plg_claim_effect returned no run");
+      return { runId: row.run_id, claimed: !!row.claimed };
+    },
+    async settle(input) {
+      await call("plg_settle_effect", {
+        p_run_id: input.runId,
+        p_status: input.status,
+        p_stats: input.stats ?? {},
+        p_error: input.error ?? null
+      });
+    }
+  };
+}
+function buyerIdempotencyKey(parts) {
+  const { effect, subject, amountCents } = parts;
+  if (!effect || !subject) {
+    throw new RequestPlaneError("buyerIdempotencyKey needs both an effect and a subject (the order, the shipment).");
+  }
+  return amountCents === void 0 ? `${effect}:${subject}` : `${effect}:${subject}:${amountCents}`;
+}
+
+// src/integrations/index.ts
+var CONNECTOR_CATEGORIES = [
+  /** The provider IS a database or backend the app is built on. */
+  "database",
+  /** Money in: gateways, acquirers, Pix. */
+  "payments",
+  /** A bank account read (open banking, statements) — not a gateway. */
+  "banking",
+  /** Stock, invoicing, back office. */
+  "erp",
+  /** Freight quotes, labels, tracking. */
+  "logistics",
+  /** Someone else's storefront the business also sells on (iFood, Shopee). */
+  "marketplace",
+  /** The business's OWN online store. */
+  "ecommerce",
+  /** Contacts, deals, pipeline. */
+  "crm",
+  /** Courses sold by a third party (Hotmart, Kiwify). */
+  "courses",
+  /** Bookings and calendars. */
+  "scheduling",
+  /** Conversations: WhatsApp, SMS, email campaigns. */
+  "messaging",
+  /** Measurement, pixels, SEO. */
+  "analytics",
+  /** Presence on a map or a directory (Google Meu Negócio). */
+  "local",
+  /** Models and agent frameworks. */
+  "ai",
+  /** Wiring between other tools (Zapier, n8n). */
+  "automation"
+];
+var CATEGORY_SET = new Set(CONNECTOR_CATEGORIES);
+function isConnectorCategory(value) {
+  return typeof value === "string" && CATEGORY_SET.has(value);
+}
+function invocationPlane(moment) {
+  return moment.plane ?? "request";
+}
+function connectorPlanes(def) {
+  return def.planes?.length ? def.planes : ["sync"];
+}
+function preferredPlane(def) {
+  const planes = connectorPlanes(def);
+  return planes.includes("agentic") ? "agentic" : planes[0];
+}
+function connectorDirection(def) {
+  return def.direction ?? "outbound";
+}
+function withAfterHooks(target, methods) {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      const orig = Reflect.get(obj, prop, receiver);
+      const hook = methods[prop];
+      if (typeof orig !== "function" || !hook) return orig;
+      return (...args) => {
+        const result = orig.apply(obj, args);
+        if (result instanceof Promise) {
+          return result.then((value) => {
+            try {
+              void Promise.resolve(hook(args, value)).catch(() => {
+              });
+            } catch {
+            }
+            return value;
+          });
+        }
+        try {
+          void Promise.resolve(hook(args, result)).catch(() => {
+          });
+        } catch {
+        }
+        return result;
+      };
+    }
+  });
+}
+
+export { CONNECTIONS_TABLE, CONNECTOR_CATEGORIES, ConnectionSettingsError, ConnectorRuntimeTokenUnavailableError, RequestBlockedError, RequestPlaneError, SYNC_RUNS_TABLE, assertSettingsAllowed, buyerIdempotencyKey, connectionKey, connectionRuns, connectionSettings, connectionStatus, connectorDirection, connectorEntities, connectorGrantScopes, connectorPermissions, connectorPlanes, connectorRuntimeToken, connectorSettings, connectorSubscribes, connectorSubscribesTo, createConnectionStore, createRpcEffectLedger, eventKeyMatches, getConnectorRuntimeTokenSource, grants, groupedPermissions, hasRequestPlane, hasSensitivePermission, invocationPlane, isConnectorCategory, isDataPermission, isEventPermission, isSettingSet, listConnections, missingRequiredSettings, permissionActions, permissionsWrite, preferredPlane, requestPlaneSpec, runEffect, runRequest, setConnectorRuntimeTokenSource, settingsStatus, setupStatusDetail, sortedPermissions, withAfterHooks };
+//# sourceMappingURL=chunk-BEGXYHS4.js.map
+//# sourceMappingURL=chunk-BEGXYHS4.js.map