@hivemindhq/core 0.4.0 → 0.5.0

package/src/utils/atom.ts

@@ -0,0 +1,279 @@
+/**
+ * Atom-related utility functions for Intuition protocol
+ */
+
+/**
+ * All possible atom types from the Intuition protocol.
+ * These correspond to the PostgreSQL enum and Rust AtomType.
+ */
+export const ATOM_TYPES = [
+  'Account',
+  'Book',
+  'ByteObject',
+  'Caip10',
+  'FollowAction',
+  'JsonObject',
+  'Keywords',
+  'LikeAction',
+  'Organization',
+  'OrganizationPredicate',
+  'Person',
+  'PersonPredicate',
+  'TextObject',
+  'Thing',
+  'ThingPredicate',
+  'Unknown',
+] as const
+
+export type AtomType = typeof ATOM_TYPES[number]
+
+/**
+ * Detects atom type from data string patterns.
+ * Used as a fallback when type field is not available.
+ *
+ * @param data - The raw atom data string
+ * @returns Detected atom type or undefined
+ */
+function detectTypeFromData(data: string): AtomType | undefined {
+  if (!data) return undefined
+
+  const lowered = data.toLowerCase()
+  const trimmed = data.trim()
+
+  // EVM addresses
+  if (data.startsWith('0x') && data.length === 42) {
+    return 'Account'
+  }
+
+  // CAIP-10 identifiers
+  if (lowered.startsWith('caip10:') || lowered.includes('eip155:')) {
+    return 'Caip10'
+  }
+
+  // Schema.org predicate URLs
+  if (lowered.includes('schema.org/')) {
+    if (lowered.includes('person')) return 'PersonPredicate'
+    if (lowered.includes('organization')) return 'OrganizationPredicate'
+    if (lowered.includes('thing')) return 'ThingPredicate'
+    if (lowered.includes('likeaction')) return 'LikeAction'
+    if (lowered.includes('followaction')) return 'FollowAction'
+  }
+
+  // IPFS URIs typically contain JSON data
+  if (data.startsWith('ipfs://')) {
+    return undefined // Can't determine type without fetching
+  }
+
+  // HTTP/HTTPS URLs - could be many types, can't determine without fetching
+  if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+    return undefined
+  }
+
+  // JSON-like strings (starts with { or [) - likely JsonObject, but can't parse here
+  const firstChar = trimmed[0]
+  if (firstChar === '{' || firstChar === '[') {
+    return undefined // Could be JsonObject, but needs parsing to confirm
+  }
+
+  // Plain text strings that don't match other patterns are likely TextObject
+  // This matches the indexer behavior: if data is not JSON, not an address,
+  // not a CAIP10, not a schema.org URL, and not IPFS, it becomes a TextObject
+  if (trimmed.length > 0) {
+    return 'TextObject'
+  }
+
+  return undefined
+}
+
+/**
+ * Shape of atom data that can be passed to getAtomType.
+ * Supports various atom object shapes from GraphQL responses.
+ */
+export interface AtomTypeInput {
+  /** Direct type field from GraphQL (primary source) */
+  type?: string
+  /** Alternate naming used in some contexts */
+  atomType?: string
+  /** Value object with typed sub-objects (secondary source) */
+  value?: {
+    // Structured entity types (schema.org)
+    thing?: unknown
+    person?: unknown
+    organization?: unknown
+    book?: unknown
+    // Identity types
+    account?: unknown
+    // Raw data types
+    text_object?: unknown   // Plain text like "John Doe", "Hive Mind"
+    json_object?: unknown   // JSON without schema.org context
+    byte_object?: unknown   // Binary data
+  }
+  /** Raw atom data string for pattern detection (tertiary source) */
+  data?: string
+}
+
+/**
+ * Extracts the atom type from an atom object using a cascade/fallback strategy:
+ *
+ * 1. **Primary**: Direct `type` or `atomType` field from GraphQL
+ * 2. **Secondary**: Inferred from populated `value.*` sub-objects
+ * 3. **Tertiary**: Pattern detection from `data` string
+ *
+ * @param atom - Atom object with type information
+ * @returns The atom type string, or undefined if not determinable
+ *
+ * @example
+ * // From GraphQL type field
+ * getAtomType({ type: 'Person' }) // Returns: 'Person'
+ *
+ * @example
+ * // From value sub-object
+ * getAtomType({ value: { person: { name: 'Vitalik' } } }) // Returns: 'Person'
+ *
+ * @example
+ * // From text_object value (plain text atoms)
+ * getAtomType({ value: { text_object: { data: 'Hive Mind' } } }) // Returns: 'TextObject'
+ *
+ * @example
+ * // From data pattern
+ * getAtomType({ data: '0x1234...5678' }) // Returns: 'Account'
+ *
+ * @example
+ * // Plain text detection
+ * getAtomType({ data: 'Hive Mind' }) // Returns: 'TextObject'
+ * getAtomType({ data: 'John Doe' }) // Returns: 'TextObject'
+ */
+export function getAtomType(atom: AtomTypeInput): AtomType | undefined {
+  console.log('getAtomType', atom)
+  if (!atom) return undefined
+
+  // 1. Primary: Direct type field
+  if (atom.type && typeof atom.type === 'string') {
+    return atom.type as AtomType
+  }
+  if (atom.atomType && typeof atom.atomType === 'string') {
+    return atom.atomType as AtomType
+  }
+
+  // 2. Secondary: Infer from value sub-objects
+  // Only check value sub-objects if they are truthy (not null/undefined/false)
+  if (atom.value) {
+    // Structured entity types (schema.org)
+    if (atom.value.person) return 'Person'
+    if (atom.value.organization) return 'Organization'
+    if (atom.value.book) return 'Book'
+    if (atom.value.thing) return 'Thing'
+    // Identity types
+    if (atom.value.account) return 'Account'
+    // Raw data types
+    if (atom.value.text_object) return 'TextObject'
+    if (atom.value.json_object) return 'JsonObject'
+    if (atom.value.byte_object) return 'ByteObject'
+  }
+
+  // 3. Tertiary: Pattern detection from data
+  if (atom.data && typeof atom.data === 'string') {
+    return detectTypeFromData(atom.data)
+  }
+
+  return undefined
+}
+
+/**
+ * Formats an atom type for display purposes.
+ * Converts internal type names to user-friendly labels.
+ *
+ * @param type - The atom type string
+ * @returns Formatted display string
+ *
+ * @example
+ * formatAtomType('TextObject') // Returns: 'Text'
+ * formatAtomType('PersonPredicate') // Returns: 'Person Predicate'
+ * formatAtomType('FollowAction') // Returns: 'Follow'
+ */
+export function formatAtomType(type: string | undefined): string {
+  console.log('formatAtomType', type)
+  if (!type) return ''
+
+  // Handle "Object" suffix types
+  if (type.endsWith('Object')) {
+    return type.replace('Object', '')
+  }
+
+  // Handle "Predicate" suffix types
+  if (type.endsWith('Predicate')) {
+    const base = type.replace('Predicate', '')
+    return `${base} Predicate`
+  }
+
+  // Handle "Action" suffix types
+  if (type.endsWith('Action')) {
+    return type.replace('Action', '')
+  }
+
+  return type
+}
+
+/**
+ * Checks if an atom type is a predicate type.
+ * Predicates are used as the middle component of triples.
+ *
+ * @param type - The atom type to check
+ * @returns True if the type is a predicate
+ *
+ * @example
+ * isPredicateType('ThingPredicate') // Returns: true
+ * isPredicateType('Person') // Returns: false
+ */
+export function isPredicateType(type: string | undefined): boolean {
+  if (!type) return false
+  return (
+    type.endsWith('Predicate') ||
+    type === 'LikeAction' ||
+    type === 'FollowAction'
+  )
+}
+
+/**
+ * Checks if an atom type represents a structured entity (Person, Organization, Thing).
+ * These types typically have rich metadata from schema.org.
+ *
+ * @param type - The atom type to check
+ * @returns True if the type is a structured entity
+ */
+export function isEntityType(type: string | undefined): boolean {
+  if (!type) return false
+  return ['Person', 'Organization', 'Thing', 'Book'].includes(type)
+}
+
+/**
+ * Checks if an atom type is a raw data type (TextObject, JsonObject, ByteObject).
+ * These types contain data without schema.org structure.
+ *
+ * @param type - The atom type to check
+ * @returns True if the type is a raw data type
+ *
+ * @example
+ * isRawDataType('TextObject') // Returns: true
+ * isRawDataType('Person') // Returns: false
+ */
+export function isRawDataType(type: string | undefined): boolean {
+  if (!type) return false
+  return ['TextObject', 'JsonObject', 'ByteObject'].includes(type)
+}
+
+/**
+ * Checks if an atom type is plain text (TextObject).
+ * Plain text atoms contain simple strings like names, labels, or concepts.
+ *
+ * @param type - The atom type to check
+ * @returns True if the type is TextObject
+ *
+ * @example
+ * isPlainTextType('TextObject') // Returns: true
+ * isPlainTextType('Person') // Returns: false
+ */
+export function isPlainTextType(type: string | undefined): boolean {
+  return type === 'TextObject'
+}
+

package/src/utils/cn.ts

@@ -0,0 +1,18 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Combines class names using clsx and merges Tailwind classes intelligently.
+ * This is the standard utility for conditional and merged class names.
+ *
+ * @param inputs - Class values to combine (strings, objects, arrays)
+ * @returns Merged class string with Tailwind conflicts resolved
+ *
+ * @example
+ * cn('px-4 py-2', isActive && 'bg-blue-500', { 'opacity-50': isDisabled })
+ * // Returns: "px-4 py-2 bg-blue-500" (if isActive is true, isDisabled is false)
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+