@agentuity/queue 3.0.11 → 3.1.0

package/AGENTS.md

@@ -13,8 +13,8 @@ Standalone package for the Agentuity Queue service. Provides a simple, ergonomic
 ## Architecture
 
 - **Runtime**: Node.js and Bun compatible
-- **Exports**: QueueClient and all types from @agentuity/core/queue
-- **Dependencies**: @agentuity/core, zod
+- **Exports**: QueueClient and runtime types from `@agentuity/queue`
+- **Dependencies**: `@agentuity/adapter`, `@agentuity/client`, `@agentuity/config`, zod
 
 ## Usage
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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/adapter';
+export * from './service.ts';
+import { type QueuePublishParams, type QueuePublishResult, type QueueCreateParams, type QueueCreateResult } from './service.ts';
+import { type Logger } from '@agentuity/client';
 import { z } from 'zod';
 export declare const QueueClientOptionsSchema: z.ZodObject<{
     apiKey: z.ZodOptional<z.ZodString>;

package/dist/index.d.ts.map

@@ -1 +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,oBAAoB,CAAC;AAI/F,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;;IAGvB,YAAY,OAAO,GAAE,kBAAuB,EAkC3C;IAEK,OAAO,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAE7B;IAEK,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE3F;IAEK,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;CACD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAMN,KAAK,MAAM,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,CAAC,EAAY,MAAM,KAAK,CAAC;AAOlC,eAAO,MAAM,wBAAwB;;;;;iBAKnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,qBAAa,WAAW;;IAGvB,YAAY,OAAO,GAAE,kBAAuB,EA+B3C;IAEK,OAAO,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAE7B;IAEK,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE3F;IAEK,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElD;CACD"}

package/dist/index.js

@@ -1,13 +1,9 @@
-export { QueueStorageService, QueuePublishParamsSchema, QueuePublishResultSchema, QueueCreateParamsSchema, QueueCreateResultSchema, QueuePublishError, QueueNotFoundError, QueueValidationError, } from '@agentuity/core/queue';
-import { QueueStorageService, } from '@agentuity/core/queue';
-import { createServerFetchAdapter, buildClientHeaders } from '@agentuity/adapter';
-import { createMinimalLogger, StructuredError } from '@agentuity/core';
-import { getEnv } from '@agentuity/core';
-import { getServiceUrls } from '@agentuity/core/config';
+export * from './service.js';
+import { QueueStorageService, } from './service.js';
+import { StructuredError } from '@agentuity/adapter';
+import { getServiceUrls } from '@agentuity/config';
+import { createServiceAdapter, isLogger, resolveApiKey, resolveRegion, resolveServiceUrl, } from '@agentuity/client';
 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'),
@@ -36,16 +32,18 @@ export class QueueClient {
             }
             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({
+        const apiKey = resolveApiKey(validatedOptions.apiKey);
+        const serviceUrls = getServiceUrls(resolveRegion());
+        const url = resolveServiceUrl({
+            url: validatedOptions.url,
+            envKey: 'AGENTUITY_QUEUE_URL',
+            fallback: serviceUrls.catalyst,
+        });
+        const { adapter } = createServiceAdapter({
             apiKey,
             orgId: validatedOptions.orgId,
+            logger: validatedOptions.logger,
         });
-        const adapter = createServerFetchAdapter({ headers }, logger);
         this.#service = new QueueStorageService(url, adapter);
     }
     async publish(queueName, payload, params) {

package/dist/index.js.map

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

package/dist/service.d.ts

@@ -0,0 +1,335 @@
+/**
+ * @module queue
+ *
+ * Queue service for publishing messages to Agentuity queues.
+ *
+ * Used internally by `@agentuity/queue`'s `QueueClient`. App code should
+ * use `QueueClient` directly rather than reaching for these primitives.
+ *
+ * @example
+ * ```typescript
+ * import { QueueClient } from '@agentuity/queue';
+ *
+ * const queue = new QueueClient();
+ * const result = await queue.publish('order-queue', {
+ *   orderId: 123,
+ *   action: 'process',
+ * });
+ * console.log(`Published message ${result.id}`);
+ * ```
+ */
+import type { FetchAdapter } from '@agentuity/adapter';
+import { z } from 'zod';
+/**
+ * Parameters for publishing a message to a queue.
+ *
+ * @example
+ * ```typescript
+ * const params: QueuePublishParams = {
+ *   metadata: { priority: 'high' },
+ *   partitionKey: 'customer-123',
+ *   idempotencyKey: 'order-456-v1',
+ *   ttl: 3600, // 1 hour
+ * };
+ * ```
+ */
+export declare const QueuePublishParamsSchema: z.ZodObject<{
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    partitionKey: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    ttl: z.ZodOptional<z.ZodNumber>;
+    projectId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    sync: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type QueuePublishParams = z.infer<typeof QueuePublishParamsSchema>;
+/**
+ * Result of publishing a message to a queue.
+ *
+ * @example
+ * ```typescript
+ * const result = await queue.publish('my-queue', payload);
+ * console.log(`Message ${result.id} published at offset ${result.offset}`);
+ * ```
+ */
+export declare const QueuePublishResultSchema: z.ZodObject<{
+    id: z.ZodString;
+    offset: z.ZodNumber;
+    publishedAt: z.ZodString;
+}, z.core.$strip>;
+export type QueuePublishResult = z.infer<typeof QueuePublishResultSchema>;
+/**
+ * Parameters for creating a queue.
+ *
+ * @example
+ * ```typescript
+ * const result = await queue.createQueue('my-queue', {
+ *   queueType: 'pubsub',
+ *   settings: { defaultTtlSeconds: 86400 },
+ * });
+ * ```
+ */
+export declare const QueueCreateParamsSchema: z.ZodObject<{
+    queueType: z.ZodOptional<z.ZodEnum<{
+        pubsub: "pubsub";
+        worker: "worker";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    settings: z.ZodOptional<z.ZodObject<{
+        defaultTtlSeconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        defaultVisibilityTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        defaultMaxRetries: z.ZodOptional<z.ZodNumber>;
+        maxInFlightPerClient: z.ZodOptional<z.ZodNumber>;
+        retentionSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type QueueCreateParams = z.infer<typeof QueueCreateParamsSchema>;
+/**
+ * Result of creating a queue.
+ */
+export declare const QueueCreateResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    queueType: z.ZodString;
+}, z.core.$strip>;
+export type QueueCreateResult = z.infer<typeof QueueCreateResultSchema>;
+/**
+ * Queue service interface for publishing messages.
+ *
+ * Provides a simple publish-only surface suitable for app handlers.
+ * Implemented by `QueueStorageService` (cloud) and `LocalQueueStorage`
+ * (local dev).
+ *
+ * For full queue management (create queues, consume messages, manage
+ * destinations), use the `@agentuity/queue` package directly.
+ *
+ * @example
+ * ```typescript
+ * import { QueueClient } from '@agentuity/queue';
+ *
+ * const queue = new QueueClient();
+ *
+ * await queue.publish('notifications', {
+ *   type: 'email',
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ * });
+ * ```
+ */
+export interface QueueService {
+    /**
+     * Publish a message to a queue.
+     *
+     * The payload can be a string or an object. Objects are automatically
+     * JSON-stringified before publishing.
+     *
+     * @param queueName - The name of the queue to publish to
+     * @param payload - The message payload (string or JSON-serializable object)
+     * @param params - Optional publish parameters (metadata, TTL, etc.)
+     * @returns The publish result with message ID and offset
+     * @throws {QueueNotFoundError} If the queue does not exist
+     * @throws {QueueValidationError} If validation fails (invalid name, payload too large, etc.)
+     * @throws {QueuePublishError} If the publish operation fails
+     *
+     * @example Publishing a simple message
+     * ```typescript
+     * const result = await queue.publish('my-queue', 'Hello, World!');
+     * ```
+     *
+     * @example Publishing with options
+     * ```typescript
+     * const result = await queue.publish('my-queue', { task: 'process' }, {
+     *   metadata: { priority: 'high' },
+     *   idempotencyKey: 'task-123',
+     *   ttl: 3600,
+     * });
+     * ```
+     */
+    publish(queueName: string, payload: string | object, params?: QueuePublishParams): Promise<QueuePublishResult>;
+    /**
+     * Create a queue with idempotent semantics.
+     *
+     * If the queue already exists, this returns successfully without error.
+     * Safe to call multiple times — uses an internal cache to avoid redundant API calls.
+     *
+     * @param queueName - The name of the queue to create
+     * @param params - Optional creation parameters (queue type, settings, etc.)
+     * @returns The create result with queue name and type
+     * @throws {QueueValidationError} If the queue name is invalid
+     *
+     * @example Creating a worker queue
+     * ```typescript
+     * const result = await queue.createQueue('task-queue');
+     * ```
+     *
+     * @example Creating a pubsub queue with settings
+     * ```typescript
+     * const result = await queue.createQueue('events', {
+     *   queueType: 'pubsub',
+     *   settings: { defaultTtlSeconds: 86400 },
+     * });
+     * ```
+     */
+    createQueue(queueName: string, params?: QueueCreateParams): Promise<QueueCreateResult>;
+    /**
+     * Delete a queue.
+     *
+     * Permanently deletes a queue and all its messages. This action cannot be undone.
+     * If the queue has already been deleted or does not exist, a {@link QueueNotFoundError} is thrown.
+     *
+     * @param queueName - The name of the queue to delete
+     * @throws {QueueNotFoundError} If the queue does not exist
+     * @throws {QueueValidationError} If the queue name is invalid
+     *
+     * @example Deleting a queue
+     * ```typescript
+     * await queue.deleteQueue('old-queue');
+     * ```
+     */
+    deleteQueue(queueName: string): Promise<void>;
+}
+/**
+ * Error thrown when a publish operation fails.
+ *
+ * This is a general error for publish failures that aren't specifically
+ * validation or not-found errors.
+ */
+export declare const QueuePublishError: {
+    new (args?: {
+        message?: string;
+        cause?: unknown;
+    } | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueuePublishError";
+    } & Readonly<Record<string, never>>;
+    readonly defaultMessage?: string;
+} & (<Shape extends {
+    [x: string]: any;
+} = Record<string, never>>() => {
+    new (args?: (Shape extends Record<string, never> ? {
+        message?: string;
+        cause?: unknown;
+    } : Shape & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueuePublishError";
+    } & Readonly<Shape>;
+    readonly defaultMessage?: string;
+});
+/**
+ * Error thrown when a queue creation operation fails.
+ *
+ * This is a general error for create failures that aren't specifically
+ * validation, not-found, or conflict (409) errors.
+ */
+export declare const QueueCreateError: {
+    new (args?: {
+        message?: string;
+        cause?: unknown;
+    } | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueueCreateError";
+    } & Readonly<Record<string, never>>;
+    readonly defaultMessage?: string;
+} & (<Shape extends {
+    [x: string]: any;
+} = Record<string, never>>() => {
+    new (args?: (Shape extends Record<string, never> ? {
+        message?: string;
+        cause?: unknown;
+    } : Shape & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueueCreateError";
+    } & Readonly<Shape>;
+    readonly defaultMessage?: string;
+});
+/**
+ * Error thrown when a queue is not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await queue.publish('non-existent', 'payload');
+ * } catch (error) {
+ *   if (error instanceof QueueNotFoundError) {
+ *     console.error('Queue does not exist');
+ *   }
+ * }
+ * ```
+ */
+export declare const QueueNotFoundError: {
+    new (args?: {
+        message?: string;
+        cause?: unknown;
+    } | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueueNotFoundError";
+    } & Readonly<Record<string, never>>;
+    readonly defaultMessage?: string;
+} & (<Shape extends {
+    [x: string]: any;
+} = Record<string, never>>() => {
+    new (args?: (Shape extends Record<string, never> ? {
+        message?: string;
+        cause?: unknown;
+    } : Shape & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueueNotFoundError";
+    } & Readonly<Shape>;
+    readonly defaultMessage?: string;
+});
+/**
+ * Error thrown when validation fails.
+ *
+ * Contains the field name and optionally the invalid value for debugging.
+ */
+export declare const QueueValidationError: {
+    new (args?: ({
+        /** The field that failed validation */
+        field: string;
+        /** The invalid value (for debugging) */
+        value?: unknown;
+    } & {
+        message?: string;
+        cause?: unknown;
+    }) | undefined): import("@agentuity/adapter").RichError & {
+        readonly _tag: "QueueValidationError";
+    } & Readonly<{
+        /** The field that failed validation */
+        field: string;
+        /** The invalid value (for debugging) */
+        value?: unknown;
+    }>;
+    readonly defaultMessage?: string;
+};
+/**
+ * HTTP-based implementation of the {@link QueueService} interface.
+ *
+ * This service communicates with the Agentuity Queue API to publish
+ * messages. App code should use `QueueClient` from `@agentuity/queue`
+ * rather than instantiating this class directly.
+ */
+export declare class QueueStorageService implements QueueService {
+    #private;
+    /**
+     * Creates a new QueueStorageService.
+     *
+     * @param baseUrl - The base URL of the Queue API
+     * @param adapter - The fetch adapter for making HTTP requests
+     */
+    constructor(baseUrl: string, adapter: FetchAdapter);
+    /**
+     * @inheritdoc
+     */
+    publish(queueName: string, payload: string | object, params?: QueuePublishParams): Promise<QueuePublishResult>;
+    /**
+     * @inheritdoc
+     */
+    createQueue(queueName: string, params?: QueueCreateParams): Promise<QueueCreateResult>;
+    /**
+     * @inheritdoc
+     */
+    deleteQueue(queueName: string): Promise<void>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;iBA8CnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB;;;;iBAiBnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;iBAiDlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;iBAKlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CACN,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEvF;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAMD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAAuC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAAsC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAAwC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;QAChC,uCAAuC;eAChC,MAAM;QACb,wCAAwC;gBAChC,OAAO;;;;;;;QAHf,uCAAuC;;QAEvC,wCAAwC;;;;CAErC,CAAC;AAsFL;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,YAAY;;IAKvD;;;;;OAKG;IACH,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAGjD;IAED;;OAEG;IACG,OAAO,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,CAAC,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CA6F7B;IAED;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAkF3F;IAED;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BlD;CACD"}