s3db.js 13.6.0 → 14.0.2

package/src/plugins/concerns/resource-names.js

@@ -0,0 +1,100 @@
+import { PluginError } from '../../errors.js';
+
+const PREFIX = 'plg_';
+
+function normalizeNamespace(namespace) {
+  if (!namespace) return null;
+  const text = String(namespace).trim().toLowerCase();
+  if (!text) return null;
+  const normalized = text
+    .replace(/[^a-z0-9]+/g, '-')  // Use hyphens instead of underscores
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  return normalized || null;
+}
+
+function applyNamespace(name, namespace) {
+  const ensured = ensurePlgPrefix(name);
+  if (!namespace) {
+    return ensured;
+  }
+
+  const withoutPrefix = ensured.slice(PREFIX.length);
+  if (withoutPrefix.startsWith(`${namespace}_`)) {
+    return ensured;
+  }
+
+  return `${PREFIX}${namespace}_${withoutPrefix}`;
+}
+
+function sanitizeName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new PluginError('[resource-names] Resource name must be a non-empty string', {
+      pluginName: 'SharedConcerns',
+      operation: 'resourceNames:sanitize',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Pass a non-empty string when deriving resource names.'
+    });
+  }
+  return name.trim();
+}
+
+export function ensurePlgPrefix(name) {
+  const sanitized = sanitizeName(name);
+  if (sanitized.startsWith(PREFIX)) {
+    return sanitized;
+  }
+  return `${PREFIX}${sanitized.replace(/^\_+/, '')}`;
+}
+
+export function resolveResourceName(pluginKey, { defaultName, override, suffix } = {}, options = {}) {
+  const namespace = normalizeNamespace(options.namespace);
+  const applyOverrideNamespace = options.applyNamespaceToOverrides === true;
+
+  if (!defaultName && !override && !suffix) {
+    throw new PluginError(`[resource-names] Missing name parameters for plugin "${pluginKey}"`, {
+      pluginName: 'SharedConcerns',
+      operation: 'resourceNames:resolve',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide at least one of defaultName, override, or suffix when resolving resource names.'
+    });
+  }
+
+  if (override) {
+    const ensured = ensurePlgPrefix(override);
+    return applyOverrideNamespace ? applyNamespace(ensured, namespace) : ensured;
+  }
+
+  if (defaultName) {
+    const ensured = defaultName.startsWith(PREFIX) ? defaultName : ensurePlgPrefix(defaultName);
+    return applyNamespace(ensured, namespace);
+  }
+
+  if (!suffix) {
+    throw new PluginError(`[resource-names] Cannot derive resource name for plugin "${pluginKey}" without suffix`, {
+      pluginName: 'SharedConcerns',
+      operation: 'resourceNames:resolve',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Provide a suffix or defaultName when computing derived resource names.'
+    });
+  }
+
+  const ensured = ensurePlgPrefix(`${pluginKey}_${suffix}`);
+  return applyNamespace(ensured, namespace);
+}
+
+export function resolveResourceNames(pluginKey, descriptors = {}, options = {}) {
+  const result = {};
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (typeof descriptor === 'string') {
+      result[key] = resolveResourceName(pluginKey, { defaultName: descriptor }, options);
+      continue;
+    }
+
+    result[key] = resolveResourceName(pluginKey, descriptor, options);
+  }
+  return result;
+}

package/src/plugins/consumers/index.js

@@ -1,5 +1,6 @@
 import { SqsConsumer } from './sqs-consumer.js';
 import { RabbitMqConsumer } from './rabbitmq-consumer.js';
+import { PluginError } from '../../errors.js';
 
 export { SqsConsumer, RabbitMqConsumer };
 
@@ -18,7 +19,14 @@ export const CONSUMER_DRIVERS = {
 export function createConsumer(driver, config) {
   const ConsumerClass = CONSUMER_DRIVERS[driver];
   if (!ConsumerClass) {
-    throw new Error(`Unknown consumer driver: ${driver}. Available: ${Object.keys(CONSUMER_DRIVERS).join(', ')}`);
+    throw new PluginError(`Unknown consumer driver: ${driver}`, {
+      pluginName: 'ConsumersPlugin',
+      operation: 'createConsumer',
+      statusCode: 400,
+      retriable: false,
+      suggestion: `Use one of the available drivers: ${Object.keys(CONSUMER_DRIVERS).join(', ')}`,
+      driver
+    });
   }
   return new ConsumerClass(config);
-} 
+} 

package/src/plugins/consumers/sqs-consumer.js

@@ -1,5 +1,6 @@
 import tryFn from "../../concerns/try-fn.js";
 import requirePluginDependency from "../concerns/plugin-dependencies.js";
+import { PluginError } from '../../errors.js';
 // Remove static SDK import
 // import { SQSClient, ReceiveMessageCommand, DeleteMessageCommand } from '@aws-sdk/client-sqs';
 
@@ -31,7 +32,16 @@ export class SqsConsumer {
 
     // Carregar SDK dinamicamente
     const [ok, err, sdk] = await tryFn(() => import('@aws-sdk/client-sqs'));
-    if (!ok) throw new Error('SqsConsumer: @aws-sdk/client-sqs is not installed. Please install it to use the SQS consumer.');
+    if (!ok) {
+      throw new PluginError('SqsConsumer requires @aws-sdk/client-sqs', {
+        pluginName: 'ConsumersPlugin',
+        operation: 'SqsConsumer.start',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Install @aws-sdk/client-sqs as a dependency to enable SQS consumption.',
+        original: err
+      });
+    }
     const { SQSClient, ReceiveMessageCommand, DeleteMessageCommand } = sdk;
     this._SQSClient = SQSClient;
     this._ReceiveMessageCommand = ReceiveMessageCommand;
@@ -103,4 +113,4 @@ export class SqsConsumer {
     }
     return { $body: body, $attributes: attributes, $raw: msg };
   }
-} 
+} 

package/src/plugins/cookie-farm-suite.plugin.js

@@ -0,0 +1,278 @@
+import tryFn from "../concerns/try-fn.js";
+import { Plugin } from "./plugin.class.js";
+import { PuppeteerPlugin } from "./puppeteer.plugin.js";
+import { CookieFarmPlugin } from "./cookie-farm.plugin.js";
+import { S3QueuePlugin } from "./s3-queue.plugin.js";
+import { TTLPlugin } from "./ttl.plugin.js";
+import { PluginError } from "../errors.js";
+
+function sanitizeNamespace(value) {
+  return (value || 'persona')
+    .toString()
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-');
+}
+
+function defaultJobsResource(namespace) {
+  return `${namespace.replace(/[^a-z0-9]+/g, '_')}_persona_jobs`;
+}
+
+/**
+ * CookieFarmSuitePlugin
+ *
+ * Bundles CookieFarm + Puppeteer + S3Queue (+ optional TTL) with shared
+ * namespace handling for persona farming workloads.
+ */
+export class CookieFarmSuitePlugin extends Plugin {
+  constructor(options = {}) {
+    const namespace = options.namespace || 'persona';
+    super({ ...options, namespace });
+
+    this.namespace = this.namespace || sanitizeNamespace(namespace);
+
+    const jobsResource =
+      options.jobsResource ||
+      (options.resources && options.resources.jobs) ||
+      defaultJobsResource(this.namespace);
+
+    this.config = {
+      namespace: this.namespace,
+      jobsResource,
+      queue: {
+        resource: jobsResource,
+        deadLetterResource: options.queue?.deadLetterResource || null,
+        visibilityTimeout: options.queue?.visibilityTimeout || 30000,
+        pollInterval: options.queue?.pollInterval || 1000,
+        maxAttempts: options.queue?.maxAttempts || 3,
+        concurrency: options.queue?.concurrency || 1,
+        autoStart: options.queue?.autoStart === true,
+        ...options.queue
+      },
+      puppeteer: {
+        pool: { enabled: false },
+        ...options.puppeteer
+      },
+      cookieFarm: {
+        ...options.cookieFarm
+      },
+      ttl: options.ttl || null,
+      processor: typeof options.processor === 'function' ? options.processor : null
+    };
+
+    this.pluginFactories = {
+      puppeteer: options.pluginFactories?.puppeteer ||
+        ((pluginOptions) => new PuppeteerPlugin(pluginOptions)),
+      cookieFarm: options.pluginFactories?.cookieFarm ||
+        ((pluginOptions) => new CookieFarmPlugin(pluginOptions)),
+      queue: options.pluginFactories?.queue ||
+        ((queueOptions) => new S3QueuePlugin(queueOptions)),
+      ttl: options.pluginFactories?.ttl ||
+        ((ttlOptions) => new TTLPlugin(ttlOptions))
+    };
+
+    this.dependencies = [];
+    this.jobsResource = null;
+    this.puppeteerPlugin = null;
+    this.cookieFarmPlugin = null;
+    this.queuePlugin = null;
+    this.ttlPlugin = null;
+    this.processor = this.config.processor;
+
+    this.queueHandler = this.queueHandler.bind(this);
+  }
+
+  _dependencyName(alias) {
+    return `${this.namespace}-${alias}`.toLowerCase();
+  }
+
+  async _installDependency(alias, plugin) {
+    const name = this._dependencyName(alias);
+    const instance = await this.database.usePlugin(plugin, name);
+    this.dependencies.push({ name, instance });
+    return instance;
+  }
+
+  async _ensureJobsResource() {
+    if (this.database.resources?.[this.config.jobsResource]) {
+      this.jobsResource = this.database.resources[this.config.jobsResource];
+      return;
+    }
+
+    const [created, err, resource] = await tryFn(() => this.database.createResource({
+      name: this.config.jobsResource,
+      attributes: {
+        id: 'string|required',
+        jobType: 'string|required',
+        payload: 'json|optional',
+        priority: 'number|default:0',
+        requestedBy: 'string|optional',
+        metadata: 'json|optional',
+        createdAt: 'string|required'
+      },
+      behavior: 'body-overflow',
+      timestamps: true,
+      asyncPartitions: true,
+      partitions: {
+        byJobType: { fields: { jobType: 'string' } },
+        byPriority: { fields: { priority: 'number' } },
+        byDate: { fields: { createdAt: 'string|maxlength:10' } }
+      }
+    }));
+
+    if (!created) {
+      if (resource) {
+        this.jobsResource = resource;
+        return;
+      }
+      throw err;
+    }
+
+    this.jobsResource = this.database.resources[this.config.jobsResource];
+  }
+
+  async onInstall() {
+    await this._ensureJobsResource();
+
+    this.puppeteerPlugin = await this._installDependency('puppeteer',
+      this.pluginFactories.puppeteer({
+        namespace: this.namespace,
+        ...this.config.puppeteer
+      })
+    );
+
+    this.cookieFarmPlugin = await this._installDependency('cookie-farm',
+      this.pluginFactories.cookieFarm({
+        namespace: this.namespace,
+        ...this.config.cookieFarm
+      })
+    );
+
+    const queueOptions = {
+      namespace: this.namespace,
+      resource: this.config.queue.resource,
+      deadLetterResource: this.config.queue.deadLetterResource,
+      visibilityTimeout: this.config.queue.visibilityTimeout,
+      pollInterval: this.config.queue.pollInterval,
+      maxAttempts: this.config.queue.maxAttempts,
+      concurrency: this.config.queue.concurrency,
+      autoStart: this.config.queue.autoStart && typeof this.processor === 'function',
+      onMessage: this.queueHandler,
+      verbose: this.config.queue.verbose
+    };
+
+    this.queuePlugin = await this._installDependency('queue', this.pluginFactories.queue(queueOptions));
+
+    if (this.config.ttl) {
+      const ttlConfig = {
+        namespace: this.namespace,
+        ...this.config.ttl
+      };
+
+      ttlConfig.resources = ttlConfig.resources || {};
+
+      if (!ttlConfig.resources[this.queuePlugin.queueResourceName]) {
+        ttlConfig.resources[this.queuePlugin.queueResourceName] = {
+          ttl: ttlConfig.queue?.ttl || 7200,
+          onExpire: ttlConfig.queue?.onExpire || 'hard-delete',
+          field: ttlConfig.queue?.field || null
+        };
+      }
+
+      delete ttlConfig.queue;
+
+      this.ttlPlugin = await this._installDependency('ttl', this.pluginFactories.ttl(ttlConfig));
+    }
+
+    this.emit('cookieFarmSuite.installed', {
+      namespace: this.namespace,
+      jobsResource: this.config.jobsResource
+    });
+  }
+
+  async onStart() {
+    if (this.config.queue.autoStart && typeof this.processor === 'function') {
+      await this.startProcessing();
+    }
+  }
+
+  async onStop() {
+    await this.stopProcessing();
+  }
+
+  async onUninstall(options = {}) {
+    await this.onStop();
+
+    for (const dep of [...this.dependencies].reverse()) {
+      await this.database.uninstallPlugin(dep.name, { purgeData: options.purgeData === true });
+    }
+    this.dependencies = [];
+  }
+
+  /**
+   * Register a job processor.
+   */
+  async setProcessor(handler, { autoStart = true, concurrency } = {}) {
+    this.processor = handler;
+
+    if (autoStart && typeof handler === 'function') {
+      await this.startProcessing({ concurrency });
+    }
+  }
+
+  /**
+   * Enqueue a persona job.
+   */
+  async enqueueJob(data, options = {}) {
+    if (!this.jobsResource?.enqueue) {
+      throw new PluginError('[CookieFarmSuitePlugin] Queue helpers not initialized yet', {
+        pluginName: 'CookieFarmSuitePlugin',
+        operation: 'enqueueJob',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Call plugin.initialize() before enqueuing jobs so queue helpers are registered.'
+      });
+    }
+    return await this.jobsResource.enqueue({
+      createdAt: new Date().toISOString().slice(0, 10),
+      ...data
+    }, options);
+  }
+
+  async startProcessing(options = {}) {
+    if (!this.jobsResource?.startProcessing) return;
+    const concurrency = options.concurrency || this.config.queue.concurrency;
+    await this.jobsResource.startProcessing(this.queueHandler, { concurrency });
+  }
+
+  async stopProcessing() {
+    if (this.jobsResource?.stopProcessing) {
+      await this.jobsResource.stopProcessing();
+    }
+  }
+
+  async queueHandler(record, context) {
+    if (typeof this.processor !== 'function') {
+      throw new PluginError('[CookieFarmSuitePlugin] No processor registered. Call setProcessor(fn) first.', {
+        pluginName: 'CookieFarmSuitePlugin',
+        operation: 'queueHandler',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Register a processor via plugin.setProcessor(jobHandler) before starting the queue.'
+      });
+    }
+
+    const helpers = {
+      puppeteer: this.puppeteerPlugin,
+      cookieFarm: this.cookieFarmPlugin,
+      queue: this.queuePlugin,
+      enqueue: this.enqueueJob.bind(this),
+      resource: this.jobsResource,
+      plugin: this
+    };
+
+    return await this.processor(record, context, helpers);
+  }
+}
+
+export default CookieFarmSuitePlugin;

package/src/plugins/cookie-farm.errors.js

@@ -0,0 +1,73 @@
+import { PluginError } from '../errors.js';
+
+/**
+ * Custom errors for CookieFarmPlugin with actionable guidance.
+ */
+
+export class CookieFarmError extends PluginError {
+  constructor(message, details = {}) {
+    const merged = {
+      pluginName: details.pluginName || 'CookieFarmPlugin',
+      operation: details.operation || 'unknown',
+      statusCode: details.statusCode ?? 500,
+      retriable: details.retriable ?? false,
+      suggestion: details.suggestion ?? 'Check CookieFarmPlugin configuration and persona storage before retrying.',
+      ...details
+    };
+    super(message, merged);
+  }
+}
+
+export class PersonaNotFoundError extends CookieFarmError {
+  constructor(personaId, details = {}) {
+    super(`Persona not found: ${personaId}`, {
+      code: 'PERSONA_NOT_FOUND',
+      personaId,
+      statusCode: 404,
+      retriable: false,
+      suggestion: 'Ensure the persona exists or create it before running CookieFarm operations.',
+      docs: details.docs || 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/cookie-farm.md',
+      ...details
+    });
+    this.name = 'PersonaNotFoundError';
+  }
+}
+
+export class WarmupError extends CookieFarmError {
+  constructor(message, details = {}) {
+    super(message, {
+      code: 'WARMUP_ERROR',
+      statusCode: details.statusCode ?? 500,
+      retriable: details.retriable ?? true,
+      suggestion: details.suggestion ?? 'Inspect warmup logs and retry; ensure upstream services are reachable.',
+      ...details
+    });
+    this.name = 'WarmupError';
+  }
+}
+
+export class GenerationError extends CookieFarmError {
+  constructor(message, details = {}) {
+    super(message, {
+      code: 'GENERATION_ERROR',
+      statusCode: details.statusCode ?? 500,
+      retriable: details.retriable ?? false,
+      suggestion: details.suggestion ?? 'Review persona generation inputs and plugin configuration before retrying.',
+      ...details
+    });
+    this.name = 'GenerationError';
+  }
+}
+
+export class QualityCalculationError extends CookieFarmError {
+  constructor(message, details = {}) {
+    super(message, {
+      code: 'QUALITY_CALCULATION_ERROR',
+      statusCode: details.statusCode ?? 500,
+      retriable: details.retriable ?? false,
+      suggestion: details.suggestion ?? 'Verify quality metrics configuration and input scores.',
+      ...details
+    });
+    this.name = 'QualityCalculationError';
+  }
+}