{"_id":"@aidp-protocol/core","name":"@aidp-protocol/core","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@aidp-protocol/core","version":"1.0.2","description":"AIDP Protocol - The open protocol for AI-accessible local business data","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"jest","lint":"eslint src/**/*.ts","prepare":"npm run build","validate":"node dist/examples/validate.js"},"keywords":["aidp","ai-discovery","protocol","local-business","schema","validation","mcp","ai-assistant"],"author":{"name":"AIDP Protocol Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/gugga7/aidp.git"},"homepage":"https://aidp.dev","bugs":{"url":"https://github.com/gugga7/aidp.git"},"dependencies":{"ajv":"^8.12.0","ajv-formats":"^2.1.1"},"devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.0.0","typescript":"^5.0.0"},"engines":{"node":">=16.0.0"},"publishConfig":{"access":"public"},"gitHead":"6b45187351f11c7a45c639a301574b1b66ff0c2c","_id":"@aidp-protocol/core@1.0.2","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-mrKHiURyRdupr++JHIhokBXNE1W1nNdAa9yjFjXNlLtMQVD95yMiDLNH9Rftioyu6VcSER/VI4y4e5FaSMXIQw==","shasum":"b1e76baded05893c148d806e61ace25526cd0497","tarball":"https://registry.npmjs.org/@aidp-protocol/core/-/core-1.0.2.tgz","fileCount":26,"unpackedSize":107260,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGUjCmPdf3XTVd6aF2EEqoYrC6HQ3p/T45i6TOmwAneGAiBovV6y3SYvOAroUAwpE7wTBGNy0Cfbp8GBKiwfBtIbHg=="}]},"_npmUser":{"name":"gugga7","email":"amine7@gmail.com"},"directories":{},"maintainers":[{"name":"gugga7","email":"amine7@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_1.0.2_1765694721966_0.5483864112056436"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-14T06:45:21.875Z","1.0.2":"2025-12-14T06:45:22.119Z","modified":"2025-12-14T06:45:22.436Z"},"maintainers":[{"name":"gugga7","email":"amine7@gmail.com"}],"description":"AIDP Protocol - The open protocol for AI-accessible local business data","homepage":"https://aidp.dev","keywords":["aidp","ai-discovery","protocol","local-business","schema","validation","mcp","ai-assistant"],"repository":{"type":"git","url":"git+https://github.com/gugga7/aidp.git"},"author":{"name":"AIDP Protocol Team"},"bugs":{"url":"https://github.com/gugga7/aidp.git"},"license":"MIT","readme":"# AIDP Protocol\n\n[![npm version](https://badge.fury.io/js/%40aidp%2Fprotocol.svg)](https://badge.fury.io/js/%40aidp%2Fprotocol)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\n**The open protocol for AI-accessible local business data**\n\nAIDP (AI Discovery Protocol) is an open standard that defines how local business data should be structured for AI platforms. Like HTTP for web traffic, AIDP standardizes the data exchange between local businesses and AI assistants.\n\n## 🚀 Quick Start\n\n```bash\nnpm install @aidp/protocol\n```\n\n```typescript\nimport { BusinessProfile, validateBusinessProfile } from '@aidp/protocol';\n\n// Create a business profile\nconst business: BusinessProfile = {\n  id: 'biz_123',\n  name: 'Blue Bottle Coffee',\n  category: 'Coffee Shop',\n  location: {\n    address: '123 Main St, San Francisco, CA 94102',\n    coordinates: { lat: 37.7749, lng: -122.4194 }\n  },\n  contact: {\n    phone: '+1-555-0123',\n    website: 'https://bluebottlecoffee.com'\n  },\n  // ... more fields\n};\n\n// Validate the profile\nconst validation = validateBusinessProfile(business);\nif (validation.valid) {\n  console.log('✅ Valid AIDP business profile');\n} else {\n  console.error('❌ Validation errors:', validation.errors);\n}\n```\n\n## 📋 Features\n\n- **🔧 TypeScript Support** - Full type definitions for all AIDP entities\n- **✅ Schema Validation** - Built-in validation using JSON Schema\n- **🛠️ MCP Tools** - Ready-to-use MCP tool definitions\n- **📊 Analytics Types** - Upstream metrics and intent journey types\n- **🔄 Migration Helpers** - Convert from Google Business Profile, Yelp, etc.\n- **📖 Comprehensive Docs** - Complete API reference and examples\n\n## 🏗️ Core Concepts\n\n### Business Profile\n\nThe foundation of AIDP - a comprehensive business data structure:\n\n```typescript\nimport { BusinessProfile } from '@aidp/protocol';\n\nconst profile: BusinessProfile = {\n  // Basic Information\n  id: 'unique_business_id',\n  name: 'Business Name',\n  category: 'Primary Category',\n  description: 'Business description',\n  \n  // Location\n  location: {\n    address: 'Full address',\n    coordinates: { lat: 37.7749, lng: -122.4194 },\n    neighborhood: 'SOMA'\n  },\n  \n  // Contact Information\n  contact: {\n    phone: '+1-555-0123',\n    email: 'info@business.com',\n    website: 'https://business.com'\n  },\n  \n  // Services & Pricing\n  services: [\n    {\n      id: 'service_1',\n      name: 'Service Name',\n      description: 'Service description',\n      price: 25.00,\n      duration: 60,\n      bookable: true\n    }\n  ],\n  \n  // Operating Hours\n  availability: {\n    schedule: {\n      monday: { open: '09:00', close: '17:00' },\n      tuesday: { open: '09:00', close: '17:00' }\n      // ... other days\n    },\n    timezone: 'America/Los_Angeles'\n  },\n  \n  // AI-Exclusive Content\n  exclusiveContent: {\n    insiderTips: ['Hidden menu items', 'Best times to visit'],\n    localSecrets: ['Local knowledge only businesses know'],\n    ownerStory: 'The story behind the business'\n  },\n  \n  // Trust & Verification\n  trustSignals: {\n    verified: true,\n    claimedByOwner: true,\n    lastUpdated: '2024-11-15T10:30:00Z'\n  }\n};\n```\n\n### Booking System\n\nStandardized booking requests and responses:\n\n```typescript\nimport { BookingRequest, BookingResponse } from '@aidp/protocol';\n\nconst bookingRequest: BookingRequest = {\n  businessId: 'biz_123',\n  serviceId: 'service_1',\n  date: '2024-11-20',\n  time: '10:00',\n  partySize: 2,\n  customer: {\n    name: 'John Doe',\n    email: 'john@example.com',\n    phone: '+1-555-0199'\n  }\n};\n\nconst bookingResponse: BookingResponse = {\n  id: 'booking_456',\n  status: 'confirmed',\n  confirmationCode: 'ABC123',\n  // ... booking details\n};\n```\n\n### Upstream Analytics\n\nTrack AI discovery metrics:\n\n```typescript\nimport { UpstreamMetrics, IntentJourney } from '@aidp/protocol';\n\nconst metrics: UpstreamMetrics = {\n  impressions: {\n    total: 15420,\n    byPlatform: {\n      claude: 8234,\n      chatgpt: 4892,\n      perplexity: 2294\n    }\n  },\n  citations: {\n    total: 892,\n    placement: {\n      primary: 234,\n      secondary: 445,\n      tertiary: 213\n    }\n  },\n  zeroClick: {\n    total: 1247,\n    visibility: 78.5\n  }\n};\n```\n\n## 🛠️ Validation\n\nValidate any AIDP entity against the official schema:\n\n```typescript\nimport { \n  validateBusinessProfile,\n  validateBookingRequest,\n  validateReview \n} from '@aidp/protocol';\n\n// Validate business profile\nconst profileValidation = validateBusinessProfile(businessData);\nif (!profileValidation.valid) {\n  console.error('Validation errors:', profileValidation.errors);\n}\n\n// Validate booking request\nconst bookingValidation = validateBookingRequest(bookingData);\nif (bookingValidation.valid) {\n  console.log('✅ Valid booking request');\n}\n\n// Custom validation with options\nconst validation = validateBusinessProfile(data, {\n  strict: true,           // Strict validation mode\n  allowAdditional: false, // Don't allow additional properties\n  coerceTypes: true      // Coerce types when possible\n});\n```\n\n## 🔧 MCP Integration\n\nReady-to-use MCP tool definitions:\n\n```typescript\nimport { MCPTools } from '@aidp/protocol';\n\n// Get all AIDP MCP tools\nconst tools = MCPTools.getAllTools();\n\n// Get specific tool definition\nconst searchTool = MCPTools.getSearchBusinessesTool();\nconst bookingTool = MCPTools.getCreateBookingTool();\n\n// Use with MCP server\nserver.setRequestHandler(ListToolsRequestSchema, async () => {\n  return {\n    tools: MCPTools.getAllTools()\n  };\n});\n```\n\n## 🔄 Migration Helpers\n\nConvert from existing platforms:\n\n```typescript\nimport { \n  convertFromGoogleBusiness,\n  convertFromYelp,\n  convertFromFoursquare \n} from '@aidp/protocol';\n\n// Convert Google Business Profile\nconst googleData = { /* Google Business Profile data */ };\nconst aidpProfile = convertFromGoogleBusiness(googleData);\n\n// Convert Yelp Business data\nconst yelpData = { /* Yelp API response */ };\nconst aidpProfile2 = convertFromYelp(yelpData);\n\n// Validate converted data\nconst validation = validateBusinessProfile(aidpProfile);\n```\n\n## 📊 Analytics & Insights\n\nWork with upstream analytics data:\n\n```typescript\nimport { \n  UpstreamMetrics,\n  IntentJourney,\n  calculateShareOfVoice,\n  analyzeIntentProgression \n} from '@aidp/protocol';\n\n// Calculate share of voice\nconst shareOfVoice = calculateShareOfVoice(metrics, competitorMetrics);\n\n// Analyze intent progression\nconst journey: IntentJourney = {\n  id: 'journey_123',\n  turns: [\n    { turn: 1, intentScore: 20, query: 'coffee shops near me' },\n    { turn: 2, intentScore: 35, query: 'best coffee downtown' },\n    { turn: 3, intentScore: 65, query: 'Blue Bottle Coffee hours' },\n    { turn: 4, intentScore: 88, query: 'book table at Blue Bottle' }\n  ]\n};\n\nconst analysis = analyzeIntentProgression(journey);\nconsole.log(`Conversion probability: ${analysis.conversionProbability}`);\n```\n\n## 🎯 Use Cases\n\n### For AI Platform Developers\n\n```typescript\nimport { BusinessProfile, MCPTools } from '@aidp/protocol';\n\n// Implement AIDP-compatible search\nasync function searchBusinesses(query: string, location: string) {\n  const tool = MCPTools.getSearchBusinessesTool();\n  const result = await callMCPTool(tool, { query, location });\n  \n  // Result is guaranteed to match AIDP schema\n  return result.businesses as BusinessProfile[];\n}\n```\n\n### For Business Software Developers\n\n```typescript\nimport { BusinessProfile, validateBusinessProfile } from '@aidp/protocol';\n\n// Export business data in AIDP format\nfunction exportToAIDP(businessData: any): BusinessProfile {\n  const aidpProfile: BusinessProfile = {\n    id: businessData.id,\n    name: businessData.name,\n    // ... map your data to AIDP format\n  };\n  \n  const validation = validateBusinessProfile(aidpProfile);\n  if (!validation.valid) {\n    throw new Error(`Invalid AIDP profile: ${validation.errors.join(', ')}`);\n  }\n  \n  return aidpProfile;\n}\n```\n\n### For Local Business Platforms\n\n```typescript\nimport { convertFromGoogleBusiness, validateBusinessProfile } from '@aidp/protocol';\n\n// Migrate existing business data\nasync function migrateToAIDP(googleBusinessData: any) {\n  // Convert from Google Business Profile format\n  const aidpProfile = convertFromGoogleBusiness(googleBusinessData);\n  \n  // Add AI-exclusive content\n  aidpProfile.exclusiveContent = {\n    insiderTips: ['Try our secret menu items'],\n    localSecrets: ['Best parking is around the corner'],\n    ownerStory: 'Family-owned since 1985'\n  };\n  \n  // Validate before saving\n  const validation = validateBusinessProfile(aidpProfile);\n  if (validation.valid) {\n    await saveBusinessProfile(aidpProfile);\n  }\n}\n```\n\n## 📚 API Reference\n\n### Core Types\n\n- `BusinessProfile` - Complete business information\n- `BookingRequest` - Booking request structure\n- `BookingResponse` - Booking confirmation details\n- `Review` - Customer review data\n- `UpstreamMetrics` - AI discovery analytics\n- `IntentJourney` - User intent progression\n\n### Validation Functions\n\n- `validateBusinessProfile(data, options?)` - Validate business profile\n- `validateBookingRequest(data, options?)` - Validate booking request\n- `validateBookingResponse(data, options?)` - Validate booking response\n- `validateReview(data, options?)` - Validate review data\n- `validateUpstreamMetrics(data, options?)` - Validate analytics data\n\n### MCP Tools\n\n- `MCPTools.getAllTools()` - Get all AIDP MCP tools\n- `MCPTools.getSearchBusinessesTool()` - Search businesses tool\n- `MCPTools.getCreateBookingTool()` - Create booking tool\n- `MCPTools.getGetReviewsTool()` - Get reviews tool\n\n### Migration Helpers\n\n- `convertFromGoogleBusiness(data)` - Convert Google Business Profile\n- `convertFromYelp(data)` - Convert Yelp business data\n- `convertFromFoursquare(data)` - Convert Foursquare venue data\n\n### Analytics Utilities\n\n- `calculateShareOfVoice(metrics, competitors)` - Calculate market share\n- `analyzeIntentProgression(journey)` - Analyze user intent\n- `calculateConversionProbability(journey)` - Predict conversion\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/aidp-protocol/aidp-protocol.git\ncd aidp-protocol\nnpm install\nnpm run build\nnpm test\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- **Documentation**: [docs.aidp.dev](https://docs.aidp.dev)\n- **Protocol Specification**: [aidp.dev/protocol](https://aidp.dev/protocol)\n- **GitHub Repository**: [github.com/aidp-protocol/aidp-protocol](https://github.com/aidp-protocol/aidp-protocol)\n- **NPM Package**: [@aidp/protocol](https://www.npmjs.com/package/@aidp/protocol)\n- **Community**: [Discord](https://discord.gg/aidp-protocol)\n\n## 🆘 Support\n\n- **Documentation**: [docs.aidp.dev](https://docs.aidp.dev)\n- **Issues**: [GitHub Issues](https://github.com/aidp-protocol/aidp-protocol/issues)\n- **Email**: [support@aidp.dev](mailto:support@aidp.dev)\n- **Discord**: [AIDP Protocol Community](https://discord.gg/aidp-protocol)\n\n---\n\n**AIDP Protocol** - Making local business data accessible to AI, one protocol at a time. 🚀","readmeFilename":"README.md","_rev":"1-bf95e5c6cc05695d34b3eda93611cc11"}