@agentuity/core 1.0.32 → 1.0.34

package/dist/services/queue/index.js

@@ -0,0 +1,98 @@
+/**
+ * @module queue
+ *
+ * Queue API client for managing message queues, messages, destinations, and dead letter queues.
+ *
+ * This module provides a complete client for the Agentuity Queue API, supporting:
+ * - **Queue Management**: Create, read, update, and delete message queues
+ * - **Message Operations**: Publish, consume, acknowledge, and manage messages
+ * - **Destinations**: Configure webhook endpoints for automatic message delivery
+ * - **Dead Letter Queue**: Handle failed messages that exceeded retry limits
+ *
+ * @example Basic Queue Operations
+ * ```typescript
+ * import { createQueue, publishMessage, receiveMessage, ackMessage } from '@agentuity/server';
+ *
+ * // Create a worker queue
+ * const queue = await createQueue(client, {
+ *   name: 'order-processing',
+ *   queue_type: 'worker',
+ * });
+ *
+ * // Publish a message
+ * await publishMessage(client, 'order-processing', {
+ *   payload: { orderId: 123 },
+ * });
+ *
+ * // Receive and acknowledge a message
+ * const message = await receiveMessage(client, 'order-processing');
+ * if (message) {
+ *   // Process the message...
+ *   await ackMessage(client, 'order-processing', message.id);
+ * }
+ * ```
+ *
+ * @example Webhook Destinations
+ * ```typescript
+ * import { createDestination } from '@agentuity/server';
+ *
+ * // Messages are automatically delivered to this URL
+ * await createDestination(client, 'order-processing', {
+ *   destination_type: 'http',
+ *   config: { url: 'https://api.example.com/webhook' },
+ * });
+ * ```
+ */
+// ============================================================================
+// Types & Schemas
+// ============================================================================
+export { 
+// Analytics types
+AnalyticsGranularitySchema, AnalyticsOptionsSchema, BatchPublishMessagesRequestSchema, ConsumeMessagesRequestSchema, CreateDestinationRequestSchema, CreateQueueRequestSchema, CreateSourceRequestSchema, DeadLetterMessageSchema, DeliveryLogSchema, DestinationAnalyticsSchema, DestinationSchema, DestinationStatsSchema, DestinationTypeSchema, HttpDestinationConfigSchema, LatencyStatsSchema, ListDeliveryLogsRequestSchema, ListDlqRequestSchema, ListMessagesRequestSchema, ListQueuesRequestSchema, ListSourceEventsRequestSchema, MessageSchema, MessageStateSchema, OrgAnalyticsSchema, OrgAnalyticsSummarySchema, PublishMessageRequestSchema, QueueAnalyticsSchema, QueueApiOptionsSchema, QueueCurrentStatsSchema, QueuePeriodStatsSchema, QueueSchema, QueueSettingsSchema, QueueStatsSchema, QueueSummarySchema, QueueTypeSchema, 
+// Consumer types
+ConsumerSchema, 
+// Source types
+SourceAuthTypeSchema, SourceEventSchema, SourceSchema, SSEStatsEventSchema, StreamAnalyticsOptionsSchema, TimePeriodSchema, TimeSeriesDataSchema, TimeSeriesPointSchema, UpdateDestinationRequestSchema, UpdateQueueRequestSchema, UpdateSourceRequestSchema, WebSocketAuthRequestSchema, WebSocketAuthResponseSchema, WebSocketMessageSchema, } from "./types.js";
+// ============================================================================
+// Errors
+// ============================================================================
+export { DestinationAlreadyExistsError, DestinationNotFoundError, MessageNotFoundError, QueueError, QueueInvalidArgumentError, SourceAlreadyExistsError, SourceNotFoundError, } from "./util.js";
+// Runtime queue service exports (preferred defaults for shared barrel)
+export * from "./service.js";
+// ============================================================================
+// Queue Operations
+// ============================================================================
+export { createQueue, DeleteQueueResponseSchema, deleteQueue, getQueue, listQueues, pauseQueue, QueueResponseSchema, QueuesListResponseSchema, resumeQueue, updateQueue, } from "./queues.js";
+// ============================================================================
+// Message Operations
+// ============================================================================
+export { AckNackResponseSchema, ackMessage, BatchPublishResponseSchema, batchPublishMessages, consumeMessages, DeleteMessageResponseSchema, deleteMessage, getMessage, getMessageByOffset, getQueueHead, getQueueTail, listMessages, MessageResponseSchema, MessagesListResponseSchema, nackMessage, OffsetResponseSchema, publishMessage, ReceiveResponseSchema, receiveMessage, replayMessage, } from "./messages.js";
+// ============================================================================
+// Dead Letter Queue Operations
+// ============================================================================
+export { DeleteDlqResponseSchema, DlqListResponseSchema, deleteDeadLetterMessage, listDeadLetterMessages, purgeDeadLetter, ReplayDlqResponseSchema, replayDeadLetterMessage, } from "./dlq.js";
+// ============================================================================
+// Destination Operations
+// ============================================================================
+export { createDestination, DeleteDestinationResponseSchema, DeliveryLogsListResponseSchema, DestinationResponseSchema, DestinationsListResponseSchema, deleteDestination, listDestinationDeliveries, listDestinations, updateDestination, } from "./destinations.js";
+// ============================================================================
+// Source Operations
+// ============================================================================
+export { createSource, DeleteSourceResponseSchema, deleteSource, getSource, listSourceEvents, listSources, SourceEventsListResponseSchema, SourceResponseSchema, SourcesListResponseSchema, updateSource, } from "./sources.js";
+// ============================================================================
+// Consumer Operations
+// ============================================================================
+export { listConsumers, ConsumersListResponseSchema, } from "./consumers.js";
+// ============================================================================
+// Analytics Operations
+// ============================================================================
+export { getOrgAnalytics, getOrgTimeSeries, getQueueAnalytics, getQueueTimeSeries, OrgAnalyticsResponseSchema, TimeSeriesResponseSchema, QueueAnalyticsResponseSchema, streamOrgAnalytics, streamQueueAnalytics, } from "./analytics.js";
+// ============================================================================
+// WebSocket Operations
+// ============================================================================
+export { createQueueWebSocket, QueueWebSocketOptionsSchema, subscribeToQueue, SubscribeToQueueOptionsSchema, } from "./websocket.js";
+// ============================================================================
+// Validation Utilities
+// ============================================================================
+export { MAX_BATCH_SIZE, MAX_DESCRIPTION_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_IN_FLIGHT, MAX_METADATA_SIZE, MAX_PARTITION_KEY_LENGTH, MAX_PAYLOAD_SIZE, MAX_QUEUE_NAME_LENGTH, MAX_RETRIES, MAX_SOURCE_NAME_LENGTH, MAX_VISIBILITY_TIMEOUT, MIN_QUEUE_NAME_LENGTH, validateBatchSize, validateDescription, validateDestinationConfig, validateDestinationId, validateIdempotencyKey, validateLimit, validateMaxInFlight, validateMaxRetries, validateMessageId, validateOffset, validatePartitionKey, validatePayload, validateQueueName, validateQueueType, validateSourceId, validateSourceName, validateTTL, validateVisibilityTimeout, validateWebhookUrl, } from "./validation.js";
+//# sourceMappingURL=index.js.map

package/dist/services/queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/queue/index.ts"],"names":[],"mappings":"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"}

package/dist/services/queue/messages.d.ts

@@ -0,0 +1,511 @@
+import { z } from 'zod';
+import { type APIClient } from '../api.ts';
+import { type BatchPublishMessagesRequest, type ConsumeMessagesRequest, type ListMessagesRequest, type Message, type PublishMessageRequest, type QueueApiOptions } from './types.ts';
+export declare const MessageResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        message: z.ZodObject<{
+            id: z.ZodString;
+            queue_id: z.ZodString;
+            offset: z.ZodNumber;
+            payload: z.ZodUnknown;
+            size: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            state: z.ZodOptional<z.ZodEnum<{
+                pending: "pending";
+                failed: "failed";
+                leased: "leased";
+                processing: "processing";
+                delivered: "delivered";
+                dead: "dead";
+            }>>;
+            idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            partition_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            ttl_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            delivery_attempts: z.ZodOptional<z.ZodNumber>;
+            max_retries: z.ZodOptional<z.ZodNumber>;
+            published_at: z.ZodOptional<z.ZodString>;
+            expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            delivered_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            acknowledged_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            created_at: z.ZodOptional<z.ZodString>;
+            updated_at: z.ZodOptional<z.ZodString>;
+            source_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            source_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "success">;
+export declare const MessagesListResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            queue_id: z.ZodString;
+            offset: z.ZodNumber;
+            payload: z.ZodUnknown;
+            size: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            state: z.ZodOptional<z.ZodEnum<{
+                pending: "pending";
+                failed: "failed";
+                leased: "leased";
+                processing: "processing";
+                delivered: "delivered";
+                dead: "dead";
+            }>>;
+            idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            partition_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            ttl_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            delivery_attempts: z.ZodOptional<z.ZodNumber>;
+            max_retries: z.ZodOptional<z.ZodNumber>;
+            published_at: z.ZodOptional<z.ZodString>;
+            expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            delivered_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            acknowledged_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            created_at: z.ZodOptional<z.ZodString>;
+            updated_at: z.ZodOptional<z.ZodString>;
+            source_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            source_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+        total: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "success">;
+export declare const BatchPublishResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        messages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            queue_id: z.ZodString;
+            offset: z.ZodNumber;
+            payload: z.ZodUnknown;
+            size: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            state: z.ZodOptional<z.ZodEnum<{
+                pending: "pending";
+                failed: "failed";
+                leased: "leased";
+                processing: "processing";
+                delivered: "delivered";
+                dead: "dead";
+            }>>;
+            idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            partition_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            ttl_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            delivery_attempts: z.ZodOptional<z.ZodNumber>;
+            max_retries: z.ZodOptional<z.ZodNumber>;
+            published_at: z.ZodOptional<z.ZodString>;
+            expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            delivered_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            acknowledged_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            created_at: z.ZodOptional<z.ZodString>;
+            updated_at: z.ZodOptional<z.ZodString>;
+            source_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            source_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+        failed: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "success">;
+export declare const DeleteMessageResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+}, z.core.$strip>], "success">;
+export declare const AckNackResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+}, z.core.$strip>], "success">;
+export declare const OffsetResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        offset: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>], "success">;
+export declare const ReceiveResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        message: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            queue_id: z.ZodString;
+            offset: z.ZodNumber;
+            payload: z.ZodUnknown;
+            size: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            state: z.ZodOptional<z.ZodEnum<{
+                pending: "pending";
+                failed: "failed";
+                leased: "leased";
+                processing: "processing";
+                delivered: "delivered";
+                dead: "dead";
+            }>>;
+            idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            partition_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            ttl_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            delivery_attempts: z.ZodOptional<z.ZodNumber>;
+            max_retries: z.ZodOptional<z.ZodNumber>;
+            published_at: z.ZodOptional<z.ZodString>;
+            expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            delivered_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            acknowledged_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            created_at: z.ZodOptional<z.ZodString>;
+            updated_at: z.ZodOptional<z.ZodString>;
+            source_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            source_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "success">;
+/**
+ * Publish a message to a queue.
+ *
+ * Publishes a single message to the specified queue. The message will be assigned
+ * a unique ID and offset.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue to publish to
+ * @param params - Message parameters including payload
+ * @returns The published message with assigned ID and offset
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const message = await publishMessage(client, 'order-queue', {
+ *   payload: { orderId: 123, action: 'process' },
+ *   metadata: { priority: 'high' },
+ *   idempotency_key: 'order-123-process',
+ * });
+ * console.log(`Published message ${message.id} at offset ${message.offset}`);
+ * ```
+ */
+export declare function publishMessage(client: APIClient, queueName: string, params: PublishMessageRequest, options?: QueueApiOptions): Promise<Message>;
+/**
+ * Batch publish multiple messages to a queue.
+ *
+ * Publishes up to 1000 messages in a single API call. This is more efficient
+ * than publishing messages individually.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue to publish to
+ * @param messages - Array of message parameters (max 1000)
+ * @returns Object containing the published messages and optionally failed indices
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const result = await batchPublishMessages(client, 'order-queue', [
+ *   { payload: { orderId: 1 } },
+ *   { payload: { orderId: 2 } },
+ *   { payload: { orderId: 3 } },
+ * ]);
+ * console.log(`Published ${result.messages.length} messages`);
+ * ```
+ */
+export declare function batchPublishMessages(client: APIClient, queueName: string, messages: BatchPublishMessagesRequest['messages'], options?: QueueApiOptions): Promise<{
+    messages: Message[];
+    failed?: number[];
+}>;
+/**
+ * Get a message by ID.
+ *
+ * Retrieves a specific message from a queue by its message ID.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID (prefixed with msg_)
+ * @returns The message details
+ * @throws {QueueValidationError} If validation fails
+ * @throws {MessageNotFoundError} If the message does not exist
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const message = await getMessage(client, 'order-queue', 'msg_abc123');
+ * console.log(`Message state: ${message.state}`);
+ * ```
+ */
+export declare function getMessage(client: APIClient, queueName: string, messageId: string, options?: QueueApiOptions): Promise<Message>;
+/**
+ * Get a message by its offset position.
+ *
+ * Retrieves a specific message from a queue by its offset (sequential position).
+ * Useful for log-style consumption where you track position by offset.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param offset - The message offset (0-based sequential position)
+ * @returns The message at the specified offset
+ * @throws {QueueValidationError} If validation fails
+ * @throws {MessageNotFoundError} If no message exists at the offset
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const message = await getMessageByOffset(client, 'events', 42);
+ * console.log(`Message at offset 42: ${message.id}`);
+ * ```
+ */
+export declare function getMessageByOffset(client: APIClient, queueName: string, offset: number, options?: QueueApiOptions): Promise<Message>;
+/**
+ * List messages in a queue.
+ *
+ * Retrieves messages from a queue with optional filtering and pagination.
+ * Supports filtering by state and pagination via limit/offset.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param params - Optional filtering and pagination parameters
+ * @param params.limit - Maximum number of messages to return (1-1000)
+ * @param params.offset - Starting offset for pagination
+ * @param params.state - Filter by message state (pending, processing, completed, failed, dead)
+ * @returns Object containing messages array and optional total count
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // List first 10 pending messages
+ * const result = await listMessages(client, 'order-queue', {
+ *   limit: 10,
+ *   state: 'pending',
+ * });
+ * console.log(`Found ${result.messages.length} pending messages`);
+ * ```
+ */
+export declare function listMessages(client: APIClient, queueName: string, params?: ListMessagesRequest, options?: QueueApiOptions): Promise<{
+    messages: Message[];
+    total?: number;
+}>;
+/**
+ * Delete a message from a queue.
+ *
+ * Permanently removes a message from the queue. This operation cannot be undone.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID to delete (prefixed with msg_)
+ * @returns void
+ * @throws {QueueValidationError} If validation fails
+ * @throws {MessageNotFoundError} If the message does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * await deleteMessage(client, 'order-queue', 'msg_abc123');
+ * console.log('Message deleted');
+ * ```
+ */
+export declare function deleteMessage(client: APIClient, queueName: string, messageId: string, options?: QueueApiOptions): Promise<void>;
+/**
+ * Replay a message.
+ *
+ * Re-queues a previously processed message for reprocessing. The message
+ * is reset to pending state and will be delivered again to consumers.
+ * Useful for retrying failed messages or reprocessing historical data.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID to replay (prefixed with msg_)
+ * @returns The replayed message with updated state
+ * @throws {QueueValidationError} If validation fails
+ * @throws {MessageNotFoundError} If the message does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const message = await replayMessage(client, 'order-queue', 'msg_abc123');
+ * console.log(`Message replayed, new state: ${message.state}`);
+ * ```
+ */
+export declare function replayMessage(client: APIClient, queueName: string, messageId: string, options?: QueueApiOptions): Promise<Message>;
+/**
+ * Consume messages from a queue starting at an offset.
+ *
+ * Retrieves messages for log-style consumption, starting from the specified
+ * offset. Unlike receive/ack flow, this does not mark messages as processing.
+ * Ideal for event sourcing or fan-out patterns where multiple consumers
+ * read the same messages.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param params - Consume parameters
+ * @param params.offset - Starting offset (0-based)
+ * @param params.limit - Maximum messages to return (optional, 1-1000)
+ * @returns Object containing the messages array
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Consume 100 messages starting at offset 500
+ * const result = await consumeMessages(client, 'events', {
+ *   offset: 500,
+ *   limit: 100,
+ * });
+ * for (const msg of result.messages) {
+ *   console.log(`Processing event at offset ${msg.offset}`);
+ * }
+ * ```
+ */
+export declare function consumeMessages(client: APIClient, queueName: string, params: ConsumeMessagesRequest, options?: QueueApiOptions): Promise<{
+    messages: Message[];
+}>;
+/**
+ * Get the head offset of a queue.
+ *
+ * Returns the offset of the oldest (first) message in the queue.
+ * Useful for determining the starting point for log-style consumption.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @returns The head offset (oldest message position)
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const head = await getQueueHead(client, 'events');
+ * console.log(`Queue starts at offset ${head}`);
+ * ```
+ */
+export declare function getQueueHead(client: APIClient, queueName: string, options?: QueueApiOptions): Promise<number>;
+/**
+ * Get the tail offset of a queue.
+ *
+ * Returns the offset of the newest (last) message in the queue.
+ * The next published message will have offset = tail + 1.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @returns The tail offset (newest message position)
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const tail = await getQueueTail(client, 'events');
+ * console.log(`Queue ends at offset ${tail}`);
+ * ```
+ */
+export declare function getQueueTail(client: APIClient, queueName: string, options?: QueueApiOptions): Promise<number>;
+/**
+ * Receive the next available message from a queue.
+ *
+ * Atomically retrieves and locks the next pending message for processing.
+ * The message state transitions to "processing" and must be acknowledged
+ * (ack) or negative-acknowledged (nack) when done. Supports long polling
+ * with an optional timeout.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param timeout - Optional timeout in seconds for long polling (0-30)
+ * @returns The received message, or null if no message is available
+ * @throws {QueueValidationError} If validation fails
+ * @throws {QueueNotFoundError} If the queue does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * // Receive with 10 second long poll
+ * const message = await receiveMessage(client, 'tasks', 10);
+ * if (message) {
+ *   console.log(`Received: ${message.id}`);
+ *   // Process message...
+ *   await ackMessage(client, 'tasks', message.id);
+ * }
+ * ```
+ */
+export declare function receiveMessage(client: APIClient, queueName: string, timeout?: number, options?: QueueApiOptions): Promise<Message | null>;
+/**
+ * Acknowledge successful processing of a message.
+ *
+ * Marks a message as successfully processed (completed state).
+ * Should be called after successfully processing a message received
+ * via receiveMessage. The message will not be redelivered.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID to acknowledge (prefixed with msg_)
+ * @returns void
+ * @throws {QueueValidationError} If validation fails
+ * @throws {MessageNotFoundError} If the message does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const message = await receiveMessage(client, 'tasks');
+ * if (message) {
+ *   try {
+ *     await processTask(message.payload);
+ *     await ackMessage(client, 'tasks', message.id);
+ *   } catch (error) {
+ *     await nackMessage(client, 'tasks', message.id);
+ *   }
+ * }
+ * ```
+ */
+export declare function ackMessage(client: APIClient, queueName: string, messageId: string, options?: QueueApiOptions): Promise<void>;
+/**
+ * Negative acknowledge a message (mark as failed).
+ *
+ * Returns a message to the queue for retry. The message state returns
+ * to pending and will be redelivered. Use when processing fails and
+ * the message should be retried. After max retries, the message moves
+ * to the dead letter queue.
+ *
+ * @param client - The API client instance
+ * @param queueName - The name of the queue
+ * @param messageId - The message ID to nack (prefixed with msg_)
+ * @returns void
+ * @throws {QueueValidationError} If validation fails
+ * @throws {MessageNotFoundError} If the message does not exist
+ * @throws {QueueError} If the API request fails
+ *
+ * @example
+ * ```typescript
+ * const message = await receiveMessage(client, 'tasks');
+ * if (message) {
+ *   try {
+ *     await processTask(message.payload);
+ *     await ackMessage(client, 'tasks', message.id);
+ *   } catch (error) {
+ *     // Processing failed, return to queue for retry
+ *     await nackMessage(client, 'tasks', message.id);
+ *   }
+ * }
+ * ```
+ */
+export declare function nackMessage(client: APIClient, queueName: string, messageId: string, options?: QueueApiOptions): Promise<void>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/services/queue/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/services/queue/messages.ts"],"names":[],"mappings":"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"}