dooor-shared-config 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./topics";
-export * from "./messages";
-export * from "./pubsubClient";
+export { SERVICES, getRequestTopic, getResponseTopic, parseResponseTopic, isRequestTopic, isResponseTopic, type ServiceKey, type ServiceTopic, } from "./topics";
+export { createEnvelope, type AtlasEnvelope, type IngestionRequestPayload, type IngestionRequestMessage, type IngestionResponsePayload, type IngestionResponseMessage, type AiRequestPayload, type AiRequestMessage, type AiResponsePayload, type AiResponseMessage, type ExtractionRequestPayload, type ExtractionRequestMessage, type ExtractionResponsePayload, type ExtractionResponseMessage, type AtlasRequestMessage, type AtlasResponseMessage, type AtlasMessage, type AtlasRequestPayload, type AtlasResponsePayload, } from "./messages";
+export { getPubSubClient, resetPubSubClient, getTopic, getServiceRequestTopic, getServiceResponseTopic, publishJson, publishRequest, publishResponse, subscribeToRequests, subscribeToResponses, createMessageConsumer, type MessageHandler, } from "./pubsubClient";

package/dist/index.js

@@ -1,20 +1,28 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./topics"), exports);
-__exportStar(require("./messages"), exports);
-__exportStar(require("./pubsubClient"), exports);
+exports.createMessageConsumer = exports.subscribeToResponses = exports.subscribeToRequests = exports.publishResponse = exports.publishRequest = exports.publishJson = exports.getServiceResponseTopic = exports.getServiceRequestTopic = exports.getTopic = exports.resetPubSubClient = exports.getPubSubClient = exports.createEnvelope = exports.isResponseTopic = exports.isRequestTopic = exports.parseResponseTopic = exports.getResponseTopic = exports.getRequestTopic = exports.SERVICES = void 0;
+// Topics and topic utilities
+var topics_1 = require("./topics");
+Object.defineProperty(exports, "SERVICES", { enumerable: true, get: function () { return topics_1.SERVICES; } });
+Object.defineProperty(exports, "getRequestTopic", { enumerable: true, get: function () { return topics_1.getRequestTopic; } });
+Object.defineProperty(exports, "getResponseTopic", { enumerable: true, get: function () { return topics_1.getResponseTopic; } });
+Object.defineProperty(exports, "parseResponseTopic", { enumerable: true, get: function () { return topics_1.parseResponseTopic; } });
+Object.defineProperty(exports, "isRequestTopic", { enumerable: true, get: function () { return topics_1.isRequestTopic; } });
+Object.defineProperty(exports, "isResponseTopic", { enumerable: true, get: function () { return topics_1.isResponseTopic; } });
+// Message types and helpers
+var messages_1 = require("./messages");
+Object.defineProperty(exports, "createEnvelope", { enumerable: true, get: function () { return messages_1.createEnvelope; } });
+// PubSub client and utilities
+var pubsubClient_1 = require("./pubsubClient");
+Object.defineProperty(exports, "getPubSubClient", { enumerable: true, get: function () { return pubsubClient_1.getPubSubClient; } });
+Object.defineProperty(exports, "resetPubSubClient", { enumerable: true, get: function () { return pubsubClient_1.resetPubSubClient; } });
+Object.defineProperty(exports, "getTopic", { enumerable: true, get: function () { return pubsubClient_1.getTopic; } });
+Object.defineProperty(exports, "getServiceRequestTopic", { enumerable: true, get: function () { return pubsubClient_1.getServiceRequestTopic; } });
+Object.defineProperty(exports, "getServiceResponseTopic", { enumerable: true, get: function () { return pubsubClient_1.getServiceResponseTopic; } });
+Object.defineProperty(exports, "publishJson", { enumerable: true, get: function () { return pubsubClient_1.publishJson; } });
+Object.defineProperty(exports, "publishRequest", { enumerable: true, get: function () { return pubsubClient_1.publishRequest; } });
+Object.defineProperty(exports, "publishResponse", { enumerable: true, get: function () { return pubsubClient_1.publishResponse; } });
+Object.defineProperty(exports, "subscribeToRequests", { enumerable: true, get: function () { return pubsubClient_1.subscribeToRequests; } });
+Object.defineProperty(exports, "subscribeToResponses", { enumerable: true, get: function () { return pubsubClient_1.subscribeToResponses; } });
+Object.defineProperty(exports, "createMessageConsumer", { enumerable: true, get: function () { return pubsubClient_1.createMessageConsumer; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,6CAA2B;AAC3B,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6BAA6B;AAC7B,mCASkB;AARhB,kGAAA,QAAQ,OAAA;AACR,yGAAA,eAAe,OAAA;AACf,0GAAA,gBAAgB,OAAA;AAChB,4GAAA,kBAAkB,OAAA;AAClB,wGAAA,cAAc,OAAA;AACd,yGAAA,eAAe,OAAA;AAKjB,4BAA4B;AAC5B,uCAoBoB;AAnBlB,0GAAA,cAAc,OAAA;AAqBhB,8BAA8B;AAC9B,+CAawB;AAZtB,+GAAA,eAAe,OAAA;AACf,iHAAA,iBAAiB,OAAA;AACjB,wGAAA,QAAQ,OAAA;AACR,sHAAA,sBAAsB,OAAA;AACtB,uHAAA,uBAAuB,OAAA;AACvB,2GAAA,WAAW,OAAA;AACX,8GAAA,cAAc,OAAA;AACd,+GAAA,eAAe,OAAA;AACf,mHAAA,mBAAmB,OAAA;AACnB,oHAAA,oBAAoB,OAAA;AACpB,qHAAA,qBAAqB,OAAA"}

package/dist/messages.d.ts

@@ -5,11 +5,12 @@
  */
 export interface AtlasEnvelope<TPayload = unknown> {
     /**
-     * High-level action being performed, e.g. INGEST, RAG.
+     * High-level action being performed, e.g. INGEST, RAG, EXTRACT.
      */
     action: string;
     /**
-     * Logical source application, e.g. "scaffold".
+     * Logical source application, e.g. "scaffold", "myapp".
+     * Used to determine the response topic.
      */
     appId: string;
     /**
@@ -26,31 +27,49 @@ export interface AtlasEnvelope<TPayload = unknown> {
     payload: TPayload;
 }
 /**
- * Message contracts per topic, based on the high-level flows
- * in the sequence diagram.
+ * Helper to create a new envelope with current timestamp
  */
-export interface FileUploadPayload {
+export declare function createEnvelope<TPayload>(action: string, appId: string, correlationId: string, payload: TPayload): AtlasEnvelope<TPayload>;
+export interface IngestionRequestPayload {
     /**
-     * Identifier of the uploaded file in the upstream app (Scaffold).
-     * Can be used by Ingestion to call Cortex /records.create.
+     * Identifier of the uploaded file in the upstream app.
      */
     uploadId: string;
     fileName?: string;
     mimeType?: string;
     sizeBytes?: number;
+    /**
+     * Optional: database in CortexDB to store the record
+     */
+    database?: string;
+    /**
+     * Optional: collection in CortexDB
+     */
+    collection?: string;
 }
-export interface FileUploadMessage extends AtlasEnvelope<FileUploadPayload> {
-    topic: "file-upload.scaffold";
+export interface IngestionRequestMessage extends AtlasEnvelope<IngestionRequestPayload> {
     action: "INGEST";
 }
-export interface FileReadyPayload {
+export interface IngestionResponsePayload {
     /**
-     * Identifier of the record inside CortexDB.
+     * Status of the ingestion: success, error, processing
      */
-    recordId: string;
+    status: "success" | "error" | "processing";
+    /**
+     * Record ID in CortexDB (if successful)
+     */
+    recordId?: string;
+    /**
+     * Error message (if failed)
+     */
+    error?: string;
+    /**
+     * Original upload ID for correlation
+     */
+    uploadId: string;
 }
-export interface FileReadyMessage extends AtlasEnvelope<FileReadyPayload> {
-    topic: "file-ready.scaffold";
+export interface IngestionResponseMessage extends AtlasEnvelope<IngestionResponsePayload> {
+    action: "INGEST_RESPONSE";
 }
 export interface AiRequestPayload {
     /**
@@ -61,9 +80,16 @@ export interface AiRequestPayload {
      * Optional record or file that should scope the RAG context.
      */
     recordId?: string;
+    /**
+     * Optional: specific database to search
+     */
+    database?: string;
+    /**
+     * Optional: specific collection to search
+     */
+    collection?: string;
 }
 export interface AiRequestMessage extends AtlasEnvelope<AiRequestPayload> {
-    topic: "ai-request.scaffold";
     action: "RAG";
 }
 export interface AiResponsePayload {
@@ -75,26 +101,68 @@ export interface AiResponsePayload {
      * Optional trace identifier for debugging.
      */
     traceId?: string;
+    /**
+     * Sources used to generate the response
+     */
+    sources?: Array<{
+        recordId: string;
+        snippet?: string;
+        score?: number;
+    }>;
 }
 export interface AiResponseMessage extends AtlasEnvelope<AiResponsePayload> {
-    topic: "ai-response.scaffold";
+    action: "RAG_RESPONSE";
+}
+export interface ExtractionRequestPayload {
+    /**
+     * The record in CortexDB to extract insights from
+     */
+    recordId: string;
+    /**
+     * Optional: AI response text to extract insights from
+     */
+    aiResponseText?: string;
+    /**
+     * Optional: specific extraction types to perform
+     */
+    extractionTypes?: string[];
 }
-export interface InsightReadyPayload {
+export interface ExtractionRequestMessage extends AtlasEnvelope<ExtractionRequestPayload> {
+    action: "EXTRACT";
+}
+export interface ExtractionResponsePayload {
+    /**
+     * Status of the extraction
+     */
+    status: "success" | "error" | "processing";
     /**
-     * The record in CortexDB that these insights belong to.
+     * The record these insights belong to
      */
     recordId: string;
     /**
-     * Structured KPIs / metrics extracted from the AI response.
+     * Structured KPIs / metrics extracted.
      * Shape is intentionally open so teams can iterate quickly.
      */
-    insights: Record<string, unknown>;
+    insights?: Record<string, unknown>;
+    /**
+     * Error message (if failed)
+     */
+    error?: string;
 }
-export interface InsightReadyMessage extends AtlasEnvelope<InsightReadyPayload> {
-    topic: "insight-ready.scaffold";
+export interface ExtractionResponseMessage extends AtlasEnvelope<ExtractionResponsePayload> {
+    action: "EXTRACT_RESPONSE";
 }
 /**
- * Union type for any ATLAS message.
+ * Union type for request messages (sent TO services)
+ */
+export type AtlasRequestMessage = IngestionRequestMessage | AiRequestMessage | ExtractionRequestMessage;
+/**
+ * Union type for response messages (sent FROM services)
+ */
+export type AtlasResponseMessage = IngestionResponseMessage | AiResponseMessage | ExtractionResponseMessage;
+/**
+ * Union type for any ATLAS message
  */
-export type AtlasMessage = FileUploadMessage | FileReadyMessage | AiRequestMessage | AiResponseMessage | InsightReadyMessage;
-export type AtlasPayload = FileUploadPayload | FileReadyPayload | AiRequestPayload | AiResponsePayload | InsightReadyPayload;
+export type AtlasMessage = AtlasRequestMessage | AtlasResponseMessage;
+export type AtlasRequestPayload = IngestionRequestPayload | AiRequestPayload | ExtractionRequestPayload;
+export type AtlasResponsePayload = IngestionResponsePayload | AiResponsePayload | ExtractionResponsePayload;

package/dist/messages.js

@@ -1,3 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnvelope = createEnvelope;
+/**
+ * Helper to create a new envelope with current timestamp
+ */
+function createEnvelope(action, appId, correlationId, payload) {
+    return {
+        action,
+        appId,
+        correlationId,
+        timestamp: new Date().toISOString(),
+        payload,
+    };
+}
 //# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":""}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":";;AAsCA,wCAaC;AAhBD;;GAEG;AACH,SAAgB,cAAc,CAC5B,MAAc,EACd,KAAa,EACb,aAAqB,EACrB,OAAiB;IAEjB,OAAO;QACL,MAAM;QACN,KAAK;QACL,aAAa;QACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/pubsubClient.d.ts

@@ -1,14 +1,114 @@
-import { PubSub, type ClientConfig, type Topic } from "@google-cloud/pubsub";
-import { TOPICS, type TopicName } from "./topics";
+import { PubSub, type ClientConfig, type Topic, type Subscription, type Message } from "@google-cloud/pubsub";
+import { SERVICES, getRequestTopic, getResponseTopic, type ServiceKey } from "./topics";
+import type { AtlasEnvelope } from "./messages";
 /**
  * Creates (or returns a cached) PubSub client.
  * Configuration is driven by standard Google environment variables
  * (GOOGLE_CLOUD_PROJECT, credentials, PUBSUB_EMULATOR_HOST, etc).
  */
 export declare function getPubSubClient(options?: ClientConfig): PubSub;
-export declare function getTopic(topicName: TopicName, options?: ClientConfig): Topic;
 /**
- * Helper to publish a JSON-encoded message with optional attributes.
+ * Reset the cached PubSub client (useful for testing)
  */
-export declare function publishJson(topicName: TopicName, message: unknown, attributes?: Record<string, string>, pubSubOptions?: ClientConfig): Promise<string>;
-export { TOPICS };
+export declare function resetPubSubClient(): void;
+/**
+ * Get a topic reference by name
+ */
+export declare function getTopic(topicName: string, options?: ClientConfig): Topic;
+/**
+ * Get the request topic for a service
+ */
+export declare function getServiceRequestTopic(service: ServiceKey, options?: ClientConfig): Topic;
+/**
+ * Get the response topic for a service + app combination
+ */
+export declare function getServiceResponseTopic(service: ServiceKey, appId: string, options?: ClientConfig): Topic;
+/**
+ * Helper to publish a JSON-encoded message to any topic
+ */
+export declare function publishJson(topicName: string, message: unknown, attributes?: Record<string, string>, pubSubOptions?: ClientConfig): Promise<string>;
+/**
+ * Publish a request message to a service
+ *
+ * @example
+ * await publishRequest("ingestion", {
+ *   action: "INGEST",
+ *   appId: "scaffold",
+ *   correlationId: "uuid-123",
+ *   timestamp: new Date().toISOString(),
+ *   payload: { uploadId: "file-123" }
+ * });
+ */
+export declare function publishRequest<T>(service: ServiceKey, message: AtlasEnvelope<T>, attributes?: Record<string, string>, pubSubOptions?: ClientConfig): Promise<string>;
+/**
+ * Publish a response message back to the requesting app.
+ * Uses the appId from the original request to determine the response topic.
+ *
+ * @example
+ * // Service receives a request with appId: "scaffold"
+ * // Service publishes response to "ingestion-service-response.scaffold"
+ * await publishResponse("ingestion", "scaffold", {
+ *   action: "INGEST_RESPONSE",
+ *   appId: "ingestion-service",
+ *   correlationId: "uuid-123",
+ *   timestamp: new Date().toISOString(),
+ *   payload: { status: "success", recordId: "rec-456", uploadId: "file-123" }
+ * });
+ */
+export declare function publishResponse<T>(service: ServiceKey, targetAppId: string, message: AtlasEnvelope<T>, attributes?: Record<string, string>, pubSubOptions?: ClientConfig): Promise<string>;
+/**
+ * Subscribe to a service's request topic.
+ * Returns the subscription for attaching message handlers.
+ *
+ * @param service - The service to subscribe to
+ * @param subscriptionName - Name of the subscription (will be created if it doesn't exist)
+ * @param options - PubSub client options
+ *
+ * @example
+ * const sub = await subscribeToRequests("ingestion", "ingestion-service-sub");
+ * sub.on("message", (message) => {
+ *   const data = JSON.parse(message.data.toString());
+ *   // Process request...
+ *   message.ack();
+ * });
+ */
+export declare function subscribeToRequests(service: ServiceKey, subscriptionName: string, options?: ClientConfig): Promise<Subscription>;
+/**
+ * Subscribe to responses for a specific app.
+ * This is used by apps to receive responses from services.
+ *
+ * @param service - The service to receive responses from
+ * @param appId - The app's identifier
+ * @param subscriptionName - Name of the subscription
+ * @param options - PubSub client options
+ *
+ * @example
+ * // App "scaffold" subscribes to responses from ingestion service
+ * const sub = await subscribeToResponses("ingestion", "scaffold", "scaffold-ingestion-responses");
+ * sub.on("message", (message) => {
+ *   const data = JSON.parse(message.data.toString());
+ *   // Handle response...
+ *   message.ack();
+ * });
+ */
+export declare function subscribeToResponses(service: ServiceKey, appId: string, subscriptionName: string, options?: ClientConfig): Promise<Subscription>;
+/**
+ * Helper type for message handlers
+ */
+export type MessageHandler<T> = (envelope: AtlasEnvelope<T>, message: Message, ack: () => void, nack: () => void) => Promise<void> | void;
+/**
+ * Create a simple message consumer that handles JSON parsing and error handling
+ *
+ * @example
+ * const subscription = await subscribeToRequests("ingestion", "ingestion-sub");
+ * createMessageConsumer(subscription, async (envelope, message, ack, nack) => {
+ *   try {
+ *     // Process the envelope...
+ *     ack();
+ *   } catch (err) {
+ *     nack();
+ *   }
+ * });
+ */
+export declare function createMessageConsumer<T>(subscription: Subscription, handler: MessageHandler<T>, onError?: (error: Error, message: Message) => void): void;
+export { SERVICES, getRequestTopic, getResponseTopic };

package/dist/pubsubClient.js

@@ -1,12 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOPICS = void 0;
+exports.getResponseTopic = exports.getRequestTopic = exports.SERVICES = void 0;
 exports.getPubSubClient = getPubSubClient;
+exports.resetPubSubClient = resetPubSubClient;
 exports.getTopic = getTopic;
+exports.getServiceRequestTopic = getServiceRequestTopic;
+exports.getServiceResponseTopic = getServiceResponseTopic;
 exports.publishJson = publishJson;
+exports.publishRequest = publishRequest;
+exports.publishResponse = publishResponse;
+exports.subscribeToRequests = subscribeToRequests;
+exports.subscribeToResponses = subscribeToResponses;
+exports.createMessageConsumer = createMessageConsumer;
 const pubsub_1 = require("@google-cloud/pubsub");
 const topics_1 = require("./topics");
-Object.defineProperty(exports, "TOPICS", { enumerable: true, get: function () { return topics_1.TOPICS; } });
+Object.defineProperty(exports, "SERVICES", { enumerable: true, get: function () { return topics_1.SERVICES; } });
+Object.defineProperty(exports, "getRequestTopic", { enumerable: true, get: function () { return topics_1.getRequestTopic; } });
+Object.defineProperty(exports, "getResponseTopic", { enumerable: true, get: function () { return topics_1.getResponseTopic; } });
 let cachedPubSub = null;
 /**
  * Creates (or returns a cached) PubSub client.
@@ -19,16 +29,173 @@ function getPubSubClient(options) {
     }
     return cachedPubSub;
 }
+/**
+ * Reset the cached PubSub client (useful for testing)
+ */
+function resetPubSubClient() {
+    cachedPubSub = null;
+}
+/**
+ * Get a topic reference by name
+ */
 function getTopic(topicName, options) {
     const client = getPubSubClient(options);
     return client.topic(topicName);
 }
 /**
- * Helper to publish a JSON-encoded message with optional attributes.
+ * Get the request topic for a service
+ */
+function getServiceRequestTopic(service, options) {
+    const topicName = (0, topics_1.getRequestTopic)(service);
+    return getTopic(topicName, options);
+}
+/**
+ * Get the response topic for a service + app combination
+ */
+function getServiceResponseTopic(service, appId, options) {
+    const topicName = (0, topics_1.getResponseTopic)(service, appId);
+    return getTopic(topicName, options);
+}
+/**
+ * Helper to publish a JSON-encoded message to any topic
  */
 async function publishJson(topicName, message, attributes, pubSubOptions) {
     const topic = getTopic(topicName, pubSubOptions);
     const dataBuffer = Buffer.from(JSON.stringify(message));
-    return topic.publish(dataBuffer, attributes ?? {});
+    return topic.publishMessage({ data: dataBuffer, attributes: attributes ?? {} });
+}
+/**
+ * Publish a request message to a service
+ *
+ * @example
+ * await publishRequest("ingestion", {
+ *   action: "INGEST",
+ *   appId: "scaffold",
+ *   correlationId: "uuid-123",
+ *   timestamp: new Date().toISOString(),
+ *   payload: { uploadId: "file-123" }
+ * });
+ */
+async function publishRequest(service, message, attributes, pubSubOptions) {
+    const topicName = (0, topics_1.getRequestTopic)(service);
+    return publishJson(topicName, message, attributes, pubSubOptions);
+}
+/**
+ * Publish a response message back to the requesting app.
+ * Uses the appId from the original request to determine the response topic.
+ *
+ * @example
+ * // Service receives a request with appId: "scaffold"
+ * // Service publishes response to "ingestion-service-response.scaffold"
+ * await publishResponse("ingestion", "scaffold", {
+ *   action: "INGEST_RESPONSE",
+ *   appId: "ingestion-service",
+ *   correlationId: "uuid-123",
+ *   timestamp: new Date().toISOString(),
+ *   payload: { status: "success", recordId: "rec-456", uploadId: "file-123" }
+ * });
+ */
+async function publishResponse(service, targetAppId, message, attributes, pubSubOptions) {
+    const topicName = (0, topics_1.getResponseTopic)(service, targetAppId);
+    return publishJson(topicName, message, attributes, pubSubOptions);
+}
+/**
+ * Subscribe to a service's request topic.
+ * Returns the subscription for attaching message handlers.
+ *
+ * @param service - The service to subscribe to
+ * @param subscriptionName - Name of the subscription (will be created if it doesn't exist)
+ * @param options - PubSub client options
+ *
+ * @example
+ * const sub = await subscribeToRequests("ingestion", "ingestion-service-sub");
+ * sub.on("message", (message) => {
+ *   const data = JSON.parse(message.data.toString());
+ *   // Process request...
+ *   message.ack();
+ * });
+ */
+async function subscribeToRequests(service, subscriptionName, options) {
+    const client = getPubSubClient(options);
+    const topicName = (0, topics_1.getRequestTopic)(service);
+    // Check if subscription exists, create if not
+    const subscription = client.subscription(subscriptionName);
+    const [exists] = await subscription.exists();
+    if (!exists) {
+        const topic = client.topic(topicName);
+        const [topicExists] = await topic.exists();
+        if (!topicExists) {
+            await topic.create();
+        }
+        await topic.createSubscription(subscriptionName);
+    }
+    return subscription;
+}
+/**
+ * Subscribe to responses for a specific app.
+ * This is used by apps to receive responses from services.
+ *
+ * @param service - The service to receive responses from
+ * @param appId - The app's identifier
+ * @param subscriptionName - Name of the subscription
+ * @param options - PubSub client options
+ *
+ * @example
+ * // App "scaffold" subscribes to responses from ingestion service
+ * const sub = await subscribeToResponses("ingestion", "scaffold", "scaffold-ingestion-responses");
+ * sub.on("message", (message) => {
+ *   const data = JSON.parse(message.data.toString());
+ *   // Handle response...
+ *   message.ack();
+ * });
+ */
+async function subscribeToResponses(service, appId, subscriptionName, options) {
+    const client = getPubSubClient(options);
+    const topicName = (0, topics_1.getResponseTopic)(service, appId);
+    const subscription = client.subscription(subscriptionName);
+    const [exists] = await subscription.exists();
+    if (!exists) {
+        const topic = client.topic(topicName);
+        const [topicExists] = await topic.exists();
+        if (!topicExists) {
+            await topic.create();
+        }
+        await topic.createSubscription(subscriptionName);
+    }
+    return subscription;
+}
+/**
+ * Create a simple message consumer that handles JSON parsing and error handling
+ *
+ * @example
+ * const subscription = await subscribeToRequests("ingestion", "ingestion-sub");
+ * createMessageConsumer(subscription, async (envelope, message, ack, nack) => {
+ *   try {
+ *     // Process the envelope...
+ *     ack();
+ *   } catch (err) {
+ *     nack();
+ *   }
+ * });
+ */
+function createMessageConsumer(subscription, handler, onError) {
+    subscription.on("message", async (message) => {
+        try {
+            const envelope = JSON.parse(message.data.toString());
+            await handler(envelope, message, () => message.ack(), () => message.nack());
+        }
+        catch (err) {
+            if (onError) {
+                onError(err, message);
+            }
+            else {
+                console.error("[PubSub] Error processing message:", err);
+                message.nack();
+            }
+        }
+    });
+    subscription.on("error", (err) => {
+        console.error("[PubSub] Subscription error:", err);
+    });
 }
 //# sourceMappingURL=pubsubClient.js.map

package/dist/pubsubClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"pubsubClient.js","sourceRoot":"","sources":["../src/pubsubClient.ts"],"names":[],"mappings":";;;AAUA,0CAKC;AAED,4BAGC;AAKD,kCAWC;AApCD,iDAA6E;AAC7E,qCAAkD;AAqCzC,uFArCA,eAAM,OAqCA;AAnCf,IAAI,YAAY,GAAkB,IAAI,CAAC;AAEvC;;;;GAIG;AACH,SAAgB,eAAe,CAAC,OAAsB;IACpD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,IAAI,eAAM,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,SAAgB,QAAQ,CAAC,SAAoB,EAAE,OAAsB;IACnE,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,WAAW,CAC/B,SAAoB,EACpB,OAAgB,EAChB,UAAmC,EACnC,aAA4B;IAE5B,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAEjD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAExD,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"pubsubClient.js","sourceRoot":"","sources":["../src/pubsubClient.ts"],"names":[],"mappings":"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"}

package/dist/topics.d.ts

@@ -1,18 +1,51 @@
-export declare const TOPICS: {
-    fileUpload: string;
-    fileReady: string;
-    aiRequest: string;
-    aiResponse: string;
-    insightReady: string;
+import topicsConfig from "./topics.json";
+/**
+ * Service names as defined in the configuration
+ */
+export declare const SERVICES: {
+    ingestion: string;
+    ai: string;
+    extraction: string;
 };
-export type TopicKey = keyof typeof TOPICS;
-export type TopicName = (typeof TOPICS)[TopicKey];
+export type ServiceKey = keyof typeof SERVICES;
+export type ServiceTopic = (typeof SERVICES)[ServiceKey];
+/**
+ * Get the request topic for a service.
+ * Request topics are fixed per service: "ingestion-service", "ai-service", etc.
+ *
+ * @example
+ * getRequestTopic("ingestion") // => "ingestion-service"
+ */
+export declare function getRequestTopic(service: ServiceKey): ServiceTopic;
+/**
+ * Get the response topic for a service + app combination.
+ * Response topics are dynamic: "{service}-response.{appId}"
+ *
+ * This allows multiple apps to use the same service and receive
+ * responses on their own dedicated topic.
+ *
+ * @example
+ * getResponseTopic("ingestion", "scaffold") // => "ingestion-service-response.scaffold"
+ * getResponseTopic("ai", "myapp") // => "ai-service-response.myapp"
+ */
+export declare function getResponseTopic(service: ServiceKey, appId: string): string;
+/**
+ * Parse a response topic to extract service and appId
+ *
+ * @example
+ * parseResponseTopic("ingestion-service-response.scaffold")
+ * // => { service: "ingestion", appId: "scaffold" }
+ */
+export declare function parseResponseTopic(topic: string): {
+    service: ServiceKey | null;
+    appId: string | null;
+};
+/**
+ * Check if a topic is a request topic
+ */
+export declare function isRequestTopic(topic: string): boolean;
 /**
- * Convenience constants for each topic, for nicer imports.
- * Using type assertions to preserve literal types for message contracts.
+ * Check if a topic is a response topic
  */
-export declare const FILE_UPLOAD_TOPIC: "file-upload.scaffold";
-export declare const FILE_READY_TOPIC: "file-ready.scaffold";
-export declare const AI_REQUEST_TOPIC: "ai-request.scaffold";
-export declare const AI_RESPONSE_TOPIC: "ai-response.scaffold";
-export declare const INSIGHT_READY_TOPIC: "insight-ready.scaffold";
+export declare function isResponseTopic(topic: string): boolean;
+export { topicsConfig };

package/dist/topics.js

@@ -3,16 +3,74 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INSIGHT_READY_TOPIC = exports.AI_RESPONSE_TOPIC = exports.AI_REQUEST_TOPIC = exports.FILE_READY_TOPIC = exports.FILE_UPLOAD_TOPIC = exports.TOPICS = void 0;
+exports.topicsConfig = exports.SERVICES = void 0;
+exports.getRequestTopic = getRequestTopic;
+exports.getResponseTopic = getResponseTopic;
+exports.parseResponseTopic = parseResponseTopic;
+exports.isRequestTopic = isRequestTopic;
+exports.isResponseTopic = isResponseTopic;
 const topics_json_1 = __importDefault(require("./topics.json"));
-exports.TOPICS = topics_json_1.default;
+exports.topicsConfig = topics_json_1.default;
 /**
- * Convenience constants for each topic, for nicer imports.
- * Using type assertions to preserve literal types for message contracts.
+ * Service names as defined in the configuration
  */
-exports.FILE_UPLOAD_TOPIC = exports.TOPICS.fileUpload;
-exports.FILE_READY_TOPIC = exports.TOPICS.fileReady;
-exports.AI_REQUEST_TOPIC = exports.TOPICS.aiRequest;
-exports.AI_RESPONSE_TOPIC = exports.TOPICS.aiResponse;
-exports.INSIGHT_READY_TOPIC = exports.TOPICS.insightReady;
+exports.SERVICES = topics_json_1.default.services;
+/**
+ * Get the request topic for a service.
+ * Request topics are fixed per service: "ingestion-service", "ai-service", etc.
+ *
+ * @example
+ * getRequestTopic("ingestion") // => "ingestion-service"
+ */
+function getRequestTopic(service) {
+    return exports.SERVICES[service];
+}
+/**
+ * Get the response topic for a service + app combination.
+ * Response topics are dynamic: "{service}-response.{appId}"
+ *
+ * This allows multiple apps to use the same service and receive
+ * responses on their own dedicated topic.
+ *
+ * @example
+ * getResponseTopic("ingestion", "scaffold") // => "ingestion-service-response.scaffold"
+ * getResponseTopic("ai", "myapp") // => "ai-service-response.myapp"
+ */
+function getResponseTopic(service, appId) {
+    const serviceTopic = exports.SERVICES[service];
+    return `${serviceTopic}${topics_json_1.default.responsePrefix}.${appId}`;
+}
+/**
+ * Parse a response topic to extract service and appId
+ *
+ * @example
+ * parseResponseTopic("ingestion-service-response.scaffold")
+ * // => { service: "ingestion", appId: "scaffold" }
+ */
+function parseResponseTopic(topic) {
+    const responsePrefix = topics_json_1.default.responsePrefix;
+    for (const [key, serviceTopic] of Object.entries(exports.SERVICES)) {
+        const prefix = `${serviceTopic}${responsePrefix}.`;
+        if (topic.startsWith(prefix)) {
+            return {
+                service: key,
+                appId: topic.slice(prefix.length),
+            };
+        }
+    }
+    return { service: null, appId: null };
+}
+/**
+ * Check if a topic is a request topic
+ */
+function isRequestTopic(topic) {
+    return Object.values(exports.SERVICES).includes(topic);
+}
+/**
+ * Check if a topic is a response topic
+ */
+function isResponseTopic(topic) {
+    const responsePrefix = topics_json_1.default.responsePrefix;
+    return Object.values(exports.SERVICES).some(serviceTopic => topic.startsWith(`${serviceTopic}${responsePrefix}.`));
+}
 //# sourceMappingURL=topics.js.map

package/dist/topics.js.map

@@ -1 +1 @@
-{"version":3,"file":"topics.js","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":";;;;;;AAAA,gEAAmC;AAEtB,QAAA,MAAM,GAAG,qBAAM,CAAC;AAK7B;;;GAGG;AACU,QAAA,iBAAiB,GAAG,cAAM,CAAC,UAAoC,CAAC;AAChE,QAAA,gBAAgB,GAAG,cAAM,CAAC,SAAkC,CAAC;AAC7D,QAAA,gBAAgB,GAAG,cAAM,CAAC,SAAkC,CAAC;AAC7D,QAAA,iBAAiB,GAAG,cAAM,CAAC,UAAoC,CAAC;AAChE,QAAA,mBAAmB,GAAG,cAAM,CAAC,YAAwC,CAAC"}
+{"version":3,"file":"topics.js","sourceRoot":"","sources":["../src/topics.ts"],"names":[],"mappings":";;;;;;AAgBA,0CAEC;AAaD,4CAGC;AASD,gDAcC;AAKD,wCAEC;AAKD,0CAKC;AA1ED,gEAAyC;AA6EhC,uBA7EF,qBAAY,CA6EE;AA3ErB;;GAEG;AACU,QAAA,QAAQ,GAAG,qBAAY,CAAC,QAAQ,CAAC;AAI9C;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,OAAmB;IACjD,OAAO,gBAAQ,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAAC,OAAmB,EAAE,KAAa;IACjE,MAAM,YAAY,GAAG,gBAAQ,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,GAAG,YAAY,GAAG,qBAAY,CAAC,cAAc,IAAI,KAAK,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,KAAa;IAC9C,MAAM,cAAc,GAAG,qBAAY,CAAC,cAAc,CAAC;IAEnD,KAAK,MAAM,CAAC,GAAG,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,MAAM,GAAG,GAAG,YAAY,GAAG,cAAc,GAAG,CAAC;QACnD,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE,GAAiB;gBAC1B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;aAClC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAO,MAAM,CAAC,MAAM,CAAC,gBAAQ,CAAC,CAAC,QAAQ,CAAC,KAAqB,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,KAAa;IAC3C,MAAM,cAAc,GAAG,qBAAY,CAAC,cAAc,CAAC;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,gBAAQ,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CACjD,KAAK,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,cAAc,GAAG,CAAC,CACtD,CAAC;AACJ,CAAC"}

package/dist/topics.json

@@ -1,7 +1,8 @@
 {
-    "fileUpload": "file-upload.scaffold",
-    "fileReady": "file-ready.scaffold",
-    "aiRequest": "ai-request.scaffold",
-    "aiResponse": "ai-response.scaffold",
-    "insightReady": "insight-ready.scaffold"
+    "services": {
+        "ingestion": "ingestion-service",
+        "ai": "ai-service",
+        "extraction": "extraction-service"
+    },
+    "responsePrefix": "-response"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dooor-shared-config",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared Pub/Sub topics, message contracts and client for Dooor AI services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,8 +11,7 @@
     "directory": "packages/shared-config"
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/index.ts

@@ -1,4 +0,0 @@
-export * from "./topics";
-export * from "./messages";
-export * from "./pubsubClient";
-

package/src/messages.ts

@@ -1,138 +0,0 @@
-import type { TopicName } from "./topics";
-
-/**
- * Base envelope shared across all ATLAS Pub/Sub messages.
- * This is intentionally generic so Cortex (Python) and Node
- * services can both rely on a stable shape.
- */
-export interface AtlasEnvelope<TPayload = unknown> {
-  /**
-   * High-level action being performed, e.g. INGEST, RAG.
-   */
-  action: string;
-
-  /**
-   * Logical source application, e.g. "scaffold".
-   */
-  appId: string;
-
-  /**
-   * Correlation id for tracing a flow end-to-end.
-   */
-  correlationId: string;
-
-  /**
-   * ISO8601 timestamp (when the message was created).
-   */
-  timestamp: string;
-
-  /**
-   * Arbitrary payload specific to the topic / flow.
-   */
-  payload: TPayload;
-}
-
-/**
- * Message contracts per topic, based on the high-level flows
- * in the sequence diagram.
- */
-
-export interface FileUploadPayload {
-  /**
-   * Identifier of the uploaded file in the upstream app (Scaffold).
-   * Can be used by Ingestion to call Cortex /records.create.
-   */
-  uploadId: string;
-  fileName?: string;
-  mimeType?: string;
-  sizeBytes?: number;
-}
-
-export interface FileUploadMessage
-  extends AtlasEnvelope<FileUploadPayload> {
-  topic: "file-upload.scaffold";
-  action: "INGEST";
-}
-
-export interface FileReadyPayload {
-  /**
-   * Identifier of the record inside CortexDB.
-   */
-  recordId: string;
-}
-
-export interface FileReadyMessage
-  extends AtlasEnvelope<FileReadyPayload> {
-  topic: "file-ready.scaffold";
-}
-
-export interface AiRequestPayload {
-  /**
-   * Natural language query sent by the user.
-   */
-  query: string;
-
-  /**
-   * Optional record or file that should scope the RAG context.
-   */
-  recordId?: string;
-}
-
-export interface AiRequestMessage
-  extends AtlasEnvelope<AiRequestPayload> {
-  topic: "ai-request.scaffold";
-  action: "RAG";
-}
-
-export interface AiResponsePayload {
-  /**
-   * Final answer shown to the end user.
-   */
-  replyText: string;
-
-  /**
-   * Optional trace identifier for debugging.
-   */
-  traceId?: string;
-}
-
-export interface AiResponseMessage
-  extends AtlasEnvelope<AiResponsePayload> {
-  topic: "ai-response.scaffold";
-}
-
-export interface InsightReadyPayload {
-  /**
-   * The record in CortexDB that these insights belong to.
-   */
-  recordId: string;
-
-  /**
-   * Structured KPIs / metrics extracted from the AI response.
-   * Shape is intentionally open so teams can iterate quickly.
-   */
-  insights: Record<string, unknown>;
-}
-
-export interface InsightReadyMessage
-  extends AtlasEnvelope<InsightReadyPayload> {
-  topic: "insight-ready.scaffold";
-}
-
-/**
- * Union type for any ATLAS message.
- */
-export type AtlasMessage =
-  | FileUploadMessage
-  | FileReadyMessage
-  | AiRequestMessage
-  | AiResponseMessage
-  | InsightReadyMessage;
-
-export type AtlasPayload =
-  | FileUploadPayload
-  | FileReadyPayload
-  | AiRequestPayload
-  | AiResponsePayload
-  | InsightReadyPayload;
-

package/src/pubsubClient.ts

@@ -1,40 +0,0 @@
-import { PubSub, type ClientConfig, type Topic } from "@google-cloud/pubsub";
-import { TOPICS, type TopicName } from "./topics";
-
-let cachedPubSub: PubSub | null = null;
-
-/**
- * Creates (or returns a cached) PubSub client.
- * Configuration is driven by standard Google environment variables
- * (GOOGLE_CLOUD_PROJECT, credentials, PUBSUB_EMULATOR_HOST, etc).
- */
-export function getPubSubClient(options?: ClientConfig): PubSub {
-  if (!cachedPubSub) {
-    cachedPubSub = new PubSub(options);
-  }
-  return cachedPubSub;
-}
-
-export function getTopic(topicName: TopicName, options?: ClientConfig): Topic {
-  const client = getPubSubClient(options);
-  return client.topic(topicName);
-}
-
-/**
- * Helper to publish a JSON-encoded message with optional attributes.
- */
-export async function publishJson(
-  topicName: TopicName,
-  message: unknown,
-  attributes?: Record<string, string>,
-  pubSubOptions?: ClientConfig
-): Promise<string> {
-  const topic = getTopic(topicName, pubSubOptions);
-
-  const dataBuffer = Buffer.from(JSON.stringify(message));
-
-  return topic.publish(dataBuffer, attributes ?? {});
-}
-
-export { TOPICS };
-

package/src/topics.json

@@ -1,8 +0,0 @@
-{
-  "fileUpload": "file-upload.scaffold",
-  "fileReady": "file-ready.scaffold",
-  "aiRequest": "ai-request.scaffold",
-  "aiResponse": "ai-response.scaffold",
-  "insightReady": "insight-ready.scaffold"
-}
-

package/src/topics.ts

@@ -1,17 +0,0 @@
-import topics from "./topics.json";
-
-export const TOPICS = topics;
-
-export type TopicKey = keyof typeof TOPICS;
-export type TopicName = (typeof TOPICS)[TopicKey];
-
-/**
- * Convenience constants for each topic, for nicer imports.
- * Using type assertions to preserve literal types for message contracts.
- */
-export const FILE_UPLOAD_TOPIC = TOPICS.fileUpload as "file-upload.scaffold";
-export const FILE_READY_TOPIC = TOPICS.fileReady as "file-ready.scaffold";
-export const AI_REQUEST_TOPIC = TOPICS.aiRequest as "ai-request.scaffold";
-export const AI_RESPONSE_TOPIC = TOPICS.aiResponse as "ai-response.scaffold";
-export const INSIGHT_READY_TOPIC = TOPICS.insightReady as "insight-ready.scaffold";
-