@fayz-ai/core 0.1.6

package/src/runtime/oauth.ts

@@ -0,0 +1,219 @@
+export type FayzRuntimeEnvironment = 'preview' | 'production'
+
+export interface FayzRuntimeClientOptions {
+  baseUrl: string
+  projectId: string
+  runtimeToken: string | (() => string | Promise<string>)
+  fetcher?: typeof fetch
+}
+
+export interface PluginOAuthExchangeInput {
+  pluginId: string
+  environment?: FayzRuntimeEnvironment
+  scopes?: string[]
+}
+
+export interface RuntimePluginOAuthGrant {
+  grantId: string
+  provider: string
+  scopes: string[]
+}
+
+export interface PluginOAuthExchangeResponse {
+  token: string
+  tokenType: 'Bearer'
+  expiresIn: number
+  projectId: string
+  tenantKey: string
+  environment: FayzRuntimeEnvironment
+  pluginId: string
+  grants: RuntimePluginOAuthGrant[]
+}
+
+export interface GoogleCalendarEventTime {
+  dateTime: string
+  timeZone?: string
+}
+
+export interface GoogleCalendarEventInput {
+  summary: string
+  description?: string
+  location?: string
+  start: GoogleCalendarEventTime
+  end: GoogleCalendarEventTime
+  attendees?: Array<{ email: string }>
+}
+
+export interface GoogleCalendarEvent {
+  id: string
+  summary?: string
+  description?: string
+  location?: string
+  start: { dateTime?: string; date?: string; timeZone?: string }
+  end: { dateTime?: string; date?: string; timeZone?: string }
+  status?: string
+  htmlLink?: string
+  [key: string]: unknown
+}
+
+export interface ListGoogleCalendarEventsInput {
+  calendarId: string
+  timeMin?: string
+  timeMax?: string
+  maxResults?: number
+  q?: string
+}
+
+export class FayzRuntimeError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly responseBody?: unknown,
+  ) {
+    super(message)
+    this.name = 'FayzRuntimeError'
+  }
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, '')
+}
+
+function assertRequired(value: string, field: string): string {
+  const normalized = value.trim()
+  if (!normalized) throw new Error(`[@fayz-ai/core] ${field} is required`)
+  return normalized
+}
+
+async function resolveRuntimeToken(
+  runtimeToken: FayzRuntimeClientOptions['runtimeToken'],
+): Promise<string> {
+  const value = typeof runtimeToken === 'function' ? await runtimeToken() : runtimeToken
+  return assertRequired(value, 'runtimeToken')
+}
+
+function runtimePath(projectId: string, suffix: string): string {
+  return `/api/v1/runtime/projects/${encodeURIComponent(projectId)}${suffix}`
+}
+
+function queryString(params: Record<string, string | number | undefined>): string {
+  const search = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== '') search.set(key, String(value))
+  }
+  const value = search.toString()
+  return value ? `?${value}` : ''
+}
+
+async function parseResponse<T>(response: Response): Promise<T> {
+  if (response.status === 204) return undefined as T
+
+  const text = await response.text()
+  let body: unknown
+  try {
+    body = text ? JSON.parse(text) : undefined
+  } catch {
+    body = text
+  }
+
+  if (!response.ok) {
+    const message = typeof body === 'object' && body && 'message' in body
+      ? String((body as { message: unknown }).message)
+      : `[@fayz-ai/core] Runtime request failed with status ${response.status}`
+    throw new FayzRuntimeError(message, response.status, body)
+  }
+
+  return body as T
+}
+
+export function createFayzRuntimeClient(options: FayzRuntimeClientOptions) {
+  const baseUrl = normalizeBaseUrl(assertRequired(options.baseUrl, 'baseUrl'))
+  const projectId = assertRequired(options.projectId, 'projectId')
+  const fetcher = options.fetcher ?? fetch
+
+  async function request<T>(
+    path: string,
+    token: string,
+    init: Omit<RequestInit, 'headers'> & { headers?: Record<string, string> } = {},
+  ): Promise<T> {
+    const response = await fetcher(`${baseUrl}${path}`, {
+      ...init,
+      headers: {
+        ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+        ...init.headers,
+        Authorization: `Bearer ${token}`,
+      },
+    })
+    return parseResponse<T>(response)
+  }
+
+  async function exchangePluginOAuth(
+    input: PluginOAuthExchangeInput,
+  ): Promise<PluginOAuthExchangeResponse> {
+    return request<PluginOAuthExchangeResponse>(
+      runtimePath(projectId, '/oauth/exchange'),
+      await resolveRuntimeToken(options.runtimeToken),
+      {
+        method: 'POST',
+        body: JSON.stringify({
+          pluginId: assertRequired(input.pluginId, 'pluginId'),
+          environment: input.environment ?? 'preview',
+          ...(input.scopes ? { scopes: input.scopes } : {}),
+        }),
+      },
+    )
+  }
+
+  function googleCalendar(pluginOAuthToken: string) {
+    const brokerToken = assertRequired(pluginOAuthToken, 'pluginOAuthToken')
+    const eventsPath = runtimePath(projectId, '/oauth/google-calendar/events')
+
+    return {
+      listEvents(input: ListGoogleCalendarEventsInput) {
+        const calendarId = assertRequired(input.calendarId, 'calendarId')
+        return request<{
+          provider: 'google-calendar'
+          calendarId: string
+          timeMin: string
+          timeMax: string
+          events: GoogleCalendarEvent[]
+        }>(
+          `${eventsPath}${queryString({
+            calendarId,
+            timeMin: input.timeMin,
+            timeMax: input.timeMax,
+            maxResults: input.maxResults,
+            q: input.q,
+          })}`,
+          brokerToken,
+        )
+      },
+      createEvent(calendarId: string, event: GoogleCalendarEventInput) {
+        return request<{ provider: 'google-calendar'; calendarId: string; event: GoogleCalendarEvent }>(
+          `${eventsPath}${queryString({ calendarId: assertRequired(calendarId, 'calendarId') })}`,
+          brokerToken,
+          { method: 'POST', body: JSON.stringify(event) },
+        )
+      },
+      updateEvent(calendarId: string, eventId: string, updates: Partial<GoogleCalendarEventInput>) {
+        return request<{ provider: 'google-calendar'; calendarId: string; event: GoogleCalendarEvent }>(
+          `${eventsPath}/${encodeURIComponent(assertRequired(eventId, 'eventId'))}${queryString({ calendarId: assertRequired(calendarId, 'calendarId') })}`,
+          brokerToken,
+          { method: 'PATCH', body: JSON.stringify(updates) },
+        )
+      },
+      deleteEvent(calendarId: string, eventId: string) {
+        return request<void>(
+          `${eventsPath}/${encodeURIComponent(assertRequired(eventId, 'eventId'))}${queryString({ calendarId: assertRequired(calendarId, 'calendarId') })}`,
+          brokerToken,
+          { method: 'DELETE' },
+        )
+      },
+    }
+  }
+
+  return {
+    exchangePluginOAuth,
+    googleCalendar,
+  }
+}

package/src/tenant/index.ts

@@ -0,0 +1,18 @@
+// Active tenant context — a global accessor the data layer reads for tenant
+// scoping and cache keying. The host (saas shell / app) sets it from its org
+// store via setActiveTenantId; the data providers stay decoupled from any
+// specific org-store implementation (runtime DI).
+import { clearGlobalCache } from '../lib/cache'
+
+let _activeTenantId: string | undefined
+
+export function setActiveTenantId(id: string | undefined): void {
+  if (id !== _activeTenantId) {
+    _activeTenantId = id
+    clearGlobalCache()
+  }
+}
+
+export function getActiveTenantId(): string | undefined {
+  return _activeTenantId
+}

package/src/types/auth.ts

@@ -0,0 +1,26 @@
+export type AuthProvider = 'google' | 'github' | 'apple' | 'facebook' | (string & {})
+
+export interface AuthUser {
+  id: string
+  email: string
+  fullName?: string
+  avatarUrl?: string
+  role?: string
+}
+
+export interface AuthSession {
+  user: AuthUser
+  accessToken: string
+  refreshToken?: string
+  expiresAt?: number
+}
+
+export interface AuthAdapter {
+  getSession(): Promise<{ user: AuthUser; session: AuthSession } | null>
+  onAuthStateChange(cb: (user: AuthUser | null) => void): () => void
+  signIn(email: string, password: string): Promise<AuthSession>
+  signUp(email: string, password: string, fullName: string): Promise<AuthSession>
+  signOut(): Promise<void>
+  signInWithOAuth(provider: AuthProvider): Promise<void>
+  resetPassword(email: string): Promise<void>
+}

package/src/types/billing.ts

@@ -0,0 +1,17 @@
+export interface Plan {
+  id: string
+  name: string
+  description?: string
+  price: number
+  currency: string
+  interval: 'month' | 'year'
+  features: string[]
+  highlighted?: boolean
+  stripePriceId?: string
+}
+
+export interface BillingConfig {
+  plans: Plan[]
+  stripePublishableKey?: string
+  portalUrl?: string
+}

package/src/types/crud.ts

@@ -0,0 +1,108 @@
+import type React from 'react'
+import type { EntityArchetype } from './entities'
+
+export type FieldType =
+  | 'text' | 'email' | 'phone' | 'url' | 'image'
+  | 'number' | 'currency'
+  | 'select' | 'multiselect' | 'segmented'
+  | 'date' | 'datetime' | 'time'
+  | 'boolean' | 'textarea'
+  | 'color' | 'computed'
+
+/** Read-only display produced by a `computed` field's `compute()`. */
+export interface ComputedFieldValue {
+  display: string
+  /** Drives the value colour (green / red / muted). Default: neutral. */
+  tone?: 'positive' | 'negative' | 'neutral'
+}
+
+export interface FieldDef {
+  key: string
+  label: string
+  type: FieldType
+  required?: boolean
+  placeholder?: string
+  /** Small helper text shown under the field input. */
+  hint?: string
+  /** 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 }[]
+  min?: number
+  max?: number
+  /** ISO currency code for `currency` fields (e.g. 'BRL'). */
+  currency?: string
+  /** Symbol/locale for the `currency` field's CurrencyInput. Default 'R$' / 'pt-BR'. */
+  currencySymbol?: string
+  currencyLocale?: string
+  showInTable?: boolean
+  showInForm?: boolean
+  showInDetail?: boolean
+  sortable?: boolean
+  searchable?: boolean
+  /** Custom cell renderer (code escape hatch). For a serializable EntityDef in
+   *  an AppManifest, reference a registered cell renderer by id instead. */
+  renderCell?: (value: unknown, row: unknown) => React.ReactNode
+  renderCellId?: string
+  /** Derives a read-only value from the other form values (for `computed`
+   *  fields, e.g. margin). Returns null to render an em-dash. */
+  compute?: (values: Record<string, unknown>) => ComputedFieldValue | null
+  defaultValue?: unknown
+  group?: string
+  span?: 1 | 2
+  inlineToggle?: boolean
+}
+
+export interface FieldGroup {
+  id: string
+  label: string
+  description?: string
+  columns?: 1 | 2 | 3
+  /** Renders a decorative image slot to the left of the group's fields. */
+  imageSlot?: boolean
+}
+
+export interface DetailTab {
+  id: string
+  label: string
+  icon?: string
+  /** Tab content component, or a registered component id (componentId) for a
+   *  serializable EntityDef. Exactly one is expected. */
+  component?: React.ComponentType<{ item: unknown; entityDef: EntityDef; [key: string]: unknown }>
+  componentId?: string
+  visibleFor?: string[]
+  props?: Record<string, unknown>
+}
+
+export type FormLayout = 'person' | 'product' | 'service' | 'location' | 'order' | 'subject' | 'generic'
+
+export interface EntityDef<T = Record<string, unknown>> {
+  name: string
+  namePlural?: string
+  icon: string
+  layout?: FormLayout
+  fields: FieldDef[]
+  fieldGroups?: FieldGroup[]
+  detailTabs?: DetailTab[]
+  data?: {
+    table: string
+    schema?: string
+    tenantScoped?: boolean
+    tenantIdColumn?: string
+    searchColumns?: string[]
+    selectColumns?: string
+    columnMap?: Record<string, string>
+    archetype?: EntityArchetype
+    archetypeKind?: string
+    filters?: Record<string, string>
+    defaults?: Record<string, unknown>
+    cacheTTL?: number
+  }
+  defaultSort?: string
+  defaultSortDir?: 'asc' | 'desc'
+  displayField?: string
+  subtitleField?: string
+  imageField?: string
+  /** Faceted filters shown as pills below the list search box. Each references a
+   *  field whose `options` supply the pills; an "All" pill clears the filter. */
+  facets?: { field: string; allLabel?: string }[]
+}

package/src/types/entities.ts

@@ -0,0 +1,142 @@
+export type EntityArchetype = 'person' | 'category' | 'product' | 'service' | 'order' | 'transaction' | 'schedule' | 'location'
+
+export interface BaseEntity {
+  id: string
+  tenantId: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface PersonEntity extends BaseEntity {
+  archetype: 'person'
+  kind: string
+  name: string
+  email?: string
+  phone?: string
+  documentNumber?: string
+  avatarUrl?: string
+  dateOfBirth?: string
+  address?: string
+  city?: string
+  state?: string
+  country: string
+  postalCode?: string
+  tags: string[]
+  isActive: boolean
+  notes?: string
+  metadata: Record<string, unknown>
+}
+
+export interface CategoryEntity extends BaseEntity {
+  archetype: 'category'
+  kind: string
+  name: string
+  slug?: string
+  parentId?: string
+  icon?: string
+  color?: string
+  sortOrder: number
+  isActive: boolean
+  metadata: Record<string, unknown>
+}
+
+export interface ProductEntity extends BaseEntity {
+  archetype: 'product'
+  categoryId?: string
+  name: string
+  description?: string
+  sku?: string
+  price?: number
+  cost?: number
+  currency: string
+  unit?: string
+  imageUrl?: string
+  stock?: number
+  minStock?: number
+  status: string
+  isActive: boolean
+  tags: string[]
+  metadata: Record<string, unknown>
+}
+
+export interface ServiceEntity extends BaseEntity {
+  archetype: 'service'
+  categoryId?: string
+  name: string
+  description?: string
+  price?: number
+  cost?: number
+  currency: string
+  durationMinutes?: number
+  imageUrl?: string
+  status: string
+  isActive: boolean
+  tags: string[]
+  metadata: Record<string, unknown>
+}
+
+export interface OrderEntity extends BaseEntity {
+  archetype: 'order'
+  kind: string
+  referenceNumber?: string
+  status: string
+  partyId?: string
+  assigneeId?: string
+  locationId?: string
+  subtotal: number
+  discount: number
+  tax: number
+  total: number
+  currency: string
+  dueAt?: string
+  completedAt?: string
+  notes?: string
+  tags: string[]
+  metadata: Record<string, unknown>
+}
+
+export interface TransactionEntity extends BaseEntity {
+  archetype: 'transaction'
+  kind: string
+  orderId?: string
+  partyId?: string
+  amount: number
+  currency: string
+  paymentMethod?: string
+  reference?: string
+  status: string
+  transactedAt: string
+  notes?: string
+  metadata: Record<string, unknown>
+}
+
+export interface LocationEntity extends BaseEntity {
+  archetype: 'location'
+  kind: string
+  name: string
+  email?: string
+  phone?: string
+  address?: string
+  city?: string
+  state?: string
+  country: string
+  postalCode?: string
+  isHeadquarters: boolean
+  isActive: boolean
+  tags: string[]
+  notes?: string
+  metadata: Record<string, unknown>
+}
+
+export interface ScheduleEntity extends BaseEntity {
+  archetype: 'schedule'
+  kind: string
+  assigneeId?: string
+  locationId?: string
+  dayOfWeek?: number
+  specificDate?: string
+  startsAt: string
+  endsAt: string
+  isActive: boolean
+  metadata: Record<string, unknown>
+}

package/src/types/i18n.ts

@@ -0,0 +1,7 @@
+export interface LocaleConfig {
+  default: string
+  supported: string[]
+  translations?: Record<string, Record<string, string>>
+  /** ISO 4217 currency code for money formatting (e.g. 'BRL', 'USD'). */
+  currency?: string
+}

package/src/types/index.ts

@@ -0,0 +1,10 @@
+// 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 { AuthAdapter, AuthUser, AuthSession } from './auth'
+export type { OrgAdapter, Organization, OrgMember } from './org'
+export type { PermissionsConfig, FeatureDeclaration, PermissionAction } from './permissions'
+export type { Plan, BillingConfig } from './billing'
+export type { SaasTheme, ThemeConfig } from './theme'
+export type { LocaleConfig } from './i18n'

package/src/types/org.ts

@@ -0,0 +1,94 @@
+import type { PermissionProfile } from './permissions'
+
+export interface Organization {
+  id: string
+  name: string
+  slug: string
+  logoUrl?: string
+  verticalId?: string
+  plan?: string
+  settings?: Record<string, unknown>
+  createdAt: string
+  updatedAt: string
+}
+
+export interface OrgMember {
+  id: string
+  userId: string
+  orgId: string
+  profileId: string
+  profileName: string
+  user: {
+    id: string
+    email: string
+    fullName: string
+    avatarUrl?: string
+  }
+  joinedAt: string
+}
+
+export interface OrgMembership {
+  orgId: string
+  orgName: string
+  orgSlug: string
+  orgLogoUrl?: string
+  profileId: string
+  profileName: string
+}
+
+export interface Location {
+  id: string
+  tenantId: string
+  name: string
+  address?: string
+  city?: string
+  state?: string
+  country?: string
+  phone?: string
+  isHeadquarters: boolean
+  isActive: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+export interface Invite {
+  id: string
+  orgId: string
+  email: string
+  profileId: string
+  profileName: string
+  invitedBy: string
+  token: string
+  status: 'pending' | 'accepted' | 'expired'
+  createdAt: string
+  expiresAt: string
+}
+
+export interface CreateOrgOptions {
+  verticalId?: string
+  timezone?: string
+  currency?: string
+  locale?: string
+  teamSize?: string
+}
+
+export interface OrgAdapter {
+  listUserOrgs(userId: string): Promise<OrgMembership[]>
+  getOrg(orgId: string): Promise<Organization>
+  createOrg(name: string, userId: string, options?: CreateOrgOptions): Promise<Organization>
+  updateOrg(orgId: string, data: Partial<Organization>): Promise<Organization>
+  listMembers(orgId: string): Promise<OrgMember[]>
+  updateMemberProfile(orgId: string, memberId: string, profileId: string): Promise<void>
+  removeMember(orgId: string, memberId: string): Promise<void>
+  listProfiles(orgId: string): Promise<PermissionProfile[]>
+  createProfile(orgId: string, profile: Omit<PermissionProfile, 'id' | 'isSystem'>): Promise<PermissionProfile>
+  updateProfile(orgId: string, profileId: string, data: Partial<PermissionProfile>): Promise<PermissionProfile>
+  deleteProfile(orgId: string, profileId: string): Promise<void>
+  listInvites(orgId: string): Promise<Invite[]>
+  createInvite(orgId: string, email: string, profileId: string, invitedBy: string): Promise<Invite>
+  bulkInvite(orgId: string, emails: string[], profileId: string, invitedBy: string): Promise<Invite[]>
+  revokeInvite(orgId: string, inviteId: string): Promise<void>
+  resendInvite(orgId: string, inviteId: string): Promise<Invite>
+  listLocations(orgId: string): Promise<Location[]>
+  createLocation(orgId: string, data: { name: string; address?: string; city?: string; state?: string; country?: string; phone?: string; isHeadquarters?: boolean }): Promise<Location>
+}

package/src/types/permissions.ts

@@ -0,0 +1,32 @@
+export type PermissionAction = 'read' | 'create' | 'edit' | 'write' | 'delete' | 'manage' | (string & {})
+
+export type SystemPermission =
+  | 'manage_team'
+  | 'manage_billing'
+  | 'manage_settings'
+  | 'manage_permissions'
+
+export interface FeatureDeclaration {
+  id: string
+  label: string
+  description?: string
+  /** Settings group this feature appears under (matches saas-core runtime) */
+  group?: string
+  actions?: PermissionAction[]
+  pluginId?: string
+}
+
+export interface PermissionProfile {
+  id: string
+  name: string
+  description?: string
+  isSystem?: boolean
+  systemPermissions?: SystemPermission[]
+  /** feature key → allowed actions. The canonical permission map (saas-core shell name). */
+  grants: Record<string, PermissionAction[]>
+}
+
+export interface PermissionsConfig {
+  features: FeatureDeclaration[]
+  defaultProfiles?: PermissionProfile[]
+}