@celerity-sdk/topic 0.3.1 → 0.5.0

package/README.md

@@ -1,12 +1,13 @@
 # @celerity-sdk/topic
 
-Pub/Sub topic abstraction for the Celerity Node SDK.
+Cloud-agnostic pub/sub topic abstraction for the Celerity Node SDK.
 
-Provides a unified `TopicClient` interface for publishing messages to topics across cloud providers:
+Provides a unified `TopicClient` interface for publishing messages to topics across cloud providers. The Celerity runtime handles all consumption — this package is **publish-only** (`publish`, `publishBatch`).
 
-- **AWS**:Amazon SNS
-- **GCP**:Google Cloud Pub/Sub
-- **Azure**:Azure Service Bus Topics
+- **AWS**: Amazon SNS
+- **GCP**: Google Cloud Pub/Sub *(planned)*
+- **Azure**: Azure Service Bus Topics *(planned)*
+- **Local**: Redis pub/sub channels via Celerity CLI
 
 ## Installation
 
@@ -20,17 +21,14 @@ Install the cloud SDK for your target platform as a peer dependency:
 # AWS
 pnpm add @aws-sdk/client-sns
 
-# GCP
-pnpm add @google-cloud/pubsub
-
-# Azure
-pnpm add @azure/service-bus
+# Local development (managed by Celerity CLI, but needed for direct usage)
+pnpm add ioredis
 ```
 
 ## Status
 
-This package is a stub:the interface and provider implementations are planned but not yet implemented.
+This package implements the `TopicClient` interface with providers for AWS SNS and Redis (local development). Support for Google Cloud Pub/Sub and Azure Service Bus Topics will be added in future releases.
 
 ## Part of the Celerity Framework
 
-See [celerityframework.com](https://celerityframework.com) for full documentation.
+See [celerityframework.io](https://celerityframework.io) for full documentation.

package/dist/chunk-T4LCI5X5.js

@@ -0,0 +1,20 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/errors.ts
+var TopicError = class extends Error {
+  static {
+    __name(this, "TopicError");
+  }
+  topic;
+  constructor(message, topic, options) {
+    super(message, options), this.topic = topic;
+    this.name = "TopicError";
+  }
+};
+
+export {
+  __name,
+  TopicError
+};
+//# sourceMappingURL=chunk-T4LCI5X5.js.map

package/dist/chunk-T4LCI5X5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Base error for topic operations. Wraps provider SDK errors and includes\n * the topic identifier for context.\n */\nexport class TopicError extends Error {\n  constructor(\n    message: string,\n    public readonly topic: string,\n    options?: { cause?: unknown },\n  ) {\n    super(message, options);\n    this.name = \"TopicError\";\n  }\n}\n"],"mappings":";;;;AAIO,IAAMA,aAAN,cAAyBC,MAAAA;EAJhC,OAIgCA;;;;EAC9B,YACEC,SACgBC,OAChBC,SACA;AACA,UAAMF,SAASE,OAAAA,GAAAA,KAHCD,QAAAA;AAIhB,SAAKE,OAAO;EACd;AACF;","names":["TopicError","Error","message","topic","options","name"]}

package/dist/index.cjs

@@ -1,8 +1,18 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -11,9 +21,523 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/errors.ts
+var TopicError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    TopicError = class extends Error {
+      static {
+        __name(this, "TopicError");
+      }
+      topic;
+      constructor(message, topic, options) {
+        super(message, options), this.topic = topic;
+        this.name = "TopicError";
+      }
+    };
+  }
+});
+
+// src/providers/sns/sns-topic.ts
+function toSNSAttributes(attrs) {
+  const result = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    result[key] = {
+      DataType: "String",
+      StringValue: value
+    };
+  }
+  return result;
+}
+var import_debug, import_client_sns, debug, SNS_MAX_BATCH_SIZE, SNSTopic;
+var init_sns_topic = __esm({
+  "src/providers/sns/sns-topic.ts"() {
+    "use strict";
+    import_debug = __toESM(require("debug"), 1);
+    import_client_sns = require("@aws-sdk/client-sns");
+    init_errors();
+    debug = (0, import_debug.default)("celerity:topic:sns");
+    SNS_MAX_BATCH_SIZE = 10;
+    SNSTopic = class {
+      static {
+        __name(this, "SNSTopic");
+      }
+      topicArn;
+      client;
+      tracer;
+      constructor(topicArn, client, tracer) {
+        this.topicArn = topicArn;
+        this.client = client;
+        this.tracer = tracer;
+      }
+      async publish(body, options) {
+        debug("publish %s", this.topicArn);
+        return this.traced("celerity.topic.publish", {
+          "topic.arn": this.topicArn
+        }, async () => {
+          try {
+            const result = await this.client.send(new import_client_sns.PublishCommand({
+              TopicArn: this.topicArn,
+              Message: JSON.stringify(body),
+              MessageGroupId: options?.groupId,
+              MessageDeduplicationId: options?.deduplicationId,
+              Subject: options?.subject,
+              MessageAttributes: options?.attributes ? toSNSAttributes(options.attributes) : void 0
+            }));
+            return {
+              messageId: result.MessageId
+            };
+          } catch (error) {
+            throw new TopicError(`Failed to publish message to topic "${this.topicArn}"`, this.topicArn, {
+              cause: error
+            });
+          }
+        });
+      }
+      async publishBatch(entries) {
+        debug("publishBatch %s (%d entries)", this.topicArn, entries.length);
+        return this.traced("celerity.topic.publish_batch", {
+          "topic.arn": this.topicArn,
+          "topic.message_count": entries.length
+        }, async () => {
+          const successful = [];
+          const failed = [];
+          for (let i = 0; i < entries.length; i += SNS_MAX_BATCH_SIZE) {
+            const chunk = entries.slice(i, i + SNS_MAX_BATCH_SIZE);
+            const snsEntries = chunk.map((entry) => ({
+              Id: entry.id,
+              Message: JSON.stringify(entry.body),
+              MessageGroupId: entry.options?.groupId,
+              MessageDeduplicationId: entry.options?.deduplicationId,
+              Subject: entry.options?.subject,
+              MessageAttributes: entry.options?.attributes ? toSNSAttributes(entry.options.attributes) : void 0
+            }));
+            try {
+              const result = await this.client.send(new import_client_sns.PublishBatchCommand({
+                TopicArn: this.topicArn,
+                PublishBatchRequestEntries: snsEntries
+              }));
+              for (const s of result.Successful ?? []) {
+                successful.push({
+                  id: s.Id,
+                  messageId: s.MessageId
+                });
+              }
+              for (const f of result.Failed ?? []) {
+                failed.push({
+                  id: f.Id,
+                  code: f.Code,
+                  message: f.Message ?? "Unknown error"
+                });
+              }
+            } catch (error) {
+              throw new TopicError(`Failed to publish message batch to topic "${this.topicArn}"`, this.topicArn, {
+                cause: error
+              });
+            }
+          }
+          return {
+            successful,
+            failed
+          };
+        });
+      }
+      traced(name, attributes, fn) {
+        if (!this.tracer) return fn();
+        return this.tracer.withSpan(name, (span) => fn(span), attributes);
+      }
+    };
+    __name(toSNSAttributes, "toSNSAttributes");
+  }
+});
+
+// src/providers/sns/config.ts
+function captureSNSConfig() {
+  return {
+    region: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION,
+    endpoint: process.env.CELERITY_AWS_SNS_ENDPOINT ?? process.env.AWS_ENDPOINT_URL,
+    credentials: process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY ? {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+    } : void 0
+  };
+}
+var init_config = __esm({
+  "src/providers/sns/config.ts"() {
+    "use strict";
+    __name(captureSNSConfig, "captureSNSConfig");
+  }
+});
+
+// src/providers/sns/sns-topic-client.ts
+var sns_topic_client_exports = {};
+__export(sns_topic_client_exports, {
+  SNSTopicClient: () => SNSTopicClient
+});
+var import_client_sns2, SNSTopicClient;
+var init_sns_topic_client = __esm({
+  "src/providers/sns/sns-topic-client.ts"() {
+    "use strict";
+    import_client_sns2 = require("@aws-sdk/client-sns");
+    init_sns_topic();
+    init_config();
+    SNSTopicClient = class {
+      static {
+        __name(this, "SNSTopicClient");
+      }
+      tracer;
+      client = null;
+      config;
+      constructor(config, tracer) {
+        this.tracer = tracer;
+        this.config = config ?? captureSNSConfig();
+      }
+      topic(name) {
+        return new SNSTopic(name, this.getClient(), this.tracer);
+      }
+      close() {
+        this.client?.destroy();
+        this.client = null;
+      }
+      getClient() {
+        if (!this.client) {
+          this.client = new import_client_sns2.SNSClient({
+            region: this.config.region,
+            endpoint: this.config.endpoint,
+            credentials: this.config.credentials
+          });
+        }
+        return this.client;
+      }
+    };
+  }
+});
+
+// src/providers/redis/redis-topic.ts
+function buildEnvelope(body, messageId, options) {
+  const envelope = {
+    body: JSON.stringify(body),
+    messageId
+  };
+  if (options?.subject) {
+    envelope.subject = options.subject;
+  }
+  if (options?.attributes && Object.keys(options.attributes).length > 0) {
+    envelope.attributes = options.attributes;
+  }
+  return JSON.stringify(envelope);
+}
+var import_node_crypto, import_debug2, debug2, RedisTopic;
+var init_redis_topic = __esm({
+  "src/providers/redis/redis-topic.ts"() {
+    "use strict";
+    import_node_crypto = require("crypto");
+    import_debug2 = __toESM(require("debug"), 1);
+    init_errors();
+    debug2 = (0, import_debug2.default)("celerity:topic:redis");
+    RedisTopic = class {
+      static {
+        __name(this, "RedisTopic");
+      }
+      channelName;
+      client;
+      tracer;
+      constructor(channelName, client, tracer) {
+        this.channelName = channelName;
+        this.client = client;
+        this.tracer = tracer;
+      }
+      async publish(body, options) {
+        debug2("publish %s", this.channelName);
+        return this.traced("celerity.topic.publish", {
+          "topic.channel": this.channelName
+        }, async () => {
+          try {
+            const messageId = (0, import_node_crypto.randomUUID)();
+            const payload = buildEnvelope(body, messageId, options);
+            await this.client.publish(this.channelName, payload);
+            return {
+              messageId
+            };
+          } catch (error) {
+            throw new TopicError(`Failed to publish message to channel "${this.channelName}"`, this.channelName, {
+              cause: error
+            });
+          }
+        });
+      }
+      async publishBatch(entries) {
+        debug2("publishBatch %s (%d entries)", this.channelName, entries.length);
+        return this.traced("celerity.topic.publish_batch", {
+          "topic.channel": this.channelName,
+          "topic.message_count": entries.length
+        }, async () => {
+          const successful = [];
+          const failed = [];
+          const messageIds = [];
+          const pipeline = this.client.pipeline();
+          for (const entry of entries) {
+            const messageId = (0, import_node_crypto.randomUUID)();
+            messageIds.push(messageId);
+            const payload = buildEnvelope(entry.body, messageId, entry.options);
+            pipeline.publish(this.channelName, payload);
+          }
+          try {
+            const results = await pipeline.exec();
+            if (!results) {
+              throw new Error("Pipeline returned null");
+            }
+            for (let i = 0; i < entries.length; i++) {
+              const [err] = results[i];
+              if (err) {
+                failed.push({
+                  id: entries[i].id,
+                  code: err.name ?? "PipelineError",
+                  message: err.message
+                });
+              } else {
+                successful.push({
+                  id: entries[i].id,
+                  messageId: messageIds[i]
+                });
+              }
+            }
+          } catch (error) {
+            throw new TopicError(`Failed to publish message batch to channel "${this.channelName}"`, this.channelName, {
+              cause: error
+            });
+          }
+          return {
+            successful,
+            failed
+          };
+        });
+      }
+      traced(name, attributes, fn) {
+        if (!this.tracer) return fn();
+        return this.tracer.withSpan(name, (span) => fn(span), attributes);
+      }
+    };
+    __name(buildEnvelope, "buildEnvelope");
+  }
+});
+
+// src/providers/redis/config.ts
+function captureRedisConfig() {
+  return {
+    url: process.env.CELERITY_REDIS_ENDPOINT ?? DEFAULT_REDIS_URL
+  };
+}
+var DEFAULT_REDIS_URL;
+var init_config2 = __esm({
+  "src/providers/redis/config.ts"() {
+    "use strict";
+    DEFAULT_REDIS_URL = "redis://localhost:6379";
+    __name(captureRedisConfig, "captureRedisConfig");
+  }
+});
+
+// src/providers/redis/redis-topic-client.ts
+var redis_topic_client_exports = {};
+__export(redis_topic_client_exports, {
+  RedisTopicClient: () => RedisTopicClient
+});
+var RedisTopicClient;
+var init_redis_topic_client = __esm({
+  "src/providers/redis/redis-topic-client.ts"() {
+    "use strict";
+    init_redis_topic();
+    init_config2();
+    RedisTopicClient = class {
+      static {
+        __name(this, "RedisTopicClient");
+      }
+      tracer;
+      client = null;
+      ioredisModule = null;
+      config;
+      constructor(config, tracer) {
+        this.tracer = tracer;
+        this.config = config ?? captureRedisConfig();
+      }
+      topic(name) {
+        const channel = `celerity:topic:channel:${name}`;
+        return new RedisTopic(channel, this.getClient(), this.tracer);
+      }
+      async close() {
+        if (this.client) {
+          await this.client.quit();
+          this.client = null;
+        }
+      }
+      async ensureIoRedis() {
+        if (!this.ioredisModule) {
+          const pkg = "ioredis";
+          this.ioredisModule = await import(pkg);
+        }
+      }
+      getClient() {
+        if (!this.client) {
+          const ioredis = this.ioredisModule;
+          const Redis = ioredis.default ?? ioredis;
+          this.client = new Redis(this.config.url);
+        }
+        return this.client;
+      }
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  DEFAULT_TOPIC_TOKEN: () => DEFAULT_TOPIC_TOKEN,
+  Topic: () => Topic,
+  TopicClient: () => TopicClient,
+  TopicError: () => TopicError,
+  TopicLayer: () => TopicLayer,
+  createTopicClient: () => createTopicClient,
+  getTopic: () => getTopic,
+  topicToken: () => topicToken
+});
 module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var TopicClient = /* @__PURE__ */ Symbol.for("TopicClient");
+
+// src/factory.ts
+var import_config3 = require("@celerity-sdk/config");
+async function createTopicClient(options) {
+  const resolved = (0, import_config3.resolveConfig)("topic");
+  const provider = options?.provider ?? resolved.provider;
+  switch (provider) {
+    case "aws": {
+      const { SNSTopicClient: SNSTopicClient2 } = await Promise.resolve().then(() => (init_sns_topic_client(), sns_topic_client_exports));
+      return new SNSTopicClient2(options?.aws, options?.tracer);
+    }
+    // Local environments always use Redis pub/sub regardless of deploy target.
+    // The Celerity CLI manages the Redis instance and local-events sidecar.
+    case "local": {
+      const { RedisTopicClient: RedisTopicClient2 } = await Promise.resolve().then(() => (init_redis_topic_client(), redis_topic_client_exports));
+      const client = new RedisTopicClient2(options?.local, options?.tracer);
+      await client.ensureIoRedis();
+      return client;
+    }
+    // case "gcp":
+    //   v1: Google Cloud Pub/Sub
+    // case "azure":
+    //   v1: Azure Service Bus Topics
+    default:
+      throw new Error(`Unsupported topic provider: "${provider}"`);
+  }
+}
+__name(createTopicClient, "createTopicClient");
+
+// src/decorators.ts
+var import_reflect_metadata = require("reflect-metadata");
+var import_common = require("@celerity-sdk/common");
+function topicToken(resourceName) {
+  return /* @__PURE__ */ Symbol.for(`celerity:topic:${resourceName}`);
+}
+__name(topicToken, "topicToken");
+var DEFAULT_TOPIC_TOKEN = /* @__PURE__ */ Symbol.for("celerity:topic:default");
+function Topic(resourceName) {
+  return (target, _propertyKey, parameterIndex) => {
+    const token = resourceName ? topicToken(resourceName) : DEFAULT_TOPIC_TOKEN;
+    const existing = Reflect.getOwnMetadata(import_common.INJECT_METADATA, target) ?? /* @__PURE__ */ new Map();
+    existing.set(parameterIndex, token);
+    Reflect.defineMetadata(import_common.INJECT_METADATA, existing, target);
+    if (resourceName) {
+      const resources = Reflect.getOwnMetadata(import_common.USE_RESOURCE_METADATA, target) ?? [];
+      if (!resources.includes(resourceName)) {
+        Reflect.defineMetadata(import_common.USE_RESOURCE_METADATA, [
+          ...resources,
+          resourceName
+        ], target);
+      }
+    }
+  };
+}
+__name(Topic, "Topic");
+
+// src/helpers.ts
+function getTopic(container, resourceName) {
+  const token = resourceName ? topicToken(resourceName) : DEFAULT_TOPIC_TOKEN;
+  return container.resolve(token);
+}
+__name(getTopic, "getTopic");
+
+// src/layer.ts
+var import_debug3 = __toESM(require("debug"), 1);
+var import_common2 = require("@celerity-sdk/common");
+var import_config4 = require("@celerity-sdk/config");
+var debug3 = (0, import_debug3.default)("celerity:topic");
+var TopicLayer = class {
+  static {
+    __name(this, "TopicLayer");
+  }
+  initialized = false;
+  async handle(context, next) {
+    if (!this.initialized) {
+      const tracer = context.container.has(import_common2.TRACER_TOKEN) ? await context.container.resolve(import_common2.TRACER_TOKEN) : void 0;
+      const client = await createTopicClient({
+        tracer
+      });
+      debug3("registering TopicClient");
+      context.container.register("TopicClient", {
+        useValue: client
+      });
+      const links = (0, import_config4.captureResourceLinks)();
+      const topicLinks = (0, import_config4.getLinksOfType)(links, "topic");
+      if (topicLinks.size > 0) {
+        const configService = await context.container.resolve(import_common2.CONFIG_SERVICE_TOKEN);
+        const resourceConfig = configService.namespace(import_config4.RESOURCE_CONFIG_NAMESPACE);
+        for (const [resourceName, configKey] of topicLinks) {
+          const actualName = await resourceConfig.getOrThrow(configKey);
+          debug3("registered topic resource %s \u2192 %s", resourceName, actualName);
+          context.container.register(topicToken(resourceName), {
+            useValue: client.topic(actualName)
+          });
+        }
+        if (topicLinks.size === 1) {
+          const [, configKey] = [
+            ...topicLinks.entries()
+          ][0];
+          const actualName = await resourceConfig.getOrThrow(configKey);
+          debug3("registered default topic \u2192 %s", actualName);
+          context.container.register(DEFAULT_TOPIC_TOKEN, {
+            useValue: client.topic(actualName)
+          });
+        }
+      }
+      this.initialized = true;
+    }
+    return next();
+  }
+};
+
+// src/index.ts
+init_errors();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_TOPIC_TOKEN,
+  Topic,
+  TopicClient,
+  TopicError,
+  TopicLayer,
+  createTopicClient,
+  getTopic,
+  topicToken
+});
 //# sourceMappingURL=index.cjs.map