@foruai/shared

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

Installation

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

Usage

Types

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

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 — Server-side HMAC token signing
• @foruai/gatekeeper-client — Full API client for browser & Node.js

License

MIT