dooor-shared-config 0.1.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,20 @@
+"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);
+//# 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,2CAAyB;AACzB,6CAA2B;AAC3B,iDAA+B"}

package/dist/messages.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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/dist/messages.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":""}

package/dist/pubsubClient.d.ts

@@ -0,0 +1,14 @@
+import { PubSub, type ClientConfig, type Topic } from "@google-cloud/pubsub";
+import { TOPICS, type TopicName } from "./topics";
+/**
+ * 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.
+ */
+export declare function publishJson(topicName: TopicName, message: unknown, attributes?: Record<string, string>, pubSubOptions?: ClientConfig): Promise<string>;
+export { TOPICS };

package/dist/pubsubClient.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOPICS = void 0;
+exports.getPubSubClient = getPubSubClient;
+exports.getTopic = getTopic;
+exports.publishJson = publishJson;
+const pubsub_1 = require("@google-cloud/pubsub");
+const topics_1 = require("./topics");
+Object.defineProperty(exports, "TOPICS", { enumerable: true, get: function () { return topics_1.TOPICS; } });
+let cachedPubSub = null;
+/**
+ * Creates (or returns a cached) PubSub client.
+ * Configuration is driven by standard Google environment variables
+ * (GOOGLE_CLOUD_PROJECT, credentials, PUBSUB_EMULATOR_HOST, etc).
+ */
+function getPubSubClient(options) {
+    if (!cachedPubSub) {
+        cachedPubSub = new pubsub_1.PubSub(options);
+    }
+    return cachedPubSub;
+}
+function getTopic(topicName, options) {
+    const client = getPubSubClient(options);
+    return client.topic(topicName);
+}
+/**
+ * Helper to publish a JSON-encoded message with optional attributes.
+ */
+async function publishJson(topicName, message, attributes, pubSubOptions) {
+    const topic = getTopic(topicName, pubSubOptions);
+    const dataBuffer = Buffer.from(JSON.stringify(message));
+    return topic.publish(dataBuffer, attributes ?? {});
+}
+//# sourceMappingURL=pubsubClient.js.map

package/dist/pubsubClient.js.map

@@ -0,0 +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"}

package/dist/topics.d.ts

@@ -0,0 +1,18 @@
+export declare const TOPICS: {
+    fileUpload: string;
+    fileReady: string;
+    aiRequest: string;
+    aiResponse: string;
+    insightReady: string;
+};
+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 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";

package/dist/topics.js

@@ -0,0 +1,18 @@
+"use strict";
+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;
+const topics_json_1 = __importDefault(require("./topics.json"));
+exports.TOPICS = topics_json_1.default;
+/**
+ * Convenience constants for each topic, for nicer imports.
+ * Using type assertions to preserve literal types for message contracts.
+ */
+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;
+//# sourceMappingURL=topics.js.map

package/dist/topics.js.map

@@ -0,0 +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"}

package/dist/topics.json

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

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "dooor-shared-config",
+  "version": "0.1.0",
+  "description": "Shared Pub/Sub topics, message contracts and client for Dooor AI services",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dooor/mono.git",
+    "directory": "packages/shared-config"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@google-cloud/pubsub": "^4.9.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}
+

package/src/index.ts

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

package/src/messages.ts

@@ -0,0 +1,138 @@
+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

@@ -0,0 +1,40 @@
+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

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

package/src/topics.ts

@@ -0,0 +1,17 @@
+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";
+