@agentuity/queue 1.0.54

package/AGENTS.md

@@ -0,0 +1,37 @@
+# Agent Guidelines for @agentuity/queue
+
+## Package Overview
+
+Standalone package for the Agentuity Queue service. Provides a simple, ergonomic client for publishing messages to queues.
+
+## Commands
+
+- **Build**: `bun run build`
+- **Typecheck**: `bun run typecheck`
+- **Clean**: `rm -rf dist`
+
+## Architecture
+
+- **Runtime**: Node.js and Bun compatible
+- **Exports**: QueueClient and all types from @agentuity/core/queue
+- **Dependencies**: @agentuity/core, zod
+
+## Usage
+
+```typescript
+import { QueueClient } from '@agentuity/queue';
+
+const client = new QueueClient();
+
+// Create a queue
+await client.createQueue('my-queue');
+
+// Publish a message
+const result = await client.publish('my-queue', { task: 'process' });
+console.log(`Message ${result.id} published at offset ${result.offset}`);
+```
+
+## Publishing
+
+1. Run `bun run build`
+2. Must publish **after** @agentuity/core

package/README.md

@@ -0,0 +1,55 @@
+# @agentuity/queue
+
+A standalone package for the Agentuity Queue service.
+
+## Installation
+
+```bash
+npm install @agentuity/queue
+```
+
+## Quick Start
+
+```typescript
+import { QueueClient } from '@agentuity/queue';
+
+const client = new QueueClient();
+
+// Create a queue
+await client.createQueue('order-processing');
+
+// Publish a message
+const result = await client.publish('order-processing', {
+  orderId: 123,
+  action: 'process'
+}, {
+  metadata: { priority: 'high' },
+  ttl: 3600
+});
+
+console.log(`Message ${result.id} published`);
+
+// Delete a queue
+await client.deleteQueue('old-queue');
+```
+
+## Configuration
+
+```typescript
+const client = new QueueClient({
+  apiKey: 'your-api-key',
+  url: 'https://api.agentuity.com',
+});
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AGENTUITY_SDK_KEY` | API key for authentication | Required |
+| `AGENTUITY_REGION` | Region for API endpoints | `usc` |
+| `AGENTUITY_QUEUE_URL` | Override Queue API URL | Auto-detected |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { QueueStorageService, QueueService, type QueuePublishParams, type QueuePublishResult, type QueueCreateParams, type QueueCreateResult, QueuePublishParamsSchema, QueuePublishResultSchema, QueueCreateParamsSchema, QueueCreateResultSchema, QueuePublishError, QueueNotFoundError, QueueValidationError, } from '@agentuity/core/queue';
+import { type QueuePublishParams, type QueuePublishResult, type QueueCreateParams, type QueueCreateResult } from '@agentuity/core/queue';
+import { type Logger } from '@agentuity/server';
+import { z } from 'zod';
+export declare const QueueClientOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    orgId: z.ZodOptional<z.ZodString>;
+    logger: z.ZodOptional<z.ZodCustom<Logger, Logger>>;
+}, z.core.$strip>;
+export type QueueClientOptions = z.infer<typeof QueueClientOptionsSchema>;
+export declare class QueueClient {
+    #private;
+    constructor(options?: QueueClientOptions);
+    publish(queueName: string, payload: string | object, params?: QueuePublishParams): Promise<QueuePublishResult>;
+    createQueue(queueName: string, params?: QueueCreateParams): Promise<QueueCreateResult>;
+    deleteQueue(queueName: string): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,mBAAmB,EACnB,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAgD,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI9F,OAAO,EAAE,CAAC,EAAY,MAAM,KAAK,CAAC;AAclC,eAAO,MAAM,wBAAwB;;;;;iBAKnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,qBAAa,WAAW;;gBAGX,OAAO,GAAE,kBAAuB;IAoCtC,OAAO,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC;IAIxB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAItF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnD"}

package/dist/index.js

@@ -0,0 +1,61 @@
+export { QueueStorageService, QueuePublishParamsSchema, QueuePublishResultSchema, QueueCreateParamsSchema, QueueCreateResultSchema, QueuePublishError, QueueNotFoundError, QueueValidationError, } from '@agentuity/core/queue';
+import { QueueStorageService, } from '@agentuity/core/queue';
+import { createServerFetchAdapter, buildClientHeaders } from '@agentuity/server';
+import { createMinimalLogger, StructuredError } from '@agentuity/core';
+import { getEnv } from '@agentuity/core';
+import { getServiceUrls } from '@agentuity/core/config';
+import { z, ZodError } from 'zod';
+const isLogger = (val) => typeof val === 'object' &&
+    val !== null &&
+    ['info', 'warn', 'error', 'debug', 'trace'].every((m) => typeof val[m] === 'function');
+const QueueClientValidationError = StructuredError('QueueClientValidationError')();
+export const QueueClientOptionsSchema = z.object({
+    apiKey: z.string().optional().describe('API key for authentication'),
+    url: z.string().optional().describe('Base URL for the Queue API'),
+    orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
+    logger: z.custom(isLogger).optional().describe('Custom logger instance'),
+});
+export class QueueClient {
+    #service;
+    constructor(options = {}) {
+        let validatedOptions;
+        try {
+            validatedOptions = QueueClientOptionsSchema.parse(options);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                throw new QueueClientValidationError({
+                    message: 'Invalid QueueClient options',
+                    schema: 'QueueClientOptionsSchema',
+                    issues: err.issues.map((i) => ({
+                        path: i.path.join('.'),
+                        message: i.message,
+                    })),
+                    cause: err,
+                });
+            }
+            throw err;
+        }
+        const apiKey = validatedOptions.apiKey || getEnv('AGENTUITY_SDK_KEY') || getEnv('AGENTUITY_CLI_KEY');
+        const region = getEnv('AGENTUITY_REGION') ?? 'usc';
+        const serviceUrls = getServiceUrls(region);
+        const url = validatedOptions.url || getEnv('AGENTUITY_QUEUE_URL') || serviceUrls.catalyst;
+        const logger = validatedOptions.logger ?? createMinimalLogger();
+        const headers = buildClientHeaders({
+            apiKey,
+            orgId: validatedOptions.orgId,
+        });
+        const adapter = createServerFetchAdapter({ headers }, logger);
+        this.#service = new QueueStorageService(url, adapter);
+    }
+    async publish(queueName, payload, params) {
+        return this.#service.publish(queueName, payload, params);
+    }
+    async createQueue(queueName, params) {
+        return this.#service.createQueue(queueName, params);
+    }
+    async deleteQueue(queueName) {
+        return this.#service.deleteQueue(queueName);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,mBAAmB,EAMnB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,mBAAmB,GAKnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAe,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAElC,MAAM,QAAQ,GAAG,CAAC,GAAY,EAAiB,EAAE,CAChD,OAAO,GAAG,KAAK,QAAQ;IACvB,GAAG,KAAK,IAAI;IACZ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,OAAQ,GAA+B,CAAC,CAAC,CAAC,KAAK,UAAU,CAChE,CAAC;AAEH,MAAM,0BAA0B,GAAG,eAAe,CAAC,4BAA4B,CAAC,EAG5E,CAAC;AAEL,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACpE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACjE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;IACpF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAS,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;CAChF,CAAC,CAAC;AAGH,MAAM,OAAO,WAAW;IACd,QAAQ,CAAsB;IAEvC,YAAY,UAA8B,EAAE;QAC3C,IAAI,gBAAoC,CAAC;QACzC,IAAI,CAAC;YACJ,gBAAgB,GAAG,wBAAwB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,0BAA0B,CAAC;oBACpC,OAAO,EAAE,6BAA6B;oBACtC,MAAM,EAAE,0BAA0B;oBAClC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAC9B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;wBACtB,OAAO,EAAE,CAAC,CAAC,OAAO;qBAClB,CAAC,CAAC;oBACH,KAAK,EAAE,GAAG;iBACV,CAAC,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACX,CAAC;QACD,MAAM,MAAM,GACX,gBAAgB,CAAC,MAAM,IAAI,MAAM,CAAC,mBAAmB,CAAC,IAAI,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACvF,MAAM,MAAM,GAAG,MAAM,CAAC,kBAAkB,CAAC,IAAI,KAAK,CAAC;QACnD,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QAE3C,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,IAAI,MAAM,CAAC,qBAAqB,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC;QAE1F,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;QAEhE,MAAM,OAAO,GAAG,kBAAkB,CAAC;YAClC,MAAM;YACN,KAAK,EAAE,gBAAgB,CAAC,KAAK;SAC7B,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9D,IAAI,CAAC,QAAQ,GAAG,IAAI,mBAAmB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,OAAO,CACZ,SAAiB,EACjB,OAAwB,EACxB,MAA2B;QAE3B,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,SAAiB,EAAE,MAA0B;QAC9D,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,SAAiB;QAClC,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;CACD"}

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@agentuity/queue",
+	"version": "1.0.54",
+	"license": "Apache-2.0",
+	"author": "Agentuity employees and contributors",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"AGENTS.md",
+		"README.md",
+		"src",
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist tsconfig.tsbuildinfo",
+		"build": "bunx tsc --build --force",
+		"typecheck": "bunx tsc --noEmit",
+		"prepublishOnly": "bun run clean && bun run build"
+	},
+	"dependencies": {
+		"@agentuity/core": "1.0.54",
+		"@agentuity/server": "1.0.54",
+		"zod": "^4.3.5"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/node": "^22.0.0",
+		"bun-types": "latest",
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+export {
+	QueueStorageService,
+	QueueService,
+	type QueuePublishParams,
+	type QueuePublishResult,
+	type QueueCreateParams,
+	type QueueCreateResult,
+	QueuePublishParamsSchema,
+	QueuePublishResultSchema,
+	QueueCreateParamsSchema,
+	QueueCreateResultSchema,
+	QueuePublishError,
+	QueueNotFoundError,
+	QueueValidationError,
+} from '@agentuity/core/queue';
+
+import {
+	QueueStorageService,
+	type QueuePublishParams,
+	type QueuePublishResult,
+	type QueueCreateParams,
+	type QueueCreateResult,
+} from '@agentuity/core/queue';
+import { createServerFetchAdapter, buildClientHeaders, type Logger } from '@agentuity/server';
+import { createMinimalLogger, StructuredError } from '@agentuity/core';
+import { getEnv } from '@agentuity/core';
+import { getServiceUrls } from '@agentuity/core/config';
+import { z, ZodError } from 'zod';
+
+const isLogger = (val: unknown): val is Logger =>
+	typeof val === 'object' &&
+	val !== null &&
+	['info', 'warn', 'error', 'debug', 'trace'].every(
+		(m) => typeof (val as Record<string, unknown>)[m] === 'function'
+	);
+
+const QueueClientValidationError = StructuredError('QueueClientValidationError')<{
+	schema: string;
+	issues: Array<{ path: string; message: string }>;
+}>();
+
+export const QueueClientOptionsSchema = z.object({
+	apiKey: z.string().optional().describe('API key for authentication'),
+	url: z.string().optional().describe('Base URL for the Queue API'),
+	orgId: z.string().optional().describe('Organization ID for multi-tenant operations'),
+	logger: z.custom<Logger>(isLogger).optional().describe('Custom logger instance'),
+});
+export type QueueClientOptions = z.infer<typeof QueueClientOptionsSchema>;
+
+export class QueueClient {
+	readonly #service: QueueStorageService;
+
+	constructor(options: QueueClientOptions = {}) {
+		let validatedOptions: QueueClientOptions;
+		try {
+			validatedOptions = QueueClientOptionsSchema.parse(options);
+		} catch (err) {
+			if (err instanceof ZodError) {
+				throw new QueueClientValidationError({
+					message: 'Invalid QueueClient options',
+					schema: 'QueueClientOptionsSchema',
+					issues: err.issues.map((i) => ({
+						path: i.path.join('.'),
+						message: i.message,
+					})),
+					cause: err,
+				});
+			}
+			throw err;
+		}
+		const apiKey =
+			validatedOptions.apiKey || getEnv('AGENTUITY_SDK_KEY') || getEnv('AGENTUITY_CLI_KEY');
+		const region = getEnv('AGENTUITY_REGION') ?? 'usc';
+		const serviceUrls = getServiceUrls(region);
+
+		const url = validatedOptions.url || getEnv('AGENTUITY_QUEUE_URL') || serviceUrls.catalyst;
+
+		const logger = validatedOptions.logger ?? createMinimalLogger();
+
+		const headers = buildClientHeaders({
+			apiKey,
+			orgId: validatedOptions.orgId,
+		});
+
+		const adapter = createServerFetchAdapter({ headers }, logger);
+		this.#service = new QueueStorageService(url, adapter);
+	}
+
+	async publish(
+		queueName: string,
+		payload: string | object,
+		params?: QueuePublishParams
+	): Promise<QueuePublishResult> {
+		return this.#service.publish(queueName, payload, params);
+	}
+
+	async createQueue(queueName: string, params?: QueueCreateParams): Promise<QueueCreateResult> {
+		return this.#service.createQueue(queueName, params);
+	}
+
+	async deleteQueue(queueName: string): Promise<void> {
+		return this.#service.deleteQueue(queueName);
+	}
+}