@craftlead/schema

TypeScript schemas and type definitions for CraftLead — Zod-validated types for agents, database, and blockchain interactions.

Installation

npm install @craftlead/schema
# or
pnpm add @craftlead/schema
# or
yarn add @craftlead/schema

Overview

@craftlead/schema provides shared TypeScript types and Zod schemas used across the CraftLead platform:

• Agent Types — Input/output schemas for all 4 agents
• Database Types — Supabase table definitions
• Blockchain Types — Smart contract interfaces
• Validation — Runtime schema validation with Zod

Architecture

flowchart TD
    subgraph Schema["@craftlead/schema"]
        subgraph Types["Type Definitions"]
            Agent[Agent Types]
            DB[Database Types]
            Chain[Blockchain Types]
            OG[0G Storage Types]
        end
        
        subgraph Zod["Zod Schemas"]
            ZAgent[Agent Schemas]
            ZDB[DB Schemas]
            ZChain[Chain Schemas]
        end
    end
    
    subgraph SDK["@craftlead/sdk"]
        SDKTypes[Uses Types]
        SDKValidate[Validates Data]
    end
    
    subgraph Frontend["Frontend"]
        FE[Uses Types]
    end
    
    Types --> SDKTypes
    Types --> FE
    Zod --> SDKValidate
    
    style Schema fill:#f59e0b

Type Categories

| Category | Types | Zod Schemas | |----------|-------|-------------| | Agent | PlannerTask, ResearchObservation, CriticReview, ExecutorReport | *Schema | | Database | Mission, AgentLog, Artifact, UserCredit | MissionSchema, etc. | | Blockchain | AgentNFTMetadata, SwapQuote, SwapResult | *Schema | | 0G Storage | StorageEntry, KVEntry, RootHash | *Schema | | Uniswap | QuoteRequest, SwapRequest, Settlement | *Schema |

Quick Start

import { 
  PlannerTaskSchema,
  ResearchObservationSchema,
  ExecutorReportSchema 
} from '@craftlead/schema'

// Validate agent output
const result = PlannerTaskSchema.safeParse(data)
if (result.success) {
  const tasks: PlannerTask[] = result.data
}

// Type inference
import type { Mission, AgentLog, Artifact } from '@craftlead/schema'

Agent Schemas

Planner

import { PlannerTaskSchema, type PlannerTask } from '@craftlead/schema'

const task = PlannerTaskSchema.parse({
  task_id: 'task-1',
  description: 'Analyze company background',
  data_source: 'crunchbase',
  focus: 'funding_history'
})

Researcher

import { 
  ResearchObservationSchema, 
  type ResearchObservation 
} from '@craftlead/schema'

const observation = ResearchObservationSchema.parse({
  finding: 'Company raised $50M Series B in 2024',
  data_points: ['crunchbase.com/company/acme'],
  confidence: 0.92,
  tags: ['funding', 'series-b']
})

Critic

import { 
  CriticReviewSchema, 
  type CriticReview 
} from '@craftlead/schema'

const review = CriticReviewSchema.parse({
  verified: true,
  issues: [],
  adjusted_confidence: 0.89,
  suggestions: ['Add more recent data']
})

Executor

import { 
  ExecutorReportSchema, 
  type ExecutorReport 
} from '@craftlead/schema'

const report = ExecutorReportSchema.parse({
  title: 'Senior React Developer at Acme Corp',
  summary: 'Strong opportunity with competitive compensation',
  key_findings: ['Series B fintech', 'Remote-first culture'],
  methodology: 'Multi-source analysis with AI verification',
  confidence_score: 0.91,
  recommendations: ['Apply within 7 days']
})

Database Types

Supabase Schema

import type { 
  Database, 
  Tables, 
  Enums 
} from '@craftlead/schema/supabase'

// Full database type
type DB = Database

// Individual tables
type Mission = Tables['missions']['Row']
type AgentLog = Tables['agent_logs']['Row']
type Artifact = Tables['artifacts']['Row']
type UserCredit = Tables['user_credits']['Row']

// Enums
type MissionStatus = Enums['mission_status']
type AgentType = Enums['agent_type']

Table Schemas

import { 
  MissionSchema,
  AgentLogSchema,
  ArtifactSchema 
} from '@craftlead/schema/database'

// Validate before insert
const validMission = MissionSchema.parse({
  title: 'Job Analysis',
  description: 'Analyze senior role',
  status: 'pending',
  type: 'standard'
})

Blockchain Types

Agent NFT

import { 
  AgentNFTMetadataSchema,
  type AgentNFTMetadata 
} from '@craftlead/schema/nft'

const metadata = AgentNFTMetadataSchema.parse({
  name: 'Researcher Agent #42',
  description: 'Specialized in company analysis',
  image: 'https://...',
  attributes: [
    { trait_type: 'Role', value: 'researcher' },
    { trait_type: 'Missions', value: '15' }
  ]
})

Uniswap

import { 
  SwapQuoteSchema,
  SwapRequestSchema,
  type SwapQuote,
  type SwapRequest 
} from '@craftlead/schema/uniswap'

const quote: SwapQuote = SwapQuoteSchema.parse({
  tokenIn: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
  tokenOut: '0xA0b86a33E6441e0aDA2e87046Aea47f05D07b666',
  amountIn: '1000000000000000',
  amountOut: '1140000',
  route: 'CLASSIC'
})

Mission Types

import type { 
  MissionInput,
  MissionConfig,
  MissionResult,
  AgentOutput 
} from '@craftlead/schema'

interface MissionInput {
  missionId: string
  title: string
  description: string
  jobData: JobData
  config?: MissionConfig
}

interface MissionResult {
  report: ExecutorReport
  iterations: number
  confidence: number
  txHash?: string
  agentOutputs: AgentOutput[]
}

Available Schemas

Agent Schemas

| Schema | Description | |--------|-------------| | PlannerTaskSchema | Task decomposition output | | ResearchObservationSchema | Research findings | | CriticReviewSchema | Quality review output | | ExecutorReportSchema | Final report structure |

Database Schemas

| Schema | Description | |--------|-------------| | MissionSchema | Mission table row | | AgentLogSchema | Agent log entry | | ArtifactSchema | Report artifact | | UserCreditSchema | Credit balance | | CreditTransactionSchema | Transaction record | | JobSchema | Job listing |

Blockchain Schemas

| Schema | Description | |--------|-------------| | AgentNFTMetadataSchema | ERC-721 metadata | | SwapQuoteSchema | Uniswap quote | | SwapRequestSchema | Swap execution request | | SettlementReceiptSchema | Agent payment receipt |

Peer Dependencies

{
  "zod": ">=3.22.0",
  "@supabase/supabase-js": ">=2.0.0",
  "ethers": ">=6.0.0"
}

Install peer dependencies:

npm install zod @supabase/supabase-js ethers

Usage in Projects

Frontend

// Validate API responses
import { ExecutorReportSchema } from '@craftlead/schema'

const response = await fetch('/api/reports/123')
const data = await response.json()
const report = ExecutorReportSchema.parse(data)

SDK

// Type-safe agent outputs
import type { PlannerTask, ResearchObservation } from '@craftlead/schema'

async function runPlanner(mission: Mission): Promise<PlannerTask[]> {
  // Returns validated PlannerTask[]
}

Database

// Type-safe Supabase queries
import type { Database } from '@craftlead/schema/supabase'
import { createClient } from '@supabase/supabase-js'

const supabase = createClient<Database>(url, key)

const { data } = await supabase
  .from('missions')
  .select('*')
  .eq('id', missionId)
// data is fully typed as Mission[]

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

Learn More

• NPM Package
• SDK Package
• Zod Documentation
• Main Project README