@agapi/core

Core TypeScript models and utilities for the Agapi ecosystem. This package provides framework-agnostic interfaces and utilities for Point of Sale (POS) systems and Provider Directory management.

Installation

npm install @agapi/core

yarn add @agapi/core

pnpm add @agapi/core

Quick Start

Using the Main Export

Import everything from the main entry point:

import { Cart, Product, Provider, ProviderStatus } from '@agapi/core';

// Create a product
const product: Product = {
  id: 'prod-1',
  name: 'Coffee',
  price: 4.99,
  isAvailable: true,
  createdAt: new Date(),
  updatedAt: new Date(),
};

// Create a cart
const cart: Cart = {
  items: [],
  subtotal: 0,
  tax: 0,
  total: 0,
};

Using Submodule Imports

For better tree-shaking and smaller bundle sizes, import from specific modules:

import { Cart, CartItem, calculateCartTotal } from '@agapi/core/pos';
import { Provider, ProviderStatus, Contact } from '@agapi/core/providers';

Module Overview

POS Module

The POS module provides models and utilities for building point-of-sale systems.

Core Models:

• Product - Product information with pricing, inventory, and metadata
• ProductCategory - Product categorization
• Cart - Shopping cart with items and calculated totals
• CartItem - Individual items in a cart
• Order - Finalized orders with payment and fulfillment info
• OrderItem - Line items in an order

Utilities:

• Cart calculations (subtotal, tax, total)
• Cart item management (add, update, remove)
• Order calculations and processing

Example:

import {
  Cart,
  CartItem,
  Product,
  addItemToCart,
  calculateCartTotal,
  updateCartItemQuantity,
} from '@agapi/core/pos';

// Create a product
const coffee: Product = {
  id: 'prod-1',
  name: 'Espresso',
  price: 3.50,
  isAvailable: true,
  taxRate: 0.08,
  createdAt: new Date(),
  updatedAt: new Date(),
};

// Initialize empty cart
let cart: Cart = {
  items: [],
  subtotal: 0,
  tax: 0,
  total: 0,
};

// Add item to cart
const cartItem: CartItem = {
  product: coffee,
  quantity: 2,
  price: coffee.price,
  subtotal: coffee.price * 2,
};

cart = addItemToCart(cart, cartItem);
cart = calculateCartTotal(cart);

console.log(`Total: $${cart.total.toFixed(2)}`);

Providers Module

The Providers module contains models for managing a directory of service providers, suppliers, and business contacts.

Core Models:

• Provider - Business entity with contacts, addresses, and metadata
• ProviderStatus - Enum for provider states (ACTIVE, INACTIVE, PENDING, SUSPENDED)
• Contact - Contact person information
• Address - Physical address information

Example:

import {
  Provider,
  ProviderStatus,
  Contact,
  Address,
} from '@agapi/core/providers';

// Create a provider
const supplier: Provider = {
  id: 'prov-1',
  name: 'Coffee Beans Co.',
  businessName: 'Coffee Beans Company LLC',
  status: ProviderStatus.ACTIVE,
  contacts: [
    {
      id: 'cont-1',
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      phone: '+1-555-0123',
      isPrimary: true,
    },
  ],
  addresses: [
    {
      id: 'addr-1',
      street: '123 Bean Street',
      city: 'Seattle',
      state: 'WA',
      postalCode: '98101',
      country: 'USA',
      isPrimary: true,
    },
  ],
  createdAt: new Date(),
  updatedAt: new Date(),
};

Import Patterns

Main Export Pattern

Best for: Small applications, prototyping, when bundle size is not a concern

// Import everything from the main entry point
import { Cart, Product, Provider, Contact } from '@agapi/core';

This pattern exports all modules from a single entry point, making imports simpler but potentially including unused code in your bundle.

Submodule Pattern

Best for: Production applications, when optimizing bundle size, modular architecture

// Import only POS-related types and utilities
import { Cart, Product, calculateCartTotal } from '@agapi/core/pos';

// Import only Provider-related types
import { Provider, ProviderStatus, Address } from '@agapi/core/providers';

This pattern allows for better tree-shaking and smaller bundle sizes by only importing what you need from specific modules.

Package Exports

The package provides three entry points configured in package.json:

{
  ".": "./dist/index.js",           // Main export (all modules)
  "./pos": "./dist/pos.js",         // POS module only
  "./providers": "./dist/providers.js"  // Providers module only
}

Development

Scripts

# Build the package
npm run build

# Type checking
npm run type-check

# Run tests
npm run test

# Development mode (watch)
npm run dev

Requirements

• Node.js >= 16
• TypeScript >= 5.0

API Documentation

For detailed API documentation, type definitions, and examples, visit:

https://github.com/agapi/core/tree/main/docs

Features

• Framework Agnostic - Pure TypeScript interfaces with no framework dependencies
• Type Safe - Full TypeScript support with comprehensive type definitions
• Tree-Shakeable - Optimized for modern bundlers with ES modules
• Modular - Import only what you need with submodule exports
• Well Tested - Comprehensive test coverage for all utilities
• Zero Dependencies - No runtime dependencies, minimal footprint

License

ISC

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Version

Current version: 1.0.0