procedere-mq-sdk 0.2.0

package/README.md

@@ -0,0 +1,106 @@
+# procedere-mq-sdk
+
+SDK oficial em Node.js para consumir a API HTTP do ProcedereMQ.
+
+## Requisitos
+
+- Node.js 18 ou superior
+
+## Instalacao
+
+```bash
+npm install procedere-mq-sdk
+```
+
+## Uso
+
+### Producer
+
+```js
+const { LiteMQClient } = require("procedere-mq-sdk");
+
+async function main() {
+  const client = new LiteMQClient("http://127.0.0.1:65090");
+  const producer = client.producer("emails");
+
+  const job = await producer.publish(
+    { to: "alice@example.com", template: "welcome" },
+    { maxRetry: 3 }
+  );
+
+  console.log("job criado:", job.id);
+}
+
+main().catch(console.error);
+```
+
+### Consumer
+
+```js
+const { LiteMQClient, QueueEmptyError } = require("procedere-mq-sdk");
+
+async function main() {
+  const client = new LiteMQClient("http://127.0.0.1:65090");
+  const consumer = client.consumer("emails");
+
+  try {
+    const job = await consumer.receive();
+    await consumer.ack(job);
+  } catch (error) {
+    if (error instanceof QueueEmptyError) {
+      return;
+    }
+    throw error;
+  }
+}
+
+main().catch(console.error);
+```
+
+## API
+
+### `new LiteMQClient(baseUrl, options?)`
+
+- `baseUrl`: endereco HTTP do ProcedereMQ
+- `options.timeout`: timeout em milissegundos
+- `options.fetchImpl`: implementacao customizada de `fetch`
+
+### `client.producer(queue)`
+
+- Retorna um `Producer` vinculado a uma fila
+
+### `client.consumer(queue)`
+
+- Retorna um `Consumer` vinculado a uma fila
+
+### `producer.publish(payload?, options?)`
+
+- `options.jobId`: id customizado do job
+- `options.maxRetry`: quantidade maxima de retries
+- `options.runAt`: `Date`, string ISO ou timestamp
+
+### `consumer.receive()`
+
+- Faz `dequeue` da fila configurada
+
+### `consumer.ack(jobOrId)`
+
+- Confirma um job por objeto ou id
+
+### `consumer.fail(jobOrId)`
+
+- Marca falha de um job por objeto ou id
+
+## Erros
+
+- `LiteMQError`
+- `QueueEmptyError`
+- `NotFoundError`
+
+## Publicacao
+
+```bash
+npm test
+npm pack --dry-run
+npm publish --access public
+```

package/index.d.ts

@@ -0,0 +1,62 @@
+export class LiteMQError extends Error {}
+
+export class QueueEmptyError extends LiteMQError {}
+
+export class NotFoundError extends LiteMQError {}
+
+export interface LiteMQClientOptions {
+  timeout?: number;
+  fetchImpl?: typeof fetch;
+}
+
+export interface PublishOptions {
+  jobId?: string;
+  maxRetry?: number;
+  runAt?: Date | string | number;
+}
+
+export interface JobRecord {
+  id?: string;
+  queue?: string;
+  payload?: unknown;
+  status?: string;
+  last_error?: string;
+  attempts?: number;
+  max_retry?: number;
+  run_at?: string;
+  locked_at?: string;
+  created_at?: string;
+  [key: string]: unknown;
+}
+
+export class Producer {
+  constructor(client: LiteMQClient, queue: string);
+  client: LiteMQClient;
+  queue: string;
+  publish(payload?: unknown, options?: PublishOptions): Promise<Record<string, unknown>>;
+}
+
+export class Consumer {
+  constructor(client: LiteMQClient, queue: string);
+  client: LiteMQClient;
+  queue: string;
+  receive(): Promise<Record<string, unknown>>;
+  ack(jobOrId: string | JobRecord): Promise<Record<string, unknown>>;
+  fail(jobOrId: string | JobRecord): Promise<Record<string, unknown>>;
+}
+
+export class LiteMQClient {
+  constructor(baseUrl: string, options?: LiteMQClientOptions);
+  baseUrl: string;
+  timeout: number;
+  producer(queue: string): Producer;
+  consumer(queue: string): Consumer;
+  enqueue(
+    queue: string,
+    payload?: unknown,
+    options?: PublishOptions
+  ): Promise<Record<string, unknown>>;
+  dequeue(queue: string): Promise<Record<string, unknown>>;
+  ack(jobId: string): Promise<Record<string, unknown>>;
+  fail(jobId: string): Promise<Record<string, unknown>>;
+}

package/index.js

@@ -0,0 +1,229 @@
+"use strict";
+
+class LiteMQError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LiteMQError";
+  }
+}
+
+class QueueEmptyError extends LiteMQError {
+  constructor(message = "queue empty") {
+    super(message);
+    this.name = "QueueEmptyError";
+  }
+}
+
+class NotFoundError extends LiteMQError {
+  constructor(message = "not found") {
+    super(message);
+    this.name = "NotFoundError";
+  }
+}
+
+class Producer {
+  constructor(client, queue) {
+    this.client = client;
+    this.queue = normalizeRequiredString(queue, "queue");
+  }
+
+  async publish(payload = null, options = {}) {
+    const { jobId, maxRetry, runAt } = options;
+    return this.client.enqueue(this.queue, payload, {
+      jobId,
+      maxRetry,
+      runAt,
+    });
+  }
+}
+
+class Consumer {
+  constructor(client, queue) {
+    this.client = client;
+    this.queue = normalizeRequiredString(queue, "queue");
+  }
+
+  async receive() {
+    return this.client.dequeue(this.queue);
+  }
+
+  async ack(jobOrId) {
+    return this.client.ack(extractJobId(jobOrId));
+  }
+
+  async fail(jobOrId) {
+    return this.client.fail(extractJobId(jobOrId));
+  }
+}
+
+class LiteMQClient {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.timeout = options.timeout ?? 10000;
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+    if (typeof this.fetchImpl !== "function") {
+      throw new LiteMQError("fetch API is not available in this runtime");
+    }
+  }
+
+  producer(queue) {
+    return new Producer(this, queue);
+  }
+
+  consumer(queue) {
+    return new Consumer(this, queue);
+  }
+
+  async enqueue(queue, payload = null, options = {}) {
+    const normalizedQueue = normalizeRequiredString(queue, "queue");
+    const body = { queue: normalizedQueue };
+
+    if (payload !== null) {
+      body.payload = payload;
+    }
+    if (isNonEmptyString(options.jobId)) {
+      body.id = options.jobId.trim();
+    }
+    if (options.maxRetry !== undefined) {
+      body.max_retry = options.maxRetry;
+    }
+    if (options.runAt !== undefined && options.runAt !== null) {
+      body.run_at = formatDateTime(options.runAt);
+    }
+
+    return this._request("POST", "/enqueue", 201, { body });
+  }
+
+  async dequeue(queue) {
+    const normalizedQueue = normalizeRequiredString(queue, "queue");
+    const params = new URLSearchParams({ queue: normalizedQueue });
+    return this._request("GET", `/dequeue?${params.toString()}`, 200);
+  }
+
+  async ack(jobId) {
+    const normalizedJobId = normalizeRequiredString(jobId, "job_id");
+    return this._request("POST", "/ack", 200, {
+      body: { id: normalizedJobId },
+    });
+  }
+
+  async fail(jobId) {
+    const normalizedJobId = normalizeRequiredString(jobId, "job_id");
+    return this._request("POST", "/fail", 200, {
+      body: { id: normalizedJobId },
+    });
+  }
+
+  async _request(method, path, expectedStatus, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const init = {
+      method,
+      signal: controller.signal,
+      headers: {},
+    };
+
+    if (options.body !== undefined) {
+      init.headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(options.body);
+    }
+
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+    } catch (error) {
+      if (error && error.name === "AbortError") {
+        throw new LiteMQError(`request timed out after ${this.timeout}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    if (response.status === 204) {
+      throw new QueueEmptyError("queue empty");
+    }
+    if (response.status === 404) {
+      throw new NotFoundError(await extractError(response));
+    }
+    if (response.status !== expectedStatus) {
+      throw new LiteMQError(await extractError(response));
+    }
+
+    const text = await response.text();
+    if (!text) {
+      return {};
+    }
+
+    const data = JSON.parse(text);
+    if (isPlainObject(data)) {
+      return data;
+    }
+    return { data };
+  }
+}
+
+async function extractError(response) {
+  const text = await response.text();
+  if (!text) {
+    return response.statusText || `HTTP ${response.status}`;
+  }
+
+  try {
+    const payload = JSON.parse(text);
+    if (isPlainObject(payload) && isNonEmptyString(payload.error)) {
+      return payload.error.trim();
+    }
+  } catch (_) {
+    return text;
+  }
+
+  return text;
+}
+
+function normalizeBaseUrl(baseUrl) {
+  return normalizeRequiredString(baseUrl, "base_url").replace(/\/+$/, "");
+}
+
+function normalizeRequiredString(value, fieldName) {
+  if (!isNonEmptyString(value)) {
+    throw new TypeError(`${fieldName} is required`);
+  }
+  return value.trim();
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function formatDateTime(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError("runAt must be a valid Date");
+  }
+  return date.toISOString();
+}
+
+function extractJobId(jobOrId) {
+  if (isNonEmptyString(jobOrId)) {
+    return jobOrId.trim();
+  }
+  if (isPlainObject(jobOrId) && isNonEmptyString(jobOrId.id)) {
+    return jobOrId.id.trim();
+  }
+  throw new TypeError("job id is required");
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+module.exports = {
+  Consumer,
+  LiteMQClient,
+  LiteMQError,
+  NotFoundError,
+  Producer,
+  QueueEmptyError,
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "procedere-mq-sdk",
+  "version": "0.2.0",
+  "description": "Node.js SDK para ProcedereMQ",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "queue",
+    "mq",
+    "sdk",
+    "nodejs",
+    "procedere"
+  ],
+  "author": "Jefferson Tadeu Leite",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeffersontadeuleite/procedereMQ.git",
+    "directory": "node_sdk"
+  },
+  "homepage": "https://github.com/jeffersontadeuleite/procedereMQ",
+  "bugs": {
+    "url": "https://github.com/jeffersontadeuleite/procedereMQ/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}