@hivemindhq/core 0.4.0 → 0.5.0

package/dist/utils/index.d.ts

@@ -292,7 +292,7 @@ interface AtomTypeInput {
  *
  * @example
  * // From text_object value (plain text atoms)
- * getAtomType({ value: { text_object: { data: 'Revel8' } } }) // Returns: 'TextObject'
+ * getAtomType({ value: { text_object: { data: 'Hive Mind' } } }) // Returns: 'TextObject'
  *
  * @example
  * // From data pattern
@@ -300,8 +300,8 @@ interface AtomTypeInput {
  *
  * @example
  * // Plain text detection
- * getAtomType({ data: 'Revel8' }) // Returns: 'TextObject'
- * getAtomType({ data: 'Kylan Hurt' }) // Returns: 'TextObject'
+ * getAtomType({ data: 'Hive Mind' }) // Returns: 'TextObject'
+ * getAtomType({ data: 'John Doe' }) // Returns: 'TextObject'
  */
 declare function getAtomType(atom: AtomTypeInput): AtomType | undefined;
 /**
@@ -362,9 +362,208 @@ declare function isRawDataType(type: string | undefined): boolean;
  */
 declare function isPlainTextType(type: string | undefined): boolean;
 
+/**
+ * Atom Label Detection System
+ *
+ * Provides unified detection and formatting of atom labels across Hive Mind applications.
+ * Takes a raw label string and returns a rich typed object with:
+ * - Detected kind (address, atom-id, ens, social, url, domain, ipfs, text)
+ * - Normalized/canonical form for storage
+ * - Shortened form for display in tight spaces
+ * - Human-readable display name
+ * - Type-specific metadata
+ *
+ * @module atom-label-detection
+ */
+/**
+ * Supported social media platforms.
+ * Extend this as new platforms are added.
+ */
+type SocialPlatform = 'twitter' | 'github' | 'linkedin' | 'farcaster' | 'lens' | 'youtube' | 'instagram' | 'tiktok' | 'discord' | 'telegram' | 'reddit' | 'medium';
+/** Base properties shared by all detection results */
+interface BaseDetectionResult {
+    /** Original input string */
+    raw: string;
+    /** Canonical/normalized form for storage and comparison */
+    normalized: string;
+    /** Shortened form for display in tight spaces */
+    shortened: string;
+    /** Human-readable display name */
+    displayName: string;
+}
+/** EVM address (42 characters, 0x + 40 hex) */
+interface AddressDetectionResult extends BaseDetectionResult {
+    kind: 'address';
+    /** The checksummed address (if valid) or original */
+    address: `0x${string}`;
+    /** Whether the address was provided in checksummed format */
+    isChecksummed: boolean;
+}
+/** Atom ID (66 characters, 0x + 64 hex) */
+interface AtomIdDetectionResult extends BaseDetectionResult {
+    kind: 'atom-id';
+    /** The atom ID */
+    id: `0x${string}`;
+}
+/** ENS domain name */
+interface EnsDetectionResult extends BaseDetectionResult {
+    kind: 'ens';
+    /** The full ENS name (e.g., "vitalik.eth") */
+    name: string;
+}
+/** Social media profile */
+interface SocialDetectionResult extends BaseDetectionResult {
+    kind: 'social';
+    /** The detected platform */
+    platform: SocialPlatform;
+    /** The extracted handle/username */
+    handle: string;
+    /** Full profile URL (normalized) */
+    profileUrl: string;
+    /** Unavatar URL for profile image (if available) */
+    avatarUrl?: string;
+}
+/** Generic URL (not matching any social platform) */
+interface UrlDetectionResult extends BaseDetectionResult {
+    kind: 'url';
+    /** Full normalized URL */
+    url: string;
+    /** Origin (protocol + hostname) */
+    origin: string;
+    /** Hostname only */
+    hostname: string;
+    /** Path after hostname */
+    pathname: string;
+}
+/** Domain/hostname without protocol */
+interface DomainDetectionResult extends BaseDetectionResult {
+    kind: 'domain';
+    /** The domain name */
+    domain: string;
+    /** Top-level domain */
+    tld: string;
+}
+/** IPFS content identifier */
+interface IpfsDetectionResult extends BaseDetectionResult {
+    kind: 'ipfs';
+    /** The content identifier */
+    cid: string;
+    /** CID version (0 for Qm..., 1 for bafy...) */
+    version: 0 | 1;
+    /** Gateway URL for accessing content */
+    gatewayUrl: string;
+}
+/** Arweave content identifier */
+interface ArweaveDetectionResult extends BaseDetectionResult {
+    kind: 'arweave';
+    /** The transaction ID */
+    txId: string;
+    /** Gateway URL for accessing content */
+    gatewayUrl: string;
+}
+/** Plain text (fallback) */
+interface TextDetectionResult extends BaseDetectionResult {
+    kind: 'text';
+    /** The text content (normalized) */
+    text: string;
+}
+/**
+ * Discriminated union of all detection result types.
+ * Use TypeScript's type narrowing with `result.kind` to access type-specific properties.
+ *
+ * @example
+ * const result = detectAtomLabel('https://x.com/vitalik')
+ * if (result.kind === 'social') {
+ *   console.log(result.handle) // 'vitalik'
+ *   console.log(result.platform) // 'twitter'
+ * }
+ */
+type AtomLabelDetectionResult = AddressDetectionResult | AtomIdDetectionResult | EnsDetectionResult | SocialDetectionResult | UrlDetectionResult | DomainDetectionResult | IpfsDetectionResult | ArweaveDetectionResult | TextDetectionResult;
+/**
+ * Detects the type of an atom label and returns a rich typed result.
+ *
+ * This is the primary function for understanding what kind of entity a label represents.
+ * Use this when you need to:
+ * - Display a label appropriately (shortened, with icon, etc.)
+ * - Generate creation data for new atoms
+ * - Compare two labels to see if they represent the same entity
+ *
+ * Detection priority (most specific first):
+ * 1. ENS (.eth suffix)
+ * 2. IPFS (ipfs:// or CID patterns)
+ * 3. Arweave (ar://)
+ * 4. Atom ID (66-char hex)
+ * 5. EVM Address (42-char hex)
+ * 6. Social Profile (known platform URLs)
+ * 7. URL (has protocol)
+ * 8. Domain (matches TLD pattern)
+ * 9. Text (fallback)
+ *
+ * @param label - The raw label string to detect
+ * @returns A discriminated union result with kind-specific properties
+ *
+ * @example
+ * // EVM Address
+ * detectAtomLabel('0x1234567890123456789012345678901234567890')
+ * // { kind: 'address', shortened: '0x1234...7890', ... }
+ *
+ * @example
+ * // Social Profile
+ * detectAtomLabel('https://x.com/vitalik')
+ * // { kind: 'social', platform: 'twitter', handle: 'vitalik', shortened: '@vitalik', ... }
+ *
+ * @example
+ * // ENS
+ * detectAtomLabel('vitalik.eth')
+ * // { kind: 'ens', name: 'vitalik.eth', shortened: 'vitalik.eth', ... }
+ */
+declare function detectAtomLabel(label: string): AtomLabelDetectionResult;
+/**
+ * Compares two labels to determine if they represent the same entity.
+ * Handles various representations of the same entity:
+ * - Case insensitivity
+ * - Protocol variations (http vs https)
+ * - Domain aliases (x.com vs twitter.com)
+ * - Trailing slashes
+ *
+ * @param labelA - First label to compare
+ * @param labelB - Second label to compare
+ * @returns True if labels represent the same entity
+ *
+ * @example
+ * isSameAtomLabel('0xABC...', '0xabc...') // true (case insensitive)
+ * isSameAtomLabel('x.com/vitalik', 'https://x.com/vitalik') // true
+ * isSameAtomLabel('twitter.com/vitalik', 'x.com/vitalik') // true (same platform)
+ */
+declare function isSameAtomLabel(labelA: string, labelB: string): boolean;
+/**
+ * Type guard to check if result is a specific kind.
+ *
+ * @example
+ * const result = detectAtomLabel(input)
+ * if (isAtomLabelKind(result, 'address')) {
+ *   console.log(result.address) // TypeScript knows this is AddressDetectionResult
+ * }
+ */
+declare function isAtomLabelKind<K extends AtomLabelDetectionResult['kind']>(result: AtomLabelDetectionResult, kind: K): result is Extract<AtomLabelDetectionResult, {
+    kind: K;
+}>;
+/**
+ * Checks if a result is an on-chain identity (address or atom ID).
+ */
+declare function isOnChainIdentity(result: AtomLabelDetectionResult): result is AddressDetectionResult | AtomIdDetectionResult;
+/**
+ * Checks if a result is a web reference (URL, domain, social).
+ */
+declare function isWebReference(result: AtomLabelDetectionResult): result is UrlDetectionResult | DomainDetectionResult | SocialDetectionResult;
+/**
+ * Checks if a result is decentralized storage (IPFS, Arweave).
+ */
+declare function isDecentralizedStorage(result: AtomLabelDetectionResult): result is IpfsDetectionResult | ArweaveDetectionResult;
+
 /**
  * Shared type definitions for atom search functionality
- * Used by both revel8-explorer and intuition-extension
+ * Used by both hivemind-explorer and intuition-extension
  */
 /**
  * Vault data from GraphQL response
@@ -474,7 +673,7 @@ interface SearchResult<T extends GraphQLAtom = GraphQLAtom> {
  * Provides stake-first ranking with relevance as secondary sort
  *
  * @example
- * import { rankAtoms } from '@revel8/core'
+ * import { rankAtoms } from '@hivemindhq/core'
  * const rankedResults = rankAtoms(response.data.atoms, searchTerm)
  */
 
@@ -570,4 +769,111 @@ declare function highlightMatch(text: string, searchTerm: string): React__defaul
  */
 declare function formatTermId(termId: string): string;
 
-export { ATOM_TYPES, type AtomCreator, type AtomType, type AtomTypeInput, type AtomValue, type AtomVault, type FormatCryptoAmountOptions, type FormattedCryptoAmount, type GraphQLAtom, type RankedAtom, type SearchResult, type SearchSummary, calculateMatchScore, capitalize, capitalizeFirstLetter, cn, ellipsizeHex, ellipsizeString, formatAtomType, formatCompact, formatCryptoAmount, formatStake, formatTermId, getAtomDescription, getAtomDisplayName, getAtomImage, getAtomType, highlightMatch, ipfsToHttp, isEntityType, isPlainTextType, isPredicateType, isRawDataType, rankAtoms, secondsToDhms, secondsToHms, shortenLabel, strengthenImageUrl, timeAgo, truncateId, truncateSignificantDigits, truncateString };
+/**
+ * MultiVault Contract Error Mappings
+ *
+ * Maps Solidity error names from the MultiVault contract to user-friendly messages.
+ * These errors are thrown by the Intuition Protocol's MultiVault contract.
+ *
+ * @see intuition-contracts-v2/src/protocol/MultiVault.sol
+ * @see intuition-contracts-v2/src/protocol/MultiVaultCore.sol
+ */
+interface MultiVaultErrorInfo {
+    /** The Solidity error name as it appears in the contract */
+    errorName: string;
+    /** User-friendly message to display in the UI */
+    userMessage: string;
+    /** More detailed explanation for tooltips or error details */
+    description: string;
+    /** Category for grouping/filtering errors */
+    category: 'atom' | 'triple' | 'deposit' | 'redeem' | 'balance' | 'limits' | 'batch' | 'approval' | 'existence' | 'epoch' | 'wallet' | 'internal';
+    /** Whether this error is commonly encountered by users */
+    isCommon: boolean;
+}
+/**
+ * Result of parsing a MultiVault error
+ */
+interface ParsedMultiVaultError {
+    /** User-friendly message to display in the UI */
+    userMessage: string;
+    /** More detailed explanation for tooltips or error details */
+    description: string;
+    /** Whether this error is commonly encountered by users */
+    isCommon: boolean;
+    /** The original error name if matched, undefined if fallback */
+    errorName?: string;
+    /** The error category if matched */
+    category?: MultiVaultErrorInfo['category'];
+    /** Whether this was a known MultiVault error */
+    isMultiVaultError: boolean;
+}
+/**
+ * Complete mapping of MultiVault contract errors to user-friendly messages.
+ *
+ * @example
+ * ```typescript
+ * const errorInfo = MULTIVAULT_ERRORS['MultiVault_AtomExists']
+ * toast.error(errorInfo.userMessage)
+ * ```
+ */
+declare const MULTIVAULT_ERRORS: Record<string, MultiVaultErrorInfo>;
+/**
+ * All error categories for filtering/grouping
+ */
+declare const ERROR_CATEGORIES: readonly ["atom", "triple", "deposit", "redeem", "balance", "limits", "batch", "approval", "existence", "epoch", "wallet", "internal"];
+type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
+/**
+ * Get all errors marked as commonly encountered by users
+ */
+declare const COMMON_ERRORS: Record<string, MultiVaultErrorInfo>;
+/**
+ * Total count of mapped errors
+ */
+declare const TOTAL_ERROR_COUNT: number;
+/**
+ * Parse a contract error and return user-friendly error information
+ *
+ * This function attempts to match the error against known MultiVault errors
+ * and returns structured information for display in the UI.
+ *
+ * @param error - The error object from a contract call
+ * @returns Parsed error information with user-friendly message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await createAtom(...)
+ * } catch (err) {
+ *   const parsed = parseMultiVaultError(err)
+ *   toast.error(parsed.userMessage)
+ *   if (parsed.isMultiVaultError) {
+ *     console.log('Contract error:', parsed.errorName)
+ *   }
+ * }
+ * ```
+ */
+declare function parseMultiVaultError(error: unknown): ParsedMultiVaultError;
+/**
+ * Check if an error is a specific MultiVault error
+ *
+ * @param error - The error to check
+ * @param errorName - The specific error name to check for
+ * @returns True if the error matches the specified error name
+ *
+ * @example
+ * ```typescript
+ * if (isMultiVaultError(err, 'MultiVault_AtomExists')) {
+ *   // Handle atom already exists case
+ * }
+ * ```
+ */
+declare function isMultiVaultError(error: unknown, errorName: keyof typeof MULTIVAULT_ERRORS): boolean;
+/**
+ * Check if an error is any known MultiVault error
+ *
+ * @param error - The error to check
+ * @returns True if the error is a known MultiVault error
+ */
+declare function isKnownMultiVaultError(error: unknown): boolean;
+
+export { ATOM_TYPES, type AddressDetectionResult, type ArweaveDetectionResult, type AtomCreator, type AtomIdDetectionResult, type AtomLabelDetectionResult, type AtomType, type AtomTypeInput, type AtomValue, type AtomVault, COMMON_ERRORS, type DomainDetectionResult, ERROR_CATEGORIES, type EnsDetectionResult, type ErrorCategory, type FormatCryptoAmountOptions, type FormattedCryptoAmount, type GraphQLAtom, type IpfsDetectionResult, MULTIVAULT_ERRORS, type MultiVaultErrorInfo, type ParsedMultiVaultError, type RankedAtom, type SearchResult, type SearchSummary, type SocialDetectionResult, type SocialPlatform, TOTAL_ERROR_COUNT, type TextDetectionResult, type UrlDetectionResult, calculateMatchScore, capitalize, capitalizeFirstLetter, cn, detectAtomLabel, ellipsizeHex, ellipsizeString, formatAtomType, formatCompact, formatCryptoAmount, formatStake, formatTermId, getAtomDescription, getAtomDisplayName, getAtomImage, getAtomType, highlightMatch, ipfsToHttp, isAtomLabelKind, isDecentralizedStorage, isEntityType, isKnownMultiVaultError, isMultiVaultError, isOnChainIdentity, isPlainTextType, isPredicateType, isRawDataType, isSameAtomLabel, isWebReference, parseMultiVaultError, rankAtoms, secondsToDhms, secondsToHms, shortenLabel, strengthenImageUrl, timeAgo, truncateId, truncateSignificantDigits, truncateString };

package/dist/utils/index.js

@@ -1,5 +1,5 @@
-export { ATOM_TYPES, calculateMatchScore, formatAtomType, formatStake, formatTermId, getAtomDescription, getAtomDisplayName, getAtomImage, getAtomType, highlightMatch, isEntityType, isPlainTextType, isPredicateType, isRawDataType, rankAtoms } from '../chunk-H4RMZQ2Z.js';
-export { capitalize, capitalizeFirstLetter, ellipsizeHex, ellipsizeString, formatCompact, formatCryptoAmount, ipfsToHttp, secondsToDhms, secondsToHms, shortenLabel, strengthenImageUrl, timeAgo, truncateId, truncateSignificantDigits, truncateString } from '../chunk-ERZSVDIB.js';
+export { ATOM_TYPES, COMMON_ERRORS, ERROR_CATEGORIES, MULTIVAULT_ERRORS, TOTAL_ERROR_COUNT, calculateMatchScore, detectAtomLabel, formatAtomType, formatStake, formatTermId, getAtomDescription, getAtomDisplayName, getAtomImage, getAtomType, highlightMatch, isAtomLabelKind, isDecentralizedStorage, isEntityType, isKnownMultiVaultError, isMultiVaultError, isOnChainIdentity, isPlainTextType, isPredicateType, isRawDataType, isSameAtomLabel, isWebReference, parseMultiVaultError, rankAtoms } from '../chunk-VU3OPG32.js';
+export { capitalize, capitalizeFirstLetter, ellipsizeHex, ellipsizeString, formatCompact, formatCryptoAmount, ipfsToHttp, secondsToDhms, secondsToHms, shortenLabel, strengthenImageUrl, timeAgo, truncateId, truncateSignificantDigits, truncateString } from '../chunk-RW4JXOAM.js';
 export { cn } from '../chunk-VIRNUAYY.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemindhq/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Shared components, utilities, and types for hivemindhq applications",
   "author": "Kylan Hurt <kylan@hivemindhq.io>",
   "license": "ISC",
@@ -32,15 +32,9 @@
   },
   "files": [
     "dist",
+    "src",
     "tailwind.config.js"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
@@ -87,8 +81,8 @@
   "devDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
     "@types/react-dom": "^18.0.0 || ^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"
   },
@@ -103,5 +97,15 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/hivemindhq-io/core.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "version:patch": "pnpm version patch --no-git-tag-version",
+    "version:minor": "pnpm version minor --no-git-tag-version",
+    "version:major": "pnpm version major --no-git-tag-version",
+    "release": "pnpm run build && pnpm publish --no-git-checks --access public"
   }
-}
+}

package/src/components/AtomIcon.tsx

@@ -0,0 +1,21 @@
+export const AtomIcon = ({ ...props }: React.SVGProps<SVGSVGElement>) => {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="rgba(255,255,255,0.6)"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="lucide lucide-atom"
+      {...props}
+    >
+      <circle cx="12" cy="12" r="1" />
+      <path d="M20.2 20.2c2.04-2.03.02-7.36-4.5-11.9-4.54-4.52-9.87-6.54-11.9-4.5-2.04 2.03-.02 7.36 4.5 11.9 4.54 4.52 9.87 6.54 11.9 4.5Z" />
+      <path d="M15.7 15.7c4.52-4.54 6.54-9.87 4.5-11.9-2.03-2.04-7.36-.02-11.9 4.5-4.52 4.54-6.54 9.87-4.5 11.9 2.03 2.04 7.36.02 11.9-4.5Z" />
+    </svg>
+  )
+}