HASO AI Common Core

A comprehensive library of interfaces, schemas, and utilities shared across HASO AI projects.

Overview

The HASO AI Common Core library provides a standardized set of interfaces and type definitions for building consistent and interoperable components within the HASO AI ecosystem. It serves as the foundation for all HASO AI applications, ensuring consistent data structures and API contracts.

Installation

# Install latest version
npm install hasoai-common-core

# Or install a specific version
npm install [email protected]

# Or using yarn
yarn add hasoai-common-core

Directory Structure

src/
├── interfaces/            # Reusable interfaces across projects
│   ├── ai.ts              # General AI-related interfaces
│   ├── data.ts            # Data structure interfaces
│   ├── haso-ai/           # HASO AI specific interfaces (migrated from career-optima)
│   │   ├── ai.ts          # HASO AI models and interfaces
│   │   ├── models/        # Domain models organized by concept 
│   │   │   ├── base.ts    # Base types and common structures
│   │   │   ├── challenge.ts 
│   │   │   ├── communication.ts
│   │   │   ├── community.ts
│   │   │   ├── event.ts
│   │   │   ├── full-community.ts
│   │   │   ├── gamification.ts
│   │   │   ├── resource.ts
│   │   │   └── user.ts
│   │   └── services.ts    # Service interfaces for implementation contracts
│   ├── index.ts           # Main export file
│   └── services.ts        # Common service interfaces
├── schemas/               # JSON schemas for validation
│   ├── index.ts           # Schema exports
│   └── validation.ts      # Validation utilities
└── index.ts               # Package entry point

Core Interfaces

The library provides interfaces organized by domain:

User and Profile Interfaces

import { UserProfile, User, UserSettings } from 'hasoai-common-core';

// Create a user object with proper typing
const user: User = {
  id: 'user123',
  email: '[email protected]',
  displayName: 'Example User'
};

Community and Organization Models

import { Community, CommunityMember, MembershipTier } from 'hasoai-common-core';

// Access community data with proper typing
const community: Community = {
  id: 'community123',
  name: 'HASO AI Community',
  accessType: 'public',
  // ...other properties
};

AI and Data Interfaces

import { AIModel, DataSource, ModelConfig } from 'hasoai-common-core';

// Configure AI models with proper typing
const model: AIModel = {
  id: 'model123',
  name: 'HASO GPT',
  version: '1.0.0',
  // ...other properties
};

Service Interfaces

import { IUserService, ICommunityService } from 'hasoai-common-core';

// Implement service interfaces for consistent API patterns
class UserService implements IUserService {
  async getUserById(id: string): Promise<User> {
    // implementation
  }
  // ...other methods
}

Usage Examples

Basic Usage

// Import specific interfaces
import { UserProfile, Challenge, Resource } from 'hasoai-common-core';

// Use in your component or service
const userProfile: UserProfile = { /* ... */ };

Example Usage in React Components

// UserProfileComponent.tsx
import React from 'react';
import { UserProfile } from 'hasoai-common-core';

interface Props {
  user: UserProfile;
}

export const UserProfileComponent: React.FC<Props> = ({ user }) => {
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.bio}</p>
      <div>
        <h2>Skills</h2>
        <ul>
          {user.skills.map(skill => (
            <li key={skill.id}>
              {skill.name} - {skill.level}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
};

Example Usage in API Services

// challenge-service.ts
import { Challenge, IImplementationService, Milestone } from 'hasoai-common-core';

export class ChallengeService implements IImplementationService {
  async getUserChallengeProgress(userId: string, challengeId: string) {
    const response = await fetch(`/api/challenges/${challengeId}/progress/${userId}`);
    const data = await response.json();
    
    return {
      completedMilestones: data.completedMilestones,
      totalMilestones: data.totalMilestones,
      currentMilestone: data.currentMilestone as Milestone,
      nextMilestones: data.nextMilestones as Milestone[],
      daysRemaining: data.daysRemaining,
      status: data.status as 'on-track' | 'behind' | 'ahead',
    };
  }
  
  // Implement other methods...
}

## Publishing

This package is published to the npm registry. There are two ways to publish a new version:

### Local Publishing

For quick local publishing, you can use:

```bash
# Update the version in package.json first!

# Run the deploy script which checks if the version exists before publishing
npm run deploy

# To only check if the current version exists without publishing
npm run version-check

Automated Publishing via GitHub Actions

The package is automatically published through GitHub Actions when changes are pushed to the main branch:

1. Update the version in package.json
2. Commit and push your changes to the main branch
3. The GitHub Action will:
   • Install dependencies
   • Run tests
   • Lint the code
   • Build the package
   • Check if the version already exists
   • Publish to npm (only if the version doesn't exist)

# Example workflow
git add .
git commit -m "Update to version x.y.z"
git push

The workflow is designed to be resilient - if you've already published a version locally, the GitHub workflow will detect this and skip the publish step rather than failing.

Development

Adding New Interfaces

1. Add new interfaces to the appropriate file in the src/interfaces/haso-ai/models directory
2. Ensure the interface is properly exported in the corresponding index file
3. Update this README if adding a major new category of interfaces

Testing

Ensure all interfaces are properly defined with no circular dependencies or linting errors:

npm run lint

License

Proprietary - HASO AI 2025