@simpleapps-com/augur-api 0.2.3 → 0.2.5

package/README.md

@@ -5,6 +5,7 @@ A comprehensive TypeScript client library for accessing Augur microservices with
 ## Table of Contents
 
 - [Overview](#overview)
+- [🎯 AI-Powered Discovery System - Where Code Writes Itself](#-ai-powered-discovery-system---where-code-writes-itself)
 - [Features](#features)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
@@ -31,8 +32,107 @@ The Augur API Client Library provides a unified TypeScript SDK for accessing Aug
 - **Runtime Validation**: Zod schemas validate all requests and responses
 - **Developer Experience**: Rich JSDoc documentation and IntelliSense support
 
+## IDE Support & AI Assistant Integration
+
+This client library is designed to work seamlessly with modern IDEs and AI coding assistants through comprehensive semantic documentation.
+
+### IntelliSense & Auto-completion
+
+Every method includes detailed JSDoc with:
+- **Parameter descriptions** and types
+- **Usage examples** with real code
+- **Related methods** and cross-service connections
+- **Business context** and workflow information
+
+```typescript
+client.agrSite.settings. // ← IDE shows all available methods with descriptions
+```
+
+### AI Assistant Features
+
+The semantic JSDoc tags help AI assistants understand:
+
+```typescript
+/**
+ * @searchTerms ["settings", "configuration", "site config"]
+ * @relatedEndpoints ["api.agrSite.settings.get", "api.agrSite.settings.update"]
+ * @workflow ["settings-management", "site-configuration"]
+ * @commonPatterns ["Get all settings", "List site configuration"]
+ */
+```
+
+This means when you ask an AI assistant to "help me manage site settings", it can:
+1. Find the right service (`agrSite.settings`)
+2. Suggest the correct method (`list`, `get`, `create`, etc.)
+3. Show related operations you might need
+4. Provide complete workflow examples
+
+### Dual API Pattern
+
+Each service provides two ways to call methods:
+
+```typescript
+// Standard method - returns full response with metadata
+const response = await client.agrSite.settings.list();
+console.log(response.data, response.total, response.message);
+
+// Data method - returns only the data portion
+const settings = await client.agrSite.settings.listData();
+console.log(settings); // Direct array access
+```
+
+### API Discovery Functions
+
+The client provides discovery functions for exploring available services and endpoints:
+
+#### `discover()` - Service Map
+
+Get an overview of available services and their discoverable endpoints:
+
+```typescript
+const api = new AugurAPI({ siteId: 'my-site', bearerToken: 'token' });
+const services = await api.discover();
+
+// Returns ServiceMap[] with:
+// - serviceName: string
+// - description: string  
+// - baseUrl: string
+// - endpointCount: number
+// - endpoints: DiscoveryEndpoint[]
+
+services.forEach(service => {
+  console.log(`${service.serviceName}: ${service.endpointCount} endpoints`);
+});
+```
+
+#### `findEndpoint()` - Endpoint Search
+
+Search across services for endpoints matching a search term:
+
+```typescript
+// Basic search
+const results = await api.findEndpoint('users');
+
+// With options
+const results = await api.findEndpoint('settings', {
+  minScore: 0.1,         // Minimum relevance score (default: 0.1)
+  maxResults: 10,        // Max results (default: 10)
+  service: 'agrSite',    // Filter by service
+  domain: 'site-content-management', // Filter by domain
+  readOnly: true         // Only GET endpoints
+});
+
+// Returns EndpointSearchResult[] with:
+// - endpoint: DiscoveryEndpoint (with fullPath, service, domain, etc.)
+// - score: number (0-1 relevance)
+// - matchReason: string
+```
+
 ## Features
 
+✅ **AI-Powered Discovery** - Natural language search finds any functionality instantly  
+✅ **Semantic Intelligence** - Understands business context and suggests workflows  
+✅ **Cross-Service Awareness** - Maps relationships between all microservices  
 ✅ **Simple API** - Intuitive method names following REST conventions  
 ✅ **Type Safe** - Full TypeScript support with auto-completion  
 ✅ **Runtime Validation** - Zod schemas validate all requests and responses  

package/dist/cjs/client.d.ts

@@ -1,4 +1,5 @@
 import { AugurAPIConfig } from './core/config';
+import { DiscoveryEndpoint as BaseDiscoveryEndpoint } from './core/base-client';
 import { JoomlaClient } from './services/joomla';
 import { CommerceClient } from './services/commerce';
 import { PricingClient } from './services/pricing';
@@ -12,6 +13,36 @@ import { CustomersClient } from './services/customers';
 import { OrdersClient } from './services/orders';
 import { P21PimClient } from './services/p21-pim';
 import { PaymentsClient } from './services/payments';
+/**
+ * Interface for discovery endpoint information - re-export base discovery endpoint
+ */
+export type DiscoveryEndpoint = BaseDiscoveryEndpoint;
+/**
+ * Interface for service discovery results
+ */
+export interface ServiceMap {
+    /** Service name */
+    serviceName: string;
+    /** Service description */
+    description: string;
+    /** Base URL for the service */
+    baseUrl: string;
+    /** Number of discoverable endpoints */
+    endpointCount: number;
+    /** Array of discoverable endpoints */
+    endpoints: DiscoveryEndpoint[];
+}
+/**
+ * Interface for endpoint search results
+ */
+export interface EndpointSearchResult {
+    /** The matching endpoint */
+    endpoint: DiscoveryEndpoint;
+    /** Relevance score (0-1) */
+    score: number;
+    /** Reason why this endpoint matched */
+    matchReason: string;
+}
 /**
  * Main client factory for accessing Augur microservices
  *
@@ -172,5 +203,155 @@ export declare class AugurAPI {
      * @param siteId New site ID
      */
     setSiteId(siteId: string): void;
+    /**
+     * Discover all available services and their capabilities
+     *
+     * Returns a complete service map showing all discoverable endpoints across
+     * all microservices, enabling AI agents to understand the full API topology.
+     *
+     * @returns Promise<ServiceMap[]> Array of service maps with endpoint metadata
+     *
+     * @example
+     * ```typescript
+     * const api = new AugurAPI({ siteId: 'my-site', bearerToken: 'token' });
+     * const services = await api.discover();
+     *
+     * // Find all user-related endpoints
+     * const userEndpoints = services.flatMap(s => s.endpoints)
+     *   .filter(e => e.searchTerms.some(term => term.includes('user')));
+     *
+     * // Show service capabilities
+     * services.forEach(service => {
+     *   console.log(`${service.serviceName}: ${service.endpointCount} endpoints`);
+     *   service.endpoints.forEach(endpoint => {
+     *     console.log(`  ${endpoint.fullPath} - ${endpoint.description}`);
+     *   });
+     * });
+     * ```
+     */
+    discover(): Promise<ServiceMap[]>;
+    /**
+     * Find endpoints by search term or functionality description
+     *
+     * Searches across all services to find endpoints that match the given search term.
+     * Uses intelligent matching against endpoint descriptions, search terms, domains,
+     * and common usage patterns.
+     *
+     * @param searchTerm The functionality or term to search for
+     * @param options Search options for filtering and ranking
+     * @returns Promise<EndpointSearchResult[]> Array of matching endpoints with relevance scores
+     *
+     * @example
+     * ```typescript
+     * const api = new AugurAPI({ siteId: 'my-site', bearerToken: 'token' });
+     *
+     * // Find user-related endpoints
+     * const userEndpoints = await api.findEndpoint('users');
+     * console.log(`Found ${userEndpoints.length} user-related endpoints`);
+     *
+     * // Find authentication endpoints
+     * const authEndpoints = await api.findEndpoint('authentication');
+     *
+     * // Find inventory management
+     * const inventoryEndpoints = await api.findEndpoint('inventory management');
+     *
+     * // Show results with scores
+     * userEndpoints.forEach(result => {
+     *   console.log(`${result.endpoint.fullPath} (${result.score.toFixed(2)}) - ${result.matchReason}`);
+     * });
+     * ```
+     */
+    findEndpoint(searchTerm: string, options?: {
+        /** Minimum relevance score (0-1, default: 0.1) */
+        minScore?: number;
+        /** Maximum number of results (default: 10) */
+        maxResults?: number;
+        /** Filter by specific service */
+        service?: string;
+        /** Filter by business domain */
+        domain?: string;
+        /** Include only GET endpoints */
+        readOnly?: boolean;
+    }): Promise<EndpointSearchResult[]>;
+    /**
+     * Get endpoints filtered by service, domain, and method options
+     */
+    private getFilteredEndpoints;
+    /**
+     * Search and score endpoints against search term
+     */
+    private searchAndScoreEndpoints;
+    /**
+     * Check if endpoint has required fields
+     */
+    private isValidEndpoint;
+    /**
+     * Calculate final score with domain filter adjustments
+     */
+    private calculateFinalScore;
+    /**
+     * Calculate relevance score for an endpoint against a search term
+     */
+    private calculateEndpointRelevance;
+    /**
+     * Process exact matches with appropriate combining logic
+     */
+    private processExactMatches;
+    /**
+     * Check if match type should be exclusive (no combining)
+     */
+    private isExclusiveMatch;
+    /**
+     * Check if match type can be combined with partial matches
+     */
+    private isCombinableMatch;
+    /**
+     * Process fallback matches when no exact match found
+     */
+    private processFallbackMatches;
+    /**
+     * Calculate exact field matches with high scores
+     */
+    private calculateExactMatches;
+    /**
+     * Check for path substring matches
+     */
+    private checkPathSubstringMatch;
+    /**
+     * Check for description substring matches
+     */
+    private checkDescriptionSubstringMatch;
+    /**
+     * Check for other substring matches (domain, service)
+     */
+    private checkOtherSubstringMatches;
+    /**
+     * Check for exact field matches
+     */
+    private checkExactFieldMatches;
+    /**
+     * Check search terms and common patterns
+     */
+    private checkSearchTermsAndPatterns;
+    /**
+     * Calculate partial word matches with lower scores
+     */
+    private calculatePartialMatches;
+    /**
+     * Build searchable text from endpoint fields
+     */
+    private buildSearchableText;
+    /**
+     * Count matching words in text
+     */
+    private countWordMatches;
+    /**
+     * Build partial match result with score and reason
+     */
+    private buildPartialMatchResult;
+    /**
+     * Calculate multi-word matches by finding the best match for each word
+     */
+    private calculateMultiWordMatches;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,IAAI,CAAC,CAAY;IACzB,OAAO,CAAC,WAAW,CAAC,CAAmB;IACvC,OAAO,CAAC,MAAM,CAAC,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAc;IAC7B,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,UAAU,CAAC,CAAkB;IACrC,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,OAAO,CAAC,CAAe;IAC/B,OAAO,CAAC,SAAS,CAAC,CAAiB;gBAEvB,MAAM,EAAE,cAAc;IAIlC;;OAEG;IACH,IAAI,MAAM,IAAI,YAAY,CAMzB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,cAAc,CAM7B;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,aAAa,CAM3B;IAED;;OAEG;IACH,IAAI,GAAG,IAAI,SAAS,CAMnB;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,gBAAgB,CAMjC;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,WAAW,CAMvB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,YAAY,CAMzB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,WAAW,CAMvB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,aAAa,CAM3B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,eAAe,CAM/B;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,YAAY,CAMzB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,YAAY,CAMzB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,cAAc,CAM7B;IAED;;;OAGG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAkBvC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAiBhC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}