@celerity-sdk/topic 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,2 +1,215 @@
+import { Closeable, CelerityTracer, ServiceContainer, CelerityLayer, BaseHandlerContext } from '@celerity-sdk/types';
 
-export {  }
+declare const TopicClient: unique symbol;
+/**
+ * A topic client abstraction for pub/sub topics. Provides access to named
+ * topics, each representing a logical destination for published messages.
+ */
+interface TopicClient extends Closeable {
+    /**
+     * Retrieves a topic instance by its name. The returned topic is a lightweight
+     * handle — no network calls are made until an operation is invoked.
+     *
+     * @param name The topic identifier (SNS topic ARN, Redis channel name, etc.).
+     */
+    topic(name: string): Topic$1;
+}
+/**
+ * A topic represents a logical pub/sub destination. It provides methods for
+ * publishing messages individually or in batches. The Celerity runtime handles
+ * all subscription and consumption — this interface is producer-only.
+ */
+interface Topic$1 {
+    /**
+     * Publish a single message to the topic. The body is serialized to JSON.
+     *
+     * @param body The message body (serialized to JSON string for transport).
+     * @param options Optional publish parameters such as FIFO ordering or subject.
+     * @returns A promise that resolves to the publish result with the provider-assigned message ID.
+     */
+    publish<T = Record<string, unknown>>(body: T, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * Publish multiple messages in a single batch. The provider may impose batch
+     * size limits (e.g. SNS limits to 10 per request) — the implementation
+     * handles chunking transparently.
+     *
+     * @param entries The batch of messages to publish, each with a caller-assigned ID for correlation.
+     * @returns A promise that resolves to the batch result with successful and failed entries.
+     */
+    publishBatch<T = Record<string, unknown>>(entries: BatchPublishEntry<T>[]): Promise<BatchPublishResult>;
+}
+/**
+ * Options for the publish and publishBatch operations.
+ */
+type PublishOptions = {
+    /** Message group ID for FIFO topics (SNS: MessageGroupId, Pub/Sub: ordering key). */
+    groupId?: string;
+    /** Deduplication ID for FIFO topics. */
+    deduplicationId?: string;
+    /** Message subject (SNS: Subject). */
+    subject?: string;
+    /** String key-value message attributes (metadata sent alongside the body). */
+    attributes?: Record<string, string>;
+};
+/**
+ * The result of a single publish call.
+ */
+type PublishResult = {
+    /** The provider-assigned message identifier. */
+    messageId: string;
+};
+/**
+ * A single entry in a batch publish request.
+ */
+type BatchPublishEntry<T = Record<string, unknown>> = {
+    /** Caller-assigned ID for correlating results within the batch. */
+    id: string;
+    /** The message body (serialized to JSON). */
+    body: T;
+    /** Per-message publish options. */
+    options?: PublishOptions;
+};
+/**
+ * The result of a batch publish operation.
+ */
+type BatchPublishResult = {
+    /** Entries that were published successfully. */
+    successful: BatchPublishSuccess[];
+    /** Entries that failed. */
+    failed: BatchPublishFailure[];
+};
+/**
+ * A successfully published entry from a batch operation.
+ */
+type BatchPublishSuccess = {
+    /** The caller-assigned entry ID. */
+    id: string;
+    /** The provider-assigned message ID. */
+    messageId: string;
+};
+/**
+ * A failed entry from a batch operation.
+ */
+type BatchPublishFailure = {
+    /** The caller-assigned entry ID. */
+    id: string;
+    /** Provider error code. */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+};
+
+type SNSTopicConfig = {
+    /** AWS region (e.g. "us-east-1"). */
+    region?: string;
+    /** Override endpoint URL for LocalStack or other SNS-compatible services. */
+    endpoint?: string;
+    /** Explicit AWS credentials. When omitted, the SDK's default credential chain is used. */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+};
+
+declare class SNSTopicClient implements TopicClient {
+    private readonly tracer?;
+    private client;
+    private readonly config;
+    constructor(config?: SNSTopicConfig, tracer?: CelerityTracer | undefined);
+    topic(name: string): Topic$1;
+    close(): void;
+    private getClient;
+}
+
+type RedisTopicConfig = {
+    /** Redis/Valkey connection URL. Defaults to "redis://localhost:6379". */
+    url?: string;
+};
+
+declare class RedisTopicClient implements TopicClient {
+    private readonly tracer?;
+    private client;
+    private readonly config;
+    constructor(config?: RedisTopicConfig, tracer?: CelerityTracer | undefined);
+    topic(name: string): Topic$1;
+    close(): Promise<void>;
+    private getClient;
+}
+
+type CreateTopicClientOptions = {
+    /** Override provider selection. If omitted, derived from platform config. */
+    provider?: "aws" | "local" | "gcp" | "azure";
+    /** SNS-specific configuration overrides. */
+    aws?: SNSTopicConfig;
+    /** Redis-specific configuration overrides (local environment). */
+    local?: RedisTopicConfig;
+    /** Optional tracer for Celerity-level span instrumentation. */
+    tracer?: CelerityTracer;
+};
+declare function createTopicClient(options?: CreateTopicClientOptions): TopicClient;
+
+declare function topicToken(resourceName: string): symbol;
+declare const DEFAULT_TOPIC_TOKEN: unique symbol;
+interface Topic extends Topic$1 {
+}
+/**
+ * Parameter decorator that injects a {@link Topic} instance for the given
+ * blueprint resource. Writes both DI injection metadata and CLI resource-ref
+ * metadata using well-known `Symbol.for()` keys (no dependency on core).
+ *
+ * When `resourceName` is omitted, the default topic token is used — this
+ * auto-resolves when exactly one topic resource exists.
+ *
+ * @example
+ * ```ts
+ * @Controller("/orders")
+ * class OrderController {
+ *   constructor(@Topic("orderEvents") private events: Topic) {}
+ * }
+ * ```
+ */
+declare function Topic(resourceName?: string): ParameterDecorator;
+
+/**
+ * Resolves a {@link Topic} instance from the DI container.
+ * For function-based handlers where parameter decorators aren't available.
+ *
+ * @param container - The service container (typically `context.container`).
+ * @param resourceName - The blueprint resource name. Omit when exactly one
+ *   topic resource exists to use the default.
+ *
+ * @example
+ * ```ts
+ * const handler = createHttpHandler(async (req, ctx) => {
+ *   const events = await getTopic(ctx.container, "orderEvents");
+ *   await events.publish({ orderId: "123", action: "created" });
+ * });
+ * ```
+ */
+declare function getTopic(container: ServiceContainer, resourceName?: string): Promise<Topic$1>;
+
+/**
+ * System layer that auto-registers {@link TopicClient} and per-resource
+ * {@link Topic} handles in the DI container.
+ *
+ * Reads resource link topology from `CELERITY_RESOURCE_LINKS` and resolves
+ * actual topic ARNs / channel names from the ConfigService "resources" namespace.
+ * Must run after ConfigLayer in the layer pipeline.
+ */
+declare class TopicLayer implements CelerityLayer<BaseHandlerContext> {
+    private initialized;
+    handle(context: BaseHandlerContext, next: () => Promise<unknown>): Promise<unknown>;
+}
+
+/**
+ * Base error for topic operations. Wraps provider SDK errors and includes
+ * the topic identifier for context.
+ */
+declare class TopicError extends Error {
+    readonly topic: string;
+    constructor(message: string, topic: string, options?: {
+        cause?: unknown;
+    });
+}
+
+export { type BatchPublishEntry, type BatchPublishFailure, type BatchPublishResult, type BatchPublishSuccess, type CreateTopicClientOptions, DEFAULT_TOPIC_TOKEN, type PublishOptions, type PublishResult, RedisTopicClient, type RedisTopicConfig, SNSTopicClient, type SNSTopicConfig, Topic, TopicClient, TopicError, TopicLayer, createTopicClient, getTopic, topicToken };

package/dist/index.d.ts

@@ -1,2 +1,215 @@
+import { Closeable, CelerityTracer, ServiceContainer, CelerityLayer, BaseHandlerContext } from '@celerity-sdk/types';
 
-export {  }
+declare const TopicClient: unique symbol;
+/**
+ * A topic client abstraction for pub/sub topics. Provides access to named
+ * topics, each representing a logical destination for published messages.
+ */
+interface TopicClient extends Closeable {
+    /**
+     * Retrieves a topic instance by its name. The returned topic is a lightweight
+     * handle — no network calls are made until an operation is invoked.
+     *
+     * @param name The topic identifier (SNS topic ARN, Redis channel name, etc.).
+     */
+    topic(name: string): Topic$1;
+}
+/**
+ * A topic represents a logical pub/sub destination. It provides methods for
+ * publishing messages individually or in batches. The Celerity runtime handles
+ * all subscription and consumption — this interface is producer-only.
+ */
+interface Topic$1 {
+    /**
+     * Publish a single message to the topic. The body is serialized to JSON.
+     *
+     * @param body The message body (serialized to JSON string for transport).
+     * @param options Optional publish parameters such as FIFO ordering or subject.
+     * @returns A promise that resolves to the publish result with the provider-assigned message ID.
+     */
+    publish<T = Record<string, unknown>>(body: T, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * Publish multiple messages in a single batch. The provider may impose batch
+     * size limits (e.g. SNS limits to 10 per request) — the implementation
+     * handles chunking transparently.
+     *
+     * @param entries The batch of messages to publish, each with a caller-assigned ID for correlation.
+     * @returns A promise that resolves to the batch result with successful and failed entries.
+     */
+    publishBatch<T = Record<string, unknown>>(entries: BatchPublishEntry<T>[]): Promise<BatchPublishResult>;
+}
+/**
+ * Options for the publish and publishBatch operations.
+ */
+type PublishOptions = {
+    /** Message group ID for FIFO topics (SNS: MessageGroupId, Pub/Sub: ordering key). */
+    groupId?: string;
+    /** Deduplication ID for FIFO topics. */
+    deduplicationId?: string;
+    /** Message subject (SNS: Subject). */
+    subject?: string;
+    /** String key-value message attributes (metadata sent alongside the body). */
+    attributes?: Record<string, string>;
+};
+/**
+ * The result of a single publish call.
+ */
+type PublishResult = {
+    /** The provider-assigned message identifier. */
+    messageId: string;
+};
+/**
+ * A single entry in a batch publish request.
+ */
+type BatchPublishEntry<T = Record<string, unknown>> = {
+    /** Caller-assigned ID for correlating results within the batch. */
+    id: string;
+    /** The message body (serialized to JSON). */
+    body: T;
+    /** Per-message publish options. */
+    options?: PublishOptions;
+};
+/**
+ * The result of a batch publish operation.
+ */
+type BatchPublishResult = {
+    /** Entries that were published successfully. */
+    successful: BatchPublishSuccess[];
+    /** Entries that failed. */
+    failed: BatchPublishFailure[];
+};
+/**
+ * A successfully published entry from a batch operation.
+ */
+type BatchPublishSuccess = {
+    /** The caller-assigned entry ID. */
+    id: string;
+    /** The provider-assigned message ID. */
+    messageId: string;
+};
+/**
+ * A failed entry from a batch operation.
+ */
+type BatchPublishFailure = {
+    /** The caller-assigned entry ID. */
+    id: string;
+    /** Provider error code. */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+};
+
+type SNSTopicConfig = {
+    /** AWS region (e.g. "us-east-1"). */
+    region?: string;
+    /** Override endpoint URL for LocalStack or other SNS-compatible services. */
+    endpoint?: string;
+    /** Explicit AWS credentials. When omitted, the SDK's default credential chain is used. */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+};
+
+declare class SNSTopicClient implements TopicClient {
+    private readonly tracer?;
+    private client;
+    private readonly config;
+    constructor(config?: SNSTopicConfig, tracer?: CelerityTracer | undefined);
+    topic(name: string): Topic$1;
+    close(): void;
+    private getClient;
+}
+
+type RedisTopicConfig = {
+    /** Redis/Valkey connection URL. Defaults to "redis://localhost:6379". */
+    url?: string;
+};
+
+declare class RedisTopicClient implements TopicClient {
+    private readonly tracer?;
+    private client;
+    private readonly config;
+    constructor(config?: RedisTopicConfig, tracer?: CelerityTracer | undefined);
+    topic(name: string): Topic$1;
+    close(): Promise<void>;
+    private getClient;
+}
+
+type CreateTopicClientOptions = {
+    /** Override provider selection. If omitted, derived from platform config. */
+    provider?: "aws" | "local" | "gcp" | "azure";
+    /** SNS-specific configuration overrides. */
+    aws?: SNSTopicConfig;
+    /** Redis-specific configuration overrides (local environment). */
+    local?: RedisTopicConfig;
+    /** Optional tracer for Celerity-level span instrumentation. */
+    tracer?: CelerityTracer;
+};
+declare function createTopicClient(options?: CreateTopicClientOptions): TopicClient;
+
+declare function topicToken(resourceName: string): symbol;
+declare const DEFAULT_TOPIC_TOKEN: unique symbol;
+interface Topic extends Topic$1 {
+}
+/**
+ * Parameter decorator that injects a {@link Topic} instance for the given
+ * blueprint resource. Writes both DI injection metadata and CLI resource-ref
+ * metadata using well-known `Symbol.for()` keys (no dependency on core).
+ *
+ * When `resourceName` is omitted, the default topic token is used — this
+ * auto-resolves when exactly one topic resource exists.
+ *
+ * @example
+ * ```ts
+ * @Controller("/orders")
+ * class OrderController {
+ *   constructor(@Topic("orderEvents") private events: Topic) {}
+ * }
+ * ```
+ */
+declare function Topic(resourceName?: string): ParameterDecorator;
+
+/**
+ * Resolves a {@link Topic} instance from the DI container.
+ * For function-based handlers where parameter decorators aren't available.
+ *
+ * @param container - The service container (typically `context.container`).
+ * @param resourceName - The blueprint resource name. Omit when exactly one
+ *   topic resource exists to use the default.
+ *
+ * @example
+ * ```ts
+ * const handler = createHttpHandler(async (req, ctx) => {
+ *   const events = await getTopic(ctx.container, "orderEvents");
+ *   await events.publish({ orderId: "123", action: "created" });
+ * });
+ * ```
+ */
+declare function getTopic(container: ServiceContainer, resourceName?: string): Promise<Topic$1>;
+
+/**
+ * System layer that auto-registers {@link TopicClient} and per-resource
+ * {@link Topic} handles in the DI container.
+ *
+ * Reads resource link topology from `CELERITY_RESOURCE_LINKS` and resolves
+ * actual topic ARNs / channel names from the ConfigService "resources" namespace.
+ * Must run after ConfigLayer in the layer pipeline.
+ */
+declare class TopicLayer implements CelerityLayer<BaseHandlerContext> {
+    private initialized;
+    handle(context: BaseHandlerContext, next: () => Promise<unknown>): Promise<unknown>;
+}
+
+/**
+ * Base error for topic operations. Wraps provider SDK errors and includes
+ * the topic identifier for context.
+ */
+declare class TopicError extends Error {
+    readonly topic: string;
+    constructor(message: string, topic: string, options?: {
+        cause?: unknown;
+    });
+}
+
+export { type BatchPublishEntry, type BatchPublishFailure, type BatchPublishResult, type BatchPublishSuccess, type CreateTopicClientOptions, DEFAULT_TOPIC_TOKEN, type PublishOptions, type PublishResult, RedisTopicClient, type RedisTopicConfig, SNSTopicClient, type SNSTopicConfig, Topic, TopicClient, TopicError, TopicLayer, createTopicClient, getTopic, topicToken };