@indigoai-us/hq-cloud 5.19.1 → 5.21.0

package/src/schemas/source-channels.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import {
+  SOURCE_CHANNELS,
+  isSourceChannel,
+  assertSourceChannel,
+  InvalidSourceChannelError,
+} from "./source-channels.js";
+import type { SourceChannel } from "./source-channels.js";
+
+describe("SOURCE_CHANNELS", () => {
+  it("contains the five canonical channels", () => {
+    expect([...SOURCE_CHANNELS]).toEqual([
+      "meeting",
+      "email",
+      "slack",
+      "linear",
+      "notion",
+    ]);
+  });
+
+  it("is frozen (readonly at runtime)", () => {
+    expect(Object.isFrozen(SOURCE_CHANNELS)).toBe(true);
+  });
+});
+
+describe("isSourceChannel", () => {
+  it.each(SOURCE_CHANNELS)("returns true for '%s'", (channel) => {
+    expect(isSourceChannel(channel)).toBe(true);
+  });
+
+  it("returns false for an invalid string", () => {
+    expect(isSourceChannel("pigeon")).toBe(false);
+  });
+
+  it("returns false for non-string values", () => {
+    expect(isSourceChannel(42)).toBe(false);
+    expect(isSourceChannel(null)).toBe(false);
+    expect(isSourceChannel(undefined)).toBe(false);
+  });
+});
+
+describe("assertSourceChannel", () => {
+  it.each(SOURCE_CHANNELS)("does not throw for '%s'", (channel) => {
+    expect(() => assertSourceChannel(channel)).not.toThrow();
+  });
+
+  it("throws InvalidSourceChannelError for invalid value", () => {
+    expect(() => assertSourceChannel("pigeon")).toThrow(InvalidSourceChannelError);
+  });
+
+  it("error message contains the offending value", () => {
+    expect(() => assertSourceChannel("pigeon")).toThrow("'pigeon'");
+  });
+
+  it("error message lists all valid channels", () => {
+    try {
+      assertSourceChannel("pigeon");
+    } catch (err) {
+      const msg = (err as Error).message;
+      for (const channel of SOURCE_CHANNELS) {
+        expect(msg).toContain(channel);
+      }
+    }
+  });
+
+  it("error message matches snapshot", () => {
+    expect(() => assertSourceChannel("pigeon")).toThrowErrorMatchingInlineSnapshot(
+      `[InvalidSourceChannelError: Invalid source channel: 'pigeon'. Valid channels: meeting, email, slack, linear, notion]`,
+    );
+  });
+});
+
+describe("SourceChannel type", () => {
+  it("narrows correctly via type guard", () => {
+    const value: unknown = "meeting";
+    if (isSourceChannel(value)) {
+      // TypeScript narrows to SourceChannel — compile-time check
+      const _channel: SourceChannel = value;
+      expect(_channel).toBe("meeting");
+    }
+  });
+});

package/src/schemas/source-channels.ts

@@ -0,0 +1,36 @@
+/**
+ * Source channel schema — single source of truth.
+ *
+ * Closed enum: extension requires a code change (PR).
+ * Matches the sources-pipeline SourceChannel type.
+ */
+
+export const SOURCE_CHANNELS = Object.freeze([
+  "meeting",
+  "email",
+  "slack",
+  "linear",
+  "notion",
+] as const);
+
+export type SourceChannel = (typeof SOURCE_CHANNELS)[number];
+
+export class InvalidSourceChannelError extends Error {
+  override readonly name = "InvalidSourceChannelError";
+
+  constructor(value: unknown) {
+    super(
+      `Invalid source channel: '${String(value)}'. Valid channels: ${SOURCE_CHANNELS.join(", ")}`,
+    );
+  }
+}
+
+export function isSourceChannel(value: unknown): value is SourceChannel {
+  return typeof value === "string" && (SOURCE_CHANNELS as readonly string[]).includes(value);
+}
+
+export function assertSourceChannel(value: unknown): asserts value is SourceChannel {
+  if (!isSourceChannel(value)) {
+    throw new InvalidSourceChannelError(value);
+  }
+}

package/src/signals/get.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Unit tests for signals/get.ts.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { GetObjectCommand, type S3Client } from "@aws-sdk/client-s3";
+import { getSignal, SignalNotFoundError } from "./get.js";
+import {
+  _setSignalsS3Factory,
+  _resetSignalsS3Factory,
+} from "./internals.js";
+import type { EntityContext } from "../types.js";
+import { InvalidSignalTypeError } from "../schemas/signal-types.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const ENTITY: EntityContext = {
+  uid: "cmp_test_001",
+  slug: "test",
+  bucketName: "hq-vault-test",
+  region: "us-east-1",
+  credentials: {
+    accessKeyId: "ASIATEST",
+    secretAccessKey: "secret",
+    sessionToken: "session",
+  },
+  expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+};
+
+const ACTION_ITEM_MD = `---
+signal_id: sig_action_001
+signal_type: action_item
+source_ref: abc-meeting-001
+citations:
+  - "Stefan to review the sources pipeline implementation by end of week"
+  - "Corey to prepare roadmap slides"
+entity_refs:
+  - stefan@indigoai.us
+  - corey@indigoai.us
+---
+
+Stefan will review the sources pipeline implementation.
+
+Corey will prepare updated roadmap slides.
+`;
+
+function installStub(objects: Record<string, string>): void {
+  async function send(command: unknown): Promise<unknown> {
+    if (command instanceof GetObjectCommand) {
+      const { Key } = command.input as { Key: string };
+      const content = objects[Key];
+      if (content === undefined) {
+        const err = new Error(`NoSuchKey: ${Key}`);
+        (err as Error & { name: string }).name = "NoSuchKey";
+        throw err;
+      }
+      async function* stream(): AsyncIterable<Uint8Array> {
+        yield Buffer.from(content, "utf-8");
+      }
+      return { Body: stream(), $metadata: {} };
+    }
+    throw new Error(`unhandled command`);
+  }
+  _setSignalsS3Factory(() => ({ send } as unknown as S3Client));
+}
+
+beforeEach(() => _resetSignalsS3Factory());
+afterEach(() => _resetSignalsS3Factory());
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("getSignal", () => {
+  it("happy path: parses frontmatter, body, and surfaces typed cross-refs", async () => {
+    installStub({ "signals/action_item/foo.md": ACTION_ITEM_MD });
+
+    const doc = await getSignal({
+      entity: ENTITY,
+      signalType: "action_item",
+      signalId: "foo",
+    });
+
+    expect(doc.key).toBe("signals/action_item/foo.md");
+    expect(doc.frontmatter).toMatchObject({
+      signal_id: "sig_action_001",
+      signal_type: "action_item",
+      source_ref: "abc-meeting-001",
+    });
+    expect(doc.body).toContain("Stefan will review");
+    expect(doc.body).toContain("Corey will prepare");
+
+    // Typed cross-reference fields.
+    expect(doc.sourceRef).toBe("abc-meeting-001");
+    expect(doc.citations).toEqual([
+      "Stefan to review the sources pipeline implementation by end of week",
+      "Corey to prepare roadmap slides",
+    ]);
+    expect(doc.entityRefs).toEqual([
+      "stefan@indigoai.us",
+      "corey@indigoai.us",
+    ]);
+  });
+
+  it("throws SignalNotFoundError on NoSuchKey", async () => {
+    installStub({});
+
+    await expect(
+      getSignal({ entity: ENTITY, signalType: "action_item", signalId: "missing" }),
+    ).rejects.toBeInstanceOf(SignalNotFoundError);
+
+    await expect(
+      getSignal({ entity: ENTITY, signalType: "action_item", signalId: "missing" }),
+    ).rejects.toThrow(/signals\/action_item\/missing\.md/);
+  });
+
+  it("rejects an invalid signalType via assertSignalType BEFORE any S3 call", async () => {
+    let called = 0;
+    _setSignalsS3Factory(() => ({
+      send: async () => {
+        called++;
+        return {};
+      },
+    } as unknown as S3Client));
+
+    await expect(
+      getSignal({
+        entity: ENTITY,
+        // @ts-expect-error — invalid signal type intentional
+        signalType: "ramble",
+        signalId: "foo",
+      }),
+    ).rejects.toBeInstanceOf(InvalidSignalTypeError);
+    expect(called).toBe(0);
+  });
+
+  it("returns frontmatter:null for malformed (no frontmatter block) documents", async () => {
+    installStub({ "signals/action_item/plain.md": "Just a body, no frontmatter." });
+
+    const doc = await getSignal({
+      entity: ENTITY,
+      signalType: "action_item",
+      signalId: "plain",
+    });
+
+    expect(doc.frontmatter).toBeNull();
+    expect(doc.body).toBe("Just a body, no frontmatter.");
+    expect(doc.sourceRef).toBeUndefined();
+    expect(doc.citations).toBeUndefined();
+    expect(doc.entityRefs).toBeUndefined();
+  });
+
+  it("omits cross-ref fields when frontmatter is present but lacks them", async () => {
+    const SPARSE = `---
+signal_id: sig_summary_001
+signal_type: summary
+---
+
+A summary with no source_ref, citations, or entity_refs.
+`;
+    installStub({ "signals/summary/sparse.md": SPARSE });
+
+    const doc = await getSignal({
+      entity: ENTITY,
+      signalType: "summary",
+      signalId: "sparse",
+    });
+
+    expect(doc.frontmatter).toMatchObject({ signal_id: "sig_summary_001" });
+    expect(doc.sourceRef).toBeUndefined();
+    expect(doc.citations).toBeUndefined();
+    expect(doc.entityRefs).toBeUndefined();
+    expect(doc.body).toContain("A summary");
+  });
+
+  it("filters non-string entries out of citations + entity_refs", async () => {
+    const MIXED = `---
+signal_id: sig_test
+signal_type: action_item
+citations:
+  - "string one"
+  - 42
+  - "string two"
+entity_refs:
+  - true
+  - "kept@example.com"
+---
+
+Body.
+`;
+    installStub({ "signals/action_item/mixed.md": MIXED });
+
+    const doc = await getSignal({
+      entity: ENTITY,
+      signalType: "action_item",
+      signalId: "mixed",
+    });
+
+    expect(doc.citations).toEqual(["string one", "string two"]);
+    expect(doc.entityRefs).toEqual(["kept@example.com"]);
+  });
+});

package/src/signals/get.ts

@@ -0,0 +1,79 @@
+/**
+ * getSignal — fetch a single signal document from an entity bucket and
+ * return parsed frontmatter + body, with `sourceRef`, `citations`, and
+ * `entityRefs` surfaced as typed fields.
+ */
+
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { assertSignalType } from "../schemas/signal-types.js";
+import { getS3Client, streamToString } from "./internals.js";
+import { parseMarkdown } from "./parse.js";
+import type { GetSignalOptions, SignalDocument } from "./types.js";
+
+export class SignalNotFoundError extends Error {
+  override readonly name = "SignalNotFoundError";
+  constructor(public readonly key: string) {
+    super(`Signal not found: ${key}`);
+  }
+}
+
+function isNoSuchKey(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  // AWS SDK v3 throws either a `NoSuchKey` exception or a `NotFound` head error.
+  return name === "NoSuchKey" || name === "NoSuchKeyException";
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: string[] = [];
+  for (const item of value) {
+    if (typeof item === "string") out.push(item);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+export async function getSignal(opts: GetSignalOptions): Promise<SignalDocument> {
+  // Validate signalType BEFORE any S3 call (acceptance criterion + agent-mitigation).
+  assertSignalType(opts.signalType);
+
+  const client = getS3Client(opts.entity);
+  const key = `signals/${opts.signalType}/${opts.signalId}.md`;
+
+  let body: string;
+  try {
+    const response = await client.send(
+      new GetObjectCommand({
+        Bucket: opts.entity.bucketName,
+        Key: key,
+      }),
+    );
+    body = await streamToString(response.Body);
+  } catch (err) {
+    if (isNoSuchKey(err)) {
+      throw new SignalNotFoundError(key);
+    }
+    throw err;
+  }
+
+  const parsed = parseMarkdown(body);
+
+  const document: SignalDocument = {
+    key,
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+  };
+
+  if (parsed.frontmatter) {
+    const sourceRef = parsed.frontmatter.source_ref;
+    if (typeof sourceRef === "string") {
+      document.sourceRef = sourceRef;
+    }
+    const citations = asStringArray(parsed.frontmatter.citations);
+    if (citations) document.citations = citations;
+    const entityRefs = asStringArray(parsed.frontmatter.entity_refs);
+    if (entityRefs) document.entityRefs = entityRefs;
+  }
+
+  return document;
+}

package/src/signals/internals.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal helpers shared between signals/list.ts and signals/get.ts.
+ *
+ * Independent S3 client factory hook (separate from sources/internals.ts)
+ * so signals tests can swap their stub without disturbing sources tests.
+ * Production code never calls the setter.
+ */
+
+import { S3Client } from "@aws-sdk/client-s3";
+import type { EntityContext } from "../types.js";
+
+function defaultFactory(ctx: EntityContext): S3Client {
+  return new S3Client({
+    region: ctx.region,
+    credentials: {
+      accessKeyId: ctx.credentials.accessKeyId,
+      secretAccessKey: ctx.credentials.secretAccessKey,
+      sessionToken: ctx.credentials.sessionToken,
+    },
+  });
+}
+
+let factory: (ctx: EntityContext) => S3Client = defaultFactory;
+
+export function getS3Client(ctx: EntityContext): S3Client {
+  return factory(ctx);
+}
+
+/** Test hook: replace the S3 client factory. */
+export function _setSignalsS3Factory(f: (ctx: EntityContext) => S3Client): void {
+  factory = f;
+}
+
+/** Test hook: restore the default S3 client factory. */
+export function _resetSignalsS3Factory(): void {
+  factory = defaultFactory;
+}
+
+export async function streamToString(body: unknown): Promise<string> {
+  const stream = body as AsyncIterable<Uint8Array>;
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}