npm package: @foruai/shared
Description: Shared types, constants, and API path definitions for the ForU Gatekeeper AI ecosystem
Latest version: 0.2.0

# @foruai/shared

Shared types, constants, and API path definitions for the ForU Gatekeeper AI ecosystem.

## Installation

```bash
npm install @foruai/shared
# or
pnpm add @foruai/shared
# or
bun add @foruai/shared
```

## Usage

### Types

```typescript
import type {
  // Badge verification
  VerifyBadgeRequest,
  VerifyBadgeResponse,
  VerifiedBadge,
  BadgeInfo,
  BadgeRuleInfo,
  OnchainProof,
  AwardSource,
  MintingInfo,
  ChainConfig,

  // Discord
  DiscordCheckRequest,
  DiscordCheckResponse,
  DiscordServerStatus,

  // Profile
  ProfileRequest,
  ProfileResponse,

  // Chat
  ChatRequest,
  ChatResponse,

  // Auth
  HmacToken,

  // Discovery
  HealthResponse,
  ServicesCatalog,
  ServiceEntry,
} from '@foruai/shared'
```

### Constants

```typescript
import {
  API_PATHS,
  BADGE_STATUS,
  HMAC_MAX_AGE_MS,
  VALIDATOR_CATEGORIES,
  VALIDATOR_LABELS,
} from '@foruai/shared'

// API endpoint paths
console.log(API_PATHS.VERIFY_BADGE) // '/v1/verify-badge'
console.log(API_PATHS.CHAT)         // '/v1/chat'
console.log(API_PATHS.DISCORD)      // '/v1/discord'
console.log(API_PATHS.PROFILE)      // '/v1/profile'
console.log(API_PATHS.BADGES)       // '/v1/badges'
console.log(API_PATHS.HEALTH)       // '/v1/health'
console.log(API_PATHS.SERVICES)     // '/v1/services'

// Badge statuses
console.log(BADGE_STATUS.VERIFIED)     // 'verified'
console.log(BADGE_STATUS.NOT_VERIFIED) // 'not_verified'
console.log(BADGE_STATUS.NOT_FOUND)    // 'not_found'
```

### Type Reference

#### Badge Verification

| Type | Description |
|------|-------------|
| `VerifyBadgeRequest` | Request body for badge verification. Identify user by `user_address`, `username`, or `discord_username`. Optionally filter by `badge_id`. |
| `VerifyBadgeResponse` | Response containing `badges[]` with confidence scores, rules breakdown, on-chain proofs, and attribution. |
| `VerifiedBadge` | Individual badge with `status`, `confidence` (0-1), `badge_type`, `rules_breakdown`, `rules[]`, `awarded_via`, `minting`, `onchain_proof`, `chains[]`, `exp_earned`. |
| `BadgeRuleInfo` | Single rule: `validator_key`, `validator_label`, `operator`, `value`, `params_schema` (may include chain/contract info). |
| `OnchainProof` | On-chain verification: `contract_address`, `chain_id`, `wallet_address`, `balance`, `verified_onchain`. |
| `AwardSource` | Attribution: `source_type` (campaign/quest), campaign/quest names, community, rank, rep score. |
| `MintingInfo` | NFT minting status: `is_minted`, `mint_hash`, `chain_name`, `token_id`, `minting_cost`. |
| `BadgeInfo` | Badge catalog entry: `id`, `name`, `description`, `image`, `shape`, `source`. |

#### Discord

| Type | Description |
|------|-------------|
| `DiscordCheckRequest` | Identify user + optional `server_id` filter. |
| `DiscordCheckResponse` | `linked` status, `discord_username`, `servers[]` with membership details. |
| `DiscordServerStatus` | Per-server: `is_member`, `joined_at`, `nickname`, `roles[]`. |

#### Profile

| Type | Description |
|------|-------------|
| `ProfileRequest` | Identify user by any linked account. |
| `ProfileResponse` | `wallets[]`, `twitter`, `discord`, `badges` (total + minted counts). |

#### Chat & Auth

| Type | Description |
|------|-------------|
| `ChatRequest` | `message` + optional `sessionId` for conversation continuity. |
| `ChatResponse` | `reply`, `sessionId`, optional `routed` (which intent was matched). |
| `HmacToken` | `nonce`, `timestamp`, `signature` for HMAC-SHA256 authentication. |

## Companion Packages

- [`@foruai/gatekeeper-server`](https://www.npmjs.com/package/@foruai/gatekeeper-server) — Server-side HMAC token signing
- [`@foruai/gatekeeper-client`](https://www.npmjs.com/package/@foruai/gatekeeper-client) — Full API client for browser & Node.js

## License

MIT