@mixpeek/contentful 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 (2026-02-11)
+
+- Initial release
+- WebhookHandler, ContentEnricher, ContentfulClient modules
+- Mixpeek API client with retry logic
+- In-memory LRU cache
+- Unit, E2E, and live API tests

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mixpeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @mixpeek/contentful
+
+Contentful integration for Mixpeek — webhook handling, content enrichment, and management API integration
+
+## Installation
+
+```bash
+npm install @mixpeek/contentful contentful-management
+```
+
+## Quick Start
+
+```js
+import webhookHandler from '@mixpeek/contentful';
+
+const instance = webhookHandler({
+  apiKey: process.env.MIXPEEK_API_KEY
+});
+```
+
+## Modules
+
+### WebhookHandler
+
+Handles Contentful webhooks (entry publish/unpublish/archive) and triggers enrichment
+
+```js
+import { createWebhookHandler } from '@mixpeek/contentful';
+
+const webhookHandler = createWebhookHandler({
+  apiKey: process.env.MIXPEEK_API_KEY
+});
+```
+
+### ContentEnricher
+
+Enriches Contentful entries with Mixpeek multimodal analysis stored in custom fields
+
+```js
+import { createContentEnricher } from '@mixpeek/contentful';
+
+const contentEnricher = createContentEnricher({
+  apiKey: process.env.MIXPEEK_API_KEY
+});
+```
+
+### ContentfulClient
+
+Contentful Management API client for reading/writing enrichment data
+
+```js
+import { createContentfulClient } from '@mixpeek/contentful';
+
+const contentfulClient = createContentfulClient({
+  apiKey: process.env.MIXPEEK_API_KEY
+});
+```
+
+## Testing
+
+```bash
+npm test              # Unit tests
+npm run test:e2e      # End-to-end tests
+npm run test:live     # Live API tests (requires MIXPEEK_API_KEY)
+npm run test:coverage # Coverage report
+```
+
+## License
+
+MIT

package/dist/api/mixpeekClient.js

@@ -0,0 +1,111 @@
+/**
+ * @mixpeek/contentful — Mixpeek API Client
+ *
+ * HTTP client for Mixpeek API integration with retry logic and timeout handling.
+ */
+
+import {
+  API_ENDPOINT, API_VERSION, DEFAULT_TIMEOUT,
+  RETRY_ATTEMPTS, RETRY_DELAY, ERROR_CODES, HEADERS
+} from '../config/constants.js';
+import { getLogger } from '../utils/logger.js';
+
+class MixpeekClient {
+  /**
+   * @param {Object} config
+   * @param {string} config.apiKey - Mixpeek API key
+   * @param {string} [config.endpoint] - API endpoint
+   * @param {number} [config.timeout] - Request timeout in ms
+   * @param {boolean} [config.debug] - Enable debug logging
+   */
+  constructor(config) {
+    if (!config.apiKey) throw new Error('API key is required');
+
+    this.apiKey = config.apiKey;
+    this.endpoint = (config.endpoint || API_ENDPOINT).replace(/\/$/, '');
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.logger = getLogger({ debug: config.debug });
+  }
+
+  async request(method, path, body = null) {
+    const url = `${this.endpoint}/${API_VERSION}${path}`;
+    const headers = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Content-Type': HEADERS.CONTENT_TYPE,
+      'Accept': HEADERS.ACCEPT,
+      'User-Agent': HEADERS.USER_AGENT
+    };
+
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_ATTEMPTS; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        this.logger.debug(`API ${method} ${path} (attempt ${attempt + 1})`);
+
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : null,
+          signal: controller.signal
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          const errorBody = await response.text();
+          throw new Error(`HTTP ${response.status}: ${errorBody}`);
+        }
+
+        return await response.json();
+      } catch (error) {
+        lastError = error;
+        if (error.name === 'AbortError') {
+          lastError = new Error(`Request timeout after ${this.timeout}ms`);
+          lastError.code = ERROR_CODES.TIMEOUT;
+        }
+        if (attempt < RETRY_ATTEMPTS) {
+          await new Promise(r => setTimeout(r, RETRY_DELAY));
+        }
+      }
+    }
+
+    this.logger.error('API request failed after retries:', lastError.message);
+    throw lastError;
+  }
+
+  async healthCheck() {
+    try {
+      const start = Date.now();
+      const response = await this.request('GET', '/health');
+      return { status: 'healthy', latency: Date.now() - start, timestamp: new Date().toISOString(), response };
+    } catch (error) {
+      return { status: 'unhealthy', error: error.message, timestamp: new Date().toISOString() };
+    }
+  }
+
+  async search(query, options = {}) {
+    return this.request('POST', '/features/search', { query, ...options });
+  }
+
+  async getDocument(collectionId, documentId) {
+    return this.request('GET', `/collections/${collectionId}/documents/${documentId}`);
+  }
+
+  async createDocument(collectionId, payload) {
+    return this.request('POST', `/collections/${collectionId}/documents`, payload);
+  }
+
+  async listDocuments(collectionId, options = {}) {
+    const params = new URLSearchParams(options).toString();
+    return this.request('GET', `/collections/${collectionId}/documents${params ? '?' + params : ''}`);
+  }
+}
+
+export function createClient(config) {
+  return new MixpeekClient(config);
+}
+
+export { MixpeekClient };
+export default { createClient, MixpeekClient };

package/dist/cache/cacheManager.js

@@ -0,0 +1,90 @@
+/**
+ * @mixpeek/contentful — Cache Manager
+ *
+ * In-memory LRU caching with TTL support.
+ */
+
+import { DEFAULT_CACHE_TTL, MAX_CACHE_ITEMS, CACHE_KEY_PREFIX } from '../config/constants.js';
+import { getLogger } from '../utils/logger.js';
+
+class CacheManager {
+  constructor(options = {}) {
+    this.ttl = (options.ttl || DEFAULT_CACHE_TTL) * 1000;
+    this.maxItems = options.maxItems || MAX_CACHE_ITEMS;
+    this.cache = new Map();
+    this.stats = { hits: 0, misses: 0, sets: 0, evictions: 0 };
+    this.logger = getLogger({ debug: options.debug });
+    this.cleanupInterval = setInterval(() => this.prune(), 60000);
+    if (this.cleanupInterval.unref) this.cleanupInterval.unref();
+  }
+
+  _prefixKey(key) { return `${CACHE_KEY_PREFIX}${key}`; }
+
+  get(key) {
+    const item = this.cache.get(this._prefixKey(key));
+    if (!item) { this.stats.misses++; return null; }
+    if (Date.now() > item.expiry) { this.cache.delete(this._prefixKey(key)); this.stats.misses++; return null; }
+    this.stats.hits++;
+    item.lastAccess = Date.now();
+    return item.data;
+  }
+
+  set(key, data, ttl = null) {
+    if (this.cache.size >= this.maxItems) this._evictLRU();
+    this.cache.set(this._prefixKey(key), {
+      data, expiry: Date.now() + (ttl ? ttl * 1000 : this.ttl),
+      createdAt: Date.now(), lastAccess: Date.now()
+    });
+    this.stats.sets++;
+  }
+
+  has(key) {
+    const item = this.cache.get(this._prefixKey(key));
+    if (!item) return false;
+    if (Date.now() > item.expiry) { this.cache.delete(this._prefixKey(key)); return false; }
+    return true;
+  }
+
+  delete(key) { return this.cache.delete(this._prefixKey(key)); }
+  clear() { this.cache.clear(); }
+
+  prune() {
+    const now = Date.now();
+    let pruned = 0;
+    for (const [key, item] of this.cache.entries()) {
+      if (now > item.expiry) { this.cache.delete(key); pruned++; }
+    }
+    return pruned;
+  }
+
+  _evictLRU() {
+    let oldestKey = null, oldestAccess = Infinity;
+    for (const [key, item] of this.cache.entries()) {
+      if (item.lastAccess < oldestAccess) { oldestAccess = item.lastAccess; oldestKey = key; }
+    }
+    if (oldestKey) { this.cache.delete(oldestKey); this.stats.evictions++; }
+  }
+
+  getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    return {
+      size: this.cache.size, maxSize: this.maxItems,
+      hits: this.stats.hits, misses: this.stats.misses,
+      hitRate: total > 0 ? Math.round((this.stats.hits / total) * 10000) / 100 : 0,
+      sets: this.stats.sets, evictions: this.stats.evictions, ttlSeconds: this.ttl / 1000
+    };
+  }
+
+  resetStats() { this.stats = { hits: 0, misses: 0, sets: 0, evictions: 0 }; }
+
+  destroy() {
+    if (this.cleanupInterval) { clearInterval(this.cleanupInterval); this.cleanupInterval = null; }
+    this.cache.clear();
+  }
+
+  get size() { return this.cache.size; }
+}
+
+export function createCacheManager(options = {}) { return new CacheManager(options); }
+export { CacheManager };
+export default { createCacheManager, CacheManager };

package/dist/config/constants.js

@@ -0,0 +1,48 @@
+/**
+ * @mixpeek/contentful — Configuration Constants
+ */
+
+// API Configuration
+export const API_ENDPOINT = 'https://api.mixpeek.com';
+export const API_VERSION = 'v1';
+export const DEFAULT_TIMEOUT = 30000; // milliseconds
+export const MAX_TIMEOUT = 60000;
+export const RETRY_ATTEMPTS = 1;
+export const RETRY_DELAY = 100; // milliseconds
+
+// Cache Configuration
+export const DEFAULT_CACHE_TTL = 300; // seconds (5 minutes)
+export const MAX_CACHE_ITEMS = 1000;
+export const CACHE_KEY_PREFIX = 'mixpeek_ctfl_';
+
+// Error Codes
+export const ERROR_CODES = {
+  API_ERROR: 'MIXPEEK_API_ERROR',
+  TIMEOUT: 'MIXPEEK_TIMEOUT',
+  INVALID_CONFIG: 'MIXPEEK_INVALID_CONFIG',
+  INVALID_REQUEST: 'MIXPEEK_INVALID_REQUEST',
+  RATE_LIMITED: 'MIXPEEK_RATE_LIMITED',
+  CACHE_ERROR: 'MIXPEEK_CACHE_ERROR'
+};
+
+// HTTP Headers
+export const HEADERS = {
+  CONTENT_TYPE: 'application/json',
+  ACCEPT: 'application/json',
+  USER_AGENT: 'Mixpeek-Contentful-Connector/1.0.0'
+};
+
+// Default Configuration
+export const DEFAULT_CONFIG = {
+  endpoint: API_ENDPOINT,
+  timeout: DEFAULT_TIMEOUT,
+  cacheTTL: DEFAULT_CACHE_TTL,
+  enableCache: true,
+  debug: false
+};
+
+export default {
+  API_ENDPOINT, API_VERSION, DEFAULT_TIMEOUT, MAX_TIMEOUT,
+  RETRY_ATTEMPTS, RETRY_DELAY, DEFAULT_CACHE_TTL, MAX_CACHE_ITEMS,
+  CACHE_KEY_PREFIX, ERROR_CODES, HEADERS, DEFAULT_CONFIG
+};

package/dist/index.cjs

@@ -0,0 +1,8 @@
+'use strict';
+let modulePromise = null;
+function getModule() { if (!modulePromise) modulePromise = import('./index.js'); return modulePromise; }
+module.exports = {
+  async createWebhookHandler(config) { const mod = await getModule(); return new mod.WebhookHandler(config); },
+  getModule,
+  version: '1.0.0'
+};

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @mixpeek/contentful — TypeScript declarations
+ */
+
+export interface ConnectorConfig {
+  apiKey: string;
+  endpoint?: string;
+  timeout?: number;
+  cacheTTL?: number;
+  enableCache?: boolean;
+  debug?: boolean;
+}
+
+export interface MetricsResult {
+  requests: number;
+  errors: number;
+  totalLatencyMs: number;
+  avgLatencyMs: number;
+  cache: { size: number; hits: number; misses: number; hitRate: number } | null;
+}
+
+export declare class WebhookHandler {
+  constructor(config: ConnectorConfig);
+  handleWebhook(...args: any[]): any;
+  verifySignature(...args: any[]): any;
+  registerWebhook(...args: any[]): any;
+  listWebhooks(...args: any[]): any;
+  deleteWebhook(...args: any[]): any;
+  getMetrics(): MetricsResult;
+  resetMetrics(): void;
+  destroy(): void;
+}
+
+export declare class ContentEnricher {
+  constructor(config: ConnectorConfig);
+  enrichEntry(...args: any[]): any;
+  enrichAsset(...args: any[]): any;
+  enrichBatch(...args: any[]): any;
+  getEnrichment(...args: any[]): any;
+  writeField(...args: any[]): any;
+  getMetrics(): MetricsResult;
+  resetMetrics(): void;
+  destroy(): void;
+}
+
+export declare class ContentfulClient {
+  constructor(config: ConnectorConfig);
+  getEntry(...args: any[]): any;
+  getEntries(...args: any[]): any;
+  updateEntry(...args: any[]): any;
+  getAsset(...args: any[]): any;
+  publishEntry(...args: any[]): any;
+  getMetrics(): MetricsResult;
+  resetMetrics(): void;
+  destroy(): void;
+}
+
+export declare function createWebhookHandler(config: ConnectorConfig): WebhookHandler;
+export declare function createContentEnricher(config: ConnectorConfig): ContentEnricher;
+export declare function createContentfulClient(config: ConnectorConfig): ContentfulClient;
+
+export declare class MixpeekClient {
+  constructor(config: ConnectorConfig);
+  request(method: string, path: string, body?: any): Promise<any>;
+  healthCheck(): Promise<{ status: string; latency?: number; error?: string }>;
+  search(query: any, options?: any): Promise<any>;
+}
+
+export declare class CacheManager {
+  constructor(options?: { ttl?: number; maxItems?: number; debug?: boolean });
+  get(key: string): any | null;
+  set(key: string, value: any, ttl?: number): void;
+  has(key: string): boolean;
+  delete(key: string): boolean;
+  clear(): void;
+  getStats(): { size: number; hits: number; misses: number; hitRate: number };
+  destroy(): void;
+}
+
+export declare function createClient(config: ConnectorConfig): MixpeekClient;
+export declare function createCacheManager(options?: any): CacheManager;

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * @mixpeek/contentful — Mixpeek Contentful Connector
+ *
+ * Contentful integration for Mixpeek — webhook handling, content enrichment, and management API integration
+ *
+ * @module @mixpeek/contentful
+ * @version 1.0.0
+ */
+
+// Modules
+export { createWebhookHandler, WebhookHandler } from './modules/webhookHandler.js';
+export { createContentEnricher, ContentEnricher } from './modules/contentEnricher.js';
+export { createContentfulClient, ContentfulClient } from './modules/contentfulClient.js';
+
+// API client
+export { createClient, MixpeekClient } from './api/mixpeekClient.js';
+
+// Cache manager
+export { createCacheManager, CacheManager } from './cache/cacheManager.js';
+
+// Utilities
+export {
+  generateId,
+  createCacheKey,
+  sanitizeText,
+  deepMerge,
+  isValidUrl,
+  extractDomain
+} from './utils/helpers.js';
+
+// Logger
+export { getLogger, createLogger, Logger, LOG_LEVELS } from './utils/logger.js';
+
+// Constants
+export {
+  API_ENDPOINT,
+  API_VERSION,
+  DEFAULT_TIMEOUT,
+  DEFAULT_CACHE_TTL,
+  ERROR_CODES,
+  DEFAULT_CONFIG
+} from './config/constants.js';
+
+// Default export
+import { createWebhookHandler } from './modules/webhookHandler.js';
+export default createWebhookHandler;

package/dist/modules/contentEnricher.js

@@ -0,0 +1,92 @@
+/**
+ * @mixpeek/contentful — ContentEnricher
+ *
+ * Enriches Contentful entries with Mixpeek multimodal analysis stored in custom fields
+ */
+
+import { createClient } from '../api/mixpeekClient.js';
+import { createCacheManager } from '../cache/cacheManager.js';
+import { getLogger } from '../utils/logger.js';
+import { DEFAULT_CONFIG } from '../config/constants.js';
+
+class ContentEnricher {
+  /**
+   * @param {Object} config
+   * @param {string} config.apiKey - Mixpeek API key
+   * @param {string} [config.endpoint] - API endpoint
+   * @param {number} [config.timeout] - Request timeout in ms
+   * @param {number} [config.cacheTTL] - Cache TTL in seconds
+   * @param {boolean} [config.enableCache] - Enable caching
+   * @param {boolean} [config.debug] - Enable debug logging
+   */
+  constructor(config = {}) {
+    if (!config.apiKey) throw new Error('apiKey is required for ContentEnricher');
+
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.client = createClient({
+      apiKey: config.apiKey,
+      endpoint: this.config.endpoint,
+      timeout: this.config.timeout,
+      debug: this.config.debug
+    });
+    this.cache = this.config.enableCache ? createCacheManager({ ttl: this.config.cacheTTL, debug: this.config.debug }) : null;
+    this.logger = getLogger({ debug: this.config.debug });
+    this.metrics = { requests: 0, errors: 0, totalLatencyMs: 0 };
+    this.logger.info('ContentEnricher initialized');
+  }
+
+  async enrichEntry(...args) {
+    this.logger.debug('ContentEnricher.enrichEntry called');
+    // TODO: Implement enrichEntry
+    throw new Error('ContentEnricher.enrichEntry not yet implemented');
+  }
+
+  async enrichAsset(...args) {
+    this.logger.debug('ContentEnricher.enrichAsset called');
+    // TODO: Implement enrichAsset
+    throw new Error('ContentEnricher.enrichAsset not yet implemented');
+  }
+
+  async enrichBatch(...args) {
+    this.logger.debug('ContentEnricher.enrichBatch called');
+    // TODO: Implement enrichBatch
+    throw new Error('ContentEnricher.enrichBatch not yet implemented');
+  }
+
+  async getEnrichment(...args) {
+    this.logger.debug('ContentEnricher.getEnrichment called');
+    // TODO: Implement getEnrichment
+    throw new Error('ContentEnricher.getEnrichment not yet implemented');
+  }
+
+  async writeField(...args) {
+    this.logger.debug('ContentEnricher.writeField called');
+    // TODO: Implement writeField
+    throw new Error('ContentEnricher.writeField not yet implemented');
+  }
+
+  getMetrics() {
+    return {
+      ...this.metrics,
+      avgLatencyMs: this.metrics.requests > 0 ? this.metrics.totalLatencyMs / this.metrics.requests : 0,
+      cache: this.cache ? this.cache.getStats() : null
+    };
+  }
+
+  resetMetrics() {
+    this.metrics = { requests: 0, errors: 0, totalLatencyMs: 0 };
+    if (this.cache) this.cache.resetStats();
+  }
+
+  destroy() {
+    if (this.cache) this.cache.destroy();
+    this.logger.info('ContentEnricher destroyed');
+  }
+}
+
+export function createContentEnricher(config) {
+  return new ContentEnricher(config);
+}
+
+export { ContentEnricher };
+export default { createContentEnricher, ContentEnricher };

package/dist/modules/contentfulClient.js

@@ -0,0 +1,92 @@
+/**
+ * @mixpeek/contentful — ContentfulClient
+ *
+ * Contentful Management API client for reading/writing enrichment data
+ */
+
+import { createClient } from '../api/mixpeekClient.js';
+import { createCacheManager } from '../cache/cacheManager.js';
+import { getLogger } from '../utils/logger.js';
+import { DEFAULT_CONFIG } from '../config/constants.js';
+
+class ContentfulClient {
+  /**
+   * @param {Object} config
+   * @param {string} config.apiKey - Mixpeek API key
+   * @param {string} [config.endpoint] - API endpoint
+   * @param {number} [config.timeout] - Request timeout in ms
+   * @param {number} [config.cacheTTL] - Cache TTL in seconds
+   * @param {boolean} [config.enableCache] - Enable caching
+   * @param {boolean} [config.debug] - Enable debug logging
+   */
+  constructor(config = {}) {
+    if (!config.apiKey) throw new Error('apiKey is required for ContentfulClient');
+
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.client = createClient({
+      apiKey: config.apiKey,
+      endpoint: this.config.endpoint,
+      timeout: this.config.timeout,
+      debug: this.config.debug
+    });
+    this.cache = this.config.enableCache ? createCacheManager({ ttl: this.config.cacheTTL, debug: this.config.debug }) : null;
+    this.logger = getLogger({ debug: this.config.debug });
+    this.metrics = { requests: 0, errors: 0, totalLatencyMs: 0 };
+    this.logger.info('ContentfulClient initialized');
+  }
+
+  async getEntry(...args) {
+    this.logger.debug('ContentfulClient.getEntry called');
+    // TODO: Implement getEntry
+    throw new Error('ContentfulClient.getEntry not yet implemented');
+  }
+
+  async getEntries(...args) {
+    this.logger.debug('ContentfulClient.getEntries called');
+    // TODO: Implement getEntries
+    throw new Error('ContentfulClient.getEntries not yet implemented');
+  }
+
+  async updateEntry(...args) {
+    this.logger.debug('ContentfulClient.updateEntry called');
+    // TODO: Implement updateEntry
+    throw new Error('ContentfulClient.updateEntry not yet implemented');
+  }
+
+  async getAsset(...args) {
+    this.logger.debug('ContentfulClient.getAsset called');
+    // TODO: Implement getAsset
+    throw new Error('ContentfulClient.getAsset not yet implemented');
+  }
+
+  async publishEntry(...args) {
+    this.logger.debug('ContentfulClient.publishEntry called');
+    // TODO: Implement publishEntry
+    throw new Error('ContentfulClient.publishEntry not yet implemented');
+  }
+
+  getMetrics() {
+    return {
+      ...this.metrics,
+      avgLatencyMs: this.metrics.requests > 0 ? this.metrics.totalLatencyMs / this.metrics.requests : 0,
+      cache: this.cache ? this.cache.getStats() : null
+    };
+  }
+
+  resetMetrics() {
+    this.metrics = { requests: 0, errors: 0, totalLatencyMs: 0 };
+    if (this.cache) this.cache.resetStats();
+  }
+
+  destroy() {
+    if (this.cache) this.cache.destroy();
+    this.logger.info('ContentfulClient destroyed');
+  }
+}
+
+export function createContentfulClient(config) {
+  return new ContentfulClient(config);
+}
+
+export { ContentfulClient };
+export default { createContentfulClient, ContentfulClient };