@blamejs/core 0.4.1

package/lib/notify.js

@@ -0,0 +1,643 @@
+"use strict";
+/**
+ * b.notify — generic notification dispatcher.
+ *
+ * Composes existing primitives — retry/backoff (b.retry), per-call
+ * timeout (b.safeAsync.withTimeout), per-channel circuit breaker
+ * (b.retry.CircuitBreaker), span+counter wrapping
+ * (b.observability.tap), audit emission (b.audit.safeEmit),
+ * 5 W's actor context (b.requestHelpers.extractActorContext), URL
+ * validation (b.safeUrl.parse), HTTP I/O (b.httpClient.request), PII
+ * redaction (b.redact.redact). Notify never re-implements any of these
+ * — its job is to coordinate them around a transport abstraction.
+ *
+ *   var notify = b.notify.create({
+ *     channels: {
+ *       slack: b.notify.transports.httpJson({ url: process.env.SLACK_HOOK }),
+ *       sms:   operatorTwilioShim,
+ *       log:   b.notify.transports.log(),
+ *     },
+ *     audit: b.audit,
+ *   });
+ *
+ *   await notify.send({ channel: "slack", message: { text: "Hello" } });
+ *
+ * Transport contract:
+ *
+ *   {
+ *     name:    "slack",
+ *     send:    async function (message, sendOpts) {
+ *       // Returns { id?, status, attempts?, durationMs? }
+ *       // Throws on permanent failure. For transient failures, throw
+ *       // with err.statusCode in b.retry.RETRYABLE_HTTP_STATUS or
+ *       // err.code in b.retry.RETRYABLE_NET_ERRORS — retry classifies
+ *       // them automatically. Operators can also set err.transient =
+ *       // true for shapes outside that classification.
+ *     },
+ *   }
+ *
+ * What this primitive intentionally does NOT do (per scope):
+ *   - Ship vendor SDKs (Twilio / FCM / APNs / Slack-API): operator brings
+ *     transports; the framework provides the contract + httpJson +
+ *     log + test built-ins.
+ *   - Render templates / handle i18n: operator uses b.template + b.i18n.
+ *   - Track recipient preferences: operator app concern.
+ *   - Replace b.mail (SMTP/MIME stays its own primitive).
+ *   - Replace b.websocketChannels (different abstraction —
+ *     transient pub/sub, not retry-on-fail delivery).
+ */
+
+var lazyRequire = require("./lazy-require");
+var requestHelpers = require("./request-helpers");
+var safeAsync = require("./safe-async");
+var safeUrl = require("./safe-url");
+var validateOpts = require("./validate-opts");
+var C = require("./constants");
+var { NotifyError } = require("./framework-error");
+
+// Lazy-required modules to avoid load-order cycles. retry / observability /
+// redact / httpClient don't currently import notify, but treating them
+// the same way every primitive does keeps the load-order story uniform.
+var retryModule = lazyRequire(function () { return require("./retry"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+var redactModule = lazyRequire(function () { return require("./redact"); });
+var httpClientModule = lazyRequire(function () { return require("./http-client"); });
+
+var _err = NotifyError.factory;
+
+var DEFAULTS = Object.freeze({
+  auditSuccess:     true,
+  auditFailures:    true,
+  defaultTimeoutMs: C.TIME.seconds(30),
+  // defaultRetry inherits from b.retry.DEFAULT_RETRY at create time so
+  // we get the framework's policy without forking the constants.
+});
+
+// ---- Tier-A validation ----
+
+function _isFiniteNonNegative(n) {
+  return typeof n === "number" && isFinite(n) && n >= 0;
+}
+
+function _validateTransport(name, t) {
+  if (!t || typeof t !== "object") {
+    throw _err("BAD_OPT", "notify: transport for channel '" + name +
+      "' must be an object with a send() function");
+  }
+  if (typeof t.send !== "function") {
+    throw _err("BAD_OPT", "notify: transport for channel '" + name +
+      "' is missing required send() function");
+  }
+}
+
+function _validateChannelEntry(name, entry) {
+  if (typeof entry !== "object" || entry === null) {
+    throw _err("BAD_OPT", "notify: channel '" + name + "' must map to a transport or { transport, ... } object");
+  }
+  // Two accepted shapes:
+  //   - Transport object directly: { name, send }
+  //   - Channel-config object:     { transport, retry?, breaker?, timeoutMs?, serialize? }
+  if (typeof entry.send === "function") {
+    return { transport: entry, retry: null, breaker: null, timeoutMs: null, serialize: false };
+  }
+  if (entry.transport === undefined) {
+    throw _err("BAD_OPT", "notify: channel '" + name +
+      "': must be a transport (with send fn) OR an object with .transport");
+  }
+  _validateTransport(name, entry.transport);
+  if (entry.retry !== undefined && (typeof entry.retry !== "object" || entry.retry === null)) {
+    throw _err("BAD_OPT", "notify: channel '" + name + "' retry must be a b.retry.withRetry opts object");
+  }
+  if (entry.breaker !== undefined && entry.breaker !== null && typeof entry.breaker !== "object") {
+    throw _err("BAD_OPT", "notify: channel '" + name + "' breaker must be a b.retry.CircuitBreaker opts object or null");
+  }
+  if (entry.timeoutMs !== undefined && entry.timeoutMs !== 0 && !_isFiniteNonNegative(entry.timeoutMs)) {
+    throw _err("BAD_OPT", "notify: channel '" + name + "' timeoutMs must be a non-negative finite number (0 disables)");
+  }
+  if (entry.serialize !== undefined && typeof entry.serialize !== "boolean") {
+    throw _err("BAD_OPT", "notify: channel '" + name + "' serialize must be a boolean");
+  }
+  return {
+    transport: entry.transport,
+    retry:     entry.retry || null,
+    breaker:   entry.breaker || null,
+    timeoutMs: (entry.timeoutMs !== undefined) ? entry.timeoutMs : null,
+    serialize: entry.serialize === true,
+  };
+}
+
+function _validateCreateOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("BAD_OPT", "notify.create: opts must be an object");
+  }
+  if (!opts.channels || typeof opts.channels !== "object") {
+    throw _err("BAD_OPT", "notify.create: channels must be an object mapping channel names to transports");
+  }
+  var keys = Object.keys(opts.channels);
+  if (keys.length === 0) {
+    throw _err("BAD_OPT", "notify.create: channels object must have at least one channel");
+  }
+  if (opts.audit !== undefined && opts.audit !== null) {
+    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
+      throw _err("BAD_OPT", "notify.create: audit must be a b.audit-shaped object (safeEmit fn)");
+    }
+  }
+  if (opts.auditSuccess !== undefined && typeof opts.auditSuccess !== "boolean") {
+    throw _err("BAD_OPT", "notify.create: auditSuccess must be a boolean");
+  }
+  if (opts.auditFailures !== undefined && typeof opts.auditFailures !== "boolean") {
+    throw _err("BAD_OPT", "notify.create: auditFailures must be a boolean");
+  }
+  if (opts.redact !== undefined && opts.redact !== null && typeof opts.redact !== "function") {
+    throw _err("BAD_OPT", "notify.create: redact must be a function returning a redacted message");
+  }
+  if (opts.defaultTimeoutMs !== undefined &&
+      opts.defaultTimeoutMs !== 0 &&
+      !_isFiniteNonNegative(opts.defaultTimeoutMs)) {
+    throw _err("BAD_OPT", "notify.create: defaultTimeoutMs must be a non-negative finite number (0 disables)");
+  }
+  if (opts.defaultRetry !== undefined && opts.defaultRetry !== null &&
+      (typeof opts.defaultRetry !== "object")) {
+    throw _err("BAD_OPT", "notify.create: defaultRetry must be a b.retry.withRetry opts object");
+  }
+  if (opts.defaultBreaker !== undefined && opts.defaultBreaker !== null &&
+      typeof opts.defaultBreaker !== "object") {
+    throw _err("BAD_OPT", "notify.create: defaultBreaker must be a b.retry.CircuitBreaker opts object");
+  }
+  if (opts.queue !== undefined && opts.queue !== null) {
+    if (typeof opts.queue !== "object" || typeof opts.queue.enqueue !== "function") {
+      throw _err("BAD_OPT", "notify.create: queue must be a b.queue-shaped handle (enqueue fn)");
+    }
+  }
+  if (opts.clock !== undefined && typeof opts.clock !== "function") {
+    throw _err("BAD_OPT", "notify.create: clock must be a function");
+  }
+}
+
+// ---- Built-in transports ----
+
+// httpJson — POST JSON to a URL via b.httpClient. Default `transient`
+// classifier defers to b.retry.isRetryable so HTTP/network classification
+// matches the rest of the framework.
+function httpJson(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("BAD_OPT", "notify.transports.httpJson: opts must be { url, ... }");
+  }
+  if (typeof opts.url !== "string" || opts.url.length === 0) {
+    throw _err("BAD_OPT", "notify.transports.httpJson: url is required");
+  }
+  var allowedProtocols = opts.allowHttp ? safeUrl.ALLOW_HTTP_ALL : safeUrl.ALLOW_HTTP_TLS;
+  // Validate URL at create time so bad URLs surface at boot, not at first send.
+  safeUrl.parse(opts.url, { allowedProtocols: allowedProtocols, errorClass: NotifyError });
+
+  var method = opts.method || "POST";
+  var bodyFormat = opts.bodyFormat || "json";
+  if (bodyFormat !== "json" && bodyFormat !== "form") {
+    throw _err("BAD_OPT", "notify.transports.httpJson: bodyFormat must be 'json' or 'form'");
+  }
+  var staticHeaders = opts.headers || {};
+  var signing = opts.signing || null;
+  if (signing && typeof signing.sign !== "function") {
+    throw _err("BAD_OPT", "notify.transports.httpJson: signing must have a sign(body) function");
+  }
+  var successStatus = (typeof opts.successStatus === "function")
+    ? opts.successStatus
+    : function (s) { return typeof s === "number" && s >= 200 && s < 300; };
+  var customClient = opts.httpClient || null;
+  var name = opts.name || "httpJson";
+
+  return {
+    name: name,
+    send: async function (message, sendOpts) {
+      var client = customClient || httpClientModule();
+      var body;
+      var contentType;
+      if (bodyFormat === "form") {
+        body = new URLSearchParams(message || {}).toString();
+        contentType = "application/x-www-form-urlencoded";
+      } else {
+        body = JSON.stringify(message || {});
+        contentType = "application/json";
+      }
+      var headers = Object.assign({ "Content-Type": contentType }, staticHeaders);
+      if (sendOpts && sendOpts.headers) Object.assign(headers, sendOpts.headers);
+      if (signing) {
+        // signing.sign(body) returns either a headers object or a string.
+        // The shape mirrors b.webhook.signer outputs so operators can plug
+        // a webhook signer in directly.
+        var signed = signing.sign(body);
+        if (signed && typeof signed === "object" && !Array.isArray(signed)) {
+          if (signed.headers) Object.assign(headers, signed.headers);
+          else Object.assign(headers, signed);
+        }
+      }
+      var startedAt = Date.now();
+      var res = await client.request({
+        method:           method,
+        url:              opts.url,
+        headers:          headers,
+        body:             body,
+        allowedProtocols: allowedProtocols,
+        errorClass:       NotifyError,
+      });
+      var status = (res && (res.statusCode || res.status)) || 0;
+      if (!successStatus(status)) {
+        // Throw a plain Error (not NotifyError) so b.retry.isRetryable
+        // can classify on err.statusCode. NotifyError is alwaysPermanent
+        // by design — wrapping a 429 in it would tell retry "don't try
+        // again" before retry's HTTP-status classifier ever runs.
+        // We only convert to NotifyError after retry exhaustion (in the
+        // caller), which is when the error truly IS permanent.
+        var httpErr = new Error(
+          "notify.httpJson: " + opts.url + " responded " + status);
+        httpErr.code = "HTTP_FAILURE";
+        httpErr.statusCode = status;
+        throw httpErr;
+      }
+      return {
+        id:         null,
+        status:     "delivered",
+        attempts:   1,
+        durationMs: Date.now() - startedAt,
+        response:   res,
+      };
+    },
+  };
+}
+
+// log — fire-and-forget developer logger. Never throws; audit + obs still emit.
+function logTransport(opts) {
+  opts = opts || {};
+  var logger;
+  if (opts.logger && typeof opts.logger.info === "function") {
+    logger = opts.logger;
+  } else {
+    var bootLog = require("./log");
+    logger = bootLog.boot("notify.log");
+    // boot returns a fn-with-fields shape; tolerate both.
+    if (typeof logger === "function") {
+      logger = { info: logger, error: function (m) { try { console.error(m); } catch (_e) {} } };
+    }
+    if (typeof logger.error !== "function") {
+      logger.error = function (m) { try { console.error(m); } catch (_e) {} };
+    }
+  }
+  return {
+    name: opts.name || "log",
+    send: async function (message, _sendOpts) {
+      try { logger.info(JSON.stringify(message)); }
+      catch (_e) { /* logger best-effort */ }
+      return { id: null, status: "delivered", attempts: 1, durationMs: 0 };
+    },
+  };
+}
+
+// test — captures sends to .sent for fixture inspection. Never throws.
+function testTransport() {
+  var sent = [];
+  return {
+    name: "test",
+    sent: sent,
+    send: async function (message, sendOpts) {
+      sent.push({
+        message: message,
+        sendOpts: sendOpts || null,
+        sentAt:   Date.now(),
+      });
+      return { id: null, status: "delivered", attempts: 1, durationMs: 0 };
+    },
+    clear: function () { sent.length = 0; },
+  };
+}
+
+// ---- Public create ----
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "channels", "audit", "auditSuccess", "auditFailures",
+    "redact", "defaultTimeoutMs", "defaultRetry", "defaultBreaker",
+    "queue", "clock",
+  ], "notify");
+  _validateCreateOpts(opts);
+
+  var auditSuccess  = (opts.auditSuccess  === undefined) ? DEFAULTS.auditSuccess  : opts.auditSuccess;
+  var auditFailures = (opts.auditFailures === undefined) ? DEFAULTS.auditFailures : opts.auditFailures;
+  var audit = opts.audit || null;
+  var redactFn = (typeof opts.redact === "function")
+    ? opts.redact
+    // Default: b.redact.redact — the framework's PII detector chain.
+    : function (m) { return redactModule().redact(m); };
+  var defaultTimeoutMs = (opts.defaultTimeoutMs === undefined)
+    ? DEFAULTS.defaultTimeoutMs : opts.defaultTimeoutMs;
+  var defaultRetry = opts.defaultRetry || null;
+  var defaultBreaker = opts.defaultBreaker || null;
+  var operatorQueue = opts.queue || null;
+  var clock = opts.clock || function () { return Date.now(); };
+
+  // Build channel registry: name → { transport, retry, breaker, timeoutMs, serialize, mutex? }
+  var channels = {};
+  var channelNames = Object.keys(opts.channels);
+  for (var i = 0; i < channelNames.length; i++) {
+    var n = channelNames[i];
+    var entry = _validateChannelEntry(n, opts.channels[n]);
+    var registry = {
+      transport: entry.transport,
+      retry:     entry.retry || defaultRetry,
+      timeoutMs: (entry.timeoutMs === null) ? defaultTimeoutMs : entry.timeoutMs,
+      breaker:   null,
+      mutex:     null,
+    };
+    var breakerOpts = entry.breaker || defaultBreaker;
+    if (breakerOpts) {
+      registry.breaker = new (retryModule().CircuitBreaker)(n, breakerOpts);
+    }
+    if (entry.serialize) registry.mutex = new safeAsync.Mutex();
+    channels[n] = registry;
+  }
+
+  function _emitObs(name, labels) {
+    try { observability().event(name, 1, labels || {}); }
+    catch (_e) { /* Tier B */ }
+  }
+
+  function _emitAudit(action, info) {
+    if (!audit) return;
+    try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
+    catch (_e) { /* audit best-effort */ }
+  }
+
+  function _actor(callerOpts) {
+    var override = {};
+    if (callerOpts && callerOpts.context && typeof callerOpts.context === "object") {
+      for (var k in callerOpts.context) {
+        if (Object.prototype.hasOwnProperty.call(callerOpts.context, k)) {
+          override[k] = callerOpts.context[k];
+        }
+      }
+    }
+    return requestHelpers.extractActorContext(callerOpts && callerOpts.req, override);
+  }
+
+  function _redactedMetadata(channel, message, extra) {
+    var redactedMessage;
+    try { redactedMessage = redactFn(message); }
+    catch (_e) { redactedMessage = "[redact-failed]"; }
+    return Object.assign({
+      channel:  channel,
+      message:  redactedMessage,
+    }, extra || {});
+  }
+
+  // Send a single message to one channel. The whole call is wrapped in
+  // observability.tap (span+counter), inside which we layer:
+  //
+  //   withRetry( withTimeout( breaker.wrap( transport.send ) ) )
+  //
+  // Each layer comes from an existing primitive — notify never
+  // re-implements retry / timeout / breaker / span+counter logic.
+  async function send(input) {
+    if (!input || typeof input !== "object") {
+      throw _err("BAD_OPT", "notify.send: input must be { channel, message, ... }");
+    }
+    if (typeof input.channel !== "string" || input.channel.length === 0) {
+      throw _err("BAD_OPT", "notify.send: channel must be a non-empty string");
+    }
+    if (input.message === undefined || input.message === null) {
+      throw _err("MISSING_MESSAGE", "notify.send: message is required");
+    }
+    var channel = input.channel;
+    var entry = channels[channel];
+    if (!entry) {
+      throw _err("NO_CHANNEL", "notify.send: unknown channel '" + channel + "'");
+    }
+    var perCallTimeoutMs = (input.timeoutMs !== undefined) ? input.timeoutMs : entry.timeoutMs;
+    var perCallRetry = input.retry || entry.retry;
+    var message = input.message;
+
+    var attemptCount = 0;
+    var startedAt = clock();
+    var transport = entry.transport;
+    var transportName = transport.name || channel;
+
+    // The retryable single attempt. Each call to this function is one
+    // transport.send invocation (so withRetry's loop is the only retry
+    // mechanism — no double-retry inside the breaker or transport).
+    async function _oneAttempt(attemptIdx) {
+      attemptCount = attemptIdx;
+      _emitObs("notify.send.attempt", { channel: channel, attempt: attemptIdx });
+      var sendPromise = entry.transport.send(message, input.sendOpts || null);
+      // withTimeout from b.safeAsync — never re-implement timer races.
+      var timed = (perCallTimeoutMs > 0)
+        ? safeAsync.withTimeout(sendPromise, perCallTimeoutMs, { name: "notify." + channel })
+        : sendPromise;
+      try {
+        return await timed;
+      } catch (e) {
+        // Map withTimeout's async/timeout into a transient error so retry
+        // classifies it correctly (operators can still opt OUT by setting
+        // err.permanent in their transport).
+        if (e && e.code === "async/timeout") {
+          _emitObs("notify.send.timeout", { channel: channel });
+          var te = _err("TIMEOUT",
+            "notify.send: '" + channel + "' transport timed out after " + perCallTimeoutMs + "ms");
+          // Mark transient via a NETWORK-style code so b.retry.isRetryable
+          // routes it through the retry path.
+          te.code = "ETIMEDOUT";
+          throw te;
+        }
+        throw e;
+      }
+    }
+
+    // Wrap each attempt with the breaker, if configured.
+    async function _attemptWithBreaker(attemptIdx) {
+      if (entry.breaker) {
+        try {
+          return await entry.breaker.wrap(function () { return _oneAttempt(attemptIdx); });
+        } catch (e) {
+          if (e && e.code === "CIRCUIT_OPEN") {
+            _emitObs("notify.send.breaker.open", { channel: channel });
+          }
+          throw e;
+        }
+      }
+      return _oneAttempt(attemptIdx);
+    }
+
+    // Optional serialize: only one in-flight send per channel at a time.
+    async function _attemptSerialized(attemptIdx) {
+      if (!entry.mutex) return _attemptWithBreaker(attemptIdx);
+      await entry.mutex.acquire();
+      try { return await _attemptWithBreaker(attemptIdx); }
+      finally { entry.mutex.release(); }
+    }
+
+    // Outer span+counter wrapping via b.observability.tap so a single call
+    // produces both a span (under the operator's tracer) AND a counter.
+    return observability().tap("notify.send", { channel: channel }, async function () {
+      try {
+        // b.retry.withRetry IS the retry loop. Notify never hand-rolls
+        // backoff/jitter/classification — the framework owns it.
+        var result = await retryModule().withRetry(function (attempt) {
+          return _attemptSerialized(attempt);
+        }, perCallRetry);
+
+        var durationMs = clock() - startedAt;
+        _emitObs("notify.send.success", { channel: channel, durationMs: durationMs });
+        if (auditSuccess) {
+          _emitAudit("notify.send.success", {
+            actor:    _actor(input),
+            resource: { kind: "notify.channel", id: channel },
+            outcome:  "success",
+            metadata: _redactedMetadata(channel, message, {
+              transport:  transportName,
+              attempts:   attemptCount,
+              durationMs: durationMs,
+            }),
+          });
+        }
+        return Object.assign({}, result, {
+          channel:    channel,
+          attempts:   attemptCount,
+          durationMs: durationMs,
+        });
+      } catch (e) {
+        _emitObs("notify.send.failure", {
+          channel: channel,
+          reason:  (e && e.code) || "unknown",
+        });
+        if (auditFailures) {
+          _emitAudit("notify.send.failure", {
+            actor:    _actor(input),
+            resource: { kind: "notify.channel", id: channel },
+            outcome:  "failure",
+            reason:   (e && e.code) || "send-failed",
+            metadata: _redactedMetadata(channel, message, {
+              transport: transportName,
+              attempts:  attemptCount,
+              message_:  (e && e.message) || String(e),
+            }),
+          });
+        }
+        // If the error is already a NotifyError, propagate verbatim.
+        // Otherwise wrap so callers always catch a single class while
+        // keeping the cause chain.
+        if (e && e.isNotifyError) throw e;
+        var wrapped = _err("SEND_FAILED",
+          "notify.send: '" + channel + "' failed after " + attemptCount + " attempt(s): " +
+          ((e && e.message) || String(e)));
+        wrapped.cause = e;
+        if (e && typeof e.statusCode === "number") wrapped.statusCode = e.statusCode;
+        throw wrapped;
+      }
+    });
+  }
+
+  // sendBatch: settle each input independently. One channel down doesn't
+  // fail the whole batch; the result array carries either the success
+  // shape OR a NotifyError for each input position.
+  async function sendBatch(inputs) {
+    if (!Array.isArray(inputs)) {
+      throw _err("BAD_OPT", "notify.sendBatch: inputs must be an array");
+    }
+    var promises = inputs.map(function (input) {
+      return send(input).then(
+        function (result) { return result; },
+        function (err)    { return err; }
+      );
+    });
+    var results = await Promise.all(promises);
+    var ok = 0;
+    var failed = 0;
+    for (var i = 0; i < results.length; i++) {
+      if (results[i] && results[i].isNotifyError) failed++;
+      else ok++;
+    }
+    _emitObs("notify.batch", { size: inputs.length, ok: ok, failed: failed });
+    return results;
+  }
+
+  // queue: enqueue an async send onto the operator's b.queue. Requires a
+  // queue handle wired at create() OR per-call. Notify registers a
+  // default handler for `notifyQueueName` on first use.
+  var _queueHandlerRegistered = {};
+  async function queue(input, queueOpts) {
+    queueOpts = queueOpts || {};
+    var q = queueOpts.queue || operatorQueue;
+    if (!q || typeof q.enqueue !== "function") {
+      throw _err("NO_QUEUE", "notify.queue: requires a b.queue handle (pass at create or per-call)");
+    }
+    if (!input || typeof input !== "object" || typeof input.channel !== "string") {
+      throw _err("BAD_OPT", "notify.queue: input must be { channel, message, ... }");
+    }
+    var queueName = queueOpts.queueName || "notify";
+    // Handler registration is operator-driven for the b.queue primitive
+    // — operators have their own worker boot. We don't try to start
+    // workers here. The handler signature follows b.jobs / b.queue
+    // conventions: receives { input } and re-invokes notify.send.
+    if (!_queueHandlerRegistered[queueName] && typeof q.registerHandler === "function") {
+      try {
+        q.registerHandler(queueName, async function (job) {
+          var payload = (job && job.payload) || job;
+          return send(payload);
+        });
+        _queueHandlerRegistered[queueName] = true;
+      } catch (_e) { /* operator may register their own handler */ }
+    }
+    var jobId = await q.enqueue(queueName, input);
+    _emitObs("notify.queue.enqueued", { channel: input.channel, queueName: queueName });
+    return { jobId: jobId };
+  }
+
+  function addChannel(name, transport, channelOpts) {
+    if (channels[name]) {
+      throw _err("CHANNEL_EXISTS", "notify.addChannel: channel '" + name + "' already exists");
+    }
+    channelOpts = channelOpts || {};
+    var entry = _validateChannelEntry(name,
+      channelOpts.transport || channelOpts.send || transport
+        ? Object.assign({ transport: transport }, channelOpts)
+        : transport);
+    var registry = {
+      transport: entry.transport,
+      retry:     entry.retry || defaultRetry,
+      timeoutMs: (entry.timeoutMs === null) ? defaultTimeoutMs : entry.timeoutMs,
+      breaker:   null,
+      mutex:     null,
+    };
+    var breakerOpts = entry.breaker || defaultBreaker;
+    if (breakerOpts) registry.breaker = new (retryModule().CircuitBreaker)(name, breakerOpts);
+    if (entry.serialize) registry.mutex = new safeAsync.Mutex();
+    channels[name] = registry;
+  }
+
+  function listChannels() {
+    return Object.keys(channels);
+  }
+
+  function transportFor(name) {
+    var entry = channels[name];
+    return entry ? entry.transport : null;
+  }
+
+  return {
+    send:         send,
+    sendBatch:    sendBatch,
+    queue:        queue,
+    addChannel:   addChannel,
+    channels:     listChannels,
+    transport:    transportFor,
+  };
+}
+
+module.exports = {
+  create:      create,
+  NotifyError: NotifyError,
+  DEFAULTS:    DEFAULTS,
+  transports: {
+    httpJson: httpJson,
+    log:      logTransport,
+    test:     testTransport,
+  },
+};